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

Infinite cylinders of radius R around Poisson lines, isotropic or of directions drawn from orientation.

The model is parameterized by the volume fraction p of fibres or by the mean fibre length per unit volume L_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 is theta = L_V / pi and p = 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 direction u hitting a convex body are those crossing its projection on the plane normal to u (on average L_V S / 4 isotropic lines, Cauchy), and those hitting the fibres hit A' (+) K': for balls of radius size a ball of radius R + r (any law), for segments of length size along direction a spherocylinder of projection pi R^2 + 2 R l |sin g| (g its angle to the line, E|sin g| = pi/4 for isotropic lines; without a direction, the mean of the capacities over the directions); pairs of points at distance size: 2 p - C(h).

expected_fibers(domain: Domain) → float[source]

Mean number of fibre axes hitting the box, L_V times the mean area of its projection along the lines, sum_k A_k E|u_k| (A_k the area of the faces normal to the axis k): L_V S / 4 for 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 h along direction (any for isotropic lines; averaged over the directions of h without one).

The lines of direction u hitting {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 to u (b the angle between h and u): 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: Model

Non-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 than min_gap to 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.

expected_count(domain: Domain) → float | None[source]

Mean number of fibre centres in the domain (given a volume fraction).

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).

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

Curved fibres: chains of segments straight spherocylinders along curved axes, a Boolean model or non-overlapping fibres.

shape sets the axes. worm_like: the direction performs a persistent random walk, each segment of length ds = length / segments turning from the previous one by an angle whose cosine follows the von Mises-Fisher distribution of mean exp(-ds / persistence), about a uniformly random perpendicular axis, so that the tangents decorrelate as exp(-s / persistence) along the contour (the discrete worm-like chain); the first direction follows orientation. arc: circular arcs of radius curvature_radius (a distribution) bent in a uniformly random plane, the tangent at the middle of the contour following orientation (the curved fibres of PuMA). helix: crimped fibres, helices of radius helix_radius and pitch helix_pitch about straight axes following orientation, 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 than min_gap to 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 n worm-like chains.

axes(rng, n: int) → ndarray[source]

Points (n x (segments + 1) x 3) of the axes of n fibres, 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.

expected_count(domain: Domain) → float[source]

Mean number of fibre centres in the domain.

mean_square_end_to_end() → float[source]

Mean square distance between the ends of the axis of a fibre: for worm-like chains ds^2 (m + 2 sum_d (m - d) c^d); the chords of the arcs (exact for their polylines); the axial advance and the radial chord of the helices.

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).

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 of mean (unit vectors m) and entry of kappa (>= 0; 0 is uniform): the cosine w = m.x by inversion, w = 1 + ln(u + (1 - u) e^(-2 kappa)) / kappa, the azimuth about m uniform.

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 k follows the multivariate von Mises-Fisher law of density proportional to exp(kappa1 mu.t + kappa2 t_(k-1).t), mu the main direction (a row of main) and t_0 = mu, i.e. the von Mises-Fisher law about kappa1 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: Model

Bending 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 (from radius) and contour length L (from length) is a chain of m = round(L / (step r)) steps of length L / m. Its main direction mu follows orientation (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 to exp(kappa1 mu.t + kappa2 t'.t), t' the previous step (mu for 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 follows mu; as many fibres as bring their total volume pi r^2 L + 4/3 pi r^3 closest to volume_fraction (or number of them). As in Altendorf, Jeulin & Willot (Int. J. Solids Struct. 51, 3807, 2014): placement_trials > 1 places 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 plus recovery times the springs on their lengths and the open angular springs on the joints, until the total force falls below 0.04 r per fibre and the largest overlap below 0.1 r_min (else, after max_steps steps, 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 whose volume_fraction is 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 than contact_distance + interaction_distance are 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 by contact_weight times half its excess over contact_distance (smoothed by the friction ramp over contact_distance), until the total force changes by less than 0.001 % over a step (1000 steps at most); the pairs that leave a force above contact_threshold times 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 than contact_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/2 apart (smooth fibres, any step, no overlap meaning axes at least r_a + r_b + min_gap apart), 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 most ceil(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 tolerance 0.002 s per fibre (window s = 20 r) made 0.04 r. The realized fraction (volume_fraction of 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.

expected_count(domain: Domain) → float | None[source]

Mean number of fibres in the domain (given a volume fraction).

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).

morphogen.models.fibers.mean_sine(orientation: OrientationDistribution, pairs: int = 200000) → float[source]

E|sin g|, g the angle between two independent axes of the law: pi/4 isotropic, 2/pi planar, 0 aligned, otherwise by Monte Carlo over pairs pairs 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 reach to that of another one (axes of mean length length and mean product of two lengths length2, E|sin g| = sine between 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 for D = 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: Model

Entangled 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 (plus contact_gap: a contact is a crossing), each contact bonded by a cross-link with the probability bonded_fraction (theirs: 1/3 to 1). length: null: infinite fibres on Poisson lines whose directions follow orientation (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); a length: 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 radius link_radius centred between the closest points of the axes, of phase link_phase outside 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, g the angle between two fibres, E|sin g| = pi/4 isotropic): the contacts are on average 1 / (pi r L_V) apart along an isotropic fibre, about d / 2f at small fractions f (Mezeix et al. 2016, eq. 16, after Toll), the cross-links 1 / bonded_fraction times farther; a finite fibre has on average theta (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 phases of 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 than contact_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.

expected_count(domain: Domain) → float[source]

Mean number of fibre axes crossing the domain: theta V in a periodic box; else, A the mean area of the projection of the box along the fibres (S / 4 if isotropic), L_V A for lines and theta (V + l A) for segments.

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).