commit f97db7d992a3d24b91a0e5e34a7ae230fcdb0c08
parent 43fc7f238da6e7a1e726499aeb163c9209e3537a
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Tue, 13 Apr 2021 17:10:20 +0200
Write the atrtp man page
Diffstat:
3 files changed, 124 insertions(+), 22 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 atrtp man page cannot be generated.")
+else()
+ set(_src ${PROJECT_SOURCE_DIR}/../doc/atrtp.5.txt)
+ set(_txt ${CMAKE_CURRENT_BINARY_DIR}/atrtp.5.txt)
+ add_custom_command(
+ OUTPUT atrtp.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 atrtp.5"
+ VERBATIM)
+ add_custom_target(man-roff ALL DEPENDS atrtp.5)
+ install(FILES ${CMAKE_CURRENT_BINARY_DIR}/atrtp.5 DESTINATION share/man/man5)
+endif()
+
+################################################################################
# Define output & install directories
################################################################################
install(TARGETS atrtp
diff --git a/doc/atrtp b/doc/atrtp
@@ -1,22 +0,0 @@
-<atrtp> ::= <pagesize> <#cells>
- <padding>
- <thermo-props>
- <padding>
-
-<pagesize> ::= INT64
-<#cells> ::= INT64
-<padding> ::= [ BYTE ... ]
-
-<thermo-props> ::= <thermo-prop>
- [ <thermo-prop ... ]
-<therm-prop> ::= <pressure> <temperature> <xH2O> <xCO2> <xCO> <vf-soot> <np-soot> <dp-soot>
-
-<pressure> ::= <double> # Pressure in Pa
-<temperature> ::= <double> # Temperature in K
-<xH2O> ::= <double> # Molar fraction of H2O in mol(H2O)/mol(mixture)
-<xCO2> ::= <double> # Molar fraction of CO2 in mol(CO2)/mol(mixture)
-<xCO> ::= <double> # Molar fraction of CO in mol(CO)/mol(mixture)
-<vf-soot> ::= <double> # Volumic fraction of soot in m^3(soot)/ m^3
-<np-soot> ::= <double> # Number of primary particles per agregate
-<dp-soot> ::= <double> # Primary particles diameter in nm
-
diff --git a/doc/atrtp.5.txt b/doc/atrtp.5.txt
@@ -0,0 +1,101 @@
+// 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:
+
+atrtp(5)
+=======
+
+NAME
+----
+atrtp - AsToRia: Thermodynamic Properties
+
+DESCRIPTION
+-----------
+
+*atrtp* is a binary file format to store a set of thermodynamic porperties for
+each node a volumetric mesh representing a medium in combustion. An *atrtp*
+file begins by a header that describes the data layout followed by a list of
+per node properties.
+
+The header is made up of 2 64-bit integers. The first integer is a power of
+two (usually 4096) that defines the _<pagesize>_ in bytes to which the
+thermodynamic properties are aligned. The remaining integer store the number
+of items in the list. In the following grammar, we name it _<#nodes>_, for
+"number of nodes", in reference to the mesh nodes to which these properties
+would be attached.
+
+Note that by aligning the thermodynamic data to _<pagesize>_, and depending on
+the system requirements, memory mapping can be used to automatically
+load/unload those data on demand (see for example the POSIX C function
+*mmap*(2)).
+
+Padding bytes follow the file header to ensure alignment of the thermodynamic
+properties to _<pagesize>_. These properties are then listed with 8 double
+precision floating point numbers per item (i.e. per node). The set of per node
+data are:
+
+* The pressure in Pascal
+* The temperature in Kelvin
+* The molar fraction of H20 in mol(H20)/mol(mixture)
+* The molar fraction of CO2 in mol(CO2)/mol(mixture)
+* The molar fraction of CO in mol(CO)/mol(mixture)
+* The volumic fraction of soot in m^3(soot)/m^3
+* The number of soot primary particules per agregate
+* The soot primary particles diameter in nm
+
+Finally, additional padding bytes are added after the listed properties to
+align the overall file size to _<pagesize>_.
+
+BINARY FILE FORMAT
+------------------
+
+Data are encoded with respect to the little endian bytes ordering, i.e. least
+significant bytes are stored first.
+
+[verse]
+-------
+<atrtp> ::= <pagesize> <#nodes>
+ <padding>
+ <thermo-props>
+ <padding>
+
+<pagesize> ::= INT64
+<#cells> ::= INT64
+<padding> ::= [ BYTE ... ]
+
+<thermo-props> ::= <thermo-prop>
+ [ <thermo-prop ... ]
+<therm-prop> ::= <pressure>
+ <temperature>
+ <xH2O>
+ <xCO2>
+ <xCO>
+ <vf-soot>
+ <np-soot>
+ <dp-soot>
+
+<pressure> ::= <double> # Pressure in Pa
+<temperature> ::= <double> # Temperature in K
+<xH2O> ::= <double> # Molar fraction of H2O in mol(H2O)/mol(mixture)
+<xCO2> ::= <double> # Molar fraction of CO2 in mol(CO2)/mol(mixture)
+<xCO> ::= <double> # Molar fraction of CO in mol(CO)/mol(mixture)
+<vf-soot> ::= <double> # Volumic fraction of soot in m^3(soot)/ m^3
+<np-soot> ::= <double> # Number of primary particles per agregate
+<dp-soot> ::= <double> # Primary particles diameter in nm
+-------
+
+SEE ALSO
+--------
+*mmap*(2)
