morphogen.models.scale_rich_3d

Scale-rich networks in three dimensions: plates or beams of power-law thicknesses grown one after another until they meet (Both et al. 2026, Fig. 6a and Supplementary S2.5-S2.7).

The sequential growth of morphogen.models.scale_rich extends to space by adding non-crossing plates or beams, lambda_t = lambda_0 t^-alpha thick:

  • plates: the plate t nucleates at a point drawn uniformly in the voids, with a normal n_t (uniform on the sphere, or drawn from a law), and grows in its plane until it meets other plates or the box. The voids are convex polyhedra (at first the box), bounded by faces of plates and of the box; the plate is the slab |n_t . x - c_t| <= lambda_t / 2 clipped by the void of its nucleation point, which it splits into two convex voids. Plates and voids partition the box exactly (the relative density is exact), the plates never overlap, and every void is a closed cell. The rim of a plate is the section of its void by its mid-plane: a convex polygon whose edges lie on the faces of the plates (or of the box) on which the plate ends, its neighbours. The area of a plate is that of its rim.

  • beams: the beam t (a cylinder of diameter lambda_t with round ends) nucleates at a point of the voids where it clears the other beams and the box, along an axis d_t, and grows both ways until its axis reaches the surface of another beam (a T-junction), or passes within contact of one (the axis ends at its closest approach, a lateral junction), or reaches the box. Beams do not split space: their voids form one connected, open cell.

A plate (beam) fits when its void holds the points p +- (lambda_t + epsilon) / 2 n_t (when the ball of radius (lambda_t + epsilon) / 2 about p clears the beams and the box); max_attempts draws in a row that do not fit jam the network. Each element draws its nucleation points and directions from its own generator, so that the network moves little when lambda_0 changes (see morphogen.models.scale_rich.grow()).

Laws: the thicknesses as in the plane, P(lambda) ~ lambda^-(1 + 1/alpha); a plate splits a void of volume about V_v / t, so that its area decays as t^-2/3 and the areas have the tail P(a) ~ a^-5/2, as the degrees (a plate is met by the later ones in proportion to its area): (2d - 1) / (d - 1) in d dimensions, 3 in the plane. The relative density of plates is exact, and in closed form to a mean field (first_area(), area_sum(), morphogen.models.ScaleRichNetwork.theory()); that of beams, the volume of the cylinders on their axes, follows the mean field of their free paths (beam_density_estimate()). Orientation laws, poles, gradients and frames: see morphogen.models.ScaleRichNetwork.

morphogen.models.scale_rich_3d.BOX = -1

their index)

Type:

Label of the faces of the voids on the boundary of the box (plates

morphogen.models.scale_rich_3d.AREA_CONSTANT = 1.236

the mean area of the plate t of a thin network (lambda_0 -> 0) in a box of volume V, measured with uniform normals: 1.2363 (standard error 0.0005) over the plates t >= 2000 of 120 realizations of 20,000 in a cube. The first plate is a_0 (first_area(), 0.9412 in a cube), the next ones approach the limit faster than in the plane (1.08, 1.13 at t = 2, 3; 1.24 from t = 10 on)

Type:

lim (t / V)^(2/3) E[a_t]

morphogen.models.scale_rich_3d.UNION_POINTS_LOG2 = 20

Points (2^k) of the quasi-Monte Carlo estimate of the relative density of beams, the volume of their union in the box (a scrambled Sobol set of a fixed seed, the same for every network): within 1.5e-4 of 2^22 points over 8 networks (5.8e-4 with 2^18)

morphogen.models.scale_rich_3d.clip_polyhedron(verts, fofs, labels, normals, planes, nx, ny, nz, c, label, tol)[source]

The part of a convex polyhedron where n . x <= c: its faces, the section by the plane (when it is a polygon) labelled label (n a unit vector).

morphogen.models.scale_rich_3d.section(verts, fofs, labels, normals, planes, nx, ny, nz, c, tol)[source]

The section of a convex polyhedron by the plane n . x = c: its vertices, counter-clockwise about n, and the label of the face of each edge.

morphogen.models.scale_rich_3d.polyhedron_volume(verts, fofs, normals, planes) → float[source]

Volume of a convex polyhedron: sum_f (c_f - n_f . x_0) A_f / 3 (the cones of its faces from a vertex x_0).

morphogen.models.scale_rich_3d.polygon_area_3d(verts) → float[source]

Area of a planar polygon of space (vertices in order).

morphogen.models.scale_rich_3d.inside_polyhedron(normals, planes, px, py, pz) → bool[source]

Whether a convex polyhedron (its face planes) holds the point p.

morphogen.models.scale_rich_3d.fits_polyhedron(normals, planes, px, py, pz, nx, ny, nz, half) → bool[source]

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

morphogen.models.scale_rich_3d.box_polyhedron(lower, upper)[source]

The box [lower, upper] as a convex polyhedron (faces labelled BOX).

morphogen.models.scale_rich_3d.frame_boxes(lower, upper, frame: float) → list[tuple][source]

The six boxes that make the frame [lower, upper] minus its inner box (frame thick), as convex polyhedra.

morphogen.models.scale_rich_3d.prism(polygon, axes, axis: int, z0: float, z1: float) → tuple[source]

The convex polygon of the plane of axes (counter-clockwise vertices) extruded along axis from z0 to z1, as a convex polyhedron (faces labelled BOX).

class morphogen.models.scale_rich_3d.Polyhedra(offsets: ndarray, face_offsets: ndarray, vertices: ndarray, normals: ndarray, planes: ndarray, labels: ndarray)[source]

Bases: object

Convex polyhedra in compressed rows: polyhedron i has the faces offsets[i] to offsets[i + 1]; face f the vertices face_offsets[f] to face_offsets[f + 1] (counter-clockwise about its outward unit normal normals[f]), the plane normals[f] . x = planes[f] and the label of what lies beyond (a plate, or BOX).

classmethod from_list(items: list[tuple]) → Polyhedra[source]

From (vertices, face offsets, labels, normals, planes) tuples.

polyhedron(i: int) → tuple[source]

(vertices, face offsets, labels, normals, planes) of polyhedron i.

faces(i: int) → list[ndarray][source]

The faces of polyhedron i (vertices of each, counter-clockwise from outside).

volumes() → ndarray[source]
bounds() → ndarray[source]

(n, 6): the lower and upper corners of the box of each polyhedron.

to_dict() → dict[source]
class morphogen.models.scale_rich_3d.PlateGrowth(nucleation: ndarray, normal: ndarray, thickness: ndarray, rim_offsets: ndarray, rim_vertices: ndarray, rim_faces: ndarray, bodies: Polyhedra, cells: Polyhedra, jammed: bool = False, attempts: int = 0)[source]

Bases: object

The plates and voids of a scale-rich network of plates.

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

The rim of each plate: the polygon of its mid-plane in its void.

property areas: ndarray

The areas of the plates (of their rims).

body_volumes() → ndarray[source]
cell_volumes() → ndarray[source]

The pairs of plates joined: each plate with the plates on which its rim lies (the edges of the dual graph, each once).

degrees() → ndarray[source]

The number of plates each plate meets (its degree in the dual graph).

boundary_contacts() → ndarray[source]

Whether each plate ends on the box.

orientation_tensor() → ndarray[source]

N = sum V_t n_t n_t / sum V_t: the normals n_t of the plates weighted by their volumes V_t (the fabric tensor of the walls).

morphogen.models.scale_rich_3d.isotropic_directions(t: int, points: ndarray, gen: Generator) → ndarray[source]

Directions uniform on the sphere, one per point.

morphogen.models.scale_rich_3d.grow_plates(lower, upper, n_plates: int, thickness, entropy: int, *, directions=None, density=None, min_spacing: float = 0.0, max_attempts: int = 1000) → PlateGrowth[source]

Grow a scale-rich network of plates in the box [lower, upper].

thickness(t) is the thickness of the plate t = 1, 2, ...; directions(t, points, generator) the unit normals of the plate at candidate nucleation points ((k, 3) arrays; default: uniform on the sphere); density(x, y, z) the relative density of nucleation in [0, 1] (default: uniform), by rejection. As in morphogen.models.scale_rich.grow(), a nucleation point is drawn uniformly in the box until it falls in a void, each plate draws from its own generators (points: SeedSequence(entropy, spawn_key=(t,)), normals: spawn_key=(t, 1)), and the growth jams after max_attempts points in a row where the plate does not fit.

morphogen.models.scale_rich_3d.beam_clearance(px, py, pz, ends, radii, n) → float[source]

min_j (|p - axis_j| - r_j) over the n first beams: negative in a beam, the distance to the nearest one outside (inf: none).

morphogen.models.scale_rich_3d.beam_stop(px, py, pz, dx, dy, dz, smax, ends, radii, n, radius)[source]

How far a beam of radius grows from p along d (|d| = 1) among the n first beams, up to smax (the box): its axis stops where it reaches the surface of a beam, or at its closest approach to a beam it passes within contact (r_j + radius); the distance and the beam (BOX: none).

morphogen.models.scale_rich_3d.beam_contacts(ax, ay, az, dx, dy, dz, length, radius, ends, radii, n, tol)[source]

The beams among the n first ones that the beam of axis a + s d (0 <= s <= length) and radius touches or overlaps (within tol).

class morphogen.models.scale_rich_3d.BeamGrowth(nucleation: ndarray, direction: ndarray, thickness: ndarray, ends: ndarray, neighbours: ndarray, contact_offsets: ndarray, contacts: ndarray, jammed: bool = False, attempts: int = 0)[source]

Bases: object

The beams of a scale-rich network of beams.

property n: int
property radii: ndarray
property lengths: ndarray

The lengths of the axes of the beams.

volumes() → ndarray[source]

The volumes of the cylinders on the axes, pi r^2 l (their round ends lie in the beams they meet or beyond the box).

The pairs of beams joined: each beam with the earlier beams it touches, those that stop its ends and those it meets beside them (the edges of the dual graph, each once).

degrees() → ndarray[source]

The number of beams each beam touches (its degree in the dual graph).

orientation_tensor() → ndarray[source]

M = sum V_t d_t d_t / sum V_t: the axes d_t of the beams weighted by their volumes V_t.

morphogen.models.scale_rich_3d.grow_beams(lower, upper, n_beams: int, thickness, entropy: int, *, directions=None, density=None, min_spacing: float = 0.0, max_attempts: int = 1000) → BeamGrowth[source]

Grow a scale-rich network of beams in the box [lower, upper]: as grow_plates(), thickness(t) the diameter of the beam t and directions its axes. A nucleation point inside a beam is drawn again; the beam fits where the ball of radius (lambda_t + epsilon) / 2 about the point clears the other beams and the faces of the box (beam_clearance()), and grows both ways (beam_stop()).

morphogen.models.scale_rich_3d.mean_inverse_distance(a: float, b: float, c: float) → float[source]

E[1 / |X - Y|] for two points uniform in an a x b x c box (1.882313 for the unit cube, Bailey, Borwein & Crandall 2007).

morphogen.models.scale_rich_3d.first_area(a: float, b: float, c: float) → float[source]

The mean area of the first plate in an a x b x c box: the section by the plane through a uniform point with a uniform normal, int A^2 dE / (4 pi V) over the planes E. As int_S2 delta(n . r) dn = 2 pi / |r|, it is V E[1/|X - Y|] / 2 (mean_inverse_distance()): 0.941156 for the unit cube.

morphogen.models.scale_rich_3d.area_sum(decay: float, n_plates: int, a: float, b: float, c: float) → float[source]

sum_t a_t t^-alpha / V^(2/3) of a thin network of T plates in an a x b x c box: a_0 / V^(2/3) + c_3 sum_{t=2..T} t^-(alpha + 2/3) (first_area(), AREA_CONSTANT), the relative density per unit of lambda_0 / V^(1/3).

morphogen.models.scale_rich_3d.beam_density_estimate(initial_thickness: float, decay: float, n_beams: int, sides) → float[source]

The mean-field relative density of T beams in a box (isotropic axes and nucleation): a beam of radius r_t is stopped by a beam j it passes within r_j + r_t of, whose capsule of that radius has the mean cross-section sigma_j = (pi / 2) (r_j + r_t) l_j + pi (r_j + r_t)^2 (Cauchy: a quarter of its surface), so that each half of its axis runs min(X, D): X exponential of rate h_t = sum_j sigma_j / V, D the distance to the box. Then l_t = 2 E[(1 - exp(-h_t D)) / h_t] and rho = sum_t pi r_t^2 l_t / V; jamming is ignored.

morphogen.models.scale_rich_3d.beam_thickness_estimate(volume_fraction: float, decay: float, n_beams: int, sides) → float[source]

The initial thickness at which the mean field of beam_density_estimate() gives the relative density (by bisection of its logarithm).

morphogen.models.scale_rich_3d.union_points() → ndarray[source]

The 2^UNION_POINTS_LOG2 points of the unit cube (a scrambled Sobol set of a fixed seed) on which the relative density of beams is estimated.

class morphogen.models.scale_rich_3d.ScaleRichPlates(domain: Domain, growth, frame: float = 0.0, **kwargs)[source]

Bases: _Network3D

A scale-rich network of plates: its plates (phase 1, convex polyhedra that never overlap) and its voids (phase 0, closed convex cells), which partition the box exactly (grow_plates()); or, with a frame, the box within a frame of that thickness (phase 1 too), on which the plates end.

property areas: ndarray

The areas of the plates (of their rims, the sections of their voids by their mid-planes).

property normals: ndarray
property volume_fraction: float

The fraction of the box in the plates and the frame, exact (1 - sum(void volumes) / V).

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

The power-law tails of the thicknesses, areas and degrees of the plates (morphogen.analysis.power_laws.power_law_tail(), degrees as integers): 1 + 1/alpha, 5/2 and 5/2 for their exponents in theory. 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 plates (phase 1, cells 1 to N), the voids (phase 0, cell 0) and the boxes of the frame (phase 1, cell N + 1), for the exact meshes of morphogen.mesh.exact.polyhedral_mesh().

summary() → dict[source]

The counts, thicknesses, areas, degrees and anisotropy of the network.

class morphogen.models.scale_rich_3d.ScaleRichBeams(domain: Domain, growth, frame: float = 0.0, **kwargs)[source]

Bases: _Network3D

A scale-rich network of beams: cylinders with round ends (phase 1) grown until they meet (grow_beams()), in one open void (phase 0); or, with a frame, within a frame of that thickness (phase 1 too), on which they end.

property lengths: ndarray

The lengths of the axes of the beams.

property directions: ndarray
property volume_fraction: float

The fraction of the box in the beams (their union, round ends and junctions included, cut by the box) and the frame, by quasi-Monte Carlo on union_points() (within about 1.5 10^-4).

property cylinder_fraction: float

The fraction of the box in the cylinders on the axes of the beams and the frame, (sum pi r^2 l + V_frame) / V (the beams of the mean field of beam_density_estimate()): within a few percent of volume_fraction, the round ends and the overlaps at the junctions counted out, the parts of fat beams beyond the box counted in.

segments()[source]

The beams as morphogen.primitives.Segments (round caps).

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

The power-law tails of the thicknesses, lengths and degrees of the beams (the exponents of the lengths and degrees depend on alpha and on the box: see docs/theory.md, §93.1). No thicknesses with a decay of 0 (one thickness).

summary() → dict[source]

The counts, thicknesses, lengths, degrees and anisotropy of the network.