commit 0769fc3cbfb226a52c1d57a701b35b22bc0de9f2
parent d7664dc5eddafad289885d973f91feccc9e89204
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Wed, 6 Apr 2016 16:27:37 +0200
Update the schiff-geometry documentation
Take into account the new "equivalent sphere" format. Add some examples.
Diffstat:
| M | doc/schiff-geometry.5 | | | 121 | ++++++++++++++++++++++++++++++++++++++++++------------------------------------- |
1 file changed, 65 insertions(+), 56 deletions(-)
diff --git a/doc/schiff-geometry.5 b/doc/schiff-geometry.5
@@ -9,7 +9,7 @@ schiff-geometry \- control the shape of soft particles
\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
+program relies on this description to generate the shape of the sampled soft
particles.
.PP
A geometry is defined by a type and a set of parameters whose value is
@@ -19,27 +19,17 @@ 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
-A geometry type defined the overall shape of the soft particles.
-\fBschiff-geometry\fR supports five geometry types: the \fBellipsoid\fR, the
-\fBcylinder\fR, the \fBhelical_pipe\fR, the \fBsphere\fR and the
-\fBsupershape\fR.
+\fBschiff-geometry\fR supports the following geometry types:
.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:
+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
-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
-An helical pipe is an helicoid whose meridian shape is a circle that is
+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
@@ -64,20 +54,17 @@ c = \fBpitch\fR / 2PI
.br
A = sqrt(\fBradius_helicoid\fR^2 + c^2)
.IP \(bu 4
-A spherical geometry is simply controlled by the distribution of its
-\fBradius\fR.
+A \fBsphere\fR is simply defined by its \fBradius\fR.
.IP \(bu 4
-A supershape 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":
+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
-The 6 parameters of each superformula \- i.e. \fBA\fR, \fBB\fR, \fBM\fR,
-\fBN0\fR, \fBN1\fR and \fBN2\fR \- are controlled independently by their own
-distribution. Assuming a point with the spherical coordinates {theta, phi}, the
-corresponding 3D coordinates onto the supershape is obtained by evaluating the
-following relations:
+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
@@ -102,8 +89,8 @@ 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";
+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:
@@ -117,7 +104,22 @@ 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.
.PP
-All the geometries have the \fBproba\fR optionnal attribute that defines the
+When the \fBradius_sphere\fR optional parameter is defined, the relative shape
+of the geometry must be fixed, i.e. all other parameters must be constants. In
+this situation, only the volume of the geometry is variable; it is equal to the
+volume of an equivalent sphere whose radius is controlled by the distribution
+of the \fBradius_sphere\fR parameter.
+.PP
+The \fBslices\fR optional attribute controls the discretization of the
+geometries in triangular meshes, i.e. the number of discrete steps around 2PI.
+When not defined it is assumed to be 64. Note that the \fBhelical_pipe\fR
+geometry exposes 2 discretization parameters: \fBslices_circle\fR and
+\fBslices_helicoid\fR. The former controls the discretization of the meridian
+around 2PI while the later defines the total number of discrete steps along the
+helicoid curve. When not defined \fBslices_circle\fR and \fBslices_helicoid\fR
+are set to 64 and 128, respectively.
+.PP
+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
@@ -140,30 +142,26 @@ assumed to be equal to 1.
<\fIcylinder\-geometry\fR> ::=
\fBcylinder:
\fBradius:\fR <\fIdistribution\fR>
- \fBheight:\fR <\fIdistribution\fR> | \fBaspect_ratio:\fR \fIREAL\fR
+ \fBheight:\fR <\fIdistribution\fR>
+ [ \fBradius_sphere:\fR <\fIdistribution\fR> ]
[ \fBslices:\fI INTEGER\fR ]
[ \fBproba:\fI REAL\fR ]
.TP
<\fIellipsoid\-geometry\fR> ::=
\fBellipsoid:\fR
- <\fIellipsoid\-parameters\fR> | <\fIellipsoid\-sphere\-parameters\fR>
+ \fBa:\fR <\fIdistribution\fR>
+ \fBc:\fR <\fIdistribution\fR>
+ [ \fBradius_sphere:\fR <\fIdistribution\fR> ]
[ \fBslices:\fI INTEGER\fR ]
[ \fBproba:\fI REAL\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
<\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
@@ -177,6 +175,7 @@ assumed to be equal to 1.
\fBsupershape:\fR
\fBformula0:\fR <\fIsuperformula\fR>
\fBformula1:\fR <\fIsuperformula\fR>
+ [ \fBradius_sphere:\fR <\fIdistribution\fR> ]
[ \fBslices:\fI INTEGER\fR ]
[ \fBproba:\fI REAL\fR ]
.TP
@@ -240,13 +239,14 @@ distributed with respect to a lognormal distribution:
sigma: 0.2
mu: 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:
+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:
- aspect_ratio: 0.33
- radius:
+ a: 1.1
+ b: 0.3
+ radius_sphere:
histogram:
lower: 1
upper: 2.5
@@ -261,13 +261,14 @@ discretized in 128 slices along 2PI:
radius: 1
height: { gaussian: { mu: 1.3, sigma: 0.84 } }\fR
.PP
-Soft particles are cylinders whose height/radius ratio is fixed. Their volume
+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:
- aspect_ratio: 1
- radius:
+ height: 1.2
+ radius: 3.4
+ radius_sphere:
histogram:
lower: 1.24
upper: 4.56
@@ -275,7 +276,7 @@ an histogram:
.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 discretised in 128 slices:
+meridian is discretized in 128 slices:
.IP "" 4
\fBhelical_pipe:
slices_helicoid: 256
@@ -287,7 +288,7 @@ meridian is discretised in 128 slices:
histogram:
lower: 1
upper: 1.5
- probabilities: [ 1, 1.2, 0.2, 0.5, 1.4 ]
+ probabilities: [ 1, 1.2, 0.2, 0.5, 1.4 ]\fR
.PP
Soft particles are supershapes whose 2 parameters of each of its superformulas
are controlled by gaussian distributions:
@@ -306,7 +307,15 @@ are controlled by gaussian distributions:
M: { gaussian: { mu: 1.2, sigma: 0.3 } }
N0: 1
N1: 1
- N2: { gaussian: { mu: 1, sigma: 0.3 } }
+ N2: { gaussian: { mu: 1, sigma: 0.3 } }\fR
+.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:
+ 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
.PP
Soft particles are spheres and cylinders with 2 times more spheres than
cylinders. The cylinder parameters are controlled by lognormal distributions
@@ -315,10 +324,10 @@ and spherical soft particles have a fixed radius:
\fB- sphere: { radius 1.12, proba: 2.0, slices: 64 }
.br
\fB- 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
+ radius: {lognormal: { sigma: 2.3, mu: 0.2 } }
+ height: {lognormal: { mu: 1, sigma: 1.5 } }
+ slices: 32 # Discretisation in 32 slices
+ proba: 1\fR
.SH NOTES
.TP
[1]
