commit dd33e21ca7d871b7b44542a329d9816947b19be1
parent 603d9bc5ff49bcdb0e0b819088d2a279be0e6f29
Author: Eduardo Fontana Lazzari <edufonlaz@gmail.com>
Date: Fri, 23 Jan 2026 12:42:29 +0100
Documentation: refine and standardize
This commit updates the documentation following revisions by multiple
proofreaders. Examples have been updated to match the latest configuration
specification, and the deprecated `ka` entries have been removed.
Overall formatting has also been improved.
Diffstat:
2 files changed, 160 insertions(+), 136 deletions(-)
diff --git a/doc/sphin.scd b/doc/sphin.scd
@@ -69,5 +69,5 @@ _star-phor-input_(5)
# HISTORY
-*star-phor-input* has been developed as part of the *PEPR SPLEEN* Ecochem
-project.
+*star-phor-input* has been developed thanks to the funding of the ECOCHEM
+project (ProjetIA-22-PESP-0006) belonging to the *PEPR SPLEEN*.
diff --git a/doc/star-phor-input.scd b/doc/star-phor-input.scd
@@ -26,32 +26,33 @@ star-phor-input(5) "UNIX"
# NAME
-star-phor-input - photoreactive system description files
+star-phor-input - photoreactor configuration files
# DESCRIPTION
-A photoreactive system description consists of a list of surfaces and volumes.
-Each of these elements is defined by a set of properties, which may represent
-either geometrical characteristics or physical properties. The only supported
-geometrical data format is the triangular mesh stored in STL files. 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 is the side from which
-its vertices appear arranged in counter-clockwise order. Its vertices appear
-arranged in counter-clockwise order. Geometries can be decomposed into multiple
-files (see example 2). Both the front and back sides of a given triangle may
-belong to the same surface or volume (see example 1), except when the volume or
-surface also acts as a source (see example 3). The geometry (or set of
-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.
+A *star-phor-input* photoreactor description consists of a list of surfaces and
+volumes. Each of these elements is defined by a set of properties, which may
+represent either geometrical characteristics or physical properties. The only
+supported geometrical data format is the triangular mesh stored in STL files.
+Geometries are composed of one keyword (`FRONT' or `BACK') and by an STL file.
+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* is the side from which its vertices appear arranged in
+counter-clockwise order. Its vertices appear arranged in counter-clockwise
+order. Geometries can be decomposed into multiple files (see example 2). Both
+the front and back sides of a given triangle may belong to the same surface or
+volume (see example 1), except when the volume or surface also acts as a source
+(see example 3). 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.
Properties are specified either as a single-line entry or as a multi-line block,
where each line corresponds to a distinct property.
-Single-line properties are declared using the "key: value" syntax. No additional
-content other than comments is allowed after the value. Both the key and the
-value must appear on the same line. The colon (:) character is reserved as a
-separator in the input file and therefore cannot be used in the names of
+Single-line properties are declared using the "keyword: value" syntax. No
+additional content other than comments is allowed after the value. Both the key
+and the value must appear on the same line. The colon (:) character is reserved
+as a separator in the input file and therefore cannot be used in the names of
volumes, surfaces, or prop_rad elements.
The star-phor-input format does not enforce a specific order for property
@@ -67,125 +68,140 @@ tabs, spaces, or combinations of both are used, they will be ignored.
# GRAMMAR
-Please note that in the following lines, the percent symbol (%) is used to
-introduce a comment in the file format description. It should not be taken into
-account when writing these files, nor should anything that comes after it.
+This sections outlines the *star-phor-input* configuration files syntax using
+the Backus-Naur notation system.
-Text enclosed in single quotation marks (') must be included in the entry as is,
-with the exception of single quotation marks.
+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.
-The file format describing a photoreactive system is as follows:
+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>
- | <geometry>
- | <sensor>
- | <surface-source>
-
-<geometry> ::= 'geometry:' <side> <geom-file> [<geom-unit>]
-<side> ::= 'FRONT' | 'BACK'
-<geom-file> ::= path % STL files only
- % Spaces not allowed
-<geom-unit> ::= 'm' % if no unit is specified,
- | 'cm' % meter is assumed
- | 'mm'
- | 'km'
-
-<sensor> ::= 'sensor:'
- 'response_function:' real
-
-
-<prop-rad> ::= 'prop_rad:' <name> <prop-rad-type>
- <concentration>
- <cross-sections>
-
-<prop-rad-type> ::= 'SCATTERER'
-
-<concentration> ::= 'concentration:' real <concentration-unit> % conc > 0
-<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> ::= %TODO
-<cross-sec-unit> ::= % should be compatible with 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> ::= real % In [0, 1]
-
-<surface-source> ::= 'source:'
- 'flux_density:' <flux-val> <flux-unit> <prop-file> <spec-unit> %TODO <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'
-
-<direction-distrib> ::= <lambert> | <collim> | <cos_pow_n>
-<lambert> ::= 'LAMBERT'
-<collim> ::= 'COLLIM' 'NORMAL' | <direction>
-<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'"'
+<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>
+ | <geometry>
+ | <sensor>
+ | <surface-source>
+
+<geometry> ::= 'geometry:' <side> <geom-file> [<geom-unit>]
+<side> ::= 'FRONT' | 'BACK'
+<geom-file> ::= path # STL files only
+ # Spaces not allowed
+
+<geom-unit> ::= 'm' # if no unit is specified,
+ | 'cm' # meter is assumed
+ | 'mm'
+ | 'km'
+
+<sensor> ::= 'sensor:'
+ 'response_function:' real
+
+<prop-rad> ::= 'prop_rad:' <name> <prop-rad-type>
+ <concentration>
+ <cross-sections>
+<prop-rad-type> ::= 'SCATTERER'
+
+<concentration> ::= 'concentration:' real <concentration-unit> # conc > 0
+<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' # assumes wavenumber (1/wavelength) is used
+ | '1/cm'
+
+<cross-sec-unit> ::= # should be compatible with 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> ::= real # 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 absorption takes place. Tube walls have diffuse reflectivity. A LED
-panel emits light with a defined flux density, and a surface base reflects light
-with specular reflectivity.
+in which only absorption takes place. Cube walls have diffuse reflectivity. A
+LED panel emits light with a defined flux density, and a surface base reflects
+light with specular reflectivity.
```
# Keyword name
volume: "reaction volume"
geometry: FRONT cube.stl
- ka: 1 m^-1 # lineic absorption coefficient
+ 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
@@ -199,7 +215,7 @@ surface: "led panel"
geometry: FRONT led_panel.stl mm
brdf: LAMBERT 0
source:
- flux_density: 200e-6 mol/m^2/s
+ flux_density: 200e-6 mol/m^2/s spectrum.txt nm nm^-1
direction: COLLIM NORMAL
# A surface in which both sides have the same properties.
@@ -212,8 +228,8 @@ surface: "reflecting base"
brdf: SPECULAR 0.9
```
-2. The example below describes a volume and a source surface composed by several
-.stl files.
+2. The example below describes a volume and a surface source composed by several
+.stl files each.
```
# Keyword name
@@ -221,7 +237,10 @@ volume: "reaction volume"
geometry: FRONT cube_top.stl
geometry: FRONT cube_bottom.stl
geometry: FRONT cube_walls.stl
- ka: 1 m^-1
+ 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
@@ -230,7 +249,7 @@ surface: "light sources"
geometry: FRONT cube_top.stl
geometry: FRONT cube_bottom.stl
source:
- flux_density: 200e-6 mol/m^2/s
+ flux_density: 200e-6 mol/m^2/s spectrum.txt nm nm^-1
direction: LAMBERT
```
@@ -243,7 +262,10 @@ total flux of the source is properly computed.
# Keyword name
volume: "reaction volume"
geometry: FRONT reaction_volume.stl
- ka: 1 m^-1
+ 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
@@ -255,7 +277,7 @@ volume: "reaction volume"
surface: "light source front"
geometry: FRONT light_source.stl
source:
- flux_density: 200e-6 mol/m^2/s
+ flux_density: 200e-6 mol/m^2/s spectrum.txt nm nm^-1
direction: LAMBERT
# The back side of the source
@@ -263,7 +285,7 @@ surface: "light source front"
surface: "light source back"
geometry: BACK light_source.stl
source:
- flux_density: 200e-6 mol/m^2/s
+ flux_density: 1 umol/m^2/s spectrum.txt nm nm^-1
direction: LAMBERT
```
@@ -271,10 +293,12 @@ surface: "light source back"
_sphin_(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 as part of the *PEPR SPLEEN* Ecochem
-project.
+*star-phor-input* has been developed thanks to the funding of the ECOCHEM
+project (ProjetIA-22-PESP-0006) belonging to the *PEPR SPLEEN*.
