schiff

commit 5ab29f8ffab000ebc458af6234441e4915a9cb57
parent 79519f4013988ba0d38a9cff498467febbdfc4ba
Author: Vincent Forest <vincent.forest@meso-star.com>
Date:   Thu, 24 Mar 2016 15:10:35 +0100

Document the supershape geometry

Diffstat:
M
doc/schiff-geometry.5
 | 
61
++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----

1 file changed, 56 insertions(+), 5 deletions(-)
diff --git a/doc/schiff-geometry.5 b/doc/schiff-geometry.5
@@ -19,9 +19,9 @@ 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
+\fBschiff-geometry\fR supports four geometry types: the \fBellipsoid\fR, the
+\fBcylinder\fR, the \fBsphere\fR and the \fBsupershape\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.
@@ -43,6 +43,24 @@ 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.
+.IP \(bu 4
+A supershape is a generalisation of the superellipsoide 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 coordinate {theta, phi}, the
+corresponding 3D coordinate 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:
@@ -90,6 +108,7 @@ the example section for illustrations of such alternatives.
     <\fIellipsoid\-geometry\fR>
   | <\fIcylinder\-geometry\fR>
   | <\fIsphere\-geometry\fR>
+  | <\fIsupershape\-geometry\fR>
 .TP
 <\fIellipsoid\-geometry\fR> ::=
   \fBellipsoid:\fR
@@ -111,11 +130,24 @@ the example section for illustrations of such alternatives.
   [ \fBslices:\fI INTEGER\fR ]
   [ \fBproba:\fI REAL\fR ]
 .TP
-<\fIsphere\-geometry\fR>
+<\fIsphere\-geometry\fR> ::=
   \fBsphere:\fR
     \fBradius:\fR <\fIdistribution\fR>
   [ \fBslices:\fI INTEGER\fR ] # Discretisation along 2PI
   [ \fBproba:\fI REAL\fR ]
+.TP
+<\fIsupershape\-geometry\fR> ::=
+  \fBsupershape:\fR
+    \fBformula0:\fR <\fIsuperformula\fR>
+    \fBformula1:\fR <\fIsuperformula\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
@@ -202,12 +234,31 @@ an histogram:
       upper: 4.56
       probabilities: [ 2, 1.2, 3, 0.2 ]\fR
 .PP
+Soft particles are supershapes whose 2 parameters of each of its superformulas
+are controlled by gaussian distributions:
+.IP " " 4
+\fBsupershape:
+  formula0: 
+    A: 1
+    B: 1
+    M: { gaussian: { mu: 5, sigma: 1 } }
+    N0: 1
+    N1: 1
+    N2: { gaussian: { mu: 3, sigma: 1 } }
+  formula1: 
+    A: 1
+    B: 1
+    M: { gaussian: { mu: 1.2, sigma: 0.3 } }
+    N0: 1
+    N1: 1
+    N2: { gaussian: { mu: 1, sigma: 0.3 } } 
+.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 }
-.IP " " 4
+.br
 \fB- cylinder:
   radius: {lognormal: { sigma: 2.3, mu: 0.2 } }
   height: {lognormal: { mu: 1, sigma: 1.5 } }