| star-phor-input(5) | File Formats Manual | star-phor-input(5) |
NAME
star-phor-input - file format describing a photoreactor configuration
DESCRIPTION
A star-phor-input photoreactor description consists of a list of surfaces and volumes. Each element is defined by a set of properties representing either geometrical characteristics or physical properties.
Properties are specified either as a single-line entry or as a multi-line block, where each line corresponds to a distinct attribute of the property being defined. Single-line properties are declared using the '<keyword>: <value>' syntax (both the keyword and the value must appear in the same line). No additional content other than comments is allowed after the value. 'volumes', 'surfaces' and 'prop_rads' are multi-line properties and declared using the '<keyword>: <name>' syntax. Note that the colon (:) character is reserved as a separator in the input file and therefore cannot be used in volumes, surfaces, or prop_rad names. All the others multi-line properties are declared with the '<keyword>:' syntax.
The only supported geometrical data format is the triangular mesh. Geometries are composed of one keyword ('FRONT' or 'BACK') and by a STL filepath. Triangles in STL files are assumed to follow the right-hand rule convention to determine their orientation; that is, the 'FRONT' face of a triangle in the star-phor-input convention is the side from which its vertices appear arranged in counterclockwise order. Geometries can be decomposed into multiple files (see example 1). Both the FRONT and BACK sides of a given triangle may belong to the same surface or volume (see examples 2 and 3), except in the particular case where the surface also acts as a source (see example 4). The geometry (or set of elementary geometries) associated with a volume must form a closed enclosure to ensure that every part of the system domain consists of a single medium with consistent properties.
The star-phor-input format does not enforce a specific order for property declarations. However, when encountering a keyword that does not belong to the current parsing scope, the parser will move up one hierarchy level. Consequently, all properties within the same scope must be declared together within the same block; otherwise, an exception will be raised and the parsing will be stopped.
Indentation of any type is not mandatory for lower hierarchy blocks. Keywords in the format file must be separated by at least one tab or space. If multiple tabs, spaces, or combinations of both are used, they will be ignored.
GRAMMAR
This sections outlines the star-phor-input configuration files syntax using the Backus-Naur notation system.
The hash symbol (#) is used to indicate a comment. In the configuration file, it marks lines or line portions that are comments and are therefore ignored by the parser. In this document, the same symbol is also used to comment the format description itself. In both cases, the # character and everything that follows it on the same line must be ignored and should not be included in the actual configuration file.
Some lines end with a backslash (\). This allows the description to continue on the next line for formatting purposes. However, this trick cannot be used in description files, and actual description lines must remain on a single line.
The syntax rules enabling the description of a photoreactor are as follows:
<photoreactive-system> ::= <element> | <comment>
...
<element> ::= <volume> | <surface>
<volume> ::= 'volume:' <name>
[<volume-props> ...]
<volume-props> ::= <geometry>
| <sensor>
| <prop-rad>
<surface> ::= 'surface:' <name>
[<surface-props> ...]
<surface-props> ::= <brdf>
| <btdf>
| <geometry>
| <sensor>
| <surface-source>
<geometry> ::= geometry:' <side> \
<geom-file> [<geom-unit>]
<side> ::= 'FRONT' | 'BACK'
<geom-file> ::= path # STL files only
# Spaces are not allowed
<geom-unit> ::= 'm' # Default unit
| 'cm'
| 'mm'
| 'km'
<sensor> ::= 'sensor:'
'response_function:' real
<prop-rad> ::= 'prop_rad:' <name>
<prop-rad-spec>
<prop-rad-spec> ::= <scatterer>
<scatterer> ::= 'scatterer:'
<concentration>
<cross-sections>
<concentration> ::= 'concentration:' real \
<concentration-unit>
<concentration-unit> ::= 'kg/L'
| 'kg.L^-1'
| 'kg.m^-3'
| 'kg/m^3'
| 'mol/L'
| 'mol.L^-1'
| 'mol.m^-3'
| 'mol/m^3'
| 'part/L'
| 'part.L^-1'
| 'part.m^-3'
| 'part/m^3'
<cross-section> ::= 'cross_sections:'
<abs-cross-sections>
<abs-cross-sections> ::= 'abs_cross_sec:' <prop-file> \
<spec-unit> \
<cross-sec-unit>
<spec-unit> ::= 'nm'
| 'cm'
| 'm'
| 'cm^-1' # wavenumber (1/wavelength)
| '1/cm'
<cross-sec-unit> ::= # must match the <concentration-unit>
| 'm^2/kg'
| 'm^2.kg^-1'
| 'm^2/mol'
| 'm^2.mol^-1'
| 'm^2/part'
| 'm^2.part^-1'
<refractive_index> ::= 'refractive_index:'
['n_real:' <prop-file>]
['n_imag:' <prop-file>]
<brdf> ::= 'brdf:' <brdf-type> <reflectivity>
<brdf-type> ::= 'LAMBERT' | 'SPECULAR'
<reflectivity> ::= 'FRESNEL_DIELECTRIC' # both media are considered
# dielectric
| 'FRESNEL_DIELECTRIC_CONDUCTOR'
| <prop-file> # Values in [0, 1]
<btdf> ::= 'btdf:' <btdf-type> <transmissivity>
<btdf-type> ::= 'LAMBERT' | 'KEEP_CURRENT_DIR' | 'SNELL_DIELECTRIC'
<transmissivity> ::= 'FRESNEL_DIELECTRIC' # both media are considered
# dielectric
| 'FRESNEL_DIELECTRIC_CONDUCTOR'
| <prop-file> # Values in [0, 1]
<surface-source> ::= 'source:'
'flux_density:' <flux-val> \
<flux-unit> \
<prop-file> \
<spec-unit> \
<spec-pdf-unit>
'direction:' <direction-distrib>
<flux-val> ::= real # Flux density value > 0
<flux-unit> ::= 'mol/m^2/s'
| 'mol.m^-2.s^-1'
| 'umol/m^2/s'
| 'umol.m^-2.s^-1'
| 'mW/m^2'
| 'mW.m^-2'
| 'W/m^2'
| 'W.m^-2'
| 'J.m^-2.s^-1'
| 'J/m^2/s'
<spec-pdf-unit> ::= 'nm^-1'
<direction-distrib> ::= <lambert> | <collim> | <cos_pow_n>
<lambert> ::= 'LAMBERT'
<collim> ::= 'COLLIM' 'NORMAL'
<cos_pow_n> ::= 'COS_POW_N' <collimation-degree>
<collimation-degree> ::= real # Collimation degree > 0
<direction> ::= '['real',' real',' real']'
<prop-file> ::= path # no spaces allowed
<comment> ::= '#' string
<name> ::= '"'string'"'
EXAMPLES
1. The example below describes a simple photoreactive system composed of a cube, in which only absorption takes place. The volume and surface are composed by several .stl files each. In the following example, the top and the bottom surface of the cube are light sources, which emit light with a defined flux density (total flux 200e-6 mol/m^2/s), with a spectrum defined in "spectrum.txt". Emission directions follow a Lambertian distribution. The volume of the cube is defined as the union of these two surfaces with the side walls. Absorption is due to the specie "chemical 1", with a concentration of 1 mol/m^3, and whose absorption cross section is provided in the file "sigma_a.txt" in m^2/mol for wavelengths in nm. Here, the volume of the cube is defined as a sensor, with a unit response function, enabling for instance to compute the number of photons absorbed within the cube per second. Note that no BRDF or BTDF is defined to the "light sources" surface. In such case, photons do not interact with the surface.
# +-------------------+
# /| /|
# / | source / |
# / | / | \ / |
# / | v v v / |
# / | / |
# +-------------------+ |
# | | | |
# | | | |
# | +-------------|-----+
# | / | /
# | / ^ ^ ^ | /
# | / \ | / | /
# | / source | /
# |/ |/
# +-------------------+
volume: "reaction volume"
geometry: FRONT cube_top.stl
geometry: FRONT cube_bottom.stl
geometry: FRONT cube_walls.stl
prop_rad: "chemical 1"
scatterer:
concentration: 1 mol/m^3
cross_sections:
abs_cross_sec: sigma_a.txt nm m^2/mol
sensor:
response_function: 1
surface: "light sources"
geometry: FRONT cube_top.stl
geometry: FRONT cube_bottom.stl
source:
flux_density: 200e-6 mol/m^2/s spectrum.txt nm nm^-1
direction: LAMBERT
2. A LED panel emits light with a defined flux density (total flux 200e-6 mol/m^2/s), with a spectrum defined in "spectrum.txt". Emission directions follow a Lambertian distribution. Here, the volume of the cube is defined as a sensor, with a unit response function, enabling for instance to compute the number of photons absorbed within the cube per second. Cube walls have the relectivity and transmissivity properties defined by the Fresnel and Snell-Descartes models. The 'reaction volume' medium has a real, spectral refractive index defined in 'refractive_index_medium.txt'. Note that the real part of the refractive index is implicitely considered 1 when not defined (for instance, in the exterior medium in this example). The imaginary part of the refractive index is implicitely considered to be 0 when not defined, like in the present case.
# + +-------------------+
# /| /| /|
# / | / | / |
# / | / | / |
# / | / | / |
# / | / | / |
# + | +-------------------+ |
# | LED | | | | |
# | | | | | |
# | + | +-------------|-----+
# | / | / | /
# | / | / | /
# | / | / | /
# | / | / | /
# |/ |/ |/
# + +-------------------+
volume: "reaction volume"
geometry: FRONT cube.stl
prop_rad: "chemical 1"
scatterer:
concentration: 1 mol/m^3
cross_sections:
abs_cross_sec: sigma_a.txt nm m^2/mol
refractive_index:
n_real: refractive_index_medium.txt
sensor:
response_function: 1
surface: "cube walls"
geometry: BACK cube.stl
geometry: FRONT cube.stl
brdf: SPECULAR FRESNEL_DIELECTRIC
btdf: SNELL_DIELECTRIC FRESNEL_DIELECTRIC
surface: "led panel"
geometry: FRONT led_panel.stl mm
source:
flux_density: 200e-6 mol/m^2/s spectrum.txt nm nm^-1
direction: COLLIM NORMAL
3. A surface in which both sides have the same properties. Note that this same syntax is not allowed when the surface is also a source. Such case is treated in example 4.
surface: "reflecting base" geometry: FRONT base.stl geometry: BACK base.stl brdf: SPECULAR reflectivity.txt
4. The example below describes the case in which both sides of a same surface emit. Since both sides are composed by the same set of triangles, each side of the geometry has to be entered as a separated source in order to ensure that the total flux of the source is properly computed.
# The front side of the source
surface: "light source front"
geometry: FRONT light_source.stl
source:
flux_density: 200e-6 mol/m^2/s spectrum.txt nm nm^-1
direction: LAMBERT
# The back side of the source
surface: "light source back"
geometry: BACK light_source.stl
source:
flux_density: 1 umol/m^2/s spectrum.txt nm nm^-1
direction: LAMBERT
SEE ALSO
sphin(3), sphin-lint(1)
https://en.wikipedia.org/wiki/Backus-Naur_form
Marshall Burns, The StL Format: Standard Data Format for Fabbers, https://www.fabbers.com/tech/STL_Format, 1993.
HISTORY
star-phor-input has been developed thanks to the funding of the ECOCHEM project (ProjetIA-22-PESP-0006) belonging to the PEPR SPLEEN.
| 2026-04-15 | UNIX |