morphogen.models.scale_rich

Scale-rich networks: ligaments of power-law thicknesses grown one after another until they meet (Both, Chen, Gao, Mooij, Charara, Wadhwa, Portela & Barabási 2026).

Mechanical metamaterials are usually ruled by one length, that of their cell. Scale-rich networks give up that length: their ligaments span orders of magnitude in thickness, length and connectivity within one sample, as the veins of leaves and dragonfly wings, the threads of spider webs or the roads of a city. Both et al. (Nature 659, 345, 2026) grow them from two parameters:

  • the ligament t = 1, 2, ..., T is lambda_t = lambda_0 t^-alpha thick (initial_thickness and decay);

  • it nucleates at a point drawn uniformly in the voids left by the ligaments before it, along an angle theta_t, and grows both ways until it meets the face of another ligament or the boundary of the box.

The voids are convex cells (at first the rectangle of the box), each bounded by faces of ligaments and of the box. A ligament lies in the cell of its nucleation point: it is the strip of width lambda_t along its line clipped by that cell, which it splits into two convex cells (the scheme of the reference implementation of the authors). The point is drawn uniformly in the box until it falls in a void, the same law as a void drawn in proportion to its area then a point uniform in it. Ligaments and voids partition the box exactly, so that the relative density 1 - sum(void areas) / A is exact; the ligaments never overlap. A ligament fits when its cell holds the two points at (lambda_t + epsilon) / 2 on either side of its nucleation point (epsilon: min_spacing, the least width of the voids beside a new ligament); when max_attempts draws in a row do not fit, the network is jammed and stops growing. The length of a ligament is that of its centre line in its cell; its neighbours are the ligaments (or the box) on which its two ends lie. As roads in the dual graphs of road networks (Rosvall et al. 2005), the ligaments are the nodes of the network and their junctions its links: the degree k of a ligament counts the ligaments on which it ends and those that end on it.

Laws (Both et al. 2026): the thicknesses follow P(lambda) ~ lambda^-(1 + 1/alpha) exactly; a ligament splits a cell of area about A_t / t, so that its length decays as t^-1/2 (A_t: the area of the voids) and the lengths have the tail P(l) ~ l^-3; a long ligament is met by the ligaments that end on it in proportion to its length (a spatial preferential attachment), and the degrees have the tail P(k) ~ k^-3. The relative density is sum_t lambda_t l_t / A (l_t the length of t), see ScaleRichNetwork.theory().

Orientations: uniform (the scale-rich networks of the paper), drawn among angles (aligned networks, e.g. [0, 90]), or polarized by a pole (the ligaments along the direction of the pole turned by pole_angle: radial, tangential or spiral, for the polarized_fraction first of them), each spread by angle_spread (a normal law). The nucleation density may follow a gradient along an axis of the plane or away from the pole (nucleation_gradient). Their combinations draw the designs of Fig. 6 of the paper, as the radial gradient of the pomelo peel protecting a payload.

The network lies in the plane of the two axes other than axis and is extruded along it through the box: the prismatic specimens of the paper (plane strain), one voxel thick for planar images. Its ligaments end on the faces of the box, which is not periodic; a frame of material around the network, on which they end, makes the sample the cell of a periodic medium (FFT solvers, Bloch waves), stiffened by the frame.

With dimension: 3, the network grows in space: plates that split convex polyhedral voids (closed cells), or beams (open cells), see morphogen.models.scale_rich_3d.

morphogen.models.scale_rich.DENSITY_TOL = 0.0002

Tolerance on the relative density of a realization solved for a volume_fraction

morphogen.models.scale_rich.LENGTH_CONSTANT = 1.166

the mean length of the ligament t of a thin network (lambda_0 -> 0) in a box of area A, measured with uniform orientations: 1.1663 and 1.1658 (standard errors 0.0004) over the ligaments t >= 2000 of 120 realizations of 20,000 in a square and in a 2 x 1 rectangle. The first ligament is l_0 (first_length(), 0.9464 in a square), the next ones approach the limit (1.05, 1.09, 1.12 at t = 2, 3, 5)

Type:

lim sqrt(t / A) E[l_t]

morphogen.models.scale_rich.polygon_area(xy) → float[source]

Area of a polygon (counter-clockwise: positive) by the shoelace formula.

morphogen.models.scale_rich.clip_polygon(xy, faces, nx, ny, c, label, tol)[source]

The part of a convex polygon where nx x + ny y <= c: its vertices and the faces of its edges, the edge along the line labelled label (Sutherland-Hodgman).

morphogen.models.scale_rich.chord(xy, faces, px, py, dx, dy)[source]

Where the line p + s d leaves a convex polygon holding p: s0 <= 0 <= s1, and the faces of the edges it leaves by.

morphogen.models.scale_rich.fits(xy, px, py, nx, ny, half) → bool[source]

Whether a convex polygon holds the points p +- half n.

morphogen.models.scale_rich.inside_polygon(xy, px, py) → bool[source]

Whether a convex polygon (counter-clockwise) holds the point p.

class morphogen.models.scale_rich.Growth(nucleation: ndarray, angle: ndarray, thickness: ndarray, ends: ndarray, neighbours: ndarray, body_offsets: ndarray, body_vertices: ndarray, cell_offsets: ndarray, cell_vertices: ndarray, cell_faces: ndarray, jammed: bool = False, attempts: int = 0)[source]

Bases: object

The ligaments and voids of a scale-rich network (coordinates of the plane).

property n: int
property n_cells: int
bodies() → list[ndarray][source]

The vertices of each ligament (convex polygons, counter-clockwise).

cells() → list[ndarray][source]

The vertices of each void (convex polygons, counter-clockwise).

body_areas() → ndarray[source]
cell_areas() → ndarray[source]
property lengths: ndarray

The lengths of the centre lines of the ligaments.

The pairs of ligaments joined: each ligament with those on which its ends lie (the edges of the dual graph, each once).

degrees() → ndarray[source]

The number of ligaments each ligament meets (its degree in the dual graph).

orientation_tensor() → ndarray[source]

M = sum A_t d_t d_t / sum A_t: the directions d_t of the ligaments weighted by their areas A_t (Both et al. 2026, eq. 1, normalized).

morphogen.models.scale_rich.grow(lower, upper, n_ligaments: int, thickness, entropy: int, *, orientation=None, density=None, min_spacing: float = 0.0, max_attempts: int = 1000) → Growth[source]

Grow a scale-rich network in the rectangle [lower, upper] of the plane.

thickness(t) is the thickness of the ligament t = 1, 2, ...; orientation(t, x, y, u, v) its angle (radians) at its nucleation point from two uniform numbers (default: pi u, uniform); density(x, y) the relative density of nucleation in [0, 1] (default: uniform), by rejection. A nucleation point is drawn uniformly in the rectangle until it falls in a void (the law of a void drawn in proportion to its area, then a point uniform in it); each ligament draws from its own generator (SeedSequence(entropy, spawn_key=(t,))): its draws do not depend on the ligaments before it, so that a small change of the thicknesses changes the network only where a point or an end falls close to a moved side (the relative density of ScaleRichNetwork is solved on realizations of the same seed). The growth stops, jammed, after max_attempts nucleation points in a row where the ligament does not fit, or when the voids vanish.

morphogen.models.scale_rich.first_length(a: float, b: float) → float[source]

The mean length of the first ligament in an a x b rectangle: the chord through a uniform point along a uniform direction, int l^2 dG / (pi a b) over the lines G. With d = sqrt(a^2 + b^2):

l_0 = (2 / pi) (a asinh(b / a) + b asinh(a / b) - (a^2 (d - a) + b^2 (d - b)) / (3 a b))

0.946402 for the unit square (Kellerer 1971).

morphogen.models.scale_rich.length_sum(decay: float, n_ligaments: int, a: float, b: float) → float[source]

sum_t l_t t^-alpha / sqrt(A) of a thin network of T ligaments in an a x b rectangle: l_0 / sqrt(A) + c sum_{t=2..T} t^-(alpha + 1/2) (LENGTH_CONSTANT), the relative density per unit of lambda_0 / sqrt(A).

morphogen.models.scale_rich.density_estimate(first_order: float, dimension: int = 2) → float[source]

The relative density of a network from its first order rho_1 = sum_t lambda_t E[l_t] / A (thin ligaments): a ligament splits a void of area A_v / t (A_v the area of the voids), so that dA_v/dt = -lambda_t c sqrt(A_v / t) and sqrt(A_v / A) = 1 - rho_1 / 2: rho = rho_1 (1 - rho_1 / 4), jammed (1) from rho_1 = 2 on. In d dimensions (plates in 3D: rho_1 = sum_t lambda_t E[a_t] / V, the area a_t of a plate about c_3 (V_v / t)^(2/3)), (V_v / V)^(1/d) = 1 - rho_1 / d: rho = 1 - (1 - rho_1 / d)^d, jammed from rho_1 = d on.

class morphogen.models.scale_rich.ScaleRichStructure(domain: Domain, axis: int, growth: Growth, frame: float = 0.0, **kwargs)[source]

Bases: Microstructure

A scale-rich network extruded along axis: its ligaments (phase 1, convex polygons of the plane of the two other axes, which never overlap) and its voids (phase 0, convex cells), which partition the face of the box exactly (grow()); or, with a frame, the face within a frame of that thickness (phase 1 too), on which the ligaments end.

property plane: tuple[ndarray, ndarray]

The lower and upper corners of the face of the box in the plane.

property area: float
property n_ligaments: int
property thicknesses: ndarray
property lengths: ndarray

The lengths of the centre lines of the ligaments in their voids.

degrees() → ndarray[source]

The degree of each ligament in the dual graph: the ligaments it meets.

The pairs of ligaments that meet (an end of the first on the second).

property volume_fraction: float

The fraction of the face in the ligaments and the frame, exact (1 - sum(void areas) / A).

orientation_tensor() → ndarray[source]

The orientation tensor of the ligaments (2 x 2, trace 1, axes of the plane).

property geometric_anisotropy: float

1 for ligaments of isotropic directions, 0 when they are all parallel (Both et al. 2026).

Type:

mu_1 / mu_2, the ratio of the eigenvalues of the orientation tensor

statistics(min_tail: int = 50) → dict[source]

The power-law tails of the thicknesses, lengths and degrees of the ligaments (morphogen.analysis.power_laws.power_law_tail(), degrees as integers): Both et al. find 1 + 1/alpha, 3 and 3 for their exponents. No thicknesses with a decay of 0 (one thickness).

convex_pieces() → tuple[list[tuple], ndarray, ndarray][source]

The convex pieces that partition the box: the ligaments (phase 1, cells 1 to N) and the voids (phase 0, cell 0) extruded along the axis into prisms, and the frame (phase 1, cell N + 1), for the exact meshes of morphogen.mesh.exact.polyhedral_mesh().

plane_field(points, reach: float = 0.0) → ndarray[source]

At points of the plane: max_e (n_e . x - c_e) of the ligament holding them (negative: the distance to its nearest side, or less), or the least such value of the ligaments within reach (the distance to the nearest one, or less), capped at reach; with a frame, the least of this and the signed distance to the inner side of the frame.

contains(points) → ndarray[source]

Whether points lie in phase 1.

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

plane_field() of the points within reach (default: the diagonal of the box), the network extruded along the axis.

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]

Negative in the ligaments, positive in the voids: the distance to the sides of the ligaments near them (a lower bound near their corners), within the largest half thickness and four voxels of them.

summary() → dict[source]

The counts, thicknesses, lengths, degrees and anisotropy of the network (the columns of the tables of results).

class morphogen.models.scale_rich.ScaleRichNetwork(n_ligaments: int = 500, dimension: int = 2, element: str = 'plates', decay: float = 0.5, initial_thickness: float | None = None, volume_fraction: float | None = None, min_spacing: float = 0.0, angles: tuple[float, ...] | None = None, orientation: OrientationDistribution | None = None, angle_spread: float = 0.0, pole: tuple[float, ...] | None = None, pole_angle: float = 0.0, polarized_fraction: float = 1.0, nucleation_gradient: tuple[float, ...] | None = None, gradient_axis: int | None = None, radial_gradient: bool = False, frame: float = 0.0, axis: int = 2, max_attempts: int = 1000)[source]

Bases: Model

Scale-rich network (Both et al. 2026): ligaments lambda_0 t^-alpha thick grown one after another from points of the voids until they meet: by default (dimension: 2) in the plane of the axes other than axis and extruded along it (see morphogen.models.scale_rich); with dimension: 3, plates or beams in the box (see morphogen.models.scale_rich_3d). The initial thickness is given, or solved on each realization for a relative density (volume_fraction). Orientations uniform, among angles (2D) or drawn from a law (3D), or polarized by a pole; a gradient of the nucleation density. Non-periodic: the ligaments end on the boundary of the box (or on a frame).

phases: ClassVar[dict[int, str]] = {0: 'voids', 1: 'ligaments'}

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] = 'ligaments'

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

property isotropic: bool

the laws of theory() hold.

Type:

Uniform orientations and nucleation

property plates: bool

Plates in 3D (closed cells), or the extruded ligaments of a planar network.

thickness_estimate(domain: Domain) → float[source]

The initial thickness of the volume_fraction by the theory (uniform orientations and nucleation), rho the density of the network within the frame (of area A, volume V): in 2D, lambda_0 = 2 sqrt(A) (1 - sqrt(1 - rho)) / S (density_estimate(), length_sum()); with plates, lambda_0 = 3 V^(1/3) (1 - (1 - rho)^(1/3)) / S (area_sum()); with beams, the mean field of beam_density_estimate().

generate(domain: Domain, seed: int | SeedSequence | Generator | None = None) → Microstructure[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]

The exponent 1 + 1/alpha of the law of the thicknesses (exact, alpha > 0), and the asymptotic exponents of the tails of the sizes and degrees: 3 for the lengths and degrees of a planar network (Both et al. 2026), 5/2 for the areas and degrees of plates ((2d - 1) / (d - 1) in d dimensions). With the domain, for uniform orientations and nucleation: in 2D, the mean length of the first ligament (first_length(), exact), the first order rho_1 = lambda_0 S / sqrt(A) of the relative density (length_sum()), its mean-field estimate rho_1 (1 - rho_1 / 4) (density_estimate()), the initial thickness at which T ligaments jam (rho_1 = 2) and, for alpha > 1/2, at which an endless growth jams (S with zeta(alpha + 1/2): the boundary of the phase diagram of the paper); with plates, the mean area of the first plate (first_area(), exact), rho_1 = lambda_0 S / V^(1/3) (area_sum()), 1 - (1 - rho_1 / 3)^3, jammed at rho_1 = 3, endless for alpha > 1/3 (zeta(alpha + 2/3)); with beams, the mean-field estimate of beam_density_estimate(). With a volume_fraction, the initial thickness that the theory gives it. With a frame, the network fills the region within it, and the relative densities count the frame.