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, ..., Tislambda_t = lambda_0 t^-alphathick (initial_thicknessanddecay);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
tof a thin network (lambda_0 -> 0) in a box of areaA, measured with uniform orientations: 1.1663 and 1.1658 (standard errors 0.0004) over the ligamentst >= 2000of 120 realizations of 20,000 in a square and in a 2 x 1 rectangle. The first ligament isl_0(first_length(), 0.9464 in a square), the next ones approach the limit (1.05, 1.09, 1.12 att= 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 labelledlabel(Sutherland-Hodgman).
- morphogen.models.scale_rich.chord(xy, faces, px, py, dx, dy)[source]¶
Where the line
p + s dleaves a convex polygon holdingp: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:
objectThe ligaments and voids of a scale-rich network (coordinates of the plane).
- property n: int¶
- property n_cells: int¶
- property lengths: ndarray¶
The lengths of the centre lines of the ligaments.
- links() ndarray[source]¶
The pairs of ligaments joined: each ligament with those on which its ends lie (the edges of the dual graph, each once).
- 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 ligamentt = 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 ofScaleRichNetworkis solved on realizations of the same seed). The growth stops, jammed, aftermax_attemptsnucleation 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 brectangle: the chord through a uniform point along a uniform direction,int l^2 dG / (pi a b)over the linesG. Withd = 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 ofTligaments in ana x brectangle:l_0 / sqrt(A) + c sum_{t=2..T} t^-(alpha + 1/2)(LENGTH_CONSTANT), the relative density per unit oflambda_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 areaA_v / t(A_vthe area of the voids), so thatdA_v/dt = -lambda_t c sqrt(A_v / t)andsqrt(A_v / A) = 1 - rho_1 / 2:rho = rho_1 (1 - rho_1 / 4), jammed (1) fromrho_1 = 2on. Inddimensions (plates in 3D:rho_1 = sum_t lambda_t E[a_t] / V, the areaa_tof a plate aboutc_3 (V_v / t)^(2/3)),(V_v / V)^(1/d) = 1 - rho_1 / d:rho = 1 - (1 - rho_1 / d)^d, jammed fromrho_1 = don.
- class morphogen.models.scale_rich.ScaleRichStructure(domain: Domain, axis: int, growth: Growth, frame: float = 0.0, **kwargs)[source]¶
Bases:
MicrostructureA 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 aframe, 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.
- 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. find1 + 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 withinreach(the distance to the nearest one, or less), capped atreach; with a frame, the least of this and the signed distance to the inner side of the frame.
- level_set_at(points, reach: float = inf) ndarray[source]¶
plane_field()of the points withinreach(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**3sub-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.
- 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:
ModelScale-rich network (Both et al. 2026): ligaments
lambda_0 t^-alphathick grown one after another from points of the voids until they meet: by default (dimension: 2) in the plane of the axes other thanaxisand extruded along it (seemorphogen.models.scale_rich); withdimension: 3, plates or beams in the box (seemorphogen.models.scale_rich_3d). The initial thickness is given, or solved on each realization for a relative density (volume_fraction). Orientations uniform, amongangles(2D) or drawn from a law (3D), or polarized by apole; 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 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_fractionby the theory (uniform orientations and nucleation),rhothe density of the network within the frame (of areaA, volumeV): 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 ofbeam_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/alphaof 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)inddimensions). With the domain, for uniform orientations and nucleation: in 2D, the mean length of the first ligament (first_length(), exact), the first orderrho_1 = lambda_0 S / sqrt(A)of the relative density (length_sum()), its mean-field estimaterho_1 (1 - rho_1 / 4)(density_estimate()), the initial thickness at whichTligaments jam (rho_1 = 2) and, foralpha > 1/2, at which an endless growth jams (Swithzeta(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 atrho_1 = 3, endless foralpha > 1/3(zeta(alpha + 2/3)); with beams, the mean-field estimate ofbeam_density_estimate(). With avolume_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.