commit ff7c3aa7b14e5b2ea7a5cbb70df1862eeb8dcb86
parent 37187a1cdf409829fb10cb71321dd538d0743dd1
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Wed, 14 Nov 2018 10:03:08 +0100
Write the les2htcp man page
Diffstat:
2 files changed, 135 insertions(+), 1 deletion(-)
diff --git a/cmake/doc/CMakeLists.txt b/cmake/doc/CMakeLists.txt
@@ -29,7 +29,7 @@ endif()
################################################################################
# Copy doc files
################################################################################
-set(MAN_NAMES htcp.5)
+set(MAN_NAMES htcp.5 les2htcp.1)
set(MAN_FILES)
foreach(_name IN LISTS MAN_NAMES)
diff --git a/doc/les2htcp.1.txt b/doc/les2htcp.1.txt
@@ -0,0 +1,134 @@
+// Copyright (C) 2018 CNRS, Université Paul Sabatier, |Meso|Star>
+//
+// 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:
+
+les2htcp(1)
+===========
+
+NAME
+----
+les2htcp - convert cloud properties from NetCDF to *htcp*(5) file format
+
+SYNOPSIS
+--------
+[verse]
+*les2htcp* [_option_] ... -i _LES__
+
+DESCRIPTION
+-----------
+*les2htcp* generates a *htcp*(5) file from cloud properties computed by a
+Large Eddy Simulation and saved in a NetCDF file [1]. Expected variables in
+the submitted NetCDF file are:
+
+* _W_E_direction_ *and* _S_N_direction_: one dimensional list of position of the
+ center of each cell along the West-East and South-North horizontal axis,
+ respectively. This should be a homogeneous mesh: each cell should have the
+ same width along each axis. The unit is assumed to be the meter but it can
+ be adjusted by the *-m* option.
+
+* _VLEV_ *or* _vertical_levels_: position of the center of each cell along the
+ vertical axis. The vertical mesh can possibly be inhomogeneous: each cell
+ can have different vertical extent. At least one of this variable must be
+ defined. Note that _VLEV_ is a four dimensional variable while
+ _vertical_levels_ is assumed to be one dimensional. In all cases, *les2htcp*
+ assumes that the vertical columns are the same for each cell along the
+ West-East and South-North axis. The unit is assumed to be the meter but it
+ can be adjusted by the *-m* option.
+
+* _RVT_: water vapor mixing ratio in each grid cell; in kg of water per m^3 of
+ dry air.
+
+* _RCT_: liquid vapor (in suspension) mixing ratio in each grid cell; in kg of
+ water per m^3 of dry air.
+
+* _PABST_: pressure in each grid cell in Pascal.
+
+* _THT_: potential temperature in each grid cell in Kelvin.
+
+OPTIONS
+-------
+*-c*::
+ Advanced checks on the validity of the submitted _LES_ file with respect to
+ the *les2htcp* prerequisites on the NetCDF data. Note that this option can
+ increase significantly the conversion time.
+
+*-f*::
+ Force overwrite of the _output_ file.
+
+*-h*::
+ List short help and exit.
+
+*-i* _LES_::
+ NetCDF file to convert.
+
+*-m* _float-to-meter_::
+ Scale factor from floating point unit to meters. By default it is set to 1.
+
+*-o* _output_::
+ Destination file where the *htcp*(5) file is written. If not defined, the
+ results are written to standard output.
+
+*-p* _page-size_::
+ Targeted page size in bytes; must be a power of 2. The size of the converted
+ LES data and their starting address into the *htcp*(5) file are aligned
+ according to _page-size_. By default, _page-size_ is 4096 bytes.
+
+*-q*::
+ Write nothing to _output_. Might be used in conjunction of the *-c* option
+ to only check the submitted _LES_.
+
+*-v*::
+ Display version information and exit.
+
+EXAMPLES
+--------
+
+Convert the *LES_clouds.nc* NetCDF file. Write the resulting *htcp*(5) file in
+*cloud.htcp* excepted if the file already exists; in this case an error is
+notified, the program stops and the *cloud.htcp* file remains unchanged:
+
+ $ les2htcp -i LES_clouds.nc -o clouds.htcp
+
+Convert the *LES_clouds_km.nc* file to *htcp*(5) file format. Use the *-f*
+option to write the output file *clouds.htcp* even though the it already
+exists. The *LES_clouds_km.nc* file to convert has its spatial unit in
+kilo-meters while the *htcp*(5) file formats assumes meters: use the *-m 1000*
+option to map kilo-meters to meters:
+
+ $ les2htcp -i LES_clouds_km.nc -m 1000 -o clouds.htcp
+
+Check that the submitted *LES_clouds.nc* file is valid regarding the
+*les2htcp* constraints. Use the *-q* option to disable the generation of
+output data:
+
+ $ les2htcp -c -i LES_clouds.nc -q
+
+NOTES
+-----
+1. Network Common Data Form -
+<https://www.unidata.ucar.edu/software/netcdf/>
+
+COPYRIGHT
+---------
+*les2htcp* is copyright © 2018 CNRS, Université Paul Sabatier
+<contact-edstar@laplace.univ-tlse.fr>, |Meso|Star> <contact@meso-star.com>.
+License GPLv3+: GNU GPL version 3 or later
+<https://gnu.org/licenses/gpl.html>. This is a free software. You are free to
+change and redistribute it. There is NO WARRANTY, to the extent permitted by
+law.
+
+SEE ALSO
+--------
+*htcp*(5)
