commit 1365d1470addb6947bec5c757032f1d7daebf103
parent 747d6686186a368619dbf1313e0e9bf047b6b6a0
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Tue, 29 Mar 2016 15:52:03 +0200
Major update of the schiff-output documentation
Take into account the data layout of the schiff output (phase function,
cumulative, phase function descriptors, etc.)
Diffstat:
| M | doc/schiff-output.5 | | | 197 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------------------- |
1 file changed, 142 insertions(+), 55 deletions(-)
diff --git a/doc/schiff-output.5 b/doc/schiff-output.5
@@ -10,9 +10,10 @@ 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
+program is a collection of ASCII floating point data. Each set of floating
+point values are separated by an empty line. The first set 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 microns), "E", "A" and "S" the estimation of the extinction,
@@ -21,34 +22,46 @@ particle, and "P" the estimated average projected area of the soft particles
expressed in square microns per particle. 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 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
+Following the list of cross\-sections comes the list of phase function
+descriptors. Each descriptor is a line that gives informations on the
+[[inverse] cumulative] phase functions. It is formatted as "W theta-l Ws Ws-SE
+Wc Wc-SE n nangles nangles\-inv" 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 at
+"theta-l", "n" the parameter of the model used to analytically evaluate the
+phase function for large scattering angles (i.e. angles greater than "theta-l"),
+"nangles" the number of scattering angles (\fB\-a\fR option of
+.BR schiff (1))
+and "nangles\-inv" the number of inverse cumulative phase function values
+(\fB\-A\fR option of
+.BR schiff (1)).
+The "Ws-SE" and "Wc-SE" values are the standard error of the "Ws" and "Wc"
+estimations, respectively.
+.PP
+Then there is the list of phase functions, each stored as a list of lines
+formatted as "A E SE" where "E" is the expected value of the phase function for
+the input scattering angle "A" in radians, and "SE" its standard error. The
+number of scattering angles is controlled by the \fB\-a\fR option of
+.BR schiff (1).
+.PP
+After the phase functions come the cumulative phase functions that follow the
+format of the phase functions, i.e. each cumulative phase function is a list a
+lines \- one per scattering angle \- that defines the input scattering angle in
+radians, followed by the expected value and the standard error of its cumulative
+phase function.
+.PP
+Finally, there is the the inverse cumulative phase functions. Each of these
+functions lists a set of N probabilities in [0, 1] and its corresponding
+scattering angles in [0, PI]. The number of entries of the inverse cumulative
+phase functions is 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.
+Note that the cross sections, the phase function descriptors, the phase
+functions, their cumulative and their inverse cumulative are all sorted in
+ascending order with respect to their associated wavelength.
.SS Grammar
The following grammar formally describes the
.BR schiff (1)
@@ -56,13 +69,20 @@ output format.
.TP
\fBschiff-output\fR ::=
<\fIcross\-sections\fR>
- \fIempty-line\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>
+ \fIWAVELENGTH\fR <\fIextinction\fR> <\fIabsorption\fR> <\fIscattering\fR> <\fIarea\fR>
[ <\fIcross\-sections\fR> ]
.TP
<\fIextinction\fR> ::=
@@ -79,48 +99,115 @@ output format.
.PP
\l'20'
.TP
-<\fIinverse\-cumulative\-phase\-functions\fR> ::=
- <\fIinverse\-cumulative\-descriptor\fR>
- <\fIangles\fR>
- \fIEMPTY-LINE\fR
- [ <\fIinverse\-cumulative\-phase\-functions\fR> ]
+<\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
-<\fIinverse\-cumulative\-descriptor\fR> ::=
- \fIWAVELENGTH THETA-LIMIT\fR <\fIPF(THETA\-LIMIT)\fR> <\fICDF(THETA\-LIMIT)\fR> \fIN\fR
-.TP
-<\fICDF(THETA\-LIMIT)\fR> ::=
+<\fICDF(THETA)\fR> ::=
\fIESTIMATION STANDARD\-ERROR\fR
.TP
-<\fIPF(THETA\-LIMIT)\fR> ::=
+<\fIPF(THETA)\fR> ::=
\fIESTIMATION STANDARD\-ERROR\fR
+.PP
+\l'20'
.TP
-<\fIangles\fR> ::=
- \fIREAL\fR
- [ <\fIangles\fR> ]
+<\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> ]
.SH EXAMPLE
The following output is emitted by the
.BR schiff (1)
-program invoked on the wavelengths 0.4 and 0.6 micron.
+program invoked on the wavelengths 0.3 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
+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.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
+0 0 \fB# Inverse cumulative (0.3 micron)\fR
+.br
+0.00050025 0.000101956
+.br
...
- 2.74326
- 3.14159
+.br
+0.9995 3.05143
+.br
+1 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
+0 0 \fB# Inverse cumulative (0.6 micron)\fR
+.br
+0.00050025 0.00034199
+.br
...
- 2.93276
- 3.14159
+.br
+0.9995 2.89409
+.br
+1 3.14159
.SH SEE ALSO
.BR schiff (1)
