commit 6987976c813f315dc45dd3339d27d0f1b5b27de7
parent b6dbe4a5315a584c816a08dd199aca3f375c0226
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Wed, 14 Apr 2021 17:26:45 +0200
Write the atrck man page
Diffstat:
3 files changed, 135 insertions(+), 37 deletions(-)
diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
@@ -86,6 +86,29 @@ if(NOT NO_TEST)
endif()
################################################################################
+# Man page
+###############################################################################
+find_program(A2X NAMES a2x a2x.py)
+if(NOT A2X)
+ message(WARNING
+ "The `a2x' program is missing. "
+ "The atrck man page cannot be generated.")
+else()
+ set(_src ${PROJECT_SOURCE_DIR}/../doc/atrck.5.txt)
+ set(_txt ${CMAKE_CURRENT_BINARY_DIR}/atrck.5.txt)
+ add_custom_command(
+ OUTPUT atrck.5
+ COMMAND ${CMAKE_COMMAND} -E copy ${_src} ${_txt}
+ COMMAND ${A2X} -dmanpage -fmanpage ${_txt}
+ DEPENDS ${_src}
+ WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+ COMMENT "Buid ROFF man page atrck.5"
+ VERBATIM)
+ add_custom_target(man-roff ALL DEPENDS atrck.5)
+ install(FILES ${CMAKE_CURRENT_BINARY_DIR}/atrck.5 DESTINATION share/man/man5)
+endif()
+
+################################################################################
# Define output & install directories
################################################################################
install(TARGETS atrck
diff --git a/doc/atrck b/doc/atrck
@@ -1,37 +0,0 @@
-<atrck> ::= <pagesize> <#bands> <#nodes>
- <bands-list>
- <padding>
- <meshes-list>
-
-<pagesize> ::= INT64
-<#bands> ::= INT64
-<#nodes> ::= INT64
-<padding> ::= [ BYTE ... ] #ensure alignment on <pagesize>
-
----
-
-<bands-list> ::= <band> [ <band> ... ]
-<band> ::= <band-id> <band-low> <band-upp> <#quad-pts>
- <quad-pts-list>
-
-<band-id> ::= INT64
-<band-low> ::= DOUBLE
-<band-upp> ::= DOUBLE
-<#quad-pts> ::= INT64
-
----
-
-<quad-pts-list> ::= <quad-pt> [ <quad-pt> ... ]
-<quad-pt> ::= <quad-abscissa> <quad-weight>
-
-<quad-abscissa> ::= DOUBLE
-<quad-weight> ::= DOUBLE
-
----
-
-<meshes-list> ::= <ka-list>
- <padding>
- [ <ka-list> ... ]
-<ka-list> ::= <ka> [ <ka> ... ]
-<ka> ::= FLOAT
-
diff --git a/doc/atrck.5.txt b/doc/atrck.5.txt
@@ -0,0 +1,112 @@
+// Copyright (C) 2020, 2021 CNRS
+//
+// 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/>.
+:toc:
+
+atrck(5)
+=======
+
+NAME
+----
+atrck - AsToRia: Correlated K
+
+DESCRIPTION
+-----------
+
+*atrck* is a binary file format for storing the correlated K of a gas mixture.
+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 *sth*(5) file
+format.
+
+An *atrck* file begins by a header that describes its data layout. Next the
+spectral bands on which the CKs were evaluated are listed. Finally, the entire
+list of CKs are stored.
+
+The header is made up of 3 64-bit integers. The first integer is a power of
+two (usually 4096) that defines the _<pagesize>_ in bytes to which the per
+quadrature point CKs are aligned. The two remaining integers store
+respectively the number of bands and the number of nodes, i.e. the number of
+CKs per quadrature point which is in fact the number of vertices of the
+volumetric mesh to which the K are mapped.
+
+After the header comes the list of spectral bands sorted in ascending order
+with respect to their spectral interval. Each spectral band begins with a
+unique identifier stored on a 64-bit signed integer. Then 2 double precision
+floating point numbers store the lower and upper limit of the band in
+nanometers. Another 64-bit signed integer then gives the number of quadrature
+points in the band. Finally the band's quadrature points are listed where each
+point is in fact 2 double precision floating numbers: the first gives its
+abscissa and the second its weight.
+
+Padding bytes follow the list of spectral bands to ensure alignment of the CK
+to _<pagesize>_.
+
+Then CKs are listed as a set of _<ka-list>_ each consisting of _<#nodes>_
+single precision floating point numbers per list. Each _<ka-list>_ is followed
+by pad bytes to ensure the alignment of the next list to _<pagesize>_. A
+_<ka-list>_ is in fact the list of the absorption coefficients of a given
+quadrature point in a specific spectral band. These lists are sorted according
+to the order of the aforementioned spectral bands and their associated
+quadrature points.
+
+BINARY FILE FORMAT
+------------------
+
+Data are encoded with respect to the little endian bytes ordering, i.e. least
+significant bytes are stored first.
+
+[verse]
+-------
+<atrck> ::= <pagesize> <#bands> <#nodes>
+ <bands-list>
+ <padding>
+ <meshes-list>
+
+<pagesize> ::= INT64
+<#bands> ::= INT64
+<#nodes> ::= INT64
+<padding> ::= [ BYTE ... ] #ensure alignment on <pagesize>
+
+---
+
+<bands-list> ::= <band> [ <band> ... ]
+<band> ::= <band-id> <band-low> <band-upp> <#quad-pts>
+ <quad-pts-list>
+
+<band-id> ::= INT64
+<band-low> ::= DOUBLE # In nm
+<band-upp> ::= DOUBLE # In nù
+<#quad-pts> ::= INT64
+
+---
+
+<quad-pts-list> ::= <quad-pt> [ <quad-pt> ... ]
+<quad-pt> ::= <quad-abscissa> <quad-weight>
+
+<quad-abscissa> ::= DOUBLE
+<quad-weight> ::= DOUBLE
+
+---
+
+<meshes-list> ::= <ka-list>
+ <padding>
+ [ <ka-list> ... ]
+<ka-list> ::= <ka> [ <ka> ... ]
+<ka> ::= FLOAT
+
+-------
+
+SEE ALSO
+--------
+*mmap*(2), *sth*(5)
