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 - 1atpoints(y-space: the seeds are spheres of radiiradii) and the indices of their seeds, from theknearest 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:
MicrostructureA foam, the region
Phi <= 0of 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_N4and the indices of their seeds atpoints(n x 3).
- learn_struts(dn: ndarray, nn: ndarray) None[source]¶
Largest
D_N4 - D_N3of 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).
- 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**3sub-samples per voxel).
- level_set(shape=None, *, voxel_size=None, grid: Grid | None = None) VoxelImage[source]¶
Phitimes half the mean short semi-axis: negative in the solid, roughly a distance near its surface (|grad D_i|is about2 / athere).
- lipschitz: float = 1.5¶
Phigrows at most twice as fast as the distance to the nearest seed
- level_set_at(points, reach: float = inf) ndarray[source]¶
Phitimes half the mean short semi-axis at the points, aslevel_set().
- 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:
ModelOpen- 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.
- 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:
objectThe result of
calibrate_seeds(): the calibratedmodel, thescaleof its seeds relative to the initial model and theiraspect, thetargetandachievedmean section radii (axis -> radius), thehistoryof (scale, aspect, achieved) over the iterations and thesectionsof 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_shapechange their shape factors, until the mean radii of the sections of itsphase(the pores) by the planes normal to the axes oftarget(a mapping axis -> mean radius, or the measuredSections) match them withintol. 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_shapeneeds the three axes; otherwise the step is the mean logarithmic deviation, and the iterations stop when it falls belowtol / 2, a shape that does not fit the sections leaving its misfit inSeedCalibration.residual); each foam is generated with the sameseed(drawn once if None) on the gridshapeorvoxel_sizeand measured as the target should have been (separate,prominence,min_radius: seesection_sizes()).