commit c53f6bdc0173f9b6854d23c9bdeaea844e0f7502
parent a11b2c9fc07611307154bda29e3af42ea1a2935b
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Tue, 14 Jun 2022 14:31:58 +0200
Write the man page
Diffstat:
| A | doc/sars.5.scd | | | 97 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 97 insertions(+), 0 deletions(-)
diff --git a/doc/sars.5.scd b/doc/sars.5.scd
@@ -0,0 +1,97 @@
+sck(5)
+
+; Copyright (C) 2022 |Meso|Star> (contact@meso-star.com)
+;
+; 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
+
+sars - Star AeoRoSol file format
+
+# DESCRIPTION
+
+*sars* is a binary file format for storing the radiative properties of an
+aerosol. The volumetric mesh to which the CKs are attached is _not_ described
+there but must be defined in a separated file via, for example, the *smsh*(5)
+file format.
+
+An *sars* file begins by a header that describes the layout of the data. Next
+the spectral bands on which the radiative coefficients were defined are listed.
+Finally, the entire list of the scattering coefficients and absorption
+coefficients are stored.
+
+The header consists of 3 64-bit integers. The first integer is a power of two
+(usually 4096) that defines the _pagesize_ in bytes on which the radiative
+coefficients are aligned. The remaining two integers store the number of bands
+and the number of nodes, that is, the number of radiative coefficients per band
+which is actually the number of nodes in the volumetric mesh to which these
+coefficients are attached.
+
+After the header comes the list of spectral bands sorted in ascending order
+relative to their interval. Each spectral band is defined by 2 double-precision
+floating-point numbers that represent the lower and upper limits of the band in
+nanometers.
+
+Fill bytes follow the list of spectral bands to ensure alignment of the
+radiative coefficients on _pagesize_. By aligning data on _pagesize_, and
+depending on system requirements, memory mapping can be used to automatically
+load/unload the radiative coefficients on demand (see *mmap*(2)). For each band,
+the diffusion coefficients are then listed before the list of absorption
+coefficients. Each list is followed by a _padding_, which is a list of bytes
+that provides memory alignment of the following data to _pagesize_. Bands are
+sorted according to the order in which they were previously declared.
+
+
+# BINARY FILE FORMAT
+
+Data are encoded with respect to the little endian bytes ordering, i.e. least
+significant bytes are stored first.
+
+```
+<ars> ::= <pagesize> <#bands> <#nodes>
+ <bands>
+ <padding>
+ <rad-coefs>
+
+<pagesize> ::= UINT64
+<#bands> ::= UINT64
+<#nodes> ::= UINT64
+<padding> ::= [ BYTE ... ] #ensure alignment on <pagesize>
+
+---
+
+<band-list> ::= <band> [ <band> ... ]
+<band> ::= <band-low> <band-upp>
+
+<band-id> ::= UINT64
+<band-low> ::= DOUBLE # In nm
+<band-upp> ::= DOUBLE # In nm
+
+---
+
+<rad-coefs> ::= <per-band-k>
+ [ <per-band-k> ... ]
+
+<per-band-k> ::= <ks-list>
+ <ka-list>
+
+<ka-list> ::= <ka> [ <ka> ... ] <padding>
+<ks-list> ::= <ks> [ <ks> ... ] <padding>
+<ka> ::= FLOAT # in m^-1
+<ks> ::= FLOAT # in m^-1
+```
+
+# SEE ALSO
+
+*mmap*(2), *smsh*(5)
