commit 6fe52fb5e5171088d647dabe6f13d66824a90817
parent 48d5d94b5f5afc8f47e3b8b71eca12cc3685bb36
Author: Eduardo Fontana Lazzari <edufonlaz@gmail.com>
Date: Tue, 24 Feb 2026 11:41:51 +0100
Add manual page for the output file specification
Create the star-phor-output manual page in section 5, describing the
syntax used in the output file.
Diffstat:
3 files changed, 107 insertions(+), 2 deletions(-)
diff --git a/.gitignore b/.gitignore
@@ -12,6 +12,7 @@ tags
input
output
star-phor.1
+star-phor-output.5
star-phor
test_*
!test*.[ch]
diff --git a/Makefile b/Makefile
@@ -81,7 +81,7 @@ $(LIBNAME): $(OBJ_LIB)
clean: clean_test clean_executable
rm -f $(DEP_LIB) $(OBJ_LIB) $(LIBNAME)
- rm -f .config sphor-local.pc sphor.pc star-phor.1
+ rm -f .config sphor-local.pc sphor.pc star-phor.1 star-phor-output.5
################################################################################
# Executable building
@@ -133,6 +133,9 @@ pkg:
star-phor.1: doc/star-phor.scd
scdoc < doc/star-phor.scd > $@
+star-phor-output.5: doc/star-phor-output.scd
+ scdoc < doc/star-phor-output.scd > $@
+
sphor-local.pc: sphor.pc.in
sed -e '1d'\
-e 's#^includedir=.*#includedir=./src/#'\
@@ -141,7 +144,7 @@ sphor-local.pc: sphor.pc.in
-e 's#@SPHIN_VERSION@#$(SPHIN_VERSION)#g'\
sphor.pc.in > $@
-install: library pkg star-phor.1
+install: library pkg star-phor.1 star-phor-output.5
install() { mode="$$1"; prefix="$$2"; shift 2; \
mkdir -p "$${prefix}"; \
cp "$$@" "$${prefix}"; \
@@ -152,6 +155,7 @@ install: library pkg star-phor.1
install 644 "$(DESTDIR)$(LIBPREFIX)/pkgconfig" sphor.pc; \
install 644 "$(DESTDIR)$(INCPREFIX)/star" src/sphor.h; \
install 644 "$(DESTDIR)$(MANPREFIX)/man1" star-phor.1; \
+ install 644 "$(DESTDIR)$(MANPREFIX)/man5" star-phor-output.5; \
install 644 "$(DESTDIR)$(PREFIX)/share/doc/star-phor" COPYING; \
install 644 "$(DESTDIR)$(PREFIX)/share/doc/star-phor" README.md
diff --git a/doc/star-phor-output.scd b/doc/star-phor-output.scd
@@ -0,0 +1,100 @@
+star-phor-input(5) "UNIX"
+
+; Copyright (C) 2024-2026 Centre National de la Recherche Scientifique
+; Copyright (C) 2024-2026 Clermont Auvergne INP
+; Copyright (C) 2024-2026 INSA Lyon
+; Copyright (C) 2024-2026 Institut Mines Télécom Albi-Carmaux
+; Copyright (C) 2024-2026 Institut National Polytechnique de Toulouse
+; Copyright (C) 2024-2026 |Méso|Star> (contact@meso-star.com)
+; Copyright (C) 2024-2026 PhotonLyX (info@photonlyx.com)
+; Copyright (C) 2024-2026 Université de Lorraine
+; Copyright (C) 2024-2026 Université Paul Sabatier
+; Copyright (C) 2024-2026 Université Toulouse - Jean Jaurès
+;
+; This program is free software: you can redistribute it and/or modify
+; it under the terms of the GNU General Public License as published by
+; the Free Software Foundation, either version 3 of the License, or
+; (at your option) any later version.
+;
+; This program is distributed in the hope that it will be useful,
+; but WITHOUT ANY WARRANTY; without even the implied warranty of
+; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+; GNU General Public License for more details.
+;
+; You should have received a copy of the GNU General Public License
+; along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+# NAME
+
+star-phor-output - file format specification for *star-phor* results.
+
+# DESCRIPTION
+
+The output of the *star-phor*(1) program consists of a list of observable
+estimators. Each estimator is described on a separate line.
+
+*star-phor* outputs are closely related to the *star-phor-input*(5) file that
+generated the simulation. For each sensor defined in the input file, star-phor
+writes a set of output values at different levels: per-volume sensor mean
+volumetric rate of energy absorption (MVREA); per radiative property MVREA
+within each specified volume; and per-sensor surface LOSSES.
+
+In addition, the total estimate of each observable (MVREA or LOSSES), combining
+all sensors of a given type, is also provided.
+
+# GRAMMAR
+
+This sections outlines the *star-phor* output files specification syntax using
+the Backus-Naur notation system.
+
+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:
+
+```
+<star-phor-output> ::= <observable-output>
+ ...
+
+<observable-output> ::= <combined-estimator>
+ <per-sensor-estimators>
+ [<per-component-estimators>]
+
+<combined-estimator> ::= <observable>:\\
+ <expected-value>:\\
+ <standard-deviation>
+
+<per-sensor-estimators> ::= <observable>:\\
+ <sensor-name>:\\
+ <expected-value>:\\
+ <standard-deviation>
+ ...
+
+<per-component-estimators> ::= <observable>:\\
+ <sensor-name>:\\
+ <component-name>:\\
+ <expected-value>:\\
+ <standard-deviation>
+ ...
+
+<observable-name> ::= MVREA | LOSSES
+<sensor-name> ::= <volume-name> | <surface-name>
+<volume-name> ::= 'string'
+<surface-name> ::= 'string'
+<component-name> ::= 'string'
+<expected-value> ::= 'real'
+<standard-deviation> ::= 'real'
+```
+
+# EXAMPLES
+
+# SEE ALSO
+_star-phor_(1), _sphin-lint_(1), _star-phor-input_(5)
+
+https://en.wikipedia.org/wiki/Backus-Naur_form
+
+# HISTORY
+
+*star-phor* has been developed thanks to the funding of the ECOCHEM
+project (ProjetIA-22-PESP-0006) belonging to the *PEPR SPLEEN*.
