star-phor-input.5.scd (15033B)
1 star-phor-input(5) "UNIX" 2 3 ; Copyright (C) 2024-2026 Centre National de la Recherche Scientifique 4 ; Copyright (C) 2024-2026 Clermont Auvergne INP 5 ; Copyright (C) 2024-2026 INSA Lyon 6 ; Copyright (C) 2024-2026 Institut Mines Télécom Albi-Carmaux 7 ; Copyright (C) 2024-2026 Institut National Polytechnique de Toulouse 8 ; Copyright (C) 2024-2026 |Méso|Star> (contact@meso-star.com) 9 ; Copyright (C) 2024-2026 PhotonLyX (info@photonlyx.com) 10 ; Copyright (C) 2024-2026 Université de Lorraine 11 ; Copyright (C) 2024-2026 Université Paul Sabatier 12 ; Copyright (C) 2024-2026 Université Toulouse - Jean Jaurès 13 ; 14 ; This program is free software: you can redistribute it and/or modify 15 ; it under the terms of the GNU General Public License as published by 16 ; the Free Software Foundation, either version 3 of the License, or 17 ; (at your option) any later version. 18 ; 19 ; This program is distributed in the hope that it will be useful, 20 ; but WITHOUT ANY WARRANTY; without even the implied warranty of 21 ; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 22 ; GNU General Public License for more details. 23 ; 24 ; You should have received a copy of the GNU General Public License 25 ; along with this program. If not, see <http://www.gnu.org/licenses/>. 26 27 # NAME 28 29 star-phor-input - file format describing a photoreactor configuration 30 31 # DESCRIPTION 32 33 A *star-phor-input* photoreactor description consists of a list of surfaces and 34 volumes. Each element is defined by a set of properties representing either 35 geometrical characteristics or physical properties. 36 37 Properties are specified either as a single-line entry or as a multi-line block, 38 where each line corresponds to a distinct attribute of the property being 39 defined. Single-line properties are declared using the '<keyword>: <value>' 40 syntax (both the keyword and the value must appear in the same line). No 41 additional content other than comments is allowed after the value. 'volumes', 42 'surfaces' and 'prop_rads' are multi-line properties and declared using the 43 '<keyword>: <name>' syntax. Note that the colon (:) character is reserved as a 44 separator in the input file and therefore cannot be used in volumes, surfaces, 45 or prop_rad names. All the others multi-line properties are declared with the 46 '<keyword>:' syntax. 47 48 The only supported geometrical data format is the triangular mesh. Geometries 49 are composed of one keyword ('FRONT' or 'BACK') and by a STL filepath. Triangles 50 in STL files are assumed to follow the right-hand rule convention to determine 51 their orientation; that is, the 'FRONT' face of a triangle in the 52 *star-phor-input* convention is the side from which its vertices appear arranged 53 in counterclockwise order. Geometries can be decomposed into multiple files (see 54 example 1). Both the FRONT and BACK sides of a given triangle may belong to the 55 same surface or volume (see examples 2 and 3), except in the particular case 56 where the surface also acts as a source (see example 4). The geometry (or set of 57 elementary geometries) associated with a volume must form a closed enclosure to 58 ensure that every part of the system domain consists of a single medium with 59 consistent properties. 60 61 The star-phor-input format does not enforce a specific order for property 62 declarations. However, when encountering a keyword that does not belong to the 63 current parsing scope, the parser will move up one hierarchy level. 64 Consequently, all properties within the same scope must be declared together 65 within the same block; otherwise, an exception will be raised and the parsing 66 will be stopped. 67 68 Indentation of any type is not mandatory for lower hierarchy blocks. Keywords in 69 the format file must be separated by at least one tab or space. If multiple 70 tabs, spaces, or combinations of both are used, they will be ignored. 71 72 # GRAMMAR 73 74 This sections outlines the *star-phor-input* configuration files syntax using 75 the Backus-Naur notation system. 76 77 The hash symbol (#) is used to indicate a comment. In the configuration file, it 78 marks lines or line portions that are comments and are therefore ignored by the 79 parser. In this document, the same symbol is also used to comment the format 80 description itself. In both cases, the # character and everything that follows 81 it on the same line must be ignored and should not be included in the actual 82 configuration file. 83 84 Some lines end with a backslash (\\). This allows the description to continue on 85 the next line for formatting purposes. However, this trick cannot be used in 86 description files, and actual description lines must remain on a single line. 87 88 The syntax rules enabling the description of a photoreactor are as follows: 89 90 ``` 91 <photoreactive-system> ::= <element> | <comment> 92 ... 93 94 <element> ::= <volume> | <surface> 95 96 <volume> ::= 'volume:' <name> 97 [<volume-props> ...] 98 99 <volume-props> ::= <geometry> 100 | <sensor> 101 | <prop-rad> 102 103 <surface> ::= 'surface:' <name> 104 [<surface-props> ...] 105 106 <surface-props> ::= <brdf> 107 | <btdf> 108 | <geometry> 109 | <sensor> 110 | <surface-source> 111 112 <geometry> ::= geometry:' <side> \\ 113 <geom-file> [<geom-unit>] 114 <side> ::= 'FRONT' | 'BACK' 115 <geom-file> ::= path # STL files only 116 # Spaces are not allowed 117 118 <geom-unit> ::= 'm' # Default unit 119 | 'cm' 120 | 'mm' 121 | 'km' 122 123 <sensor> ::= 'sensor:' 124 'response_function:' real 125 126 <prop-rad> ::= 'prop_rad:' <name> 127 <prop-rad-spec> 128 129 <prop-rad-spec> ::= <scatterer> 130 131 <scatterer> ::= 'scatterer:' 132 <concentration> 133 <cross-sections> 134 135 <concentration> ::= 'concentration:' real \\ 136 <concentration-unit> 137 <concentration-unit> ::= 'kg/L' 138 | 'kg.L^-1' 139 | 'kg.m^-3' 140 | 'kg/m^3' 141 | 'mol/L' 142 | 'mol.L^-1' 143 | 'mol.m^-3' 144 | 'mol/m^3' 145 | 'part/L' 146 | 'part.L^-1' 147 | 'part.m^-3' 148 | 'part/m^3' 149 150 <cross-section> ::= 'cross_sections:' 151 <abs-cross-sections> 152 <abs-cross-sections> ::= 'abs_cross_sec:' <prop-file> \\ 153 <spec-unit> \\ 154 <cross-sec-unit> 155 156 <spec-unit> ::= 'nm' 157 | 'cm' 158 | 'm' 159 | 'cm^-1' # wavenumber (1/wavelength) 160 | '1/cm' 161 162 <cross-sec-unit> ::= # must match the <concentration-unit> 163 | 'm^2/kg' 164 | 'm^2.kg^-1' 165 | 'm^2/mol' 166 | 'm^2.mol^-1' 167 | 'm^2/part' 168 | 'm^2.part^-1' 169 170 <refractive_index> ::= 'refractive_index:' 171 ['n_real:' <prop-file>] 172 ['n_imag:' <prop-file>] 173 174 <brdf> ::= 'brdf:' <brdf-type> <reflectivity> 175 <brdf-type> ::= 'LAMBERT' | 'SPECULAR' 176 <reflectivity> ::= 'FRESNEL_DIELECTRIC' # both media are considered 177 # dielectric 178 | 'FRESNEL_DIELECTRIC_CONDUCTOR' 179 | <prop-file> # Values in [0, 1] 180 181 <btdf> ::= 'btdf:' <btdf-type> <transmissivity> 182 <btdf-type> ::= 'LAMBERT' | 'KEEP_CURRENT_DIR' | 'SNELL_DIELECTRIC' 183 <transmissivity> ::= 'FRESNEL_DIELECTRIC' # both media are considered 184 # dielectric 185 | 'FRESNEL_DIELECTRIC_CONDUCTOR' 186 | <prop-file> # Values in [0, 1] 187 188 <surface-source> ::= 'source:' 189 'flux_density:' <flux-val> \\ 190 <flux-unit> \\ 191 <prop-file> \\ 192 <spec-unit> \\ 193 <spec-pdf-unit> 194 'direction:' <direction-distrib> 195 <flux-val> ::= real # Flux density value > 0 196 <flux-unit> ::= 'mol/m^2/s' 197 | 'mol.m^-2.s^-1' 198 | 'umol/m^2/s' 199 | 'umol.m^-2.s^-1' 200 | 'mW/m^2' 201 | 'mW.m^-2' 202 | 'W/m^2' 203 | 'W.m^-2' 204 | 'J.m^-2.s^-1' 205 | 'J/m^2/s' 206 <spec-pdf-unit> ::= 'nm^-1' 207 208 <direction-distrib> ::= <lambert> | <collim> | <cos_pow_n> 209 <lambert> ::= 'LAMBERT' 210 <collim> ::= 'COLLIM' 'NORMAL' 211 <cos_pow_n> ::= 'COS_POW_N' <collimation-degree> 212 <collimation-degree> ::= real # Collimation degree > 0 213 214 <direction> ::= '['real',' real',' real']' 215 <prop-file> ::= path # no spaces allowed 216 <comment> ::= '#' string 217 <name> ::= '"'string'"' 218 ``` 219 220 # EXAMPLES 221 222 1. The example below describes a simple photoreactive system composed of a cube, 223 in which only absorption takes place. The volume and surface are composed by 224 several .stl files each. In the following example, the top and the bottom 225 surface of the cube are light sources, which emit light with a defined flux 226 density (total flux 200e-6 mol/m^2/s), with a spectrum defined in 227 "spectrum.txt". Emission directions follow a Lambertian distribution. The 228 volume of the cube is defined as the union of these two surfaces with the side 229 walls. Absorption is due to the specie "chemical 1", with a concentration of 1 230 mol/m^3, and whose absorption cross section is provided in the file 231 "sigma_a.txt" in m^2/mol for wavelengths in nm. Here, the volume of the cube is 232 defined as a sensor, with a unit response function, enabling for instance to 233 compute the number of photons absorbed within the cube per second. Note 234 that no BRDF or BTDF is defined to the "light sources" surface. In such 235 case, photons do not interact with the surface. 236 237 ``` 238 # +-------------------+ 239 # /| /| 240 # / | source / | 241 # / | / | \\ / | 242 # / | v v v / | 243 # / | / | 244 # +-------------------+ | 245 # | | | | 246 # | | | | 247 # | +-------------|-----+ 248 # | / | / 249 # | / ^ ^ ^ | / 250 # | / \\ | / | / 251 # | / source | / 252 # |/ |/ 253 # +-------------------+ 254 255 volume: "reaction volume" 256 geometry: FRONT cube_top.stl 257 geometry: FRONT cube_bottom.stl 258 geometry: FRONT cube_walls.stl 259 prop_rad: "chemical 1" 260 scatterer: 261 concentration: 1 mol/m^3 262 cross_sections: 263 abs_cross_sec: sigma_a.txt nm m^2/mol 264 sensor: 265 response_function: 1 266 267 surface: "light sources" 268 geometry: FRONT cube_top.stl 269 geometry: FRONT cube_bottom.stl 270 source: 271 flux_density: 200e-6 mol/m^2/s spectrum.txt nm nm^-1 272 direction: LAMBERT 273 ``` 274 275 2. A LED panel emits light with a defined flux density (total flux 200e-6 276 mol/m^2/s), with a spectrum defined in "spectrum.txt". Emission directions 277 follow a Lambertian distribution. Here, the volume of the cube is defined as a 278 sensor, with a unit response function, enabling for instance to compute the 279 number of photons absorbed within the cube per second. Cube walls have the 280 relectivity and transmissivity properties defined by the Fresnel and 281 Snell-Descartes models. The 'reaction volume' medium has a real, spectral 282 refractive index defined in 'refractive_index_medium.txt'. Note that the real 283 part of the refractive index is implicitely considered 1 when not defined (for 284 instance, in the exterior medium in this example). The imaginary part of the 285 refractive index is implicitely considered to be 0 when not defined, like in the 286 present case. 287 288 ``` 289 # + +-------------------+ 290 # /| /| /| 291 # / | / | / | 292 # / | / | / | 293 # / | / | / | 294 # / | / | / | 295 # + | +-------------------+ | 296 # | LED | | | | | 297 # | | | | | | 298 # | + | +-------------|-----+ 299 # | / | / | / 300 # | / | / | / 301 # | / | / | / 302 # | / | / | / 303 # |/ |/ |/ 304 # + +-------------------+ 305 306 volume: "reaction volume" 307 geometry: FRONT cube.stl 308 prop_rad: "chemical 1" 309 scatterer: 310 concentration: 1 mol/m^3 311 cross_sections: 312 abs_cross_sec: sigma_a.txt nm m^2/mol 313 refractive_index: 314 n_real: refractive_index_medium.txt 315 sensor: 316 response_function: 1 317 318 surface: "cube walls" 319 geometry: BACK cube.stl 320 geometry: FRONT cube.stl 321 brdf: SPECULAR FRESNEL_DIELECTRIC 322 btdf: SNELL_DIELECTRIC FRESNEL_DIELECTRIC 323 324 surface: "led panel" 325 geometry: FRONT led_panel.stl mm 326 source: 327 flux_density: 200e-6 mol/m^2/s spectrum.txt nm nm^-1 328 direction: COLLIM NORMAL 329 ``` 330 331 3. A surface in which both sides have the same properties. Note that 332 this same syntax is not allowed when the surface is also a source. Such 333 case is treated in example 4. 334 335 ``` 336 surface: "reflecting base" 337 geometry: FRONT base.stl 338 geometry: BACK base.stl 339 brdf: SPECULAR reflectivity.txt 340 ``` 341 342 4. The example below describes the case in which both sides of a same surface 343 emit. Since both sides are composed by the same set of triangles, each side of 344 the geometry has to be entered as a separated source in order to ensure that the 345 total flux of the source is properly computed. 346 347 ``` 348 # The front side of the source 349 surface: "light source front" 350 geometry: FRONT light_source.stl 351 source: 352 flux_density: 200e-6 mol/m^2/s spectrum.txt nm nm^-1 353 direction: LAMBERT 354 355 # The back side of the source 356 surface: "light source back" 357 geometry: BACK light_source.stl 358 source: 359 flux_density: 1 umol/m^2/s spectrum.txt nm nm^-1 360 direction: LAMBERT 361 ``` 362 363 # SEE ALSO 364 _sphin_(3), _sphin-lint_(1) 365 366 https://en.wikipedia.org/wiki/Backus-Naur_form 367 368 Marshall Burns, _The StL Format: Standard Data Format for Fabbers_, 369 https://www.fabbers.com/tech/STL_Format, 1993. 370 371 # HISTORY 372 373 *star-phor-input* has been developed thanks to the funding of the ECOCHEM 374 project (ProjetIA-22-PESP-0006) belonging to the *PEPR SPLEEN*.