star-phor-input

commit 254245548bf10afa57c81074d5de8586f0c755de
parent ce320942390ef32c9928e218514c135c59cbae34
Author: Eduardo Fontana Lazzari <edufonlaz@gmail.com>
Date:   Wed,  9 Jul 2025 18:47:10 +0200

Extend documentation

When declaring surface sources, it is not allowed to declare the same
triangle as emitting on both sides. Doing so can lead to inconsistencies
when relating the total power of a source to its power density. This
limitation is now explicitly documented.

Additionally, examples illustrating the chosen conventions are added to
make the documentation more clear and illustrative.

Diffstat:
M
doc/star-phor-input.scd
 | 
76
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------

1 file changed, 69 insertions(+), 7 deletions(-)
diff --git a/doc/star-phor-input.scd b/doc/star-phor-input.scd
@@ -36,15 +36,19 @@ 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. 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.
+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.
 
 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
+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.
 
@@ -142,7 +146,7 @@ The file format describing a photoreactive system is as follows:
 
 # EXAMPLES
 
-The example below describes a simple photoreactive system composed of a cube, in
+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.
@@ -156,7 +160,7 @@ volume: "reaction volume"
     response_function: 1
 
 # Keyword name
-surface: "tube walls"
+surface: "cube walls"
   geometry: BACK cube.stl
   brdf: LAMBERT 0.1
 
@@ -168,12 +172,70 @@ surface: "led panel"
     flux_density: 200e-6 mol/m^2/s
     direction: COLLIM NORMAL
 
+# 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 3.
 # Keyword name
 surface: "reflecting base"
   geometry: FRONT base.stl
+  geometry: BACK base.stl
   brdf: SPECULAR 0.9
 ```
 
+2. The example below describes a volume and a source surface composed by several .stl files.
+
+```
+# Keyword name
+volume: "reaction volume"
+  geometry: FRONT cube_top.stl
+  geometry: FRONT cube_bottom.stl
+  geometry: FRONT cube_walls.stl
+  ka: 1 m^-1
+  sensor:
+    response_function: 1
+
+# Keyword name
+surface: "light sources"
+  geometry: FRONT cube_top.stl
+  geometry: FRONT cube_bottom.stl
+  source:
+    flux_density: 200e-6 mol/m^2/s
+    direction: LAMBERT
+```
+
+3. 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.
+
+```
+# Keyword name
+volume: "reaction volume"
+  geometry: FRONT reaction_volume.stl
+  ka: 1 m^-1
+  sensor:
+    response_function: 1
+
+# If both sides of a same geometry are emitting surfaces, they have to be
+# entered as separeted surfaces, even if the source properties are identical.
+
+# The front side of the source
+# Keyword name
+surface: "light source front"
+  geometry: FRONT light_source.stl
+  source:
+    flux_density: 200e-6 mol/m^2/s
+    direction: LAMBERT
+
+# The back side of the source
+# Keyword name
+surface: "light source back"
+  geometry: BACK light_source.stl
+  source:
+    flux_density: 200e-6 mol/m^2/s
+    direction: LAMBERT
+```
+
 # SEE ALSO
 
 _sphin_(1)