commit 99262a9e677704740d9fecc65522d330f3560b57
parent 6393ee7a0d0488de0a349422b7774d2e7f8da569
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Thu, 29 Jan 2026 11:43:30 +0100
Write the manual page for the sln-build tool.
This is actually its functional specification. But the tool has not yet
been implemented. That is the next step.
Diffstat:
| M | Makefile | | | 3 | +++ |
| A | doc/sln-build.1 | | | 173 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
2 files changed, 176 insertions(+), 0 deletions(-)
diff --git a/Makefile b/Makefile
@@ -125,6 +125,9 @@ clean: clean_test
rm -f $(OBJ) $(DEP) $(LIBNAME)
rm -f .config libsln.o sln.pc sln-local.pc
+lint:
+ mandoc -Tlint -Wwarning doc/sln-build.1
+
################################################################################
# Tests
################################################################################
diff --git a/doc/sln-build.1 b/doc/sln-build.1
@@ -0,0 +1,173 @@
+.\" Copyright (C) 2022, 2026 |Méso|Star> (contact@meso-star.com)
+.\" Copyright (C) 2026 Université de Lorraine
+.\" Copyright (C) 2022 Centre National de la Recherche Scientifique
+.\" Copyright (C) 2022 Université Paul Sabatier
+.\"
+.\" 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/>.
+.Dd January 29, 2026
+.Dt SLN-BUILD 1
+.Os
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh NAME
+.Nm sln-build
+.Nd build an acceleration structure for line importance sampling
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SYNOPSIS
+.Nm
+.Op Fl hsv
+.Op Fl e Ar polyline_opt Ns Op : Ns Ar polyline_opt No ...
+.Op Fl o Ar accel_struct
+.Fl P Ar pressure
+.Fl T Ar temperature
+.Fl m Ar molparams
+.Fl x Ar mixture
+.Op Ar lines
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh DESCRIPTION
+.Nm
+constructs a data structure designed to accelerate the sampling by
+importance of the spectral lines defined for a gas mixture under given
+thermodynamic conditions, from a spectroscopic parameters database.
+The generated structure is a binary tree that stores a polyline of
+spectral data at each node that it encompasses.
+.Pp
+The input spectroscopic data, i.e., the line list and isotopological
+metadata, are formatted in HITRAN file formats.
+If not provided, the list of lines is read from standard input.
+.Pp
+The options are as follows:
+.\""""""""""""""""""""""""""""""""""
+.Bl -tag -width Ds
+.It Fl e Ar polyline_opt Ns Op : Ns Ar polyline_opt No ...
+Configure the polylines, i.e., the data used to encode the shape of the
+spectrum in the acceleration structure.
+.Pp
+The polyline options are as follows:
+.Bl -tag -width Ds
+.It Cm err= Ns Ar decimation_error
+Relative error used to simplifly polylines.
+The larger it is, the coarser the polylines obtained, and therefore the
+less memory it uses.
+The default value is 0.01.
+.It Cm mesh= Ns Ar mesh_type
+Define how the polylines are meshed.
+.Pp
+The supported
+.Ar mesh_type
+values are as follows:
+.Bl -tag -width Ds
+.It Cm fit
+The polylines fit the spectrum data.
+.It Cm upper
+The polylines define an upper limit for the spectrum they encode.
+This is the default behavior.
+.El
+.It Cm vcount= Ns Ar vertex_count_hint
+Recommendation for the number of vertices around the center of the line.
+The fewer vertices there are, the coarser the polyline of a line and the
+smaller the memory usage.
+The default value is 16.
+.El
+.It Fl h
+Display short help and exit.
+.\""""""""""""""""""""""""""""""""""
+.It Fl o Ar accel_struct
+Output file.
+If not defined, the acceleration structure is written to standard output.
+.\""""""""""""""""""""""""""""""""""
+.It Fl P Ar pressure
+Pressure of the gaz mixture, in atmospheres
+.Pq 1 atm = 1.01315 bar .
+.\""""""""""""""""""""""""""""""""""
+.It Fl s
+Specifies that input lines are formatted according to the binary format
+as written by the
+.Xr shtr 1
+utility, and not according to the HITRAN format.
+This format is more compact, allowing for faster loading of line data.
+.\""""""""""""""""""""""""""""""""""
+.It Fl T Ar temperature
+Temperature of the gaz mixture, in Kelvin.
+.\""""""""""""""""""""""""""""""""""
+.It Fl m Ar molparams
+Isotopologue metadata in HITRAN format.
+.\""""""""""""""""""""""""""""""""""
+.It Fl v
+Make
+.Nm
+verbose.
+Multiple
+.Fl v
+options increase the verbosity.
+The maximum is 3.
+.\""""""""""""""""""""""""""""""""""
+.It Fl x Ar mixture
+Composition of the gaz mixture in
+.Xr sln-mixture 5
+format.
+If a molecule is absent from this file, its concentration in the mixture
+is assumed to be zero.
+.El
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh EXIT STATUS
+.Ex -std
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh EXAMPLES
+Build a structure that accelerates importance sampling of the lines in
+the H2O spectrum, between 0 and 50 cm^-1, at a pressure of 1 atm and a
+temperature of 292 K.
+Use the default options to mesh the spectrum, so that the resulting
+structure represents an upper bound on the spectral data:
+.Bd -literal -offset Ds
+sln-build -P 1 -T 292 -o H2O_0-50_HITAMP2010_tree.bin \e
+ -m /path/to/hitran/molparams.txt -x mixture.txt \e
+ /path/to/hitran//H2O/01_0-50_HITEMP2010.par
+.Ed
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SEE ALSO
+.Xr shtr 1 ,
+.Xr sln-mixture 5
+.Rs
+.%A Yaniss Nyffenegger-Péré et al.
+.%T Spectrally refined unbiased monte carlo estimate of the earth's \
+global radiative cooling
+.%J Proceedings of the National Academy of Sciences
+.%P e2315492121
+.%V 121
+.%N 5
+.%D 2024
+.Re
+.Rs
+.%T The HITRAN Database
+.%U https://hitran.org/
+.Re
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh STANDARDS
+.Rs
+.%A L.S. Rothman et al.
+.%T The HITRAN2012 molecular spectroscopic database
+.%J Journal of Quantitative Spectroscopy & Radiative Transfer
+.%V 130
+.%P pp. 4\(en50
+.%D 2013
+.Re
+.Pp
+.Rs
+.%A L.S. Rothman et al.
+.%T HITEMP, the high-temperature molecular spectroscopic database
+.%J Journal of Quantitative Spectroscopu & Radiative Transfer
+.%V 111
+.%P pp. 2139\(en2150
+.%D 2010
+.Re
