schiff-geometry.5 (14731B)
1 .\" Copyright (C) 2015, 2016, 2026 Centre National de la Recherche Scientifique 2 .\" Copyright (C) 2026 Clermont Auvergne INP 3 .\" Copyright (C) 2026 Institut Mines Télécom Albi-Carmaux 4 .\" Copyright (C) 2017, 2019-2021, 2026 |Méso|Star> (contact@meso-star.com) 5 .\" Copyright (C) 2026 Université de Lorraine 6 .\" Copyright (C) 2026 Université de Toulouse 7 .\" 8 .\" This program is free software: you can redistribute it and/or modify 9 .\" it under the terms of the GNU General Public License as published by 10 .\" the Free Software Foundation, either version 3 of the License, or 11 .\" (at your option) any later version. 12 .\" 13 .\" This program is distributed in the hope that it will be useful, 14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of 15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 .\" GNU General Public License for more details. 17 .\" 18 .\" You should have received a copy of the GNU General Public License 19 .\" along with this program. If not, see <http://www.gnu.org/licenses/>. 20 .Dd May 18, 2026 21 .Dt SCHIFF-GEOMETRY 5 22 .Os 23 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 24 .Sh NAME 25 .Nm schiff-geometry 26 .Nd control the shape of soft particles 27 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 28 .Sh DESCRIPTION 29 .Nm 30 is a plain text file format that controls the geometry distribution of soft 31 particles. 32 The 33 .Xr schiff 1 34 program relies on this description to generate the shape of the sampled 35 soft particles. 36 .Pp 37 A 38 .Nm 39 may contain one or more geometric shapes to be distributed 40 In the latter case, each geometric shape is assigned a probability such 41 that the set defines a discrete random variable comprising the geometric 42 shapes that make up the mixture. 43 This allow to finely tune the shapes of the soft particles with a 44 collection of geometries, each representing a specific sub-set of shapes 45 of the soft particles to handle: 46 .Bl -column (helical-pipe-geometry) (::=) () 47 .It Ao Va schiff-geometry Ac Ta ::= Ta Ao Va geometry Ac | 48 .Aq Va geometry-list 49 .It \ Ta Ta 50 .It Ao Va geometry-list Ac Ta ::= Ta Qo - Qc Ao Va geometry Ac 51 .It Ta Ta ... 52 .El 53 .Pp 54 A geometry is defined by its type 55 .Pq section Sx GEOMETRIC SHAPES 56 and a set of parameters whose value is controlled by a distribution 57 .Pq section Sx PARAMETER DISTRIBUTIONS . 58 .Pp 59 Note that a 60 .Nm 61 file is actually a YAML file. 62 This format provides several ways to define a mapping or a sequence of 63 data. 64 In grammar rules, the most detailed form is always used, but it is 65 possible to opt for any other, more concise form instead 66 .Pq see section Sx EXAMPLES . 67 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 68 .Sh GEOMETRIC SHAPES 69 The list of supported geometric shapes are as follows: 70 .Bl -column (helical-pipe-geometry) (::=) () 71 .It Ao Va geometry Ac Ta ::= Ta Ao Va cylinder-geometry Ac 72 .It Ta \ | Ta Ao Va ellipsoid-geometry Ac 73 .It Ta \ | Ta Ao Va helical-pipe-geometrya Ac 74 .It Ta \ | Ta Ao Va sphere-geometry Ac 75 .It Ta \ | Ta Ao Va supershape-geometry Ac 76 .El 77 .Pp 78 Each of these geometries has an optional parameter 79 .Ql radius_sphere 80 that defines the radius of a sphere whose volume would correspond to 81 that of the geometry. 82 If defined, all other parameters of the geometric distribution must be 83 constant, in order to fix the shape of the geometry and allow the 84 .Ql radius_sphere 85 parameter to control only its scaling. 86 .Pp 87 There are parameters that control the discretisation of geometries. 88 Such as the 89 .Ql slices 90 optional parameter that defines the number of discrete steps around 2PI. 91 When not defined it is assumed to be 64. 92 Note that the 93 .Ql helical_pipe 94 geometry exposes 2 discretization parameters: 95 .Ql slices_circle 96 and 97 .Ql slices_helicoid . 98 The former controls the discretisation of the meridian around 2PI while 99 the later defines the total number of discrete steps along the helicoid 100 curve. 101 When not defined 102 .Ql slices_circle 103 and 104 .Ql slices_helicoid 105 are set to 64 and 128, respectively. 106 .Pp 107 All geometric shapes have the optional attribute 108 .Ql proba , 109 which defines the unnormalised probability of selecting them from the 110 set of geometric shapes. 111 If it is not defined, it is assumed to be equal to 1. 112 .Pp 113 The rest of this section describes each of the geometric shapes. 114 .\"""""""""""""""""""""""""""""""""" 115 .Ss Cylinder 116 A cylinder is simply defined by its 117 .Ql height 118 and a its 119 .Ql radius . 120 .Pp 121 Its grammar is as follows: 122 .Bl -column (helical-pipe-geometry) (::=) () 123 .It Ao Va cylinder-geometry Ac Ta ::= Ta \& Qq cylinder\&: 124 .It Ta Ta \& Qo \& \& radius: Qc Aq Va distribution 125 .It Ta Ta \& Qo \& \& height: Qc Aq Va distribution 126 .It Ta Ta Op Qo \& \& radius_sphere: Qc Aq Va distribution 127 .It Ta Ta Op Qq \& \& slices: Vt integer 128 .It Ta Ta Op Qq \& \& proba: Vt real 129 .El 130 .\"""""""""""""""""""""""""""""""""" 131 .Ss Ellipsoid 132 The shape of an ellipsoid geometry is controlled by the length of its 133 semi-principal axises 134 .Ql a 135 and 136 .Ql c 137 used to evaluate the following equation: 138 .Bd -literal -offset Ds 139 (x/a)^2 + (y/a)^2 + (z/c)^2 = 1 140 .Ed 141 .Pp 142 Its grammar is as follows: 143 .Bl -column (helical-pipe-geometry) (::=) () 144 .It Ao Va ellipsoid-geometry Ac Ta ::= Ta \& Qq ellipsoid\&: 145 .It Ta Ta \& Qo \& \& a: Qc Aq Va distribution 146 .It Ta Ta \& Qo \& \& c: Qc Aq Va distribution 147 .It Ta Ta Op Qo \& \& radius_sphere: Qc Aq Va distribution 148 .It Ta Ta Op Qq \& \& slices: Vt integer 149 .It Ta Ta Op Qq \& \& proba: Vt real 150 .El 151 .\"""""""""""""""""""""""""""""""""" 152 .Ss Helical pipe 153 An helical pipe has a circle as a meredian shape that is orthogonal to 154 the helicoid slope. 155 Its 156 .Ql pitch 157 defines the width of a complete helicoid turn and its 158 .Ql height 159 controls the overall distance between the beginning and the end of 160 the helicoid. 161 Finally, the 162 .Ql radius_helicoid 163 and the 164 .Ql radius_circle 165 defines the radius of the helicoid and the radius of its meridian, 166 respectively. 167 Let 168 .Qq u 169 in 170 .Bq 0,height*2PI/pitch 171 and 172 .Qq t 173 in 174 .Bq 0,2PI , 175 the 176 .Qq X , 177 .Qq Y 178 and 179 .Qq Z 180 3D coordinates of the helicoid points are computed from the following 181 equations: 182 .Bd -literal -offset Ds 183 X(t, u) = x(t)*cos(u) - y(t)*sin(u) 184 Y(t, u) = x(t)*sin(u) + y(t)*cos(u) 185 Z(t, u) = z(t) + c*u 186 .Ed 187 .Pp 188 with: 189 .Bd -literal -offset Ds 190 x(t) = radius_helicoid + radius_circle*cos(t) 191 y(t) = -radius_circle * c/A*sin(t) 192 z(t) = radius_circle * radius_helicoid/A*sin(t) 193 194 c = pitch/2PI 195 A = sqrt(Bradius_helicoid^2 + c^2) 196 .Ed 197 .Pp 198 Its grammar is as follows: 199 .Bl -column (helical-pipe-geometry) (::=) () 200 .It Ao Va helical-pipe-geometry Ac Ta ::= Ta \& Qq helical_pipe\&: 201 .It Ta Ta \& Qo \& \& pitch: Qc Aq Va distribution 202 .It Ta Ta \& Qo \& \& height: Qc Aq Va distribution 203 .It Ta Ta \& Qo \& \& radius_helicoid: Qc Aq Va distribution 204 .It Ta Ta \& Qo \& \& radius_circle: Qc Aq Va distribution 205 .It Ta Ta Op Qo \& \& radius_sphere: Qc Aq Va distribution 206 .It Ta Ta Op Qq \& \& slices_helicoid: Vt integer 207 .It Ta Ta Op Qq \& \& slices_circle: Vt integer 208 .El 209 .\"""""""""""""""""""""""""""""""""" 210 .Ss Sphere 211 A sphere is simply defined by its 212 .Ql radius . 213 .Pp 214 Its grammar is as follows: 215 .Bl -column (helical-pipe-geometry) (::=) () 216 .It Ao Va sphere-geometry Ac Ta ::= Ta \& Qq sphere\&: 217 .It Ta Ta \& Qo \& \& radius: Qc Aq Va distribution 218 .It Ta Ta Op Qq \& \& slices: Vt integer 219 .It Ta Ta Op Qq \& \& proba: Vt real 220 .El 221 .\"""""""""""""""""""""""""""""""""" 222 .Ss Supershape 223 A supershape is a generalisation of the superellipsoid that is well 224 suited to represent many complex shapes found in the nature. 225 It is controlled by 2 superformulas, each 226 defining a radius 227 .Qq r 228 for a given angle 229 .Qq a : 230 .Bd -literal -offset Ds 231 r(a) = ( |cos(M*a/4)/A)|^N1 + |sin(M*a/4)/B|^N2 )^{-1/N0} 232 .Ed 233 .Pp 234 Assuming a point with the spherical coordinates 235 .Pq theta,phi , 236 the corresponding 3D coordinates onto the supershape is obtained by 237 evaluating the following relations: 238 .Bd -literal -offset Ds 239 x = r0(theta)*cos(theta) * r1(phi)*cos(phi) 240 y = r0(theta)*sin(theta) * r1(phi)*cos(phi) 241 z = r1(phi)*sin(phi) 242 .Ed 243 .Pp 244 Its grammar is as follows: 245 .Bl -column (helical-pipe-geometry) (::=) () 246 .It Ao Va supershape-geometry Ac Ta ::= Ta \& Qq supershape\&: 247 .It Ta Ta \& Qo \& \& formula0: Qc Aq Va superformula 248 .It Ta Ta \& Qo \& \& formula1: Qc Aq Va superformula 249 .It Ta Ta Op Qo \& \& radius_sphere: Qc Aq Va distribution 250 .It Ta Ta Op Qq \& \& slices: Vt integer 251 .It Ta Ta Op Qq \& \& proba: Vt real 252 .It Ao Va superformula Ac Ta ::= Ta \& Qo A: Qc Aq Va distribution 253 .It Ta Ta \& Qo B: Qc Aq Va distribution 254 .It Ta Ta \& Qo M: Qc Aq Va distribution 255 .It Ta Ta \& Qo N0: Qc Aq Va distribution 256 .It Ta Ta \& Qo N1: Qc Aq Va distribution 257 .It Ta Ta \& Qo N2: Qc Aq Va distribution 258 .El 259 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 260 .Sh PARAMETER DISTRIBUTIONS 261 Supported distributions are as follows: 262 .Bl -column (helical-pipe-geometry) (::=) () 263 .It Ao Va distribution Ac Ta ::= Ta Aq Va constant 264 .It Ta \ | Ta Aq Va gaussian 265 .It Ta \ | Ta Aq Va histogram 266 .It Ta \ | Ta Aq Va lognormal 267 .El 268 .\"""""""""""""""""""""""""""""""""" 269 .Ss Constant 270 The constant distribution fix the value of the parameter: 271 .Bl -column (helical-pipe-geometry) (::=) () 272 .It Ao Va constant Ac Ta ::= Ta Qq Vt real 273 .El 274 .\"""""""""""""""""""""""""""""""""" 275 .Ss Gaussian 276 The gaussian distribution defines the parameter according to the mean 277 value 278 .Ql mu 279 and the standard deviation 280 .Ql sigma : 281 .Bl -column (helical-pipe-geometry) (::=) () 282 .It Ao Va gaussian Ac Ta ::= Ta Qq gaussian\&: 283 .It Ta Ta Qq \& \& mu: Vt real 284 .It Ta Ta Qq \& \& sigma: Vt real 285 .El 286 .\"""""""""""""""""""""""""""""""""" 287 .Ss Histogram 288 An histogram splits the parameter domain 289 .Bq lower,upper 290 in 291 .Qq N 292 intervals of 293 length 294 .Po upper-lower Pc Ns /N . 295 The unnormalized 296 probabilities of the interval bounds are listed in the 297 .Ql probabilities 298 array and are used to build the cumulative distribution of the 299 parameter. 300 Let a random number 301 .Qq r 302 in 303 .Bq 0,1 , 304 the corresponding parameter value is computed by retrieving the interval 305 of the parameter from the aforementioned cumulative, before linearly 306 interpolating its bounds with respect to 307 .Qq r . 308 .Pp 309 Its grammar is as follows: 310 .Bl -column (helical-pipe-geometry) (::=) () 311 .It Ao Va histogram Ac Ta :: Ta Qq histogram\&: 312 .It Ta Ta Qq \& \& lower: Vt real 313 .It Ta Ta Qq \& \& upper: Vt real 314 .It Ta Ta Qq \& \& probabilities\&: 315 .It Ta Ta Qq \& \& \& \& - Vt real 316 .It Ta Ta \& \& \& \& \& ... 317 .El 318 .\"""""""""""""""""""""""""""""""""" 319 .Ss Lognormal 320 The lognormal distribution is controlled by the mean value 321 .Ql mu 322 and the standard deviation 323 .Ql sigma 324 as follows: 325 .Bd -literal -offset Ds 326 P(x) dx = 1/(log(sigma)*x*sqrt(2*PI) * 327 exp(-(ln(x)-log(mu))^2 / (2*log(sigma)^2)) dx 328 .Ed 329 .Pp 330 Its grammar is as follows: 331 .Bl -column (helical-pipe-geometry) (::=) () 332 .It Ao Va lognormal Ac Ta ::= Ta Qq lognormal\&: 333 .It Ta Ta Qq \& \& mu: Vt real 334 .It Ta Ta Qq \& \& sigma: Vt real 335 .El 336 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 337 .Sh EXAMPLES 338 Soft particles are spheres whose radius is distributed according to an 339 histogram: 340 .Bd -literal -offset Ds 341 sphere: 342 radius: 343 histogram: 344 lower: 1.0 # Min radius 345 upper: 2.1 # Max radius 346 probabilities: 347 - 2 348 - 1 349 - 0.4 350 - 1.23 351 - 3 352 .Ed 353 .\"""""""""""""""""""""""""""""""""" 354 .Pp 355 Soft particles are ellipsoids whose one of its semi-principal axis is 356 distributed with respect to a lognormal distribution: 357 .Bd -literal -offset Ds 358 ellipsoid: 359 a: 1.0 360 c: 361 lognormal: 362 sigma: 0.2 363 mu: 1.3 364 .Ed 365 .\"""""""""""""""""""""""""""""""""" 366 .Pp 367 Soft particles are ellipsoids whose semi-principal axises are fixed. 368 Its volume is equal to the volume of an equivalent sphere whose radius 369 follows an histogram distribution: 370 .Bd -literal -offset Ds 371 ellipsoid: 372 a: 1.1 373 b: 0.3 374 radius_sphere: 375 histogram: 376 lower: 1 377 upper: 2.5 378 probabilities: [ 0.5, 2, 1 ] 379 .Ed 380 .\"""""""""""""""""""""""""""""""""" 381 .Pp 382 Soft particles are cylinders. 383 Their radius is constant and their height is distributed according to a 384 gaussian distribution. 385 The cylinder geometry is discretized in 128 slices along 2PI: 386 .Bd -literal -offset Ds 387 cylinder: 388 slices: 128 389 radius: 1 390 height: { gaussian: { mu: 1.3, sigma: 0.84 } } 391 .Ed 392 .\"""""""""""""""""""""""""""""""""" 393 .Pp 394 Soft particles are cylinders whose height and radius are fixed. 395 Their volume is equal to the volume of a sphere whose radius is 396 distributed with respect to an histogram: 397 .Bd -literal -offset Ds 398 cylinder: 399 height: 1.2 400 radius: 3.4 401 radius_sphere: 402 histogram: 403 lower: 1.24 404 upper: 4.56 405 probabilities: [ 2, 1.2, 3, 0.2 ] 406 .Ed 407 .\"""""""""""""""""""""""""""""""""" 408 .Pp 409 Soft particle are helical pipes whose attributes are controlled by several 410 distribution types. 411 Their helicoid curve is split in 256 steps while its meridian is 412 discretized in 128 slices: 413 helical_pipe: 414 .Bd -literal -offset Ds 415 slices_helicoid: 256 416 slices_circle: 128 417 height : 4 418 pitch : { gaussian: { mu: 3, sigma: 1.3} } 419 radius_helicoid: { lognormal: { mu: 2, sigma: 0.4} } 420 radius_circle: 421 histogram: 422 lower: 1 423 upper: 1.5 424 probabilities: [ 1, 1.2, 0.2, 0.5, 1.4 ] 425 .Ed 426 .\"""""""""""""""""""""""""""""""""" 427 .Pp 428 Soft particles are supershapes whose 2 parameters of each of its 429 superformulas are controlled by gaussian distributions: 430 .Bd -literal -offset Ds 431 supershape: 432 formula0: 433 A: 1 434 B: 1 435 M: { gaussian: { mu: 5, sigma: 1 } } 436 N0: 1 437 N1: 1 438 N2: { gaussian: { mu: 3, sigma: 1 } } 439 formula1: 440 A: 1 441 B: 1 442 M: { gaussian: { mu: 1.2, sigma: 0.3 } } 443 N0: 1 444 N1: 1 445 N2: { gaussian: { mu: 1, sigma: 0.3 } } 446 .Ed 447 .\"""""""""""""""""""""""""""""""""" 448 .Pp 449 Soft particles are supershapes with the same shape. 450 Their volume is controlled by an equivalent sphere whose radius follows 451 a lognormal distribution: 452 .Bd -literal -offset Ds 453 supershape: 454 formula0: { A: 1, B: 1, M: 3, N0: 3, N1: 3, N2: 5 } 455 formula1: { A: 2, B: 1.1, M: 3, N0: 1, N1: 1, N2: 1 } 456 radius_sphere : { lognormal: { mu: 2.2, sigma: 1.3 } } 457 .Ed 458 .\"""""""""""""""""""""""""""""""""" 459 .Pp 460 Soft particles are spheres and cylinders with 2 times more spheres than 461 cylinders. 462 The cylinder parameters are controlled by lognormal distributions and 463 spherical soft particles have a fixed radius: 464 .Bd -literal -offset Ds 465 - sphere: { radius: 1.12, proba: 2.0, slices: 64 } 466 - cylinder: 467 radius: { lognormal: { sigma: 2.3, mu: 0.2 } } 468 height: { lognormal: { mu: 1, sigma: 1.5 } } 469 slices: 32 # Discretisation in 32 slices 470 proba: 1 471 .Ed 472 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 473 .Sh SEE ALSO 474 .Xr schiff 1 475 .Rs 476 .%T YAML Ain't Markup Language 477 .%A Clark C. Evans et al 478 .%D 2009 479 .%U https://yaml.org/ 480 .Re 481 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 482 .Sh HISTORY 483 .Nm 484 has been developed as part of 485 .Li ANR-11-IDEX-0002-02 486 ALGUE project.