UrbIrrad

UrbIrrad est un outil Python open source pour calculer le rayonnement solaire reçu sur un maillage de capteurs. Il prépare la scène, appelle Radiance via PyRadiance, puis rassemble les résultats en HDF5. Il s’adresse aux études de bâtiments et d’espaces urbains, en intérieur, en extérieur et dans les espaces semi-ouverts.

L’objectif est de rendre les calculs solaires avec Radiance plus accessibles, sans devoir assembler soi-même toute sa chaîne de commandes. On fournit la géométrie et un fichier météo, on décrit les matériaux, les capteurs et la période dans un YAML, puis on lance le calcul depuis le terminal. La bibliothèque s’installe simplement avec python -m pip install urbirrad.

Le calcul le plus simple donne le soleil direct reçu sur un plan, en tenant compte des ombres et de la transmission par les vitrages. On peut ensuite ajouter le diffus du ciel et les réflexions diffuses du soleil direct, ou calculer l’exposition dans six directions. Un mode géométrique séparé fournit aussi les heures potentielles d’ensoleillement.

Les résultats sont enregistrés en HDF5, avec un fichier XDMF pour les explorer dans ParaView. L’outil concerne uniquement le rayonnement solaire de courtes longueurs d’onde : les six directions peuvent alimenter des études de confort, mais UrbIrrad ne calcule ni les grandes longueurs d’onde, ni la température moyenne radiante globale. La documentation complète détaille les réglages et les limites de chaque option.

Les données nécessaires

Un cas associe un fichier météo EPW, des surfaces décrivant la scène et un maillage de capteurs. Les propriétés solaires sont définies dans un YAML : réflectance des surfaces opaques, transmittance des vitrages, orientation des plans récepteurs, période et composantes à calculer.

Les formats STL, VTP, VTK, OBJ et PLY sont acceptés. Les maillages doivent déjà être triangulés : il n’y a ni réparation automatique, ni import CAD. Les coordonnées suivent X Est, Y Nord, Z Haut, en mètres. Les propriétés optiques proviennent du YAML, pas des couleurs ou textures des fichiers.

Chaque triangle du maillage de capteurs fournit un point de calcul à son centre, avec un décalage configurable pour éviter de le placer exactement sur une surface. En mode plane, une normale commune fixe l’orientation de tous les plans récepteurs ; elle n’est pas déduite des normales des triangles.

Trois composantes à distinguer

Les résultats sont des irradiances incidentes en W/m², et non directement les valeurs DNI ou DHI du fichier météo. Un rayonnement rasant contribue moins qu’un rayonnement perpendiculaire au plan, et un rayonnement arrivant par l’arrière ne contribue pas.

Direct : le soleil est évalué à ses positions horaires, avec les ombres et la transmission à travers les vitrages.

Diffus : le ciel constitue une source étendue. Son accès dépend des masques, des ouvertures et des chemins de réflexion autorisés.

Direct réfléchi : une contribution supplémentaire liée au soleil et aux surfaces. Les trois figures utilisent des échelles de couleurs indépendantes ; comparer les légendes en W/m², pas seulement les couleurs.

Le diffus ne contient pas les réflexions alimentées par le soleil direct. Celles-ci sont calculées séparément. Le direct réfléchi est une approximation fondée sur des patches de ciel ; il exclut les chemins purement spéculaires, comme une réflexion solaire uniquement sur un vitrage ou un miroir.

Pourquoi des matrices

Radiance suit les chemins du rayonnement en partant des récepteurs vers les sources. Pour intégrer le diffus sur un plan, il échantillonne un hémisphère et les chemins secondaires : ce n’est pas un simple test d’ombre.

Avec une géométrie et des matériaux fixes, la réponse de la scène aux différentes régions du ciel peut être calculée une fois. UrbIrrad sépare cette réponse géométrique de l’intensité du ciel, qui varie avec la météo :

La matrice C relie les plans récepteurs aux patches de ciel et de sol ; la matrice S contient les intensités de ces patches à chaque intervalle météo. Leur produit fournit les irradiances pour tous les intervalles. Cette écriture est schématique : les matrices Radiance portent trois canaux, ensuite ramenés à une irradiance scalaire.

Les principaux programmes Radiance interviennent ainsi :

• oconv compile la scène en octree pour accélérer les intersections rayon/surface ;
• gendaymtx construit les ciels variables issus de l’EPW et les sources solaires ;
• rfluxmtx calcule les matrices de transfert à travers la scène ;
• rcontrib distingue les contributions des sources, notamment dans le calcul du direct ;
• dctimestep applique les matrices de ciel aux coefficients, sans retracer la géométrie.

On évite ainsi de relancer un calcul complet de scène pour chaque heure du diffus. Il reste naturellement des boucles, de l’échantillonnage et du travail de multiplication et d’écriture.

Le direct suit une autre voie : les sources correspondant aux positions solaires des intervalles sont traitées en un lot. Il n’utilise pas l’approximation des patches de ciel ni dctimestep. Pour le direct réfléchi, deux calculs utilisent les mêmes rayons hémisphériques, avec et sans rebonds diffus ; leur différence isole la contribution réfléchie et évite de compter une seconde fois le direct.

Précision et temps de calcul

Le comportement observé dans nos essais est le suivant :

Ce n’est pas un benchmark universel. Le nombre de capteurs, les six orientations éventuelles, la géométrie, le nombre de rayons, la profondeur des réflexions et le matériel modifient le coût. --nproc parallélise le lancer de rayons, mais doubler les processus ne garantit pas de diviser le temps par deux. Le terminal affiche la progression et les temps par étape.

Les coefficients du diffus et du direct réfléchi sont mis en cache. Une autre période ou météo peut les réutiliser si géométrie, matériaux, capteurs et paramètres numériques restent compatibles. Le cache ne supprime pas le calcul du direct, la génération des ciels, les produits matriciels ni l’écriture des résultats.

MF=1 représente le ciel par 145 patches plus le sol ; MF=2 utilise 577 patches plus le sol. Une résolution plus fine améliore la discrétisation angulaire mais augmente le coût ; elle ne modifie pas les positions solaires du direct.

Le diffus utilise initialement ambient_bounces: 3. L’intégration sur le plan consomme un niveau ambiant Radiance, laissant jusqu’à deux réflexions diffuses physiques de surface. Le direct réfléchi dispose de ses propres réglages. Les valeurs d’exemple ne dispensent pas de vérifier la convergence d’une étude.

Installation et lancement

Dans un environnement Python 3.12 ou plus récent :

python -m pip install urbirrad

PyRadiance fournit les exécutables Radiance nécessaires sous Windows. Les données d’exemple ne sont pas incluses dans le paquet ; on peut les récupérer dans le dépôt :

git clone https://gitlab.com/arep-dev/urbirrad.git
cd urbirrad
python -m urbirrad.cli check examples/template_case/case.yaml
python -m urbirrad.cli run examples/template_case/case.yaml --nproc 4

L’exemple par défaut calcule uniquement le direct. Des YAML distincts ajoutent progressivement le diffus, les six directions et le direct réfléchi. Dans un cas copié et adapté, cet extrait de configuration sélectionne juillet et les trois composantes :

simulation:
  components:
    direct: true
    diffuse: true
    reflected_direct: true
  period:
    start: "07-01"
    end: "07-31"

output:
  directory: ./results
  format: hdf5
  save_vtk_snapshots: false

Les dates sont inclusives et les chemins relatifs au YAML. Cet extrait complète un cas existant ; il ne remplace pas les sections météo, géométrie et matériaux.

Six directions et heures de soleil

six_directions calcule six irradiances hémisphériques, orientées Est, Ouest, Nord, Sud, Haut et Bas. Il est pensé pour les études de confort et les approches directionnelles du rayonnement reçu par une personne. Ce ne sont pas six rayons isolés, ni une température moyenne radiante.

potential_sunshine compte les heures potentielles de soleil sur les plans des capteurs. Les obstacles opaques sont conservés, les vitrages retirés, et les nuages et intensités météo ignorés. L’échantillonnage est horaire ou demi-horaire. Le résultat est un champ statique sunshine_hours, sans pas de temps ; la même information peut aussi accompagner un calcul d’irradiance directe. Radiance est un peu surdimensionné pour ce seul besoin, mais la géométrie est déjà prête !

Vitrages et résultats

Une commande indépendante aide à estimer une transmittance solaire normale lorsque les données fabricant donnent seulement le coefficient thermique Ug et le facteur solaire g :

python -m urbirrad.glazing --ug 1.1 --g 0.71 --tl 0.83

L’estimation est ici d’environ 0.643. Elle reprend la corrélation du modèle simplifié de vitrage d’EnergyPlus , pas une conversion normative exacte. La transmission lumineuse TL est enregistrée mais n’entre pas dans l’estimation solaire. Le facteur g inclut aussi des gains thermiques secondaires : il ne doit pas être utilisé directement comme transmittance solaire. Une valeur fabricant appropriée reste prioritaire ; pour un vitrage avec film, les données doivent décrire l’assemblage complet. Voir les hypothèses et limites .

Les irradiances sont conservées en HDF5 avec leurs composantes séparées, la géométrie et les informations temporelles. Un fichier XDMF permet de les visualiser dans ParaView. Pour ces fichiers dans ParaView 6.1, choisir XDMF Reader, et non Xdmf3 Reader ou Xdmf3 Reader T, puis sélectionner le champ à colorer.

Périmètre et ressources

UrbIrrad est en développement actif et distribué sous licence MIT. Il traite uniquement le rayonnement solaire de courtes longueurs d’onde. Il ne calcule ni le rayonnement thermique de grandes longueurs d’onde, ni la MRT globale, ni à lui seul un indicateur de confort thermique.

• Paquet PyPI .
• Billet de présentation .
• Code source, exemples et feuille de route .
• Documentation et méthodes détaillées .
• Radiance et PyRadiance .