schiff-geometry.5 (12158B)
1 .\" Copying and distribution of this file, with or without modification, 2 .\" are permitted in any medium without royalty provided the copyright 3 .\" notice and this notice are preserved. This file is offered as-is, 4 .\" without any warranty. 5 .TH SCHIFF-GEOMETRY 5 6 .SH NAME 7 schiff-geometry \- control the shape of soft particles 8 .SH DESCRIPTION 9 \fBschiff-geometry\fR is a YAML file [1] that controls the geometry 10 distribution of soft particles. The 11 .BR schiff (1) 12 program relies on this description to generate the shape of the sampled soft 13 particles. 14 .PP 15 A geometry is defined by a type and a set of parameters whose value is 16 controlled by a distribution. Several geometries with their own probability can 17 be declared in the same \fBschiff-geometry\fR file to define a discrete random 18 variate of geometries. This allow to finely tune the shapes of the soft 19 particles with a collection of geometries, each representing a specific sub-set 20 of shapes of the soft particles to handle. 21 .SH GRAMMAR 22 This section describes the \fBschiff\-geometry\fR grammar based on the YAML 23 human readable data format [1]. The YAML format provides several ways to define 24 a mapping or a sequence of data. The following grammar always uses the more 25 verbose form but any alternative YAML formatting can be used instead. Refer to 26 the example section for illustrations of such alternatives. 27 .PP 28 When the \fBradius_sphere\fR optional parameter is defined, the relative shape 29 of the geometry must be fixed, i.e. all other parameters must be constants. In 30 this situation, only the volume of the geometry is variable; it is equal to the 31 volume of an equivalent sphere whose radius is controlled by the distribution 32 of the \fBradius_sphere\fR parameter. 33 .PP 34 The \fBslices\fR optional attribute controls the discretization of the 35 geometries in triangular meshes, i.e. the number of discrete steps around 2PI. 36 When not defined it is assumed to be 64. Note that the \fBhelical_pipe\fR 37 geometry exposes 2 discretization parameters: \fBslices_circle\fR and 38 \fBslices_helicoid\fR. The former controls the discretization of the meridian 39 around 2PI while the later defines the total number of discrete steps along the 40 helicoid curve. When not defined \fBslices_circle\fR and \fBslices_helicoid\fR 41 are set to 64 and 128, respectively. 42 .PP 43 All the geometries have the \fBproba\fR optional attribute that defines the 44 unnormalized probability to sample the geometry. If it is not defined, it is 45 assumed to be equal to 1. 46 .PP 47 .RS 4 48 .nf 49 <schiff\-geometry> ::= <geometry> | <geometry\-list> 50 51 <geometry\-list> ::= \- <geometry> 52 [ \- <geometry> ] 53 54 <geometry> ::= <cylinder\-geometry> 55 | <ellipsoid\-geometry> 56 | <helical\-pipe\-geometry> 57 | <sphere\-geometry> 58 | <supershape\-geometry> 59 60 <cylinder\-geometry> ::= cylinder: 61 radius: <distribution> 62 height: <distribution> 63 [ radius_sphere: <distribution> ] 64 [ slices: INTEGER ] 65 [ proba: REAL ] 66 67 <ellipsoid\-geometry> ::= ellipsoid: 68 a: <distribution> 69 c: <distribution> 70 [ radius_sphere: <distribution> ] 71 [ slices: INTEGER ] 72 [ proba: REAL ] 73 74 <helical\-pipe\-geometry> ::= helical_pipe: 75 pitch: <distribution> 76 height: <distribution> 77 radius_helicoid: <distribution> 78 radius_circle: <distribution> 79 [ radius_sphere: <distribution> ] 80 [ slices_helicoid: INTEGER ] 81 [ slices_circle: INTEGER ] 82 83 <sphere\-geometry> ::= sphere: 84 radius: <distribution> 85 [ slices: INTEGER ] 86 [ proba: REAL ] 87 88 <supershape\-geometry> ::= supershape: 89 formula0: <superformula> 90 formula1: <superformula> 91 [ radius_sphere: <distribution> ] 92 [ slices: INTEGER ] 93 [ proba: REAL ] 94 95 <superformula> ::= A: <distribution> 96 B: <Idistribution> 97 M: <distribution> 98 N0: <distribution> 99 N1: <distribution> 100 N2: <distribution> 101 102 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- 103 104 <distribution> ::= <constant> 105 | <gaussian> 106 | <histogram> 107 | <lognormal> 108 109 <constant> ::= REAL 110 111 <lognormal> ::= lognormal: 112 mu: REAL 113 sigma: REAL 114 115 <gaussian> ::= gaussian: 116 mu: REAL 117 sigma: REAL 118 119 <histogram> ::= histogram: 120 lower: REAL 121 upper: REAL 122 probabilities: 123 <probabilities\-list> 124 125 <probabilities\-list> ::= \- REAL 126 [ \- <probabilities\-list> ] 127 .fi 128 .SH GEOMETRY TYPES 129 .PP 130 \fBcylinder\fR 131 .PP 132 .RS 4 133 A cylinder is simply defined by its \fBheight\fR and a its \fBradius\fR. 134 .RE 135 .PP 136 \fBellipsoid\fR 137 .PP 138 .RS 4 139 The shape of an ellipsoid geometry is controlled by the length of its 140 semi\-principal axises \fBa\fR and \fBc\fR used to evaluate the following 141 equation: 142 .PP 143 .RS 8 144 .nf 145 (x/\fBa\fR)^2 + (y/\fBa\fR)^2 + (z/\fBc\fR)^2 = 1 146 .fi 147 .RE 148 .RE 149 .PP 150 \fBhelical_pipe\fR 151 .RS 4 152 .PP 153 Helicoid whose meridian shape is a circle that is orthogonal to the helicoid 154 slope. Its \fBpitch\fR defines the width of a complete helicoid turn and its 155 \fBheight\fR controls the overall distance between the beginning and the end of 156 the helicoid. Finally, the \fBradius_helicoid\fR and the \fBradius_circle\fR 157 defines the radius of the helicoid and the radius of its meridian, 158 respectively. Let "u" in [0, \fBheight\fR * 2PI / \fBpitch\fR] and "t" in [0, 159 2PI], the "X", "Y" and "Z" 3D coordinates of the helicoid points are computed 160 from the following equations: 161 .PP 162 .RS 8 163 .nf 164 X(t, u) = x(t)*cos(u) - y(t)*sin(u) 165 Y(t, u) = x(t)*sin(u) + y(t)*cos(u) 166 Z(t, u) = z(t) + c*u 167 .PP 168 x(t) = \fBradius_helicoid\fR + \fBradius_circle\fR*cos(t) 169 y(t) = -\fBradius_circle\fR * c / A * sin(t) 170 z(t) = \fBradius_circle\fR*\fBradius_helicoid\fR / A * sin(t) 171 .PP 172 c = \fBpitch\fR / 2PI 173 A = sqrt(\fBradius_helicoid\fR^2 + c^2) 174 .fi 175 .RE 176 .RE 177 .PP 178 \fBsphere\fR 179 .RS 4 180 .PP 181 A sphere is simply defined by its \fBradius\fR. 182 .RE 183 .PP 184 \fBsupershape\fR 185 .RS 4 186 .PP 187 Generalisation of the superellipsoid that is well suited to represent many 188 complex shapes found in the nature. It is controlled by 2 superformulas, each 189 defining a radius "r" for a given angle "a": 190 .PP 191 .RS 8 192 .nf 193 r(a) = ( |cos(\fBM\fR*a/4)/\fBA\fR)|^\fBN1\fR + |sin(\fBM\fR*a/4)/\fBB\fR|^\fBN2\fR )^{-1/\fBN0\fR} 194 .fi 195 .RE 196 .PP 197 Assuming a point with the spherical coordinates {theta, phi}, the corresponding 198 3D coordinates onto the supershape is obtained by evaluating the following 199 relations: 200 .RS 8 201 .PP 202 .nf 203 x = r0(theta)*cos(theta) * r1(phi)*cos(phi) 204 y = r0(theta)*sin(theta) * r1(phi)*cos(phi) 205 z = r1(phi)*sin(phi) 206 .fi 207 .SH PARAMETER DISTRIBUTIONS 208 .PP 209 \fBconstant\fR 210 .RS 4 211 .PP 212 Fixe the value of the parameter. 213 .RE 214 .PP 215 \fBgaussian\fR 216 .RS 4 217 .PP 218 Use the following probability distribution to define the parameter according to 219 the mean value \fBmu\fR and the standard deviation \fBsigma\fR: 220 .PP 221 .RS 8 222 .nf 223 P(x) dx = 1 / (\fBsigma\fR*sqrt(2*PI)) * exp(1/2*((x-\fBmu\fR)/\fBsigma\fR)^2) dx 224 .fi 225 .RE 226 .RE 227 .PP 228 \fBhistogram\fR 229 .RS 4 230 .PP 231 Split the parameter domain [\fBlower\fR, \fBupper\fR] in \fIN\fR intervals of 232 length (\fBupper\fR-\fBlower\fR)/\fIN\fR. The list of unnormalized 233 probabilities of the interval bounds are listed in the \fBprobabilities\fR 234 array and are used to build the cumulative distribution of the parameter. Let a 235 random number "r" in [0, 1], the corresponding parameter value is computed by 236 retrieving the interval of the parameter from the aforementioned cumulative, 237 before linearly interpolating its bounds with respect to "r"; 238 .RE 239 .PP 240 \fBlognormal\fR 241 .RS 4 242 .PP 243 Distribute the parameter with respect to a mean value \fBmu\fR and a standard 244 deviation \fBsigma\fR as follow: 245 .PP 246 .RS 8 247 .nf 248 P(x) dx = 1/(log(\fBsigma\fR)*x*sqrt(2*PI) * 249 exp(-(ln(x)-log(\fBmu\fR))^2 / (2*log(\fBsigma\fR)^2)) dx 250 .fi 251 .SH EXAMPLES 252 .PP 253 Soft particles are spheres whose radius is distributed according to an 254 histogram: 255 .PP 256 .RS 4 257 .nf 258 sphere: 259 radius: 260 histogram: 261 lower: 1.0 # Min radius 262 upper: 2.1 # Max radius 263 probabilities: 264 - 2 265 - 1 266 - 0.4 267 - 1.23 268 - 3 269 .fi 270 .RE 271 .PP 272 Soft particles are ellipsoids whose one of its semi-principal axis is 273 distributed with respect to a lognormal distribution: 274 .PP 275 .RS 4 276 .nf 277 ellipsoid: 278 a: 1.0 279 c: 280 lognormal: 281 sigma: 0.2 282 mu: 1.3 283 .fi 284 .RE 285 .PP 286 Soft particles are ellipsoids whose semi\-principal axises are fixed. Its 287 volume is equal to the volume of an equivalent sphere whose radius follows an 288 histogram distribution: 289 .PP 290 .RS 4 291 .nf 292 ellipsoid: 293 a: 1.1 294 b: 0.3 295 radius_sphere: 296 histogram: 297 lower: 1 298 upper: 2.5 299 probabilities: [ 0.5, 2, 1 ] 300 .fi 301 .RE 302 .PP 303 Soft particles are cylinders. Their radius is constant and their height is 304 distributed according to a gaussian distribution. The cylinder geometry is 305 discretized in 128 slices along 2PI: 306 .PP 307 .RS 4 308 .nf 309 cylinder: 310 slices: 128 311 radius: 1 312 height: { gaussian: { mu: 1.3, sigma: 0.84 } } 313 .fi 314 .RE 315 .PP 316 Soft particles are cylinders whose height and radius are fixed. Their volume 317 is equal to the volume of a sphere whose radius is distributed with respect to 318 an histogram: 319 .PP 320 .RS 4 321 .nf 322 cylinder: 323 height: 1.2 324 radius: 3.4 325 radius_sphere: 326 histogram: 327 lower: 1.24 328 upper: 4.56 329 probabilities: [ 2, 1.2, 3, 0.2 ] 330 .fi 331 .RE 332 .PP 333 Soft particle are helical pipes whose attributes are controlled by several 334 distribution types. Their helicoid curve is split in 256 steps while its 335 meridian is discretized in 128 slices: 336 .PP 337 .RS 4 338 .nf 339 helical_pipe: 340 slices_helicoid: 256 341 slices_circle: 128 342 height : 4 343 pitch : { gaussian: { mu: 3, sigma: 1.3} } 344 radius_helicoid: { lognormal: { mu: 2, sigma: 0.4} } 345 radius_circle: 346 histogram: 347 lower: 1 348 upper: 1.5 349 probabilities: [ 1, 1.2, 0.2, 0.5, 1.4 ] 350 .fi 351 .RE 352 .PP 353 Soft particles are supershapes whose 2 parameters of each of its superformulas 354 are controlled by gaussian distributions: 355 .PP 356 .RS 4 357 .nf 358 supershape: 359 formula0: 360 A: 1 361 B: 1 362 M: { gaussian: { mu: 5, sigma: 1 } } 363 N0: 1 364 N1: 1 365 N2: { gaussian: { mu: 3, sigma: 1 } } 366 formula1: 367 A: 1 368 B: 1 369 M: { gaussian: { mu: 1.2, sigma: 0.3 } } 370 N0: 1 371 N1: 1 372 N2: { gaussian: { mu: 1, sigma: 0.3 } } 373 .fi 374 .RE 375 .PP 376 Soft particles are supershapes with the same shape. Their volume is controlled 377 by an equivalent sphere whose radius follows a lognormal distribution: 378 .PP 379 .RS 4 380 .nf 381 supershape: 382 formula0: { A: 1, B: 1, M: 3, N0: 3, N1: 3, N2: 5 } 383 formula1: { A: 2, B: 1.1, M: 3, N0: 1, N1: 1, N2: 1 } 384 radius_sphere : { lognormal: { mu: 2.2, sigma: 1.3 } } 385 .fi 386 .RE 387 .PP 388 Soft particles are spheres and cylinders with 2 times more spheres than 389 cylinders. The cylinder parameters are controlled by lognormal distributions 390 and spherical soft particles have a fixed radius: 391 .PP 392 .RS 4 393 .nf 394 - sphere: { radius 1.12, proba: 2.0, slices: 64 } 395 396 - cylinder: 397 radius: {lognormal: { sigma: 2.3, mu: 0.2 } } 398 height: {lognormal: { mu: 1, sigma: 1.5 } } 399 slices: 32 # Discretisation in 32 slices 400 proba: 1 401 .fi 402 .RE 403 .SH NOTES 404 .PP 405 [1] YAML Ain't Markup Language \- http://yaml.org 406 .SH SEE ALSO 407 .BR schiff (1)