commit 2236f0907c6e67c7483744a11707e14c25bf7ae7
parent 18160a766ef033d06df92467857fc86235dcdbf4
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Tue, 22 Mar 2016 15:30:44 +0100
Document the ellipsoid as sphere distribution
Minor refactoring of the schiff-geometry man page.
Diffstat:
| M | doc/schiff-geometry.5 | | | 161 | +++++++++++++++++++++++++++++++++++++++++++++---------------------------------- |
1 file changed, 92 insertions(+), 69 deletions(-)
diff --git a/doc/schiff-geometry.5 b/doc/schiff-geometry.5
@@ -15,37 +15,40 @@ particles.
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
+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 three geometry types: the \fBellipsoid\fR, the
\fBcylinder\fR and the \fBsphere\fR. A geometry type defined the overall shape
of the soft particles. This 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
-An ellipsoidal distribution of the soft particle shapes is controlled by the
-distribution of the 2 semi\-principal axis \fBa\fR and \fBc\fR of the
-\fBellipsoid\fR equation:
-.IP " " 4
+.IP \(bu 4
+An ellipsoidal geometry can be controlled in two ways. One can either
+directly define the distribution of its semi\-principal axis \fBa\fR and
+\fBc\fR, or control the distribution of the \fBradius\fR of an equivalent
+sphere whose volume is equal to the volume of an ellipsoid with a fixed a/c
+\fBaspect_ratio\fR. In both cases, the solved ellipsoid equation is:
+.IP " " 8
(x/\fBa\fR)^2 + (y/\fBa\fR)^2 + (z/\fBc\fR)^2 = 1
-.PP
-A cylindrical distribution can be defined in two ways. The first manner is to
-directly control the distribution of the \fBheight\fR and the \fBradius\fR of
-the \fBcylinder\fR. The second way is to fix its height/radius
-\fBaspect_ratio\fR and define the distribution of a sphere \fBradius\fR whose
-volume is equal to the volume of the \fBcylinder\fR. Finally, a spherical
-distribution is simply controlled by the distribution of the \fBradius\fR of
-the \fBsphere\fR.
-.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;
+Following the ellipsoidal geometry, a cylindrical geometry can be
+defined either directly or through a distribution of an equivalent sphere. In
+the first case, the \fBheight\fR and the \fBradius\fR of the \fBcylinder\fR are
+independently controlled by their own distribution. In the second case, the
+height/radius \fBaspect_ratio\fR is fixed and its volume is equal to the volume
+of a sphere whose \fRradius\fR is controlled by a distribution;
+.IP \(bu 4
+A spherical geometry is simply controlled by the distribution of its
+\fBradius\fR.
+.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. 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.
@@ -58,8 +61,9 @@ 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
+.IP " " 8
+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
@@ -81,14 +85,23 @@ the example section for illustrations of such alternatives.
| <\fIcylinder\-geometry\fR>
| <\fIsphere\-geometry\fR>
.TP
-<\fIellipsoid\-geometry\fR>
+<\fIellipsoid\-geometry\fR> ::=
+ \fBellipsoid:\fR
+ <\fIellipsoid\-parameters\fR>
+ | <\fIellipsoid\-sphere\-parameters\fR>
+.TP
+<\fIellipsoid\-parameters\fR> ::=
\fBa:\fR <\fIdistribution\fR>
\fBc:\fR <\fIdistribution\fR>
.TP
+<\fIellipsoid\-sphere\-parameters\fR> ::=
+ \fBradius:\fR <\fIdistribution\fR>
+ \fBaspect_ratio:\fR \fIREAL\fR
+.TP
<\fIcylinder\-geometry\fR> ::=
\fBcylinder:
\fBradius:\fR <\fIdistribution\fR>
- \fBheight:\fR <\fIdistribution\fR> | \fBaspect_ratio:\fR <\fIdistribution\fR>
+ \fBheight:\fR <\fIdistribution\fR> | \fBaspect_ratio:\fR \fIREAL\fR
[ \fBslices:\fI INTEGER\fR ]
[ \fBproba:\fI REAL\fR ]
.TP
@@ -122,66 +135,76 @@ the example section for illustrations of such alternatives.
.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
+.IP " " 4
+\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 ellipsoids whose one of its semi-principal axis is
distributed with respect to a lognormal distribution:
- \fBellipsoid:
- a: 1.0
- c:
- lognormal:
- sigma: 0.2
- zeta: 1.3\fR
+.IP " " 4
+\fBellipsoid:
+ a: 1.0
+ c:
+ lognormal:
+ sigma: 0.2
+ zeta: 1.3\fR
+.PP
+Soft particles are ellipsoids whose aspect ratio of its semi\-principal axis is
+fixed. Its volume is equal to the volume of an equivalent sphere whose radius
+follows an histogram distribution:
+.IP " " 4
+\fBellipsoid:
+ aspect_ratio: 0.33
+ radius:
+ histogram:
+ lower: 1
+ upper: 2.5
+ probabilities: [ 0.5, 2, 1 ]\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
+.IP " " 4
+\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
+.IP " " 4
+\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
+.IP " " 4
+\fB- sphere: { radius 1.12, proba: 2.0, slices: 64 }
+.IP " " 4
+\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)
-
