SCHIFF-GEOMETRY(5) File Formats Manual SCHIFF-GEOMETRY(5)

schiff-geometry — control the shape of soft particles

schiff-geometry is a plain text file format that controls the geometry distribution of soft particles. The schiff(1) program relies on this description to generate the shape of the sampled soft particles.

A schiff-geometry may contain one or more geometric shapes to be distributed In the latter case, each geometric shape is assigned a probability such that the set defines a discrete random variable comprising the geometric shapes that make up the mixture. 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:

⟨schiff-geometry⟩ ::= ⟨geometry⟩ | ⟨geometry-list⟩
 
⟨geometry-list⟩ ::= "-" ⟨geometry⟩
...

A geometry is defined by its type (section GEOMETRIC SHAPES) and a set of parameters whose value is controlled by a distribution (section PARAMETER DISTRIBUTIONS).

Note that a schiff-geometry file is actually a YAML file. This format provides several ways to define a mapping or a sequence of data. In grammar rules, the most detailed form is always used, but it is possible to opt for any other, more concise form instead (see section EXAMPLES).

The list of supported geometric shapes are as follows:

⟨geometry⟩ ::= ⟨cylinder-geometry⟩
  | ⟨ellipsoid-geometry⟩
  | ⟨helical-pipe-geometrya⟩
  | ⟨sphere-geometry⟩
  | ⟨supershape-geometry⟩

Each of these geometries has an optional parameter ‘radius_sphere’ that defines the radius of a sphere whose volume would correspond to that of the geometry. If defined, all other parameters of the geometric distribution must be constant, in order to fix the shape of the geometry and allow the ‘radius_sphere’ parameter to control only its scaling.

There are parameters that control the discretisation of geometries. Such as the ‘slices’ optional parameter that defines the number of discrete steps around 2PI. When not defined it is assumed to be 64. Note that the ‘helical_pipe’ geometry exposes 2 discretization parameters: ‘slices_circle’ and ‘slices_helicoid’. The former controls the discretisation of the meridian around 2PI while the later defines the total number of discrete steps along the helicoid curve. When not defined ‘slices_circle’ and ‘slices_helicoid’ are set to 64 and 128, respectively.

All geometric shapes have the optional attribute ‘proba’, which defines the unnormalised probability of selecting them from the set of geometric shapes. If it is not defined, it is assumed to be equal to 1.

The rest of this section describes each of the geometric shapes.

A cylinder is simply defined by its ‘height’ and a its ‘radius’.

Its grammar is as follows:

⟨cylinder-geometry⟩ ::= "cylinder:"
" radius:" ⟨distribution⟩
" height:" ⟨distribution⟩
[" radius_sphere:" ⟨distribution⟩]
[" slices: integer"]
[" proba: real"]

The shape of an ellipsoid geometry is controlled by the length of its semi-principal axises ‘a’ and ‘c’ used to evaluate the following equation:

(x/a)^2 + (y/a)^2 + (z/c)^2 = 1

Its grammar is as follows:

⟨ellipsoid-geometry⟩ ::= "ellipsoid:"
" a:" ⟨distribution⟩
" c:" ⟨distribution⟩
[" radius_sphere:" ⟨distribution⟩]
[" slices: integer"]
[" proba: real"]

An helical pipe has a circle as a meredian shape that is orthogonal to the helicoid slope. Its ‘pitch’ defines the width of a complete helicoid turn and its ‘height’ controls the overall distance between the beginning and the end of the helicoid. Finally, the ‘radius_helicoid’ and the ‘radius_circle’ defines the radius of the helicoid and the radius of its meridian, respectively. Let "u" in [0,height*2PI/pitch] and "t" in [0,2PI], the "X", "Y" and "Z" 3D coordinates of the helicoid points are computed from the following equations:

X(t, u) = x(t)*cos(u) - y(t)*sin(u)
Y(t, u) = x(t)*sin(u) + y(t)*cos(u)
Z(t, u) = z(t) + c*u

with:

x(t) = radius_helicoid + radius_circle*cos(t)
y(t) = -radius_circle * c/A*sin(t)
z(t) = radius_circle * radius_helicoid/A*sin(t)

c = pitch/2PI
A = sqrt(Bradius_helicoid^2 + c^2)

Its grammar is as follows:

⟨helical-pipe-geometry⟩ ::= "helical_pipe:"
" pitch:" ⟨distribution⟩
" height:" ⟨distribution⟩
" radius_helicoid:" ⟨distribution⟩
" radius_circle:" ⟨distribution⟩
[" radius_sphere:" ⟨distribution⟩]
[" slices_helicoid: integer"]
[" slices_circle: integer"]

A sphere is simply defined by its ‘radius’.

Its grammar is as follows:

⟨sphere-geometry⟩ ::= "sphere:"
" radius:" ⟨distribution⟩
[" slices: integer"]
[" proba: real"]

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":

r(a) = ( |cos(M*a/4)/A)|^N1 + |sin(M*a/4)/B|^N2 )^{-1/N0}

Assuming a point with the spherical coordinates (theta,phi), the corresponding 3D coordinates onto the supershape is obtained by evaluating the following relations:

x = r0(theta)*cos(theta) * r1(phi)*cos(phi)
y = r0(theta)*sin(theta) * r1(phi)*cos(phi)
z = r1(phi)*sin(phi)

Its grammar is as follows:

⟨supershape-geometry⟩ ::= "supershape:"
" formula0:" ⟨superformula⟩
" formula1:" ⟨superformula⟩
[" radius_sphere:" ⟨distribution⟩]
[" slices: integer"]
[" proba: real"]
⟨superformula⟩ ::= "A:" ⟨distribution⟩
"B:" ⟨distribution⟩
"M:" ⟨distribution⟩
"N0:" ⟨distribution⟩
"N1:" ⟨distribution⟩
"N2:" ⟨distribution⟩

Supported distributions are as follows:

⟨distribution⟩ ::= ⟨constant⟩
  | ⟨gaussian⟩
  | ⟨histogram⟩
  | ⟨lognormal⟩

The constant distribution fix the value of the parameter:

⟨constant⟩ ::= "real"

The gaussian distribution defines the parameter according to the mean value ‘mu’ and the standard deviation ‘sigma’:

⟨gaussian⟩ ::= "gaussian:"
" mu: real"
" sigma: real"

An histogram splits the parameter domain [lower,upper] in "N" intervals of length (upper-lower)/N. The unnormalized probabilities of the interval bounds are listed in the ‘probabilities’ 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".

Its grammar is as follows:

⟨histogram⟩ :: "histogram:"
" lower: real"
" upper: real"
" probabilities:"
" - real"
...

The lognormal distribution is controlled by the mean value ‘mu’ and the standard deviation ‘sigma’ as follows:

P(x) dx = 1/(log(sigma)*x*sqrt(2*PI) *
          exp(-(ln(x)-log(mu))^2 / (2*log(sigma)^2)) dx

Its grammar is as follows:

⟨lognormal⟩ ::= "lognormal:"
" mu: real"
" sigma: real"

Soft particles are spheres whose radius is distributed according to an histogram:

sphere:
  radius:
    histogram:
      lower: 1.0 # Min radius
      upper: 2.1 # Max radius
      probabilities:
        - 2
        - 1
        - 0.4
        - 1.23
        - 3

Soft particles are ellipsoids whose one of its semi-principal axis is distributed with respect to a lognormal distribution:

ellipsoid:
  a: 1.0
  c:
    lognormal:
      sigma: 0.2
      mu: 1.3

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:

ellipsoid:
  a: 1.1
  b: 0.3
  radius_sphere:
    histogram:
      lower: 1
      upper: 2.5
      probabilities: [ 0.5, 2, 1 ]

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:

cylinder:
  slices: 128
  radius: 1
  height: { gaussian: { mu: 1.3, sigma: 0.84 } }

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:

cylinder:
  height: 1.2
  radius: 3.4
  radius_sphere:
    histogram:
      lower: 1.24
      upper: 4.56
      probabilities: [ 2, 1.2, 3, 0.2 ]

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 discretized in 128 slices: helical_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 ]

Soft particles are supershapes whose 2 parameters of each of its superformulas are controlled by gaussian distributions:

supershape:
  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 } }

Soft particles are supershapes with the same shape. Their volume is controlled by an equivalent sphere whose radius follows a lognormal distribution:

supershape:
  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 } }

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:

- sphere: { radius: 1.12, proba: 2.0, slices: 64 }
- cylinder:
    radius: { lognormal: { sigma: 2.3, mu: 0.2 } }
    height: { lognormal: { mu: 1, sigma: 1.5 } }
    slices: 32 # Discretisation in 32 slices
    proba: 1

schiff(1)

Clark C. Evans et al, YAML Ain't Markup Language, https://yaml.org/, 2009.

schiff-geometry has been developed as part of ANR-11-IDEX-0002-02 ALGUE project.

May 18, 2026 UNIX