commit 2a9af03cd52e6f4a6fee4f5a7a73f30753155e4d
parent 13ce6042d4a41fb302a3308076685f95f005f89a
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Thu, 17 Mar 2016 21:16:06 +0100
First draft of the man page on YAML geometry fileformat
Move the manual pages to the doc directory.
Diffstat:
| A | doc/schiff-geometry.5 | | | 113 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | doc/schiff-output.5 | | | 121 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | doc/schiff.1 | | | 89 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| D | src/schiff-geometry.5 | | | 10 | ---------- |
| D | src/schiff-output.5 | | | 120 | ------------------------------------------------------------------------------- |
| D | src/schiff.1 | | | 89 | ------------------------------------------------------------------------------- |
6 files changed, 323 insertions(+), 219 deletions(-)
diff --git a/doc/schiff-geometry.5 b/doc/schiff-geometry.5
@@ -0,0 +1,113 @@
+.TH SCHIFF-GEOMETRY 5
+.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
+.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.
+.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.
+.SS Grammar
+The following grammar formally describes the fileformat of a \fBschiff\-geometry\fR.
+.TP
+\fBschiff\-geometry\fR ::=
+ <\fIgeometry\fR> | <\fIgeometry\-list>
+.TP
+<\fIgeometry\-list\fR> ::=
+ \fB-\fR <\fIgeometry\fR>
+ [ \fB-\fR <\fIgeometry\fR> ]
+.TP
+<\fIgeometry\fR> ::=
+ <\fIcylinder\-geometry\fR> | <\fIsphere\-geometry\fR>
+.TP
+<\fIcylinder\-geometry\fR> ::=
+ \fBcylinder:
+ \fBradius:\fR <\fIdistribution\fR>
+ \fBheight:\fR <\fIdistribution\fR> | \fBaspect_ratio:\fR <\fIdistribution\fR>
+ [ \fBslices:\fI integer\fR ]
+ [ \fBproba:\fI real\fR ]
+.TP
+<\fIsphere\-geometry\fR>
+ \fBsphere:\fR
+ \fBradius:\fR <\fIdistribution\fR>
+ [ \fBslices:\fI integer\fR ]
+ [ \fBproba:\fI real\fR ]
+.TP
+<\fIdistribution\fR> ::=
+ \fIreal\fR| <\fIlognormal\fR> | <\fIhistogram\fR>
+.TP
+<\fIlognormal\fR> ::=
+ \fBlognormal:
+ zeta: \fIreal\fB
+ sigma:\fI real\fB
+.TP
+<\fIhistogram\fR> ::=
+ \fBhistogram:\fR
+ \fBlower:\fI real\fR
+ \fBupper:\fI real\fR
+ \fBprobabilities:\fR
+ <\fIprobabilities\-list\fR>
+.TP
+<\fIprobabilities\-list\fR> ::=
+ \fB-\fI real\fR
+ [ \fB-\fR <\fIprobabilities\-list\fR> ]
+.SH EXAMPLES
+.PP
+Micro organisms are spheres whose radius is distributed according to an
+histogram:
+.PP
+ \fBsphere:
+ radius:
+ histogram:
+ lower: 1.0 # Min radius
+ upper: 2.1 # Max radius
+ probabilities:
+ - 2
+ - 1
+ - 0.4
+ - 1.23
+ - 3\fR
+.PP
+Micro organisms are cylinders. Their radius is constant and their height is
+distributed according to a lognormal distribution. The cylinder geometry is
+discretized in 64 slices along 2PI:
+.PP
+ \fBcylinder:
+ slices: 64
+ radius: 1
+ height:
+ lognormal:
+ 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:
+.PP
+ \fBcylinder:
+ aspect_ratio: { lognormal: { zeta: 1.3, sigma: 0.834 } }
+ radius:
+ histogram:
+ lower: 1.24
+ upper: 4.56
+ probabilities: [ 2, 1.2, 3, 0.2 ]\fR
+.PP
+Micro organisms are spheres and cylinders with 2 times more spheres than
+cylinders. The cylinder parameters are controlled by lognormal distributions
+and spherical micro organisms have a fix radius:
+.PP
+ \fB- sphere: { radius 1.12, proba: 2.0, slices: 64 }
+ \fB- cylinder:
+ radius: {lognormal: { sigma: 2.3, zeta: 0.2 } }
+ height: {lognormal: { zeta: 1, sigma: 1.5 } }
+ slices: 32 # Discretisation in 32 slices
+ proba: 1\fR
+.SH SEE ALSO
+.BR schiff (1)
+
diff --git a/doc/schiff-output.5 b/doc/schiff-output.5
@@ -0,0 +1,121 @@
+.TH SCHIFF-OUTPUT 5
+.SH NAME
+schiff\-output \- format of
+.BR schiff (1)
+results.
+.SH DESCRIPTION
+The output result of the
+.BR schiff (1)
+program is a collection of ASCII floating point data. The first set of floating
+point values is the list of per wavelength cross\-sections. Each line stores
+the estimated cross section of a wavelength submitted by the \fB\-w\fR option of
+.BR schiff (1).
+It is formatted as "W E e A a S s P p" with "W" the wavelength in vacumm
+(expressed in microns), "E", "A" and "S" the estimation of the extinction,
+absorption and scattering cross\-sections, respectively, and "P" the estimated
+average projected area of the micro organisms. The "e", "a", "s" and "p" values
+are the standard error of the aforementioned estimations.
+.PP
+An empty line then separates the cross\-sections from the list of per
+wavelength inverse cumulative phase functions.
+.PP
+Each inverse cumulative phase function begins by a line that describes how the
+function was computed. The format of this line is "W theta-l Ws Ws-SE Wc Wc-SE
+n" with "W" the wavelength in vacuum (expressed in microns) of the inverse
+cumulative phase function, "theta-l" the scattering angle in radians from which
+the phase function was analytically computed, "Ws" and "Wc" the values of the
+differential cross section and its cumulative for "theta-l", and "n" the
+parameter of the model used to analytically evaluate the phase function for
+wide scattering angles, i.e. angles greater than 'theta-l'. The "Ws-SE" and
+"Wc-SE" values are the standard error of the "Ws" and "Wc" estimations,
+respectively.
+.PP
+Following this heading line, there is the list of inverse cumulative phase
+function values, i.e. the angles in [0, PI] corresponding to a probability in
+[0, 1]. The number of these angles are controlled by the \fB\-A\fR option of
+.BR schiff (1).
+Assuming a set of N angles, the i^th angle (i in [0, N\-1]) is the angle whose
+probability is i/(N\-1).
+.PP
+The last angle of the inverse cumulative phase function is then followed by
+an empty line that separates the current inverse cumulative phase function
+from the next one.
+.PP
+Note that both the cross sections and the inverse cumulative phase functions
+are sorted in ascending order with respect to their associated wavelength.
+.SS Grammar
+The following grammar formally describes the
+.BR schiff (1)
+output format
+.TP
+\fBschiff-output\fR ::=
+ <\fIcross\-sections\fR>
+ empty-line
+ <\fIinverse\-cumulative\-phase\-functions\fR>
+.PP
+\l'20'
+.TP
+<\fIcross\-sections\fR> ::=
+ wavelength <\fIextinction\fR> <\fIabsorption\fR> <\fIscattering\fR> <\fIarea\fR>
+ [ <\fIcross\-sections\fR> ]
+.TP
+<\fIextinction\fR> ::=
+ estimation standard\-error
+.TP
+<\fIabsorption\fR> ::=
+ estimation standard\-error
+.TP
+<\fIscattering\fR> ::=
+ estimation standard\-error
+.TP
+<\fIarea\fR> ::=
+ estimation standard\-error
+.PP
+\l'20'
+.TP
+<\fIinverse\-cumulative\-phase\-functions\fR> ::=
+ <\fIinverse\-cumulative\-descriptor\fR>
+ <\fIangles\fR>
+ empty-line
+ [ <\fIinverse\-cumulative\-phase\-functions\fR> ]
+.TP
+<\fIinverse\-cumulative\-descriptor\fR> ::=
+ wavelength theta-limit <\fIPF(theta\-limit)\fR> <\fICDF(theta\-limit)\fR> n
+.TP
+<\fICDF(theta\-limit)\fR> ::=
+ estimation standard\-error
+.TP
+<\fIPF(theta\-limit)\fR> ::=
+ estimation standard\-error
+.TP
+<\fIangles\fR> ::=
+ real
+ [ <\fIangles\fR> ]
+.SH EXAMPLE
+The following result is emitted by the
+.BR schiff (1)
+program invoked on the wavelengths 0.4 and 0.6 micron.
+Note that actually,
+.BR schiff (1)
+does not write comments, i.e. text preceeded by the "#" character. However, in
+the following output, comments are added in order to help in understanding the
+data layout.
+.PP
+ 0.4 6.4e-2 1.1e-4 5.6e-2 9.1e-5 8.6e-3 1.9e-5 0.8 9.4e-4 \fB# X\-sections\fR
+ 0.6 7.7e-3 1.3e-5 7.4e-3 1.1e-5 5.5e-4 1.2e-6 0.2 2.3e-4 \fB# X\-sections\fR
+.PP
+ 0.4 0.54 6.75e-4 3.93e-6 8.02e-3 1.95e-5 3.40913 \fB# Inv Cum Descriptor\fR
+ 0.0000000 \fB# Angles list\fR
+ 0.0060234
+ ...
+ 2.74326
+ 3.14159
+.PP
+ 0.6 0.77 7.11e-5 1.05e-07 4.6e-4 1.23e-6 3.85927 \fB# Inv Cum Descriptor\fR
+ 0.0000000 \fB# Angles list\fR
+ 0.0121295
+ ...
+ 2.93276
+ 3.14159
+.SH SEE ALSO
+.BR schiff (1)
diff --git a/doc/schiff.1 b/doc/schiff.1
@@ -0,0 +1,89 @@
+.TH SCHIFF 1
+.SH NAME
+schiff \- estimate radiative properties of soft particles
+.SH SYNOPSIS
+\fBschiff
+\fR[\fIOPTIONS\fR]...
+[\fIFILE\fR]
+.SH DESCRIPTION
+\fBschiff\fR estimates the radiative properties of micro organisms with an
+"Approximation Method for Short Wavelength or High Energy Scattering" [1]. It
+relies on the Monte\-Carlo method to solve Maxwell's equations within Schiff's
+approximation [2]; it estimates total cross sections (extinction, absorption
+and scattering cross-sections) in addition of the inverse cumulative phase
+function
+.PP
+The shape of the micro organisms is controlled by the geometry distribution
+defined in the YAML file submitted by the \fB\-i\fR option while \fIFILE\fR
+stores their per wavelength optical properties. Each line of \fIFILE\fR must be
+formatted as "W Nr Kr Ne" where "W" is the wavelength in vacuum expressed in
+micron "Nr" and "Kr" are the real and imaginary parts, respectively, of the
+relative refractive index, and "Ne" the refractive index of the medium. With no
+\fIFILE\fR, the optical properties are read from standard input.
+.PP
+The estimated results are written to the \fIOUTPUT\fR file defined by the
+\fB\-o\fR option or to standard output whether the \fB-o\fR option is defined
+or not, respectively.
+.SH OPTIONS
+.TP
+.B \-a \fIANGLES\fR
+number of phase function scattering angles. Default is 1000.
+.TP
+.B \-A \fIANGLES\fR
+number of angles computed from the inverse cumulative phase function. Default
+is 2000.
+.TP
+.B \-d \fIDIRS\fR
+number of sampled directions for each geometry. Default is 100.
+.TP
+.B \-g \fIGEOMETRIES\fR
+number of sampled geometries. This is actyally the number of realisations.
+Default is 10000.
+.TP
+.B \-G \fICOUNT\fR
+sampled \fICOUNT\fR geometries with respect to the defined distribution, dump
+their data and exit. The data are written to OUTPUT or the standard output
+whether the \fB-o\fR option is defined or not, respectively. The outputted data
+followed the Alias Wavefront obj file format.
+.TP
+.B \-h
+display short help and exit.
+.TP
+.B \-i \fIDISTRIBUTION\fR
+define the YAML file that controls the geometry distributions of the micro
+organisms.
+.TP
+.B \-l \fILENGTH\fR
+caracteristic length of the micro organisms.
+.TP
+.B \-n \fITHREADS\fR
+hint on the number of threads to use during the integration. By default use as
+many threads as CPU cores.
+.TP
+.B \-o \fIOUTPUT\fR
+write results to OUTPUT. If not defined, write results to standard output.
+.TP
+.B \-q
+do not print the helper message when no FILE is submitted.
+.TP
+.B \-w \fI A[:B]...\fR
+list of wavelengths in vacuum (expressed in micron) to integrate.
+.SH NOTES
+.TP
+[1]
+L. I. Schiff, 1956. Approximation Method for Short Wavelength or High\-Energy
+Scattering. Phys. Rev. 104 \- 1481\-1485.
+.TP
+[2]
+J. Charon, S. Blanco, J. F. Cornet, J. Dauchet, M. El Hafi, R. Fournier, M.
+Kaissar Abboud, S. Weitz, 2016. Monte Carlo Implementation of Schiff's
+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.
+.SH SEE ALSO
+.BR schiff-geometry (5),
+.BR schiff-output (5)
diff --git a/src/schiff-geometry.5 b/src/schiff-geometry.5
@@ -1,10 +0,0 @@
-.TH SCHIFF-GEOMETRY 5
-.SH NAME
-schiff-geometry \- control the geometry distribution of
-.BR schiff (1)
-.SH DESCRIPTION
-A \fBschiff-geometry\fR file use ithe YAML human readable data serialization
-format to describe the geometry distribution of micro organisms for the
-.BR schiff (1)
-program.
-
diff --git a/src/schiff-output.5 b/src/schiff-output.5
@@ -1,120 +0,0 @@
-.TH SCHIFF-OUTPUT 5
-.SH NAME
-schiff\-output \- format of
-.BR schiff (1)
-results
-.SH DESCRIPTION
-The output result of the
-.BR schiff (1)
-program is a collection of ASCII floating point data. The first set of floating
-point values is the list of per wavelength cross\-sections. Each line stores
-the estimated cross section of a wavelength submitted by the \fB\-w\fR option of
-.BR schiff (1).
-It is formatted as "W E e A a S s P p" with "W" the wavelength in vacumm
-(expressed in microns), "E", "A" and "S" the estimation of the extinction,
-absorption and scattering cross\-sections, respectively, and "P" the estimated
-average projected area of the micro organisms. The "e", "a", "s" and "p" values
-are the standard error of the aforementioned estimations.
-.PP
-An empty line then separates the cross\-sections from the list of per
-wavelength inverse cumulative phase functions.
-.PP
-Each inverse cumulative phase function begins by a line that describes how the
-function was computed. The format of this line is "W theta-l Ws Ws-SE Wc Wc-SE
-n" with "W" the wavelength in vacuum (expressed in microns) of the inverse
-cumulative phase function, "theta-l" the scattering angle in radians from which
-the phase function was analytically computed, "Ws" and "Wc" the values of the
-differential cross section and its cumulative for "theta-l", and "n" the
-parameter of the model used to analytically evaluate the phase function for
-wide scattering angles, i.e. angles greater than 'theta-l'. The Ws-SE and Wc-SE
-values are the standard error of the "Ws" and "Wc" estimations, respectively.
-.PP
-Following this heading line, there is the list of inverse cumulative phase
-function values, i.e. the angles in [0, PI] corresponding to a probability in
-[0, 1]. The number of these angles are controlled by the \fB\-A\fR option of
-.BR schiff (1).
-Assuming a set of N angles, the i^th angle (i in [0, N\-1]) is the angle whose
-probability is i/(N\-1).
-.PP
-The last angle of the inverse cumulative phase function is then followed by
-an empty line that separates the current inverse cumulative phase function
-from the next one.
-.PP
-Note that both the cross sections and the inverse cumulative phase functions
-are sorted in ascending order with respect to their associated wavelength.
-.SS Grammar
-The following grammar formally describes the
-.BR schiff (1)
-output format
-.TP
-<\fIoutput\fR> ::=
- <\fIcross\-sections\fR>
- empty-line
- <\fIinverse\-cumulative\-phase\-functions\fR>
-.PP
-\l'20'
-.TP
-<\fIcross\-sections\fR> ::=
- wavelength <\fIextinction\fR> <\fIabsorption\fR> <\fIscattering\fR> <\fIarea\fR>
- <\fIcross\-sections\fR>
-.TP
-<\fIextinction\fR> ::=
- estimation standard\-error
-.TP
-<\fIabsorption\fR> ::=
- estimation standard\-error
-.TP
-<\fIscattering\fR> ::=
- estimation standard\-error
-.TP
-<\fIarea\fR> ::=
- estimation standard\-error
-.PP
-\l'20'
-.TP
-<\fIinverse\-cumulative\-phase\-functions\fR> ::=
- <\fIinverse\-cumulative\-descriptor\fR>
- <\fIangles\fR>
- empty-line
- <\fIinverse\-cumulative\-phase\-function\fR>
-.TP
-<\fIinverse\-cumulative\-descriptor\fR> ::=
- wavelength theta-limit <\fIPF(theta\-limit)\fR> <\fICDF(theta\-limit)\fR> n
-.TP
-<\fICDF(theta\-limit)\fR> ::=
- estimation standard\-error
-.TP
-<\fIPF(theta\-limit)\fR> ::=
- estimation standard\-error
-.TP
-<\fIangles\fR> ::=
- real
- <\fIangles\fR>
-.SH EXAMPLE
-The following result is emitted by the
-.BR schiff(1)
-program invoked on the wavelengths 0.4 and 0.6 micron.
-Note that actually,
-.BR schiff(1)
-does not write comments, i.e. text preceeded by the "#" character. However in
-the following output, comments are added in order to help in understanding the
-data layout.
-.PP
- 0.4 6.4e-2 1.1e-4 5.6e-2 9.1e-5 8.6e-3 1.9e-5 0.8 9.4e-4 \fB# X\-sections\fR
- 0.6 7.7e-3 1.3e-5 7.4e-3 1.1e-5 5.5e-4 1.2e-6 0.2 2.3e-4 \fB# X\-sections\fR
-.PP
- 0.4 0.54 6.75e-4 3.93e-6 8.02e-3 1.95e-5 3.40913 \fB# Inv Cum Descriptor\fR
- 0.0000000 \fB# Angles list\fR
- 0.0060234
- ...
- 2.74326
- 3.14159
-.PP
- 0.6 0.77 7.11e-5 1.05e-07 4.6e-4 1.23e-6 3.85927 \fB# Inv Cum Descriptor\fR
- 0.0000000 \fB# Angles list\fR
- 0.0121295
- ...
- 2.93276
- 3.14159
-.SH SEE ALSO
-.BR schiff (1)
diff --git a/src/schiff.1 b/src/schiff.1
@@ -1,89 +0,0 @@
-.TH SCHIFF 1
-.SH NAME
-schiff \- estimate radiative properties of soft particles
-.SH SYNOPSIS
-\fBschiff
-\fR[\fIOPTIONS\fR]...
-[\fIFILE\fR]
-.SH DESCRIPTION
-\fBschiff\fR estimates the radiative properties of micro organisms with an
-"Approximation Method for Short Wavelength or High Energy Scattering" (L.
-Schiff, 1956 [1]). It relies on the Monte\-Carlo method to solve Maxwell's
-equations within Schiff's approximation (J. Charon et al. 2016 [2]); it
-estimates total cross sections (extinction, absorption and scattering
-cross-sections) in addition of the inverse cumulative phase function.
-.PP
-The shape of the micro organisms is controlled by the geometry distribution
-defined in the YAML file submitted by the \fB\-i\fR option while \fIFILE\fR
-stores their per wavelength optical properties. Each line of \fIFILE\fR must be
-formatted as "W Nr Kr Ne" where "W" is the wavelength in vacuum expressed in
-micron "Nr" and "Kr" are the real and imaginary parts, respectively, of the
-relative refractive index, and "Ne" the refractive index of the medium. With no
-\fIFILE\fR, the optical properties are read from standard input.
-.PP
-The estimated results are written to the \fIOUTPUT\fR file defined by the
-\fB\-o\fR option or to standard output whether the \fB-o\fR option is defined
-or not, respectively.
-.SH OPTIONS
-.TP
-.B \-a \fIANGLES\fR
-number of phase function scattering angles. Default is 1000.
-.TP
-.B \-A \fIANGLES\fR
-number of angles computed from the inverse cumulative phase function. Default
-is 2000.
-.TP
-.B \-d \fIDIRS\fR
-number of sampled directions for each geometry. Default is 100.
-.TP
-.B \-g \fIGEOMETRIES\fR
-number of sampled geometries. This is actyally the number of realisations.
-Default is 10000.
-.TP
-.B \-G \fICOUNT\fR
-sampled \fICOUNT\fR geometries with respect to the defined distribution, dump
-their data and exit. The data are written to OUTPUT or the standard output
-whether the \fB-o\fR option is defined or not, respectively. The outputted data
-followed the Alias Wavefront obj file format.
-.TP
-.B \-h
-display short help and exit.
-.TP
-.B \-i \fIDISTRIBUTION\fR
-define the YAML file that controls the geometry distributions of the micro
-organisms.
-.TP
-.B \-l \fILENGTH\fR
-caracteristic length of the micro organisms.
-.TP
-.B \-n \fITHREADS\fR
-hint on the number of threads to use during the integration. By default use as
-many threads as CPU cores.
-.TP
-.B \-o \fIOUTPUT\fR
-write results to OUTPUT. If not defined, write results to standard output.
-.TP
-.B \-q
-do not print the helper message when no FILE is submitted.
-.TP
-.B \-w \fI A[:B]...\fR
-list of wavelengths in vacuum (expressed in micron) to integrate.
-.SH NOTES
-.TP
-[1]
-L. I. Schiff, 1956. Approximation Method for Short Wavelength or High\-Energy
-Scattering. Phys. Rev. 104 \- 1481\-1485.
-.TP
-[2]
-J. Charon, S. Blanco, J. F. Cornet, J. Dauchet, M. El Hafi, R. Fournier, M.
-Kaissar Abboud, S. Weitz, 2016. Monte Carlo Implementation of Schiff's
-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.
-.SH SEE ALSO
-.BR schiff-geometry (5),
-.BR schiff-output (5)
