commit d4adde28c0335443cac2339b3e1e894383ae2f13
parent 870ed23812ade74e2b34bf4d9754397872c0d179
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Sat, 19 Mar 2016 15:24:52 +0100
Rewrite some parts of the man-pages
Move the man-pages from man<1|5> doc sub-directories to the doc.
Diffstat:
7 files changed, 379 insertions(+), 376 deletions(-)
diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
@@ -88,8 +88,8 @@ set(SCHIFF_FILES_MAN5 schiff-geometry.5 schiff-output.5)
rcmake_prepend_path(SCHIFF_FILES_SRC ${SCHIFF_SOURCE_DIR})
rcmake_prepend_path(SCHIFF_FILES_INC ${SCHIFF_SOURCE_DIR})
rcmake_prepend_path(SCHIFF_FILES_DOC ${PROJECT_SOURCE_DIR}/../)
-rcmake_prepend_path(SCHIFF_FILES_MAN1 ${PROJECT_SOURCE_DIR}/../doc/man1)
-rcmake_prepend_path(SCHIFF_FILES_MAN5 ${PROJECT_SOURCE_DIR}/../doc/man5)
+rcmake_prepend_path(SCHIFF_FILES_MAN1 ${PROJECT_SOURCE_DIR}/../doc/)
+rcmake_prepend_path(SCHIFF_FILES_MAN5 ${PROJECT_SOURCE_DIR}/../doc/)
if(CMAKE_COMPILER_IS_GNUCC)
set(MATH_LIB m)
diff --git a/doc/man1/schiff.1 b/doc/man1/schiff.1
@@ -1,97 +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 computes the radiative properties of soft particles 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 shapes of a family of soft particles are controlled by the
-.BR schiff-geometry (5)
-file submitted by the \fB\-i\fR option. Their per wavelength properties are
-stored in \fIFILE\fR where each line is formatted as "W Nr Kr Ne" whith "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 follows the
-.BR schiff-output (5)
-format and 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 actually the number of realisations.
-Default is 10000.
-.TP
-.B \-G \fICOUNT\fR
-sample \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
-.BR schiff-geometry (5)
-file that controls the geometry distribution of the soft particles.
-.TP
-.B \-l \fILENGTH\fR
-caracteristic length of the soft particles.
-.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 \fIOUTPUT\fR with respect to the
-.BR schiff-output (5)
-format. If not defined, write results to standard output.
-.TP
-.B \-q
-do not print the helper message when no \fIFILE\fR is submitted.
-.TP
-.B \-w \fIA\fR[\fB:\fIB\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
-\fBschiff\fR is copyright \(co |Meso|Star> 2015-2016 (<contact@meso-star.com>).
-It is a free software released under the OSI approved CeCILL license. You are
-welcome de redistribute it under certain conditions. Refer to its COPYING file
-for details.
-.SH SEE ALSO
-.BR schiff-geometry (5),
-.BR schiff-output (5)
diff --git a/doc/man5/schiff-geometry.5 b/doc/man5/schiff-geometry.5
@@ -1,156 +0,0 @@
-.TH SCHIFF-GEOMETRY 5
-.SH NAME
-schiff-geometry \- control the shape of soft particles
-.SH DESCRIPTION
-A \fBschiff-geometry\fR is a YAML [1] file that controls the geometry
-distribution of a family of soft particles. The
-.BR schiff (1)
-program relies on this description to sample a set of soft particles
-in order to estimate the radiative properties of their family.
-.PP
-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 soft particle 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 and are 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
-This section describes the \fBschiff\-geometry\fR grammar based on the YAML
-human readable data format [1]. 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>
-.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 ] # Discretisation along 2PI
- [ \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
-Soft particles 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
-Soft particles 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
-Soft particles are cylinders whose height/radius ratio 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: 1
- radius:
- histogram:
- lower: 1.24
- upper: 4.56
- probabilities: [ 2, 1.2, 3, 0.2 ]\fR
-.PP
-Soft particles are spheres and cylinders with 2 times more spheres than
-cylinders. The cylinder parameters are controlled by lognormal distributions
-and spherical soft particles have a fixed 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 NOTE
-.TP
-[1]
-YAML Ain't Markup Language \- http://yaml.org
-.SH SEE ALSO
-.BR schiff (1)
-
diff --git a/doc/man5/schiff-output.5 b/doc/man5/schiff-output.5
@@ -1,121 +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 soft particles. 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>
- \fIempty-line\fR
- <\fIinverse\-cumulative\-phase\-functions\fR>
-.PP
-\l'20'
-.TP
-<\fIcross\-sections\fR> ::=
- \fIWAVELENGTH\fR <\fIextinction\fR> <\fIabsorption\fR> <\fIscattering\fR> <\fIarea\fR>
- [ <\fIcross\-sections\fR> ]
-.TP
-<\fIextinction\fR> ::=
- \fIESTIMATION STANDARD\-ERROR\fR
-.TP
-<\fIabsorption\fR> ::=
- \fIESTIMATION STANDARD\-ERROR\fR
-.TP
-<\fIscattering\fR> ::=
- \fIESTIMATION STANDARD\-ERROR\fR
-.TP
-<\fIarea\fR> ::=
- \fIESTIMATION STANDARD\-ERROR\fR
-.PP
-\l'20'
-.TP
-<\fIinverse\-cumulative\-phase\-functions\fR> ::=
- <\fIinverse\-cumulative\-descriptor\fR>
- <\fIangles\fR>
- \fIEMPTY-LINE\fR
- [ <\fIinverse\-cumulative\-phase\-functions\fR> ]
-.TP
-<\fIinverse\-cumulative\-descriptor\fR> ::=
- \fIWAVELENGTH THETA-LIMIT\fR <\fIPF(THETA\-LIMIT)\fR> <\fICDF(THETA\-LIMIT)\fR> \fIN\fR
-.TP
-<\fICDF(THETA\-LIMIT)\fR> ::=
- \fIESTIMATION STANDARD\-ERROR\fR
-.TP
-<\fIPF(THETA\-LIMIT)\fR> ::=
- \fIESTIMATION STANDARD\-ERROR\fR
-.TP
-<\fIangles\fR> ::=
- \fIREAL\fR
- [ <\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-geometry.5 b/doc/schiff-geometry.5
@@ -0,0 +1,158 @@
+.TH SCHIFF-GEOMETRY 5
+.SH NAME
+schiff-geometry \- control the shape of soft particles
+.SH DESCRIPTION
+\fBschiff-geometry\fR is a YAML file [1] that controls the geometry
+distribution of soft particles. The
+.BR schiff (1)
+program relies on this description to generate the geometry of the sampled soft
+particles.
+.PP
+A geometry is defined by a type and a set of parameters whose value is
+controlled by a distribution. Several geometries with their own probability can
+be declared in the same \fBschiff-geometry\fR file to define a discrete random
+variate of geometry distributions. This allow to finely tune the overall
+geometry distribution of soft particles with a collection of geometry
+distributions, each representing a specific sub-set of shapes of the soft
+particles to handle.
+.PP
+\fBschiff-geometry\fR supports two main geometry types: the \fBcylinder\fR and
+the \fBsphere\fR. A geometry type defined the shape of the soft particles that is
+then discretized by
+.BR schiff (1)
+in triangular meshes with respect to its \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 distribution of soft particles, one have to setup the
+distribution of the \fBradius\fR of a \fBsphere\fR geometry. A cylindrical
+distribution can be defined in two ways. The first way is to directly control
+the distribution of the \fBheight\fR and the \fBradius\fR of the cylinder. The
+second way is to fix its height/radius \fBaspect_ratio\fR and define the
+distribution of sphere \fBradius\fR whose volume is equal to the volume of the
+cylinder.
+.PP
+All the aforementioned 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 and are 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 as follow:
+ 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
+This section describes the \fBschiff\-geometry\fR grammar based on the YAML
+human readable data format [1]. 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>
+.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 ] # Discretisation along 2PI
+ [ \fBproba:\fI REAL\fR ]
+.TP
+<\fIdistribution\fR> ::=
+ \fIREAL\fR| <\fIlognormal\fR> | <\fIhistogram\fR>
+.TP
+<\fIlognormal\fR> ::=
+ \fBlognormal:
+ zeta: \fIREAL\fB
+ sigma: \fIREAL\fB
+.TP
+<\fIhistogram\fR> ::=
+ \fBhistogram:\fR
+ \fBlower: \fIREAL\fR
+ \fBupper: \fIREAL\fR
+ \fBprobabilities:\fR
+ <\fIprobabilities\-list\fR>
+.TP
+<\fIprobabilities\-list\fR> ::=
+ \fB- \fIREAL\fR
+ [ \fB-\fR <\fIprobabilities\-list\fR> ]
+.SH EXAMPLES
+.PP
+Soft particles 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
+Soft particles 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
+Soft particles are cylinders whose height/radius ratio 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: 1
+ radius:
+ histogram:
+ lower: 1.24
+ upper: 4.56
+ probabilities: [ 2, 1.2, 3, 0.2 ]\fR
+.PP
+Soft particles are spheres and cylinders with 2 times more spheres than
+cylinders. The cylinder parameters are controlled by lognormal distributions
+and spherical soft particles have a fixed 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 NOTE
+.TP
+[1]
+YAML Ain't Markup Language \- http://yaml.org
+.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 a list of per wavelength cross\-sections. Each line stores the
+estimated cross\-section for 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 micron), "E", "A" and "S" the estimation of the extinction,
+absorption and scattering cross\-sections, respectively, and "P" the estimated
+average projected area of the soft particles. 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 micron) 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 at "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. a set of N 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>
+ \fIempty-line\fR
+ <\fIinverse\-cumulative\-phase\-functions\fR>
+.PP
+\l'20'
+.TP
+<\fIcross\-sections\fR> ::=
+ \fIWAVELENGTH\fR <\fIextinction\fR> <\fIabsorption\fR> <\fIscattering\fR> <\fIarea\fR>
+ [ <\fIcross\-sections\fR> ]
+.TP
+<\fIextinction\fR> ::=
+ \fIESTIMATION STANDARD\-ERROR\fR
+.TP
+<\fIabsorption\fR> ::=
+ \fIESTIMATION STANDARD\-ERROR\fR
+.TP
+<\fIscattering\fR> ::=
+ \fIESTIMATION STANDARD\-ERROR\fR
+.TP
+<\fIarea\fR> ::=
+ \fIESTIMATION STANDARD\-ERROR\fR
+.PP
+\l'20'
+.TP
+<\fIinverse\-cumulative\-phase\-functions\fR> ::=
+ <\fIinverse\-cumulative\-descriptor\fR>
+ <\fIangles\fR>
+ \fIEMPTY-LINE\fR
+ [ <\fIinverse\-cumulative\-phase\-functions\fR> ]
+.TP
+<\fIinverse\-cumulative\-descriptor\fR> ::=
+ \fIWAVELENGTH THETA-LIMIT\fR <\fIPF(THETA\-LIMIT)\fR> <\fICDF(THETA\-LIMIT)\fR> \fIN\fR
+.TP
+<\fICDF(THETA\-LIMIT)\fR> ::=
+ \fIESTIMATION STANDARD\-ERROR\fR
+.TP
+<\fIPF(THETA\-LIMIT)\fR> ::=
+ \fIESTIMATION STANDARD\-ERROR\fR
+.TP
+<\fIangles\fR> ::=
+ \fIREAL\fR
+ [ <\fIangles\fR> ]
+.SH EXAMPLE
+The following output 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
+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,98 @@
+.TH SCHIFF 1
+.SH NAME
+schiff \- estimate radiative properties of soft particles
+.SH SYNOPSIS
+\fBschiff
+\fR[\fIOPTIONS\fR]...
+[\fIFILE\fR]
+.SH DESCRIPTION
+\fBschiff\fR computes the radiative properties of soft particles 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.
+.PP
+The shapes of the soft particles are controlled by the
+.BR schiff-geometry (5)
+file submitted by the \fB\-i\fR option. The per wavelength optical properties
+of the soft particles are stored in \fIFILE\fR where each line is formatted as
+"W Nr Kr Ne" whith "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 follows the
+.BR schiff-output (5)
+format and are written to the \fIOUTPUT\fR file or to standard ouptut whether
+the \fB\-o \fIOUTPUT\fR option is defined or not, respectively.
+.SH OPTIONS
+.TP
+.B \-a \fINUM_ANGLES\fR
+number of phase function scattering angles to estimate. These angles are
+uniformaly distributed in [0, PI], i.e. the value of the i^th angle, i in
+[0, \fINUM_ANGLES\fR-1], is i*PI/(\fINUM_ANGLES\fR-1). Default is 1000.
+.TP
+.B \-A \fINUM_ANGLES\fR
+number of scattering angles computed from the inverse cumulative phase
+function. The value of the i^th angle, i in [0, \fINUM_ANGLES\fR-1], is
+CDF^-1(i/(\fINUM_ANGLES-1\fR). Default is 2000.
+.TP
+.B \-d \fINUM_DIRS\fR
+number of sampled directions for each sampled geometry. Default is 100.
+.TP
+.B \-g \fINUM_PARTICLES\fR
+number of sampled soft particle instances. This is actually the number of
+realisations. Default is 10000.
+.TP
+.B \-G \fICOUNT\fR
+sample \fICOUNT\fR soft particles with respect to the defined distribution,
+dump their geometric 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
+.BR schiff-geometry (5)
+file that controls the geometry distribution of the soft particles.
+.TP
+.B \-l \fILENGTH\fR
+caracteristic length in micron of the soft particles.
+.TP
+.B \-n \fINUM_THREADS\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 \fIOUTPUT\fR with respect to the
+.BR schiff-output (5)
+format. If not defined, write results to standard output.
+.TP
+.B \-q
+do not print the helper message when no \fIFILE\fR is submitted.
+.TP
+.B \-w \fIW0\fR[\fB:\fIW1\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
+\fBschiff\fR is copyright \(co |Meso|Star> 2015-2016 (<contact@meso-star.com>).
+It is a free software released under the OSI approved CeCILL license. You are
+welcome de redistribute it under certain conditions. Refer to its COPYING file
+for details.
+.SH SEE ALSO
+.BR schiff-geometry (5),
+.BR schiff-output (5)
