commit 88146d2adf7a0a4ae16fa63e8aff3ff33771a159
parent c37065c6d4877210c1d6f895e3aea293d91e2f88
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Fri, 18 Mar 2016 12:49:29 +0100
Finalise the schiff-geometry man page
Diffstat:
2 files changed, 62 insertions(+), 18 deletions(-)
diff --git a/doc/schiff-geometry.5 b/doc/schiff-geometry.5
@@ -2,19 +2,58 @@
.SH NAME
schiff-geometry \- control the shape of micro organisms
.SH DESCRIPTION
-\fBschiff-geometry\fR is a YAML file that defines the geometry distribution of
-a family of micro organisms. The
+A \fBschiff-geometry\fR is a YAML [1] file that controls the geometry
+distribution of a family of micro organisms. The
.BR schiff (1)
-program relies on this description to sample a set of the micro organisms in
-order to estimate the radiative properties of their family.
+program relies on this description to sample a set micro organism shapes
+in order to estimate the radiative properties of their family.
.PP
-A geometry is defined by a builtin type (cylinder, sphere, etc.) whose
-parameters are controlled by a specific distribution (constant, lognormal,
-etc.). Note that a \fBschiff-geometry\fR can list several geometries with their
-own parameter distribution. This allow to describe a micro organism family with
-a high variability in their geometry type.
+A geometry is defined by a shape type whose parameters are controlled by a
+specific distribution. Several geometries with their own probability can be
+declared in the same \fBschiff-geometry\fR file to define a discrete random
+variates of geometry distributions. This allow to finely tune the overall
+geometry distribution of a micro organism family with a collection of geometry
+distributions, each representing a specific sub-set of the family shapes.
+.PP
+There is two main shape types: the \fBcylinder\fR and the \fBsphere\fR.
+A shape is discretized by
+.BR schiff (1)
+in triangular meshes with respect to the \fBslices\fR
+attribute, i.e. the number of discrete divisions along 2PI. By
+default \fBslices\fR is set to 64.
+.PP
+To declare a spherical geometry distribution, simply map the \fBsphere\fR shape to
+a distribution of its \fBradius\fR. A cylindrical geometry distribution can be
+declared in two ways. Either directly, by defining the distribution of the
+\fBheight\fR and the \fBradius\fR of the cylinder shape, or by fixing its
+height/radius \fBaspect_ratio\fR and defining the distribution of the
+\fBradius\fR of a sphere whose volume is equal to the cylinder volume.
+.PP
+All the aforementioned shape parameters can be distributed with respect to the
+following distributions:
+.IP \(bu 4
+the constant distribution simply fixes the value of the parameter. Actually
+this distribution is implicitly used if the parameter value is a constant;
+.IP \(bu 4
+the \fBhistogram\fR distribution splits the parameter domain [\fBlower\fR,
+\fBupper\fR] in \fIN\fR intervals of length (\fBupper\fR-\fBlower\fR)/\fIN\fR.
+The list of unnormalized probabilities of the interval bounds are listed in the
+\fBprobabilities\fR array of \fIN\fR+1 entries used to build the cumulative
+distribution of the parameter. Let a random number "r" in [0, 1], the
+corresponding parameter value is computed by retrieving the interval of the
+parameter from the aforementioned cumulative before linearly interpolating its
+bounds with respect to "r";
+.IP \(bu 4
+with the \fBlognormal\fR distribution, the parameter is distributed with respect
+to a mean value \fBzeta\fR and a standard deviation \fBsigma\fR:
+ P(x) dx = 1/(log(\fBsigma\fR)*x*sqrt(2*PI) *
+ exp(-(ln(x)-log(\fBzeta\fR))^2 / (2*log(\fBsigma\fR)^2)) dx
.SS Grammar
-The following grammar formally describes the fileformat of a \fBschiff\-geometry\fR.
+The section describes the \fBschiff\-geometry\fR grammar based on the YAML [1]
+human readable data format. The YAML format provides several ways to define a
+mapping or a sequence of data. The following grammar always uses the more
+verbose form but any alternative YAML formatting can be used instead. Refer to
+the example section for illustrations of such alternatives.
.TP
\fBschiff\-geometry\fR ::=
<\fIgeometry\fR> | <\fIgeometry\-list>
@@ -36,7 +75,7 @@ The following grammar formally describes the fileformat of a \fBschiff\-geometry
<\fIsphere\-geometry\fR>
\fBsphere:\fR
\fBradius:\fR <\fIdistribution\fR>
- [ \fBslices:\fI integer\fR ]
+ [ \fBslices:\fI integer\fR ] # Discretisation along 2PI
[ \fBproba:\fI real\fR ]
.TP
<\fIdistribution\fR> ::=
@@ -86,12 +125,12 @@ discretized in 64 slices along 2PI:
zeta: 1.3
sigma: 0.84\fR
.PP
-Micro organisms are cylinders with a height/radius aspect ratio distributed
-according to a lognormal distribution. Their volume is equal to the volume of a
-sphere whose radius is distributed with respect to an histogram:
+Micro organisms are cylinders whose height/radius is fixed. Their volume is
+equal to the volume of a sphere whose radius is distributed with respect to an
+histogram:
.PP
\fBcylinder:
- aspect_ratio: { lognormal: { zeta: 1.3, sigma: 0.834 } }
+ aspect_ratio: 1
radius:
histogram:
lower: 1.24
@@ -108,6 +147,10 @@ and spherical micro organisms have a fix radius:
height: {lognormal: { zeta: 1, sigma: 1.5 } }
slices: 32 # Discretisation in 32 slices
proba: 1\fR
+.SH NOTE
+.TP
+[1]
+YAML Ain't Markup Language - http://yaml.org
.SH SEE ALSO
.BR schiff (1)
diff --git a/doc/schiff.1 b/doc/schiff.1
@@ -81,9 +81,10 @@ approximation for estimating radiative properties of homogeneous, simple-shaped
and optically soft particles: Application to photosynthetic micro-organisms.
Journal of Quantitative Spectroscopy and Radiative Transfer 172 \- 3\-23.
.SH COPYRIGHT
-Copyright \(co |Meso|Star> 2015-2016 (<contact@meso-star.com>). It is a free
-software release under the OSI approved CeCILL license. You are welcome de
-redistribute it under certain conditions.
+\fBschiff\fR is copyright \(co |Meso|Star> 2015-2016 (<contact@meso-star.com>).
+It is a free software release under the OSI approved CeCILL license. You are
+welcome de redistribute it under certain conditions. Refer to the its COPYING
+files for details.
.SH SEE ALSO
.BR schiff-geometry (5),
.BR schiff-output (5)
