morphogen.models.fibers¶
Fibre models: Poisson fibres, a Boolean model on isotropic Poisson lines (Jeulin 1991); hard-core (non-overlapping) fibres by random sequential addition; curved fibres, worm-like chains, arcs or helices, overlapping or not; bending fibres, random walks packed without overlap to high fractions by forces (Altendorf & Jeulin 2011), drawn into contact (Keilmann, Redenbach & Willot 2026); entangled cross-linked fibres, straight fibres bonded at a fraction of their contacts (Chatti et al. 2018, 2020).
- class morphogen.models.fibers.PoissonFibers(radius: float = 1.0, volume_fraction: float | None = None, length_density: float | None = None, orientation: OrientationDistribution = Isotropic())[source]¶
Bases:
ModelInfinite cylinders of radius R around Poisson lines, isotropic or of directions drawn from
orientation.The model is parameterized by the volume fraction
pof fibres or by the mean fibre length per unit volumeL_V(p = 1 - exp(-L_V pi R^2)for any law of directions). In the notation of Jeulin and of Dirrenberger et al. (2014) the intensity of the lines istheta = L_V / piandp = 1 - exp(-theta pi^2 R^2).Infinite lines cannot be made periodic: domains must be non-periodic. The sample is the exact restriction of the infinite random medium to the box. The covariance (
covariance()) is in closed form along any direction, for any law.- phases: ClassVar[dict[int, str]] = {0: 'pores', 1: 'fibres'}¶
Meaning of the phase indices of the voxel images.
- supports_periodic: ClassVar[bool] = False¶
False for models that cannot be periodic (e.g. infinite Poisson fibres).
- count_label: ClassVar[str] = 'fibres'¶
Objects counted by
expected_count()(fibres, spheres, cells…).
- property lv: float¶
Mean fibre length per unit volume.
- generate(domain: Domain, seed: int | SeedSequence | Generator | None = None) PrimitiveUnion[source]¶
One realization of the model in
domain.
- theory(domain: Domain | None = None) dict[str, float][source]¶
Theoretical morphological characteristics known in closed form (may be empty).
Some values depend on the domain (e.g. the intensity implied by a number of cells).
- choquet_capacity(element: str, size, direction=None) ndarray[source]¶
T(K) = P(K hits A): the lines of directionuhitting a convex body are those crossing its projection on the plane normal tou(on averageL_V S / 4isotropic lines, Cauchy), and those hitting the fibres hitA' (+) K': for balls of radiussizea ball of radius R + r (any law), for segments of lengthsizealongdirectiona spherocylinder of projectionpi R^2 + 2 R l |sin g|(gits angle to the line,E|sin g| = pi/4for isotropic lines; without a direction, the mean of the capacities over the directions); pairs of points at distancesize:2 p - C(h).
- expected_fibers(domain: Domain) float[source]¶
Mean number of fibre axes hitting the box,
L_Vtimes the mean area of its projection along the lines,sum_k A_k E|u_k|(A_kthe area of the faces normal to the axisk):L_V S / 4for isotropic lines (Dirrenberger 2014, eq. 9).
- expected_count(domain: Domain) float[source]¶
Mean number of objects of the model in
domain(None when undefined).Used to express RVE sizes as numbers of fibres, grains or cells (Dirrenberger et al. 2014, Table 10).
- covariance(h, direction=None) ndarray[source]¶
C(h) = P(x in A, x + h in A), for
halongdirection(any for isotropic lines; averaged over the directions ofhwithout one).The lines of direction
uhitting {x, x + h} dilated by the fibre radius are those crossing the union of two disks of radius R,|h| sin(b)apart, in the plane normal tou(bthe angle betweenhandu):P(x, x + h not in A) = q^2 exp(L_V E_u[lens(|h| sin b)]), the mean over the law of the directions (cos b uniform for isotropic lines;morphogen.theory.oriented_covariance()).
- class morphogen.models.fibers.HardcoreFibers(radius: Distribution = Constant(value=0.5), length: Distribution = Constant(value=5.0), orientation: OrientationDistribution = Isotropic(), volume_fraction: float | None = None, number: int | None = None, min_gap: float = 0.0, max_attempts: int | None = None, lumen: float = 0.0)[source]¶
Bases:
ModelNon-overlapping straight fibres (spherocylinders) placed by random sequential addition (RSA).
Fibres are added one at a time, with uniformly random centres and axes drawn from
orientation; a trial is rejected when the fibre would come closer thanmin_gapto one already placed. The process jams at a volume fraction that falls as the fibres lengthen (isotropic fibres) and rises when they are aligned.Generation always takes place in a periodic box; for non-periodic domains the box is enlarged by a fibre length and cropped, which avoids wall effects.
- phases: ClassVar[dict[int, str]] = {0: 'matrix', 1: 'fibres'}¶
Meaning of the phase indices of the voxel images.
- count_label: ClassVar[str] = 'fibres'¶
Objects counted by
expected_count()(fibres, spheres, cells…).
- property mean_volume: float¶
- property mean_surface: float¶
- generate(domain: Domain, seed: int | SeedSequence | Generator | None = None) PrimitiveUnion[source]¶
One realization of the model in
domain.
- class morphogen.models.fibers.CurvedFibers(radius: float = 0.5, length: float = 20.0, persistence: float = 10.0, segments: int = 10, orientation: OrientationDistribution = Isotropic(), volume_fraction: float | None = None, intensity: float | None = None, shape: str = 'worm_like', curvature_radius: Distribution = Constant(value=20.0), helix_radius: float = 1.0, helix_pitch: float = 10.0, overlap: bool = True, min_gap: float = 0.0, max_attempts: int | None = None, lumen: float = 0.0)[source]¶
Bases:
ModelCurved fibres: chains of
segmentsstraight spherocylinders along curved axes, a Boolean model or non-overlapping fibres.shapesets the axes.worm_like: the direction performs a persistent random walk, each segment of lengthds = length / segmentsturning from the previous one by an angle whose cosine follows the von Mises-Fisher distribution of meanexp(-ds / persistence), about a uniformly random perpendicular axis, so that the tangents decorrelate asexp(-s / persistence)along the contour (the discrete worm-like chain); the first direction followsorientation.arc: circular arcs of radiuscurvature_radius(a distribution) bent in a uniformly random plane, the tangent at the middle of the contour followingorientation(the curved fibres of PuMA).helix: crimped fibres, helices of radiushelix_radiusand pitchhelix_pitchabout straight axes followingorientation, of random phase. The segments have round caps, so that the joints are smooth.overlap: true: a Boolean model, the centres of the fibres (the middles of their contours) a Poisson point process.overlap: false: fibres placed one at a time by random sequential addition, a trial rejected when it comes closer thanmin_gapto a fibre already placed (generated in a periodic box, enlarged and cropped for non-periodic domains).- phases: ClassVar[dict[int, str]] = {0: 'matrix', 1: 'fibres'}¶
Meaning of the phase indices of the voxel images.
- count_label: ClassVar[str] = 'fibres'¶
Objects counted by
expected_count()(fibres, spheres, cells…).
- property mean_grain_volume: float¶
the union of the segments of a curved one is a little smaller (their caps overlap more at the bends).
- Type:
Volume of a straight fibre
- property theta: float¶
- property correlation: float¶
Mean cosine of the angle between consecutive segments (worm-like chains).
- tangents(rng, n: int) ndarray[source]¶
Directions (n x segments x 3) of the segments of
nworm-like chains.
- axes(rng, n: int) ndarray[source]¶
Points (n x (segments + 1) x 3) of the axes of
nfibres, relative to the middles of their contours.
- generate(domain: Domain, seed: int | SeedSequence | Generator | None = None) PrimitiveUnion[source]¶
One realization of the model in
domain.
- morphogen.models.fibers.von_mises_fisher(rng, mean, kappa) ndarray[source]¶
Unit vectors drawn from von Mises-Fisher laws on the sphere, of densities
kappa exp(kappa m.x) / (4 pi sinh kappa), one per row ofmean(unit vectorsm) and entry ofkappa(>= 0; 0 is uniform): the cosinew = m.xby inversion,w = 1 + ln(u + (1 - u) e^(-2 kappa)) / kappa, the azimuth aboutmuniform.
- morphogen.models.fibers.multivariate_von_mises_fisher_walk(rng, main, kappa1: float, kappa2: float, steps: int)[source]¶
Directions (n x steps x 3) of the random walks of Altendorf & Jeulin (2011): step
kfollows the multivariate von Mises-Fisher law of density proportional toexp(kappa1 mu.t + kappa2 t_(k-1).t),muthe main direction (a row ofmain) andt_0 = mu, i.e. the von Mises-Fisher law aboutkappa1 mu + kappa2 t_(k-1)of concentration its length.
- class morphogen.models.fibers.RandomWalkFibers(radius: Distribution = Constant(value=0.5), length: Distribution = Constant(value=10.0), orientation: OrientationDistribution = Isotropic(), kappa1: float = 10.0, kappa2: float = 100.0, step: float = 0.5, volume_fraction: float | None = None, number: int | None = None, packing: bool = True, recovery: float = 0.2, max_steps: int = 10000, end_step: str = 'repulsion', min_gap: float = 0.0, lumen: float = 0.0, interaction_distance: float = 0.0, contact_distance: float = 0.0, contact_weight: float = 0.5, contact_threshold: float = 0.05, placement_trials: int = 1)[source]¶
Bases:
ModelBending fibres packed without overlap by forces (Altendorf & Jeulin 2011).
As in the papers (Phys. Rev. E 83, 041804; ISMM 2011): random walks, then a force-biased packing, to high volume fractions (0.51 for isotropic fibres of aspect ratio 11, 0.64 nearly aligned). A fibre of radius
r(fromradius) and contour lengthL(fromlength) is a chain ofm = round(L / (step r))steps of lengthL / m. Its main directionmufollowsorientation(in the papers Schladitz’s beta law,{type: beta, beta: 0.1}about z); each step follows the multivariate von Mises-Fisher law of density proportional toexp(kappa1 mu.t + kappa2 t'.t),t'the previous step (mufor the first):kappa1, the reliability to the main direction, holds the fibre to it,kappa2, the reliability to the previous step, sets the smoothness of its bending. The chain is turned about its first node, uniform in the box, so that its end-to-end vector followsmu; as many fibres as bring their total volumepi r^2 L + 4/3 pi r^3closest tovolume_fraction(ornumberof them). As in Altendorf, Jeulin & Willot (Int. J. Solids Struct. 51, 3807, 2014):placement_trials > 1places the fibres one after another at the best of that many uniform positions, the one of least overlap with the fibres placed before it (the sum of the depths of the overlapping pairs of segments;morphogen.kernels.force_biased.place()), which shortens the packing (2.5 to 9 times fewer steps for 30 trials, the more the looser the packing); the orthotropic laws of their glass fibres are mixtures of beta laws ({type: mixture, laws: [...], weights: [...]}).packing: true: the chains are packed by the forces of the paper (morphogen.kernels.force_biased), repulsions of the overlapping segments plusrecoverytimes the springs on their lengths and the open angular springs on the joints, until the total force falls below0.04 rper fibre and the largest overlap below0.1 r_min(else, aftermax_stepssteps, the fraction is out of reach); the overlaps left are removed by steps of repulsions alone (end_step: repulsion, the radii kept but for a residue) or by reducing the radius of each fibre by half its largest overlap (shrink, the paper’s end step).packing: false: the overlapping walks, a Boolean model whosevolume_fractionis that of the union.interaction_distance > 0: the contact packing of Keilmann, Redenbach & Willot (Comput. Mater. Sci. 264, 114458, 2026), which raises the number of contacts. After the packing, the pairs of segments of different fibres whose surfaces are closer thancontact_distance + interaction_distanceare candidates, shortlisted so that a segment keeps only its closest candidate of each other fibre; the packing runs again with the contact forces, each shortlisted pair drawn together bycontact_weighttimes half its excess overcontact_distance(smoothed by the friction ramp overcontact_distance), until the total force changes by less than 0.001 % over a step (1000 steps at most); the pairs that leave a force abovecontact_thresholdtimes the mean radius on one of their nodes (conflicting forces) are released and the packing run once more, before the end step. The summary counts the contacts after the packing (and before the contact packing,*_before): the pairs of fibres closer thancontact_distance(plus 1 % of the smallest radius), their mean number per fibre, and the clots, connected components of the segments in contact (consecutive ones of a fibre joined) that hold more than two fibres; the theory gives Toll’s estimate for straight fibres of the same lengths, the contacts per fibre of their Boolean model.Choices (the papers leave them open or differ): chains of spherocylinders instead of balls
r/2apart (smooth fibres, anystep, no overlap meaning axes at leastr_a + r_b + min_gapapart), the push of a segment shared by its nodes with the barycentric weights of its closest point; one radius per fibre; segments of a fibre at mostceil(2.5 / step)steps apart exempt (the paper’s five balls); the moves capped to a quarter of the shortest segment or radius, a segment stretched beyond twice its rest length shortened to it after a step; a joint folded beyond its chord moved towards the middle of the chord; the paper’s tolerance0.002 sper fibre (windows = 20 r) made0.04 r. The realized fraction (volume_fractionof the summary) departs from the target by the change of the contour lengths, which the springs leave free within 5 %. Generated in a periodic box, which fibres may outgrow (they bend around their images); non-periodic domains are cut from a periodic box enlarged by half the reach of a fibre on every side.- phases: ClassVar[dict[int, str]] = {0: 'matrix', 1: 'fibres'}¶
Meaning of the phase indices of the voxel images.
- count_label: ClassVar[str] = 'fibres'¶
Objects counted by
expected_count()(fibres, spheres, cells…).
- property mean_volume: float¶
- property mean_surface: float¶
- walks(rng, radii, lengths) tuple[ndarray, ndarray][source]¶
The nodes of the walks of fibres of the given radii and contour lengths (from their first nodes), all chains one after another, and the index of the first node of each chain (then the number of nodes).
- generate(domain: Domain, seed: int | SeedSequence | Generator | None = None) PrimitiveUnion[source]¶
One realization of the model in
domain.
- morphogen.models.fibers.mean_sine(orientation: OrientationDistribution, pairs: int = 200000) float[source]¶
E|sin g|,gthe angle between two independent axes of the law: pi/4 isotropic, 2/pi planar, 0 aligned, otherwise by Monte Carlo overpairspairs drawn from a fixed seed (deterministic, to about 0.2 %).
- morphogen.models.fibers.excluded_volume(reach: float, length: float, length2: float, sine: float) float[source]¶
Mean volume of the centres of a straight fibre whose axis comes closer than
reachto that of another one (axes of mean lengthlengthand mean product of two lengthslength2,E|sin g| = sinebetween them): the parallelogram swept by one axis along the other dilated by a ball (Steiner),4/3 pi D^3 + 2 pi D^2 l + 2 D l1 l2 E|sin g|(Onsager’s excluded volume forD = 2r).
- class morphogen.models.fibers.CrossLinkedFibers(radius: float = 0.5, length: float | None = None, orientation: OrientationDistribution = Isotropic(), volume_fraction: float | None = None, length_density: float | None = None, contact_gap: float = 0.0, bonded_fraction: float = 1.0, link_radius: float = 0.75, link_phase: int = 2)[source]¶
Bases:
ModelEntangled cross-linked fibres: straight fibres bonded by cross-links at a fraction of their contacts (Mezeix et al. 2009, 2016; Chatti et al. 2018, 2020).
As in Chatti et al. (Comput. Mater. Sci. 151, 14, 2018; Int. J. Solids Struct. 184, 221, 2020), the volume elements of carbon fibres sprayed with epoxy: straight fibres of radius
radius, in contact where their axes come closer than a diameter (pluscontact_gap: a contact is a crossing), each contact bonded by a cross-link with the probabilitybonded_fraction(theirs: 1/3 to 1).length: null: infinite fibres on Poisson lines whose directions followorientation(the fibres of Chatti et al., 12 mm long, cross their 1 mm volume element; non-periodic samples, the exact restriction of the infinite medium); alength: a Boolean model of spherocylinders of that cylindrical length (Mikado networks; periodic or not).orientation: isotropic, or for their moulded material{type: girdle, sigma: 0.4}, their Gaussian law of the angle to the axis of compression (eq. 3). A cross-link is a ball of radiuslink_radiuscentred between the closest points of the axes, of phaselink_phaseoutside the fibres (2; 1: merged with them). All the contacts bonded, the networks cross-linked at every crossing of Ban et al. (2016), Shahsavari & Picu (2015) or Bosco et al. (2017).The contacts along a fibre axis form, for Poisson lines, a Poisson process of intensity
2 D L_V E|sin g|(D = 2r + contact_gap,gthe angle between two fibres,E|sin g| = pi/4isotropic): the contacts are on average1 / (pi r L_V)apart along an isotropic fibre, aboutd / 2fat small fractionsf(Mezeix et al. 2016, eq. 16, after Toll), the cross-links1 / bonded_fractiontimes farther; a finite fibre has on averagetheta (4/3 pi D^3 + 2 pi D^2 l + 2 D l^2 E|sin g|)contacts (its excluded volume). The summary counts the contacts and cross-links centred in the domain and their spacings along the axes inside it.- phases: ClassVar[dict[int, str]] = {0: 'pores', 1: 'fibres', 2: 'cross-links'}¶
Meaning of the phase indices of the voxel images.
- count_label: ClassVar[str] = 'fibres'¶
Objects counted by
expected_count()(fibres, spheres, cells…).
- property supports_periodic: bool¶
Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.
- active_phases() dict[int, str][source]¶
Phases the realizations of this model can contain, with their names (the
phasesof the model, unless its parameters choose them).
- property grain_volume: float¶
an infinite cylinder per unit length, or a spherocylinder.
- Type:
Volume of a fibre
- property lv: float¶
Mean length of fibre axes (cylindrical parts) per unit volume.
- property contact_reach: float¶
Distance between axes below which two fibres are in contact.
- contacts(start, end, domain: Domain) tuple[ndarray, ndarray][source]¶
The contacts of the fibres of axes
start -> end: the pairs(i, j)of fibres whose axes come closer thancontact_reach(nearest periodic images in a periodic domain) and the middles of their closest points (wrapped into a periodic domain).
- generate(domain: Domain, seed: int | SeedSequence | Generator | None = None) PrimitiveUnion[source]¶
One realization of the model in
domain.