commit 2b2cc5340fe3815ceead018d5fed1e91ef89b7fa
parent ceda1f093bce8ca07861f661c86067b40febb55b
Author: Eduardo Fontana Lazzari <edufonlaz@gmail.com>
Date: Mon, 6 Apr 2026 17:41:56 +0200
Improve style and fix typos in man pages and README
Special thanks to Dr. K. Loubiere for the suggestions.
Diffstat:
3 files changed, 86 insertions(+), 81 deletions(-)
diff --git a/README.md b/README.md
@@ -1,15 +1,16 @@
# star-phor-input
**star-phor-input** is a file format convention for describing photoreactor
-configurations in photoreactive system engineering. It comes with a dedicated C
-library and a linter. The star-phor-input file format specification is used as
-the input for the star-phor solver, which depends on the sphin library.
+configurations in the field of photoreactive system engineering. It comes with a
+dedicated C library and a linter. The star-phor-input file format specification
+is used as the input for the star-phor solver, which depends on the sphin
+library.
**sphin** is a C library designed to parse star-phor-input configuration files
-and access the associated data. Thanks to an unstructured scene description, the
-memory representation is independent of any specific numerical method used to
-solve the system. This makes the library solver-agnostic while still providing
-all necessary geometries and physical properties for computation.
+and to access the associated data. Thanks to an unstructured scene description,
+the memory representation is independent of any specific numerical method used
+to solve the system. This makes the library solver-agnostic while still
+providing all necessary geometries and physical properties for computation.
**sphin-lint** is an executable that flags syntactic errors, bugs, stylistic
issues, and suspicious constructs in star-phor-input configuration files.
@@ -19,8 +20,8 @@ issues, and suspicious constructs in star-phor-input configuration files.
- POSIX make
- C compiler (C99)
- pkg-config
-- [RSys](https://gitlab.com/vaplv/rsys/)
-- [star-stl](https://gitlab.com/meso-star/star-stl/)
+- [RSys](https://meso-star.com/git/rsys/log.html)
+- [star-stl](https://meso-star.com/git/star-stl/log.html)
- scdoc
## Installation
diff --git a/doc/sphin.3.scd.in b/doc/sphin.3.scd.in
@@ -37,34 +37,30 @@ sphin - sphin library definitions
The *sphin* C library provides functions to parse, load and expose data of a
photoreactive system as described in the *star-phor-input*(5) file format.
-It provides a unified data representation that abstract original format used
-to saved data on disk.
-For example, geometries are all stored in a consistent structure - primarly
-using one-dimensional arrays - regardless of their original file format.
+It provides a unified data representation that abstract original format used to
+save data on disk. For example, geometries are all stored in a consistent
+structure - primarly using one-dimensional arrays - regardless of their original
+file format.
Once loaded, the data is intended to be independent of any specific numerical
-method.
-In other words, the library is designed to be independent of a solver but
-nevertheless aims to provide all the data (geometric and physical) necessary for
-a numerical simulation.
-The data is thus said to be unstructured with regard to a resolution method.
-A deterministic solver would therefore be responsible for meshing the
-integration domains, while a statistical solver would have to build structures
-capable of accelerating random access to the system data.
+method. In other words, the library is designed to be independent of a solver
+but nevertheless aims to provide all the data (geometric and physical) necessary
+for a numerical simulation. The data is thus said to be unstructured with regard
+to a resolution method. A deterministic solver would therefore be responsible
+for meshing the integration domains, while a statistical solver would have to
+build structures capable of accelerating random access to the system data.
-The library's dynamic memory management is based on reference counting.
-Each API object allocated by the library has a reference counter, initialized
-when it is created: the caller is therefore the owner.
-The caller can then obtain other references or release them as needed.
-However, other dynamically allocated API objects can also obtain additional
-references to the API objects on which they depend and which they need
-throughout their lifetime.
-An object is effectively released once all its references have been released,
-either by the caller or by the other objects that depend on it.
-Thus, unlike a manual allocation/deallocation policy, the caller can release the
-references it holds without having to worry about the order of release;
-the actual deallocation of an object only occurs once all references have been
-released.
+The library's dynamic memory management is based on reference counting. Each API
+object allocated by the library has a reference counter, initialized when it is
+created: the caller is therefore the owner. The caller can then obtain other
+references or release them as needed. However, other dynamically allocated API
+objects can also obtain additional references to the API objects on which they
+depend and which they need throughout their lifetime. An object is effectively
+released once all its references have been released, either by the caller or by
+the other objects that depend on it. Thus, unlike a manual
+allocation/deallocation policy, the caller can release the references it holds
+without having to worry about the order of release; the actual deallocation of
+an object only occurs once all references have been released.
There is currently no manual page documenting the API of the *sphin* library.
Users are therefore invited to consult its header *@INCPREFIX@/sphin.h* as the
@@ -76,5 +72,5 @@ _star-phor-input_(5), _sphin-lint_(1)
# HISTORY
-The *sphin* library been developed thanks to the funding of the ECOCHEM
+The *sphin* library 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.5.scd b/doc/star-phor-input.5.scd
@@ -31,30 +31,32 @@ 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 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.
+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 property.
-
-Single-line properties are declared using the "keyword: value" syntax. No
-additional content other than comments is allowed after the value. Note that the
-value can refer to a file. 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.
+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
@@ -177,7 +179,7 @@ The syntax rules enabling the description of a photoreactor are as follows:
| <prop-file> # Values in [0, 1]
<btdf> ::= 'btdf:' <btdf-type> <transmissivity>
-<btdf-type> ::= 'LAMBERT' | 'KEEP_CURRENT_DIR' | 'SNELL_DIELECTRIC'
+<btdf-type> ::= 'LAMBERT' | 'KEEP_CURRENT_DIR' | 'SNELL_DIELECTRIC'
<transmissivity> ::= 'FRESNEL_DIELECTRIC' # both media are considered
# dielectric
| 'FRESNEL_DIELECTRIC_CONDUCTOR'
@@ -224,11 +226,13 @@ 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
+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.
+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.
```
# +-------------------+
@@ -268,13 +272,18 @@ surface: "light sources"
direction: LAMBERT
```
-2. Cube walls have a reflectivity of 10%, with a diffuse (Lambertian)
-distribution. 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. The surface base reflects light
-with specular reflectivity of 0.9. Here, the volume of the cube is defined as a
+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.
+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.
```
# + +-------------------+
@@ -296,37 +305,41 @@ number of photons absorbed within the cube per second.
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
+ 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
- brdf: LAMBERT 0.1 # OPTIQUE GEOMETRIQUE
+ geometry: FRONT cube.stl
+ brdf: SPECULAR FRESNEL_DIELECTRIC
+ btdf: SNELL_DIELECTRIC FRESNEL_DIELECTRIC
surface: "led panel"
geometry: FRONT led_panel.stl mm
- brdf: LAMBERT 0
source:
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. Note that
+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 ?.
+case is treated in example 4.
```
surface: "reflecting base"
geometry: FRONT base.stl
geometry: BACK base.stl
- brdf: SPECULAR 0.9
+ brdf: SPECULAR reflectivity.txt
```
-3. The example below describes the case in which both sides of a same surface
+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.
@@ -347,11 +360,6 @@ surface: "light source back"
direction: LAMBERT
```
-?. On peut aussi décorer en deux temps
-
-LAMBERTAN
-
-
# SEE ALSO
_sphin_(3), _sphin-lint_(1)
