commit 279862edbd47adcf7278314d8fc10bff014bbbe7
parent 78050abed8b3a27a8cd02681e4150f9d9a5c9f09
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Mon, 28 Mar 2016 18:11:48 +0200
Document the helical_pipe geometry
Diffstat:
| M | doc/schiff-geometry.5 | | | 105 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------- |
1 file changed, 77 insertions(+), 28 deletions(-)
diff --git a/doc/schiff-geometry.5 b/doc/schiff-geometry.5
@@ -20,15 +20,16 @@ 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 four geometry types: the \fBellipsoid\fR, the
-\fBcylinder\fR, the \fBsphere\fR and the \fBsupershape\fR.
+\fBschiff-geometry\fR supports five geometry types: the \fBellipsoid\fR, the
+\fBcylinder\fR, the \fBhelical_pipe\fR, the \fBsphere\fR and the
+\fBsupershape\fR.
.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
+.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
@@ -38,21 +39,46 @@ 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 helipsoid 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 spherical geometry is simply controlled by the distribution of 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":
-.IP " " 8
+.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
+.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:
-.IP " " 8
+.IP "" 8
x = r0(theta)*cos(theta) * r1(phi)*cos(phi)
.br
y = r0(theta)*sin(theta) * r1(phi)*cos(phi)
@@ -67,7 +93,7 @@ the constant distribution fixes the value of the parameter;
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
+.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,
@@ -81,7 +107,7 @@ 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
+.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
@@ -91,11 +117,9 @@ 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
-Each geometry has the 2 optionnal attributes \fBslices\fR and \fBproba\fR. The
-former controls the number of discret divisions along 2PI used to generate the
-triangulated mesh of the geometry. If it is not defined, \fBslices\fR is
-assumed to be 64. The latter defines the unnormalized probability to sample the
-geometry. By default, it is equal to 1.
+All the geometries have the \fBproba\fR optionnal 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>
@@ -107,11 +131,19 @@ geometry. By default, it is equal to 1.
\l'20'
.TP
<\fIgeometry\fR> ::=
- <\fIellipsoid\-geometry\fR>
- | <\fIcylinder\-geometry\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> | \fBaspect_ratio:\fR \fIREAL\fR
+ [ \fBslices:\fI INTEGER\fR ]
+ [ \fBproba:\fI REAL\fR ]
+.TP
<\fIellipsoid\-geometry\fR> ::=
\fBellipsoid:\fR
<\fIellipsoid\-parameters\fR> | <\fIellipsoid\-sphere\-parameters\fR>
@@ -126,12 +158,14 @@ geometry. By default, it is equal to 1.
\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 \fIREAL\fR
- [ \fBslices:\fI INTEGER\fR ]
- [ \fBproba:\fI REAL\fR ]
+<\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>
+ [ \fBslices_helicoid:\fI INTEGER\fR ]
+ [ \fBslices_circle:\fI INTEGER\fR ]
.TP
<\fIsphere\-geometry\fR> ::=
\fBsphere:\fR
@@ -183,7 +217,7 @@ geometry. By default, it is equal to 1.
.PP
Soft particles are spheres whose radius is distributed according to an
histogram:
-.IP " " 4
+.IP "" 4
\fBsphere:
radius:
histogram:
@@ -198,7 +232,7 @@ histogram:
.PP
Soft particles are ellipsoids whose one of its semi-principal axis is
distributed with respect to a lognormal distribution:
-.IP " " 4
+.IP "" 4
\fBellipsoid:
a: 1.0
c:
@@ -209,7 +243,7 @@ distributed with respect to a lognormal distribution:
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
+.IP "" 4
\fBellipsoid:
aspect_ratio: 0.33
radius:
@@ -221,7 +255,7 @@ follows an histogram distribution:
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
+.IP "" 4
\fBcylinder:
slices: 128
radius: 1
@@ -230,7 +264,7 @@ discretized in 128 slices along 2PI:
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:
-.IP " " 4
+.IP "" 4
\fBcylinder:
aspect_ratio: 1
radius:
@@ -239,9 +273,24 @@ an histogram:
upper: 4.56
probabilities: [ 2, 1.2, 3, 0.2 ]\fR
.PP
+Soft particle are helical pipes. Their helicoid curve is split in 256 steps
+while its meridian is discretised in 128 slices:
+.IP "" 4
+\fBhelical_pipe:
+ slices_helicoid: 256
+ slices_circle: 128
+ height : 4
+ pitch : { gaussian: { mu: 3, sigma: 1.3} }
+ radius_helicoid: { lognormal: { mu: 2, sigma: 0.4} }
+ radius_circle:
+ histogram:
+ lower: 1
+ upper: 1.5
+ probabilities: [ 1, 1.2, 0.2, 0.5, 1.4 ]
+.PP
Soft particles are supershapes whose 2 parameters of each of its superformulas
are controlled by gaussian distributions:
-.IP " " 4
+.IP "" 4
\fBsupershape:
formula0:
A: 1
@@ -261,7 +310,7 @@ are controlled by gaussian distributions:
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
+.IP "" 4
\fB- sphere: { radius 1.12, proba: 2.0, slices: 64 }
.br
\fB- cylinder:
