commit 7d41b6c42c46e3bd1a4bd59ee66cf841501b0679
parent 74503ba38a7397b5bf3413f1fbd9a3662caa2c8b
Author: Eduardo Fontana Lazzari <edufonlaz@gmail.com>
Date: Fri, 21 Mar 2025 17:24:39 +0100
Add doc for input file
Diffstat:
2 files changed, 132 insertions(+), 0 deletions(-)
diff --git a/.gitignore b/.gitignore
@@ -8,6 +8,7 @@ file.txt
*.swp
*.stl
tags
+star-phor-input.5
test_sphin
test_sphin_load_geometry
test_sphin_load_source
diff --git a/doc/star-phor-input.scd b/doc/star-phor-input.scd
@@ -0,0 +1,131 @@
+star-phor-input(5)
+
+# NAME
+star-phor-input - photoreactive system description 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. The geometry
+(or the 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.++
+++
+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 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
+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.++
+++
+The file format describing a photoreactive system is as follows:++
+++
+<photoreactive-system> ::= <element> | <comment>++
+ ...++
+<element> ::= <volume> | <surface>++
+++
+<volume> ::= *volume*: <string> [<comment>]++
+ <ka> [<comment>]++
+ <geometry> [<comment>]++
+ [<geometry>] [<comment>]++
+ ...++
+ [<sensor>]++
+++
+<surface> ::= *surface*: <string> [<comment>]++
+ <brdf> [<comment>]++
+ <geometry> [<comment>]++
+ [<geometry>] [<comment>]++
+ ...++
+ [<sensor>]++
+ [<surface-source>]++
+++
+<geometry> ::= *geometry:* <geometry-side> <geometry-filename>++
+<geometry-side> ::= *FRONT* | *BACK*++
+<geometry-filename> ::= path % STL files only; spaces not allowed ++
+++
+<sensor> ::= *sensor:* [<comment>]++
+ *response_function:* real++
+++
+<ka> ::= *ka:* real <ka-unit> % ka > 0++
+<ka-unit> ::= *cm^-1* | *1/cm* | *mm^-1* | *1/mm* | *m^-1* | *1/m*++
+++
+<brdf> ::= *brdf:* <brdf-type> <reflectivity>++
+<brdf-type> ::= *LAMBERT* | *SPECULAR*++
+<reflectivity> ::= real % In [0, 1]++
+++
+<surface-source> ::= *source:* [<comment>]++
+ *flux_density:* <flux-density-value> <flux-density-unit>++
+ *direction:* <direction-distribution>++
+++
+<flux-density-value> ::= real % Flux density value > 0++
+<flux-density-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-distribution> ::= <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*]*++
+<comment> ::= *#* string
+# EXAMPLES
+
+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.++
+++
+ # Keyword name++
+ volume: "reaction volume"++
+ geometry: FRONT cube.stl++
+ ka: 1 m^-1 # lineic absorption coefficient++
+ sensor:++
+ response_function: 1++
+ ++
+ # Keyword name++
+ surface: "tube walls"++
+ geometry: BACK cube.stl++
+ brdf: LAMBERT 0.1++
+ ++
+ # Keyword name++
+ surface: "led panel"++
+ geometry: FRONT led_panel.stl mm++
+ brdf: LAMBERT 0++
+ source:++
+ flux_density: 200e-6 mol/m^2/s++
+ direction: COLLIM NORMAL++
+ ++
+ # Keyword name++
+ surface: "reflecting base"++
+ geometry: FRONT base.stl++
+ brdf: SPECULAR 0.9++
+++
+# SEE ALSO
+
