solstice-pp

commit 57b1ae59ad893b8b9561c62265f68c18ff728f7c
parent 691e5bd1efaa745b35b5c5fcd9836faf54dd3e14
Author: Christophe Coustet <christophe.coustet@meso-star.com>
Date:   Fri, 26 Jun 2026 14:58:38 +0200

Add man pages.

Diffstat:
M
Makefile
 | 
28
++++++++++++++++++++++++----
A
doc/solmaps.1
 | 
111
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
A
doc/solpaths.1
 | 
103
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
A
doc/solpp.1
 | 
142
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
A
doc/solppraw.1
 | 
96
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

5 files changed, 476 insertions(+), 4 deletions(-)
diff --git a/Makefile b/Makefile
@@ -23,14 +23,34 @@ PROG =\
   solppraw \
   solpaths
 
+MAN = \
+  doc/solmaps.1 \
+  doc/solpp.1 \
+  doc/solpaths.1 \
+  doc/solppraw.1
+
 PROJECTS = themis cyl
 
 default: $(PROG)
 
-install: $(PROG)
-	mkdir -p $(DESTDIR)$(PREFIX)/bin
-	cp $(PROG) $(DESTDIR)$(PREFIX)/bin
-	for i in $(PROG); do chmod 755 "$(DESTDIR)$(PREFIX)/bin/$${i}"; done
+install: $(PROG) $(MAN)
+	install() { mode="$$1"; prefix="$$2"; shift 2; \
+	  mkdir -p "$${prefix}"; \
+	  cp "$$@" "$${prefix}"; \
+	  chmod "$${mode}" "$${prefix}/$${@##*/}"; \
+	}; \
+	install 644 "$(DESTDIR)$(PREFIX)/share/doc/solstice-pp" COPYING; \
+	install 644 "$(DESTDIR)$(PREFIX)/share/doc/solstice-pp" README.md; \
+	for i in $(PROG); \
+	  do install 755 "$(DESTDIR)$(PREFIX)/bin" $${i}; done; \
+	for i in $(MAN); \
+	  do install 644 "$(DESTDIR)$(PREFIX)/share/man/man1" $${i}; done;
+
+uninstall:
+	rm -f "$(DESTDIR)$(PREFIX)/share/doc/solstice-pp/COPYING"
+	rm -f "$(DESTDIR)$(PREFIX)/share/doc/solstice-pp/README.md"
+	for i in $(PROG); do rm -f "$(DESTDIR)$(PREFIX)/bin/$${i}"; done
+	for i in $(MAN); do rm -f "$(DESTDIR)$(PREFIX)/share/man/man1/$${i##*/}"; done
 
 .PHONY: clean
 clean:
diff --git a/doc/solmaps.1 b/doc/solmaps.1
@@ -0,0 +1,111 @@
+.\" SPDX-License-Identifier: GPL-3.0-or-later
+.\" Copyright (C) 2018-2026 |Méso|Star> (contact@meso-star.com)
+.\"
+.\" This is free documentation: 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 manual 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/>.
+.Dd $Mdocdate$
+.Dt SOLMAPS 1
+.Os
+.Sh NAME
+.Nm solmaps
+.Nd extract and save receiver flux maps from Solstice results
+.Sh SYNOPSIS
+.Nm
+.Op Ar file
+.Sh DESCRIPTION
+.Nm
+reads the results of a
+.Xr solstice 1
+simulation from
+.Ar file
+or from standard input whether a filename is provided as an argument or not,
+respectively.
+It extracts the maps of incoming flux computed by
+.Xr solstice 1
+for the receivers whose
+.Cm per_primitive
+flag is enabled.
+Refer to
+.Xr solstice-receiver 5
+for more information.
+Each map is then saved in a separate
+.Tn VTK
+file that can be visualised and analysed in a data
+visualisation tool such as
+.Lk https://www.paraview.org ParaView .
+.Pp
+The naming scheme for the output files depends on the way the sun direction was
+provided to
+.Xr solstice 1 :
+.Bl -dash
+.It
+using the
+.Fl D Ar azimuth,elevation
+flag: the output file is named after the following pattern:
+.Bd -literal -offset indent
+printf "%g-%g-%s.vtk" azimuth elevation receiver_name
+.Ed
+.It
+using the
+.Fl L Ar latitude,longitude
+and
+.Fl T Ar time
+flags: the output file is named after the following pattern:
+.Bd -literal -offset indent
+printf "%g-%g-%s-%s.vtk" latitude longitude time receiver_name
+.Ed
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+Pipe
+.Xr solstice 1
+with
+.Nm
+to extract the flux maps of the receivers for each provided sun direction:
+.Bd -literal -offset indent
+solstice -D45,70 -D50,75 -R rcvs.yaml input.yaml | solmaps
+.Ed
+.Pp
+First, invoke
+.Xr solstice 1
+to write the results to
+.Pa output ,
+then run
+.Nm
+on this file to extract the flux maps of the receivers for the provided sun
+direction:
+.Bd -literal -offset indent
+solstice -L3,40 -T"2026-08-15T17:20:00" -R rcvs.yaml -o output input.yaml
+solmaps output
+.Ed
+.Sh SEE ALSO
+.Xr solpaths 1 ,
+.Xr solpp 1 ,
+.Xr solppraw 1 ,
+.Xr solstice 1 ,
+.Xr solstice-output 5 ,
+.Xr solstice-receiver 5
+.Sh HISTORY
+.Nm
+was initially developed with funding from the
+.Em SOLSTICE LabEx
+.Pq Laboratory of Excellence ,
+in collaboration with the PROMES Laboratory of the
+French National Centre for Scientific Research
+.Pq CNRS .
+Starting in 2026, a new development effort funded by Ademe is ongoing.
+.Sh AUTHORS
+.Nm
+was written and is maintained by
+.An |M\['e]so|Star> Aq Mt contact@meso-star.com .
diff --git a/doc/solpaths.1 b/doc/solpaths.1
@@ -0,0 +1,103 @@
+.\" SPDX-License-Identifier: GPL-3.0-or-later
+.\" Copyright (C) 2018-2026 |Méso|Star> (contact@meso-star.com)
+.\"
+.\" This is free documentation: 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 manual 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/>.
+.Dd $Mdocdate$
+.Dt SOLPATHS 1
+.Os
+.Sh NAME
+.Nm solpaths
+.Nd convert Solstice radiative paths to VTK files
+.Sh SYNOPSIS
+.Nm
+.Op Ar file
+.Sh DESCRIPTION
+.Nm
+reads the radiative paths dumped by
+.Xr solstice 1
+when invoked with the
+.Fl p
+option, from
+.Ar file
+or from standard input whether a filename is provided as an argument or not,
+respectively.
+For each simulated sun direction, it generates a
+.Tn VTK
+file of the radiative paths, that can be visualised and analysed in a data
+visualisation tool such as
+.Lk https://www.paraview.org ParaView .
+.Pp
+The naming scheme for the output files depends on the way the sun direction was
+provided to
+.Xr solstice 1 :
+.Bl -dash
+.It
+using the
+.Fl D Ar azimuth,elevation
+flag: the output file is named after the following pattern:
+.Bd -literal -offset indent
+printf "%g-%g-paths.vtk" azimuth elevation
+.Ed
+.It
+using the
+.Fl L Ar latitude,longitude
+and
+.Fl T Ar time
+flags: the output file is named after the following pattern:
+.Bd -literal -offset indent
+printf "%g-%g-%s-paths.vtk" latitude longitude time
+.Ed
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+Pipe
+.Xr solstice 1
+with
+.Nm
+to extract the radiative paths for each provided sun direction:
+.Bd -literal -offset indent
+solstice -n100 -D45,70 -D50,75 -R rcvs.yaml -p default input.yaml | solpaths
+.Ed
+.Pp
+First, invoke
+.Xr solstice 1
+to write the results to
+.Pa output ,
+then run
+.Nm
+on this file to extract the radiative paths for the provided sun direction:
+.Bd -literal -offset indent
+solstice -L3,40 -T"2026-08-15T17:20:00" -R rcvs.yaml -p default -o output input.yaml
+solpaths output
+.Ed
+.Sh SEE ALSO
+.Xr solmaps 1 ,
+.Xr solpp 1 ,
+.Xr solppraw 1 ,
+.Xr solstice 1 ,
+.Xr solstice-output 5
+.Sh HISTORY
+.Nm
+was initially developed with funding from the
+.Em SOLSTICE LabEx
+.Pq Laboratory of Excellence ,
+in collaboration with the PROMES Laboratory of the
+French National Centre for Scientific Research
+.Pq CNRS .
+Starting in 2026, a new development effort funded by Ademe is ongoing.
+.Sh AUTHORS
+.Nm
+was written and is maintained by
+.An |M\['e]so|Star> Aq Mt contact@meso-star.com .
diff --git a/doc/solpp.1 b/doc/solpp.1
@@ -0,0 +1,142 @@
+.\" SPDX-License-Identifier: GPL-3.0-or-later
+.\" Copyright (C) 2018-2026 |Méso|Star> (contact@meso-star.com)
+.\"
+.\" This is free documentation: 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 manual 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/>.
+.Dd $Mdocdate$
+.Dt SOLPP 1
+.Os
+.Sh NAME
+.Nm solpp
+.Nd post-process Solstice simulation results into VTK and OBJ files
+.Sh SYNOPSIS
+.Nm
+.Ar geom
+.Ar simul
+.Sh DESCRIPTION
+.Nm
+takes two input files:
+.Ar geom ,
+the geometry of a solar plant exported by
+.Xr solstice 1
+when invoked with the
+.Fl g
+option, and
+.Ar simul ,
+the results of a
+.Xr solstice 1
+simulation.
+For each simulated sun direction,
+.Nm
+writes up to three output files.
+.Pp
+The first output file is a
+.Tn VTK
+file that maps the simulation results to the meshes of the primary
+geometries, i.e.\& the reflectors.
+The mapped results include, for instance, the cosine factor of each
+reflector or the amount of flux that reaches a receiver from them.
+.Pp
+The second output file is another
+.Tn VTK
+file that stores the geometry of the receivers together with their
+simulation results, such as their incoming flux or their efficiency.
+.Pp
+The optional third output file is an
+.Tn OBJ
+file that stores the meshes of the miscellaneous geometries, i.e.\& the
+geometries that are neither receivers nor primary geometries (if any).
+.Pp
+The resulting files can be visualised and analysed in a data
+visualisation tool such as
+.Lk https://www.paraview.org ParaView .
+.Pp
+Where
+.Va end
+stands for
+.Pa primaries.vtk ,
+.Pa receivers.vtk ,
+or
+.Pa miscellaneous.obj
+for the 1st, 2nd, and optional 3rd output file respectively, the naming scheme
+for the output files depends on the way the sun direction was provided to
+.Xr solstice 1 :
+.Bl -dash
+.It
+using the
+.Fl D Ar azimuth,elevation
+flag: the output file is named after the following pattern:
+.Bd -literal -offset indent
+printf "%g-%g-%s" azimuth elevation end
+.Ed
+.It
+using the
+.Fl L Ar latitude,longitude
+and
+.Fl T Ar time
+flags: the output file is named after the following pattern:
+.Bd -literal -offset indent
+printf "%g-%g-%s-%s" latitude longitude time end
+.Ed
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+Invoke
+.Xr solstice 1
+to simulate two sun directions on the solar plant described in
+.Pa input.yaml .
+Then invoke it again to export the geometry of the solar plant for the same sun
+directions.
+Finally, post-process both outputs with
+.Nm :
+.Bd -literal -offset indent
+solstice -D45,70 -D50,75 -R rcvs.yaml -o simul input.yaml
+solstice -D45,70 -D50,75 -g format=obj -o geom input.yaml
+solpp geom simul
+.Ed
+.Pp
+Invoke
+.Xr solstice 1
+to simulate a sun direction defined by a location and a time on the solar plant
+described in
+.Pa input.yaml .
+Then invoke it again to export the geometry of the solar plant for the same sun
+direction.
+Finally, post-process both outputs with
+.Nm :
+.Bd -literal -offset indent
+solstice -L3,40 -T"2026-08-15T17:20:00" -R rcvs.yaml -o simul input.yaml
+solstice -L3,40 -T"2026-08-15T17:20:00" -g format=obj -o geom input.yaml
+solpp geom simul
+.Ed
+.Sh SEE ALSO
+.Xr solmaps 1 ,
+.Xr solpaths 1 ,
+.Xr solppraw 1 ,
+.Xr solstice 1 ,
+.Xr solstice-output 5 ,
+.Xr solstice-receiver 5
+.Sh HISTORY
+.Nm
+was initially developed with funding from the
+.Em SOLSTICE LabEx
+.Pq Laboratory of Excellence ,
+in collaboration with the PROMES Laboratory of the
+French National Centre for Scientific Research
+.Pq CNRS .
+Starting in 2026, a new development effort funded by Ademe is ongoing.
+.Sh AUTHORS
+.Nm
+was written and is maintained by
+.An |M\['e]so|Star> Aq Mt contact@meso-star.com .
diff --git a/doc/solppraw.1 b/doc/solppraw.1
@@ -0,0 +1,96 @@
+.\" SPDX-License-Identifier: GPL-3.0-or-later
+.\" Copyright (C) 2018-2026 |Méso|Star> (contact@meso-star.com)
+.\"
+.\" This is free documentation: 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 manual 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/>.
+.Dd $Mdocdate$
+.Dt SOLPPRAW 1
+.Os
+.Sh NAME
+.Nm solppraw
+.Nd format raw Solstice results into human readable text
+.Sh SYNOPSIS
+.Nm
+.Op Ar file
+.Sh DESCRIPTION
+.Nm
+reads the
+.Xr solstice 1
+outputs from
+.Ar file
+or from standard input whether a filename is provided as an argument or not,
+respectively.
+For each simulated sun direction, it formats the raw results into a human
+readable text file, simplifying the analysis of the results.
+.Pp
+The naming scheme for the output files depends on the way the sun direction was
+provided to
+.Xr solstice 1 :
+.Bl -dash
+.It
+using the
+.Fl D Ar azimuth,elevation
+flag: the output file is named after the following pattern:
+.Bd -literal -offset indent
+printf "%g-%g-raw-results.txt" azimuth elevation
+.Ed
+.It
+using the
+.Fl L Ar latitude,longitude
+and
+.Fl T Ar time
+flags: the output file is named after the following pattern:
+.Bd -literal -offset indent
+printf "%g-%g-%s-results.txt" latitude longitude time
+.Ed
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+Invoke
+.Xr solstice 1
+to simulate two sun directions and pipe the results directly to
+.Nm ,
+without any intermediary file:
+.Bd -literal -offset indent
+solstice -D45,70 -D50,75 -R rcvs.yaml input.yaml | solppraw
+.Ed
+.Pp
+Alternatively, invoke
+.Xr solstice 1
+to simulate a sun direction and write the results to the
+.Pa output
+file, then post-process it with solppraw:
+.Bd -literal -offset indent
+solstice -L3,40 -T"2026-08-15T17:20:00" -R rcvs.yaml -o output input.yaml
+solppraw output
+.Ed
+.Sh SEE ALSO
+.Xr solmaps 1 ,
+.Xr solpaths 1 ,
+.Xr solpp 1 ,
+.Xr solstice 1 ,
+.Xr solstice-output 5
+.Sh HISTORY
+.Nm
+was initially developed with funding from the
+.Em SOLSTICE LabEx
+.Pq Laboratory of Excellence ,
+in collaboration with the PROMES Laboratory of the
+French National Centre for Scientific Research
+.Pq CNRS .
+Starting in 2026, a new development effort funded by Ademe is ongoing.
+.Sh AUTHORS
+.Nm
+was written and is maintained by
+.An |M\['e]so|Star> Aq Mt contact@meso-star.com .