morphogen.models.levelset_foam

Foams as level sets of distance fields (Sonon, François & Massart 2012, 2015; Kilingar, Sonon & Massart 2019; Degdeg & Dirrenberger 2026).

Seeds: non-overlapping ellipsoids aligned with the axes, of short semi-axis a (a distribution) and shape factors b/a and c/a (aspect): a dense packing of polydisperse spheres (Lubachevsky–Stillinger) or their random sequential addition, mapped by the stretch of the y and z axes, so that the packing of the ellipsoids is the affine image of that of spheres (as the packing of Degdeg & Dirrenberger, whose aligned ellipsoids fall into a container). Each seed defines the normalized algebraic distance

D_i(x) = sum_m (x_m - x_im)^2 / r_im^2 - 1

(-1 at its centre, 0 on its surface), and D_N1 <= D_N2 <= D_N3 <= D_N4 are the four smallest at x. The open foam is the region Phi <= 0 of

Phi = O_p - t O_s - K_c O_k O_p = (D_N3 + D_N2)/2 - D_N1 zero on the edges of the tessellation O_s = sqrt(c1 xi^4 + c2 xi^2 + 1) thickening towards the nodes O_k = min(0, (delta^2 - w^2) / (2 w)) delta = (D_N3 - D_N2)/2, w = t O_s

t the thickness (dimensionless; or solved for a volume_fraction), K_c the curvature of the cross-sections of the struts (0 < K_c < 1: the concave Plateau borders of drained foams; K_c < 0: convex), xi the position along the strut (0 at mid-span, 1/2 at the nodes): D_N4 - D_N3 vanishes at the nodes and is largest at mid-span, and xi = (1 - (D_N4 - D_N3)/m)/2 with m its largest value near the axis of the strut (the strut of the three nearest seeds), found on a fine grid at generation. Closed cells add walls where D_N2 = D_N1: Phi = min(Phi, (D_N2 - D_N1)/2 - t_w).

calibrate_seeds() scales the seeds (and, if asked, changes their shape factors) until the mean radii of the sections of the pores by the planes of the grid match measured ones, the cells of a packing being larger than its seeds.

morphogen.models.levelset_foam.nearest_distances(points, centres, radii, box, periodic: bool, k: int = 16)[source]

The four smallest |y - y_i|^2 / a_i^2 - 1 at points (y-space: the seeds are spheres of radii radii) and the indices of their seeds, from the k nearest centres (more where the four could hide beyond them).

morphogen.models.levelset_foam.strut_keys(nn: ndarray, n: int) → ndarray[source]

Key of the strut of the three nearest seeds (their sorted indices).

class morphogen.models.levelset_foam.DistanceFieldFoam(domain, centres, axes, box_lower, box_lengths, thickness, *, curvature: float = 0.0, c1: float = 0.0, c2: float = 0.0, cells: str = 'open', wall_thickness: float = 0.0, periodic_box: bool = True, struts=None, **kwargs)[source]

Bases: Microstructure

A foam, the region Phi <= 0 of the level-set function of its seeds (see the module); the same realization can be evaluated at any resolution and point.

distances(points) → tuple[ndarray, ndarray][source]

D_N1..D_N4 and the indices of their seeds at points (n x 3).

learn_struts(dn: ndarray, nn: ndarray) → None[source]

Largest D_N4 - D_N3 of each strut, over the points near its axis.

phi(dn, nn, thickness: float | None = None) → ndarray[source]

The level-set function (solid where it is not positive).

values(points) → ndarray[source]
field(shape=None, *, voxel_size=None, grid: Grid | None = None) → VoxelImage[source]
voxelize(shape=None, *, voxel_size=None, grid: Grid | None = None, supersampling=1)[source]

Phase image (uint8), or partial volume fractions of phase 1 (float32) when supersampling > 1 (supersampling**3 sub-samples per voxel).

level_set(shape=None, *, voxel_size=None, grid: Grid | None = None) → VoxelImage[source]

Phi times half the mean short semi-axis: negative in the solid, roughly a distance near its surface (|grad D_i| is about 2 / a there).

contains(points) → ndarray[source]

Whether points lie in phase 1.

lipschitz: float = 1.5

Phi grows at most twice as fast as the distance to the nearest seed

level_set_at(points, reach: float = inf) → ndarray[source]

Phi times half the mean short semi-axis at the points, as level_set().

summary() → dict[source]

Counts and sizes describing the realization.

class morphogen.models.levelset_foam.LevelSetFoam(seed_radius: Distribution = Constant(value=0.1), aspect: tuple[float, ...] = (1.0, 1.0), packing: str = 'dense', packing_fraction: float = 0.6, thickness: float | None = None, volume_fraction: float | None = None, curvature: float = 0.0, c1: float = 0.0, c2: float = 0.0, cells: str = 'open', wall_thickness: float = 0.05, growth_rate: float = 0.01)[source]

Bases: Model

Open- or closed-cell foams as level sets of the distance fields of a packing of aligned ellipsoids (Sonon et al. 2012; Kilingar et al. 2019; Degdeg & Dirrenberger 2026): struts with Plateau-border cross-sections of controlled curvature, thickening towards the nodes, cells elongated by the shape of the seeds (see the module).

phases: ClassVar[dict[int, str]] = {0: 'pores', 1: 'solid'}

Meaning of the phase indices of the voxel images.

count_label: ClassVar[str] = 'seeds'

Objects counted by expected_count() (fibres, spheres, cells…).

property scale: ndarray
seeds(domain: Domain, rng) → tuple[ndarray, ndarray, Domain][source]

Centres and semi-axes of the seed ellipsoids, and their periodic box (the domain if periodic, enlarged by two long semi-axes otherwise).

generate(domain: Domain, seed: int | SeedSequence | Generator | None = None) → DistanceFieldFoam[source]

One realization of the model in domain.

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

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.levelset_foam.SeedCalibration(model: Model, scale: float, aspect: tuple[float, float], target: dict[int, float], achieved: dict[int, float], history: list, sections: list)[source]

Bases: object

The result of calibrate_seeds(): the calibrated model, the scale of its seeds relative to the initial model and their aspect, the target and achieved mean section radii (axis -> radius), the history of (scale, aspect, achieved) over the iterations and the sections of the last foam.

property residual: float

The largest relative deviation of the achieved mean section radii.

morphogen.models.levelset_foam.calibrate_seeds(model: LevelSetFoam, domain: Domain, target, *, shape=None, voxel_size=None, phase: int = 0, fit_shape: bool = False, separate: bool = True, prominence: float | None = None, min_radius: float = 0.0, iterations: int = 8, tol: float = 0.01, seed: int | SeedSequence | Generator | None = None) → SeedCalibration[source]

Scale the seeds of a foam, and with fit_shape change their shape factors, until the mean radii of the sections of its phase (the pores) by the planes normal to the axes of target (a mapping axis -> mean radius, or the measured Sections) match them within tol. Gauss–Newton steps in the logarithms of the scale and of the shape factors with the Jacobian of ellipsoids, log r_D = log s + log kappa_D(b/a, c/a) (fit_shape needs the three axes; otherwise the step is the mean logarithmic deviation, and the iterations stop when it falls below tol / 2, a shape that does not fit the sections leaving its misfit in SeedCalibration.residual); each foam is generated with the same seed (drawn once if None) on the grid shape or voxel_size and measured as the target should have been (separate, prominence, min_radius: see section_sizes()).