commit f7c6f370cfc64cccfe5321a5fd03e9312a769c60
parent 92ff34973acb72b330352ed3db364ee1ac12f2e6
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Tue, 24 Oct 2017 16:48:45 +0200
Reformat the man pages
Diffstat:
| M | doc/schiff-geometry.5 | | | 475 | +++++++++++++++++++++++++++++++++++++++++++++---------------------------------- |
| M | doc/schiff-output.5 | | | 160 | ++++++++++++++++++++++++++++++++----------------------------------------------- |
| M | doc/schiff.1 | | | 38 | ++++++++++++++++++++++++-------------- |
3 files changed, 362 insertions(+), 311 deletions(-)
diff --git a/doc/schiff-geometry.5 b/doc/schiff-geometry.5
@@ -18,86 +18,7 @@ be declared in the same \fBschiff-geometry\fR file to define a discrete random
variate of geometries. This allow to finely tune the shapes of the soft
particles with a collection of geometries, each representing a specific sub-set
of shapes of the soft particles to handle.
-.SS Geometry types
-\fBschiff-geometry\fR supports the following geometry types:
-.IP \(bu 4
-A \fBcylinder\fR is defined by its \fBheight\fR and its \fBradius\fR;
-.IP \(bu 4
-The shape of an \fBellipsoid\fR geometry is controlled by the length of its
-semi\-principal axises \fBa\fR and \fBc\fR used to evaluate the following
-equation:
-.IP "" 8
-(x/\fBa\fR)^2 + (y/\fBa\fR)^2 + (z/\fBc\fR)^2 = 1
-.IP \(bu 4
-An \fBhelical_pipe\fR is an helicoid whose meridian shape is a circle that is
-orthogonal to the helicoid slope. Its \fBpitch\fR defines the width of a
-complete helicoid turn and its \fBheight\fR controls the overall distance between
-the beginning and the end of the helicoid. Finally, the \fBradius_helicoid\fR
-and the \fBradius_circle\fR defines the radius of the helicoid and the radius
-of its meridian, respectively. Let "u" in [0, \fBheight\fR * 2PI / \fBpitch\fR]
-and "t" in [0, 2PI], the "X", "Y" and "Z" 3D coordinates of the helicoid points
-are computed from the following equations:
-.IP "" 8
-X(t, u) = x(t)*cos(u) - y(t)*sin(u)
-.br
-Y(t, u) = x(t)*sin(u) + y(t)*cos(u)
-.br
-Z(t, u) = z(t) + c*u
-.IP "" 8
-x(t) = \fBradius_helicoid\fR + \fBradius_circle\fR*cos(t)
-.br
-y(t) = -\fBradius_circle\fR * c / A * sin(t)
-.br
-z(t) = \fBradius_circle\fR*\fBradius_helicoid\fR / A * sin(t)
-.IP "" 8
-c = \fBpitch\fR / 2PI
-.br
-A = sqrt(\fBradius_helicoid\fR^2 + c^2)
-.IP \(bu 4
-A \fBsphere\fR is simply defined by its \fBradius\fR.
-.IP \(bu 4
-A \fBsupershape\fR is a generalisation of the superellipsoid that is well
-suited to represent many complex shapes found in the nature. It is controlled
-by 2 superformulas, each defining a radius "r" for a given angle "a":
-.IP "" 8
-r(a) = ( |cos(\fBM\fR*a/4)/\fBA\fR)|^\fBN1\fR + |sin(\fBM\fR*a/4)/\fBB\fR|^\fBN2\fR )^{-1/\fBN0\fR}
-.IP "" 4
-Assuming a point with the spherical coordinates {theta, phi}, the corresponding
-3D coordinates onto the supershape is obtained by evaluating the following
-relations:
-.IP "" 8
-x = r0(theta)*cos(theta) * r1(phi)*cos(phi)
-.br
-y = r0(theta)*sin(theta) * r1(phi)*cos(phi)
-.br
-z = r1(phi)*sin(phi)
-.SS Parameter distributions
-The geometry parameters can be distributed with respect to the following
-distributions:
-.IP \(bu 4
-the constant distribution fixes the value of the parameter;
-.IP \(bu 4
-the \fBgaussian\fR distribution uses the following probability distribution to
-define the parameter according to the mean value \fBmu\fR and the standard
-deviation \fBsigma\fR:
-.IP "" 8
-P(x) dx = 1 / (\fBsigma\fR*sqrt(2*PI)) * exp(1/2*((x-\fBmu\fR)/\fBsigma\fR)^2) dx
-.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 \fBmu\fR and a standard deviation \fBsigma\fR as follow:
-.IP "" 8
-P(x) dx = 1/(log(\fBsigma\fR)*x*sqrt(2*PI) *
- exp(-(ln(x)-log(\fBmu\fR))^2 / (2*log(\fBsigma\fR)^2)) dx
-.SS Grammar
+.SH 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
@@ -122,102 +43,219 @@ are set to 64 and 128, respectively.
All the geometries have the \fBproba\fR optional attribute that defines the
unnormalized probability to sample the geometry. If it is not defined, it is
assumed to be equal to 1.
-.TP
-\fBschiff\-geometry\fR ::=
- <\fIgeometry\fR> | <\fIgeometry\-list>
-.TP
-<\fIgeometry\-list\fR> ::=
- \fB-\fR <\fIgeometry\fR>
- [ \fB-\fR <\fIgeometry\fR> ]
-.PP
-\l'20'
-.TP
-<\fIgeometry\fR> ::=
- <\fIcylinder\-geometry\fR>
- | <\fIellipsoid\-geometry\fR>
- | <\fIhelical\-pipe\-geometry\fR>
- | <\fIsphere\-geometry\fR>
- | <\fIsupershape\-geometry\fR>
-.TP
-<\fIcylinder\-geometry\fR> ::=
- \fBcylinder:
- \fBradius:\fR <\fIdistribution\fR>
- \fBheight:\fR <\fIdistribution\fR>
- [ \fBradius_sphere:\fR <\fIdistribution\fR> ]
- [ \fBslices:\fI INTEGER\fR ]
- [ \fBproba:\fI REAL\fR ]
-.TP
-<\fIellipsoid\-geometry\fR> ::=
- \fBellipsoid:\fR
- \fBa:\fR <\fIdistribution\fR>
- \fBc:\fR <\fIdistribution\fR>
- [ \fBradius_sphere:\fR <\fIdistribution\fR> ]
- [ \fBslices:\fI INTEGER\fR ]
- [ \fBproba:\fI REAL\fR ]
-.TP
-<\fIhelical\-pipe\-geometry\fR> ::=
- \fBhelical_pipe\fR:
- \fBpitch:\fR <\fIdistribution\fR>
- \fBheight:\fR <\fIdistribution\fR>
- \fBradius_helicoid:\fR <\fIdistribution\fR>
- \fBradius_circle:\fR <\fIdistribution\fR>
- [ \fBradius_sphere:\fR <\fIdistribution\fR> ]
- [ \fBslices_helicoid:\fI INTEGER\fR ]
- [ \fBslices_circle:\fI INTEGER\fR ]
-.TP
-<\fIsphere\-geometry\fR> ::=
- \fBsphere:\fR
- \fBradius:\fR <\fIdistribution\fR>
- [ \fBslices:\fI INTEGER\fR ]
- [ \fBproba:\fI REAL\fR ]
-.TP
-<\fIsupershape\-geometry\fR> ::=
- \fBsupershape:\fR
- \fBformula0:\fR <\fIsuperformula\fR>
- \fBformula1:\fR <\fIsuperformula\fR>
- [ \fBradius_sphere:\fR <\fIdistribution\fR> ]
- [ \fBslices:\fI INTEGER\fR ]
- [ \fBproba:\fI REAL\fR ]
-.TP
-<\fIsuperformula\fR> ::=
- \fBA:\fR <\fIdistribution\fR>
- \fBB:\fR <\fIdistribution\fR>
- \fBM:\fR <\fIdistribution\fR>
- \fBN0:\fR <\fIdistribution\fR>
- \fBN1:\fR <\fIdistribution\fR>
- \fBN2:\fR <\fIdistribution\fR>
-.PP
-\l'20'
-.TP
-<\fIdistribution\fR> ::=
- \fIREAL\fR| <\fIlognormal\fR> | <\fIgaussian\fR\> | <\fIhistogram\fR>
-.TP
-<\fIlognormal\fR> ::=
- \fBlognormal:
- mu: \fIREAL\fB
- sigma: \fIREAL\fR
-.TP
-<\fIgaussian\fR> ::=
- \fBgaussian:
- mu: \fIREAL\fB
- sigma: \fIREAL\fR
-.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> ]
+.PP
+.RS 4
+.nf
+<schiff\-geometry> ::= <geometry> | <geometry\-list>
+
+<geometry\-list> ::= \- <geometry>
+ [ \- <geometry> ]
+
+<geometry> ::= <cylinder\-geometry>
+ | <ellipsoid\-geometry>
+ | <helical\-pipe\-geometry>
+ | <sphere\-geometry>
+ | <supershape\-geometry>
+
+<cylinder\-geometry> ::= cylinder:
+ radius: <distribution>
+ height: <distribution>
+ [ radius_sphere: <distribution> ]
+ [ slices: INTEGER ]
+ [ proba: REAL ]
+
+<ellipsoid\-geometry> ::= ellipsoid:
+ a: <distribution>
+ c: <distribution>
+ [ radius_sphere: <distribution> ]
+ [ slices: INTEGER ]
+ [ proba: REAL ]
+
+<helical\-pipe\-geometry> ::= helical_pipe:
+ pitch: <distribution>
+ height: <distribution>
+ radius_helicoid: <distribution>
+ radius_circle: <distribution>
+ [ radius_sphere: <distribution> ]
+ [ slices_helicoid: INTEGER ]
+ [ slices_circle: INTEGER ]
+
+<sphere\-geometry> ::= sphere:
+ radius: <distribution>
+ [ slices: INTEGER ]
+ [ proba: REAL ]
+
+<supershape\-geometry> ::= supershape:
+ formula0: <superformula>
+ formula1: <superformula>
+ [ radius_sphere: <distribution> ]
+ [ slices: INTEGER ]
+ [ proba: REAL ]
+
+<superformula> ::= A: <distribution>
+ B: <Idistribution>
+ M: <distribution>
+ N0: <distribution>
+ N1: <distribution>
+ N2: <distribution>
+
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+
+<distribution> ::= <constant>
+ | <gaussian>
+ | <histogram>
+ | <lognormal>
+
+<constant> ::= REAL
+
+<lognormal> ::= lognormal:
+ mu: REAL
+ sigma: REAL
+
+<gaussian> ::= gaussian:
+ mu: REAL
+ sigma: REAL
+
+<histogram> ::= histogram:
+ lower: REAL
+ upper: REAL
+ probabilities:
+ <probabilities\-list>
+
+<probabilities\-list> ::= \- REAL
+ [ \- <probabilities\-list> ]
+.fi
+.SH GEOMETRY TYPES
+.PP
+\fBcylinder\fR
+.PP
+.RS 4
+A cylinder is simply defined by its \fBheight\fR and a its \fBradius\fR.
+.RE
+.PP
+\fBellipsoid\fR
+.PP
+.RS 4
+The shape of an ellipsoid geometry is controlled by the length of its
+semi\-principal axises \fBa\fR and \fBc\fR used to evaluate the following
+equation:
+.PP
+.RS 8
+.nf
+(x/\fBa\fR)^2 + (y/\fBa\fR)^2 + (z/\fBc\fR)^2 = 1
+.fi
+.RE
+.RE
+.PP
+\fBhelical_pipe\fR
+.RS 4
+.PP
+Helicoid whose meridian shape is a circle that is orthogonal to the helicoid
+slope. Its \fBpitch\fR defines the width of a complete helicoid turn and its
+\fBheight\fR controls the overall distance between the beginning and the end of
+the helicoid. Finally, the \fBradius_helicoid\fR and the \fBradius_circle\fR
+defines the radius of the helicoid and the radius of its meridian,
+respectively. Let "u" in [0, \fBheight\fR * 2PI / \fBpitch\fR] and "t" in [0,
+2PI], the "X", "Y" and "Z" 3D coordinates of the helicoid points are computed
+from the following equations:
+.PP
+.RS 8
+.nf
+X(t, u) = x(t)*cos(u) - y(t)*sin(u)
+Y(t, u) = x(t)*sin(u) + y(t)*cos(u)
+Z(t, u) = z(t) + c*u
+.PP
+x(t) = \fBradius_helicoid\fR + \fBradius_circle\fR*cos(t)
+y(t) = -\fBradius_circle\fR * c / A * sin(t)
+z(t) = \fBradius_circle\fR*\fBradius_helicoid\fR / A * sin(t)
+.PP
+c = \fBpitch\fR / 2PI
+A = sqrt(\fBradius_helicoid\fR^2 + c^2)
+.fi
+.RE
+.RE
+.PP
+\fBsphere\fR
+.RS 4
+.PP
+A sphere is simply defined by its \fBradius\fR.
+.RE
+.PP
+\fBsupershape\fR
+.RS 4
+.PP
+Generalisation of the superellipsoid that is well suited to represent many
+complex shapes found in the nature. It is controlled by 2 superformulas, each
+defining a radius "r" for a given angle "a":
+.PP
+.RS 8
+.nf
+r(a) = ( |cos(\fBM\fR*a/4)/\fBA\fR)|^\fBN1\fR + |sin(\fBM\fR*a/4)/\fBB\fR|^\fBN2\fR )^{-1/\fBN0\fR}
+.fi
+.RE
+.PP
+Assuming a point with the spherical coordinates {theta, phi}, the corresponding
+3D coordinates onto the supershape is obtained by evaluating the following
+relations:
+.RS 8
+.PP
+.nf
+x = r0(theta)*cos(theta) * r1(phi)*cos(phi)
+y = r0(theta)*sin(theta) * r1(phi)*cos(phi)
+z = r1(phi)*sin(phi)
+.fi
+.SH PARAMETER DISTRIBUTIONS
+.PP
+\fBconstant\fR
+.RS 4
+.PP
+Fixe the value of the parameter.
+.RE
+.PP
+\fBgaussian\fR
+.RS 4
+.PP
+Use the following probability distribution to define the parameter according to
+the mean value \fBmu\fR and the standard deviation \fBsigma\fR:
+.PP
+.RS 8
+.nf
+P(x) dx = 1 / (\fBsigma\fR*sqrt(2*PI)) * exp(1/2*((x-\fBmu\fR)/\fBsigma\fR)^2) dx
+.fi
+.RE
+.RE
+.PP
+\fBhistogram\fR
+.RS 4
+.PP
+Split 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";
+.RE
+.PP
+\fBlognormal\fR
+.RS 4
+.PP
+Distribute the parameter with respect to a mean value \fBmu\fR and a standard
+deviation \fBsigma\fR as follow:
+.PP
+.RS 8
+.nf
+P(x) dx = 1/(log(\fBsigma\fR)*x*sqrt(2*PI) *
+ exp(-(ln(x)-log(\fBmu\fR))^2 / (2*log(\fBsigma\fR)^2)) dx
+.fi
.SH EXAMPLES
.PP
Soft particles are spheres whose radius is distributed according to an
histogram:
-.IP "" 4
-\fBsphere:
+.PP
+.RS 4
+.nf
+sphere:
radius:
histogram:
lower: 1.0 # Min radius
@@ -227,58 +265,78 @@ histogram:
- 1
- 0.4
- 1.23
- - 3\fR
+ - 3
+.fi
+.RE
.PP
Soft particles are ellipsoids whose one of its semi-principal axis is
distributed with respect to a lognormal distribution:
-.IP "" 4
-\fBellipsoid:
+.PP
+.RS 4
+.nf
+ellipsoid:
a: 1.0
c:
lognormal:
sigma: 0.2
- mu: 1.3\fR
+ mu: 1.3
+.fi
+.RE
.PP
Soft particles are ellipsoids whose semi\-principal axises are fixed. Its
volume is equal to the volume of an equivalent sphere whose radius follows an
histogram distribution:
-.IP "" 4
-\fBellipsoid:
+.PP
+.RS 4
+.nf
+ellipsoid:
a: 1.1
b: 0.3
radius_sphere:
histogram:
lower: 1
upper: 2.5
- probabilities: [ 0.5, 2, 1 ]\fR
+ probabilities: [ 0.5, 2, 1 ]
+.fi
+.RE
.PP
Soft particles are cylinders. Their radius is constant and their height is
distributed according to a gaussian distribution. The cylinder geometry is
discretized in 128 slices along 2PI:
-.IP "" 4
-\fBcylinder:
+.PP
+.RS 4
+.nf
+cylinder:
slices: 128
radius: 1
- height: { gaussian: { mu: 1.3, sigma: 0.84 } }\fR
+ height: { gaussian: { mu: 1.3, sigma: 0.84 } }
+.fi
+.RE
.PP
Soft particles are cylinders whose height and radius are fixed. Their volume
is equal to the volume of a sphere whose radius is distributed with respect to
an histogram:
-.IP "" 4
-\fBcylinder:
+.PP
+.RS 4
+.nf
+cylinder:
height: 1.2
radius: 3.4
radius_sphere:
histogram:
lower: 1.24
upper: 4.56
- probabilities: [ 2, 1.2, 3, 0.2 ]\fR
+ probabilities: [ 2, 1.2, 3, 0.2 ]
+.fi
+.RE
.PP
Soft particle are helical pipes whose attributes are controlled by several
distribution types. Their helicoid curve is split in 256 steps while its
meridian is discretized in 128 slices:
-.IP "" 4
-\fBhelical_pipe:
+.PP
+.RS 4
+.nf
+helical_pipe:
slices_helicoid: 256
slices_circle: 128
height : 4
@@ -288,12 +346,16 @@ meridian is discretized in 128 slices:
histogram:
lower: 1
upper: 1.5
- probabilities: [ 1, 1.2, 0.2, 0.5, 1.4 ]\fR
+ probabilities: [ 1, 1.2, 0.2, 0.5, 1.4 ]
+.fi
+.RE
.PP
Soft particles are supershapes whose 2 parameters of each of its superformulas
are controlled by gaussian distributions:
-.IP "" 4
-\fBsupershape:
+.PP
+.RS 4
+.nf
+supershape:
formula0:
A: 1
B: 1
@@ -307,30 +369,39 @@ are controlled by gaussian distributions:
M: { gaussian: { mu: 1.2, sigma: 0.3 } }
N0: 1
N1: 1
- N2: { gaussian: { mu: 1, sigma: 0.3 } }\fR
+ N2: { gaussian: { mu: 1, sigma: 0.3 } }
+.fi
+.RE
.PP
Soft particles are supershapes with the same shape. Their volume is controlled
by an equivalent sphere whose radius follows a lognormal distribution:
-.IP "" 4
-\fBsupershape:
+.PP
+.RS 4
+.nf
+supershape:
formula0: { A: 1, B: 1, M: 3, N0: 3, N1: 3, N2: 5 }
formula1: { A: 2, B: 1.1, M: 3, N0: 1, N1: 1, N2: 1 }
- radius_sphere : { lognormal: { mu: 2.2, sigma: 1.3 } }\fR
+ radius_sphere : { lognormal: { mu: 2.2, sigma: 1.3 } }
+.fi
+.RE
.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:
-.IP "" 4
-\fB- sphere: { radius 1.12, proba: 2.0, slices: 64 }
-.br
-\fB- cylinder:
+.PP
+.RS 4
+.nf
+- sphere: { radius 1.12, proba: 2.0, slices: 64 }
+
+- cylinder:
radius: {lognormal: { sigma: 2.3, mu: 0.2 } }
height: {lognormal: { mu: 1, sigma: 1.5 } }
slices: 32 # Discretisation in 32 slices
- proba: 1\fR
+ proba: 1
+.fi
+.RE
.SH NOTES
-.TP
-[1]
-YAML Ain't Markup Language \- http://yaml.org
+.PP
+[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
@@ -66,73 +66,68 @@ ascending order with respect to their associated wavelength.
The following grammar formally describes the
.BR schiff (1)
output format.
-.TP
-\fBschiff-output\fR ::=
- <\fIcross\-sections\fR>
- \fIEMPTY-LINE\fR
- <\fIphase\-function\-descriptor\fR>
- \fIEMPTY-LINE\fR
- <\fIphase\-functions\fR>
- \fIEMPTY-LINE\fR
- <\fIcumulative\-phase\-functions\fR>
- \fIEMPTY-LINE\fR
- <\fIinverse\-cumulative\-phase\-functions\fR>
- \fIEMPTY-LINE\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
-<\fIphase\-functions\-descriptors\fR> ::=
- \fIWAVELENGTH THETA\fR <\fIPF(THETA)\fR> <\fICDF(THETA)\fR> \fIN\fR \fI#ANGLES\fR \fI#INVCUM\fR
- [ <\fIphase\-functions\-descriptors\fR> ]
-.TP
-<\fICDF(THETA)\fR> ::=
- \fIESTIMATION STANDARD\-ERROR\fR
-.TP
-<\fIPF(THETA)\fR> ::=
- \fIESTIMATION STANDARD\-ERROR\fR
-.PP
-\l'20'
-.TP
-<\fIphase\-functions\fR> ::=
- <\fIfunction\-entries\fR>
- [ \fIEMPTY-LINE\fR
- <\fIphase\-functions\fR> ]
-.TP
-<\fIcumulative\-phase\-functions\fR> ::=
- <\fIfunction\-entries\fR>
- [ \fIEMPTY-LINE\fR
- <\fIcumulative\-phase\-functions\fR> ]
-.TP
-<\fIfunction\-entries\fR> ::=
- \fIANGLE ESTIMATION STANDARD-ERROR\fR
- [ <\fIphase\-function\-entries\fR> ]
-.TP
-<\fIinverse\-cumulative\-phase\-functions\fR> ::=
- <\fIinverse\-function\-entries\fR>
- [ \fIEMPTY-LINE\fR
- <\fIinverse\-cumulative\-phase\-functions\fR> ]
-.TP
-<\fIinverse\-function\-entries\fR> ::=
- \fIPROBABILITY ANGLE\fR
- [ <\fIinverse\-function\-entries\fR> ]
+The output values are ASCII data formatted line by line. By convention, in the
+following grammar the line data are listed between quote marks. The grammar may
+use new lines for formatting constraints, but data are actually on the same
+line while a closed quote mark is not defined.
+.PP
+.RS 4
+.nf
+<schiff\-output> ::= <Icross\-sections>
+ EMPTY\-LINE
+ <phase\-function\-descriptor>
+ EMPTY\-LINE
+ <phase\-functions>
+ EMPTY-LINE
+ <cumulative\-phase\-functions>
+ EMPTY\-LINE
+ <inverse\-cumulative\-phase\-functions>
+ EMPTY\-LINE
+
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+
+<cross\-sections> ::= "WAVELENGTH <extinction> <absorption>
+ <scattering> <area>"
+ [ <cross\-sections> ]
+
+<extinction> ::= ESTIMATION STANDARD\-ERROR
+<absorption> ::= ESTIMATION STANDARD\-ERROR
+<scattering> ::= ESTIMATION STANDARD\-ERROR
+<area> ::= ESTIMATION STANDARD\-ERROR
+
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+
+<phase\-functions\-descriptors>
+ ::= "WAVELENGTH THETA <PF(THETA)> <CDF(THETA)>
+ N #ANGLES #INVCUM"
+ [ <phase\-functions\-descriptors> ]
+
+<CDF(THETA)> ::= ESTIMATION STANDARD\-ERROR
+<PF(THETA)> ::= ESTIMATION STANDARD\-ERROR
+
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+
+<phase\-functions> ::= <function\-entries>
+ [ EMPTY-LINE
+ <phase\-functions> ]
+
+<cumulative\-phase\-functions>
+ ::= <function\-entries>
+ [ EMPTY-LINE
+ <cumulative\-phase\-functions> ]
+
+<function\-entries> ::= ANGLE ESTIMATION STANDARD-ERROR
+ [ <phase\-function\-entries> ]
+
+<inverse\-cumulative\-phase\-functions>
+ ::= <inverse\-function\-entries>
+ [ EMPTY-LINE
+ <inverse\-cumulative\-phase\-functions> ]
+
+<inverse\-function\-entries>
+ ::= PROBABILITY ANGLE
+ [ <inverse\-function\-entries> ]
+.fi
.SH EXAMPLE
The following output is emitted by the
.BR schiff (1)
@@ -141,73 +136,48 @@ 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.
+.RS 4
.PP
+.nf
0.3 10.61 0.20 9.51e-3 2.37e-4 10.6 0.20 5.25 0.10 \fB# X\-sections\fR
-.br
0.6 11.15 0.25 4.76e-3 1.19e-4 11.1 0.25 5.25 0.10 \fB# X\-sections\fR
-.PP
0.3 0.18 1.37 17.6 7.74 0.73 0.80 1000 2000 \fB# descriptor\fR
-.br
0.6 0.26 9.81 5.26 7.65 0.48 2.90 1000 2000 \fB# descriptor\fR
-.PP
0 520.23 64.2971 \fB# Phase function (0.3 micron)\fR
-.br
0.00314474 474.315 50.6471
-.br
...
-.br
3.13845 0.0196258 0
-.br
3.14159 0.0196259 0
.PP
0 150.183 25.4822 \fB# Phase function (0.6 micron)\fR
-.br
0.00314474 145.969 23.7955
-.br
...
-.br
3.13845 0.00262338 0
-.br
3.14159 0.00262338 0
.PP
0 0 0 \fB# Cumulative (0.3 micron)\fR
-.br
0.00314474 0.0154297 0.00177366
-.br
...
-.br
3.13845 0.999999 0
-.br
3.14159 1 0
.PP
0 0 0 \fB# Cumulative (0.6 micron)\fR
-.br
0.00314474 0.00460001 0.000765182
-.br
...
-.br
3.13845 1 0
-.br
3.14159 1 0
.PP
0 0 \fB# Inverse cumulative (0.3 micron)\fR
-.br
0.00050025 0.000101956
-.br
...
-.br
0.9995 3.05143
-.br
1 3.14159
.PP
0 0 \fB# Inverse cumulative (0.6 micron)\fR
-.br
0.00050025 0.00034199
-.br
...
-.br
0.9995 2.89409
-.br
1 3.14159
+.fi
.SH SEE ALSO
.BR schiff (1)
diff --git a/doc/schiff.1 b/doc/schiff.1
@@ -88,15 +88,23 @@ the \fBgeometry.yaml\fR file and its optical properties in the \fBproperties\fR
file. The characteristic length of the soft particle shapes is \fB2.3\fR
microns and the estimations is performed for the wavelengths \fB0.45\fR and
\fB0.6\fR microns. The results are written to the standard output:
-.IP " " 4
-$ \fBschiff -i geometry.yaml -l 2.3 -w 0.45:0.6 properties\fR
+.PP
+.RS 4
+.nf
+$ schiff -i geometry.yaml -l 2.3 -w 0.45:0.6 properties
+.fi
+.RE
.PP
The soft particles have a characteristic length of \fB1\fR and their shape is
controlled by the \fBmy_geom.yaml\fR file. Their optical properties are read
from the standard input. The estimated wavelelength is \fB0.66\fR microns and
the results are written to the \fBmy_result\fR file:
-.IP " " 4
-$ \fBschiff -w 0.66 -l 1.0 -i my_geom.yaml -o my_result\fR
+.PP
+.RS 4
+.nf
+$ schiff -w 0.66 -l 1.0 -i my_geom.yaml -o my_result
+.fi
+.RE
.PP
Sample \fB10\fR soft particles whose shape is defined by the \fBgeometry.yaml\fR
file and write their triangulated geometric data to the \fBtemp_output\fR file.
@@ -105,18 +113,20 @@ Use the
Unix command to split the \fBtemp_output\fR file in 10 files named
particle<\fINUM\fR>.obj, with NUM in [0, 9], each storing the geometric data of
a sampled soft particle:
-.IP " " 4
-$ \fBschiff -i geometry.yaml -G 10 -o temp_output\fR
-.br
-$ \fBcsplit temp_output -z /^g\\ / {*} -f particle -b %d.obj\fR
+.PP
+.RS 4
+.nf
+$ schiff -i geometry.yaml -G 10 -o temp_output
+$ csplit temp_output -z /^g\\ / {*} -f particle -b %d.obj
+.fi
+.RE
+.PP
.SH NOTES
-.TP
-[1]
-L. I. Schiff, 1956. Approximation Method for Short Wavelength or High\-Energy
+.PP
+[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.
+.PP
+[2] J. Charon, S. Blanco, J. F. Cornet, J. Dauchet, M. El Hafi, R. Fournier, M.
Kaissar Abboud, S. Weitz, 2015. Monte Carlo Implementation of Schiff's
Approximation for Estimating Radiative Properties of Homogeneous,
Simple\-Shaped and Optically Soft Particles: Application to Photosynthetic
