Pressures

Cell pressures inferred from a multimaterial mesh and its interface tensions.

The pressures are solved from the tensions (foambryo.tension_inference), by the variational method (the default) or by Laplace's law (PressureComputationMethod). They are in the unit of the tensions divided by the mesh's length unit: the tensions being relative (normalised to mean_tension), so are the pressures, which scale with the tensions. The exterior medium, label 0, has the pressure base_pressure; a cell whose pressure the mesh does not determine, or a cell the crop cuts, is nan, never a number.

Sacha Ichbiah 2021 Matthieu Perez 2024

UndeterminedTensionError

UndeterminedTensionError(interfaces: tuple[tuple[int, int], ...])

Bases: ValueError

A pressure inference was handed an interface tension that is not a finite number.

Every pressure method solves for the cell pressures from the interface tensions, and the default variational method couples every cell to every tension, so a single non-finite tension makes nearly every inferred pressure non-finite: measured on five real embryo timepoints with one to four closed interfaces, all but one cell's pressure came back non-finite each time (54 of 55 cells up to 71 of 72). Such a field carries no usable value, so the pressure inference refuses it rather than returning it.

The usual cause is not a numerical failure. An interface with no triple line at all -- a closed surface, such as an engulfed cell or a sealed lumen, or a fragment that a segmentation left inside another cell -- has no angle from which its tension could be measured, and foambryo.infer_tensions reports it as float("nan") by design. The other tensions of such a mesh remain valid; use foambryo.infer_tensions_by_junction_component to see which interfaces are undetermined and which component each determined tension belongs to.

Subclasses ValueError, so code that already caught the generic error the least-squares solve raised on a non-finite input keeps working.

Attributes:

Name	Type	Description
interfaces		the interfaces whose tension is not finite, sorted.

Build the error and its message from the offending interfaces.

Parameters:

Name	Type	Description	Default
interfaces	tuple[tuple[int, int], ...]	the interfaces whose tension is not finite.	required

UndeterminedPressureWarning

Bases: UserWarning

Emitted when the Laplace pressure leaves cells undetermined; their pressure is nan.

Also emitted by the variational method on a cropped mesh, for a cell that the crop does not cut but whose every vertex lies on a crop face or on an interface without a tension.

The Laplace methods write one equation per interface, P_a - P_b = -2 H_ab T_ab, which needs the interface's mean curvature H_ab. The curvature is read at the vertices of the interface that are not on a junction line, so an interface all of whose vertices lie on junctions has no curvature (nan), and its equation is left out. When the equations that remain do not connect a cell to the exterior, through a chain of interfaces, nothing fixes that cell's pressure: it is reported as nan, never as a number. This is common on coarse meshes of small cells, where up to about a third of the interfaces can have no curvature and a few cells per hundred can be left undetermined.

The variational method (the default) does not use curvatures and is not affected.

PressureComputationMethod

Bases: Enum

The pressure inference methods.

• Variational (the default): the least-squares solution of the vertex force balance at the given tensions (see our article). It reads no curvature, gives a number for every cell of an uncropped mesh, and is the only method with a formulation for crop faces.
• Laplace: Laplace's law, P_a - P_b = -2 H_ab T_ab, on each interface, with the interface's mean curvature H_ab averaged over its vertices off the junction lines.
• WeightedLaplace: the same, with the curvature averaged with area weights.

The two Laplace methods need each interface's mean curvature. An interface with no measurable curvature contributes no equation, and a cell that the remaining equations do not connect to the exterior gets the pressure nan (see UndeterminedPressureWarning). They refuse a cropped mesh (ValueError); has_crop_face_formulation says which methods accept one.

has_crop_face_formulation property

has_crop_face_formulation: bool

Whether the method infers pressures on a cropped mesh (one with crop faces, foambryo.crop_faces).

Only Variational does: the two Laplace methods read each interface's curvature, which on an interface the crop cuts is read partly on the crop, and infer_pressures refuses them on a cropped mesh. A front end can offer only the methods that have the formulation instead of failing after the tensions.

warn_on_undetermined_pressures

warn_on_undetermined_pressures(cells: tuple[int, ...], stacklevel: int = 4) -> None

Emit UndeterminedPressureWarning naming the cells whose Laplace pressure is nan.

Parameters:

Name	Type	Description	Default
cells	tuple[int, ...]	Labels of the undetermined cells (nothing is emitted if empty).	required
stacklevel	int	passed through to warnings.warn, so the warning points at the caller's own line rather than at this module. Defaults to 4.	4

infer_pressures

infer_pressures(mesh: DcelData, dict_tensions: dict[tuple[int, int], float], mode: PressureComputationMethod = PressureComputationMethod.Variational, base_pressure: float = 0, *, solver: str = 'auto', sparse_threshold: int | None = None, diagnostics: bool | str = False) -> dict[int, float] | tuple[dict[int, float], linear_solves.SolveDiagnostics]

Infer the pressure of every cell of a mesh from its interface tensions.

The pressures are in the unit of the tensions divided by the mesh's length unit, and scale with the tensions: tensions normalised to a mean of 1 give pressures relative to that scale.

Cropped meshes (foambryo.crop_faces, variational method only): the pressure of every cut cell is solved for and returned as nan, with a CutCellPressureWarning naming the cells; the force balances of the vertices on crop faces, and of the vertices of interfaces whose tension is nan, are left out, so nan tensions are accepted there; a cell those balances leave undetermined is nan too (UndeterminedPressureWarning). The crop interfaces need no entry in dict_tensions.

Parameters:

Name	Type	Description	Default
mesh	DcelData	Mesh to analyze, in any length unit.	required
dict_tensions	dict[tuple[int, int], float]	interface (label_1, label_2), label_1 < label_2, label 0 the exterior medium -> tension, one entry per interface of the mesh, as foambryo.infer_tensions returns it; all on one scale (tensions from separately normalised pieces of the junction graph are used as given). On an uncropped mesh every value must be finite; on a cropped mesh the crop interfaces may be absent and undetermined tensions nan.	required
mode	PressureComputationMethod	Computation method. Defaults to PressureComputationMethod.Variational.	Variational
base_pressure	float	Pressure of the exterior medium (label 0), returned as its pressure. Defaults to 0.	0
solver	str	"auto" (the default), "dense" or "sparse": how the pressure system is solved (foambryo.linear_solves). "auto" is dense below sparse_threshold unknowns (materials for the Laplace methods, interfaces plus cells for the variational one) and sparse at or above, and bitwise the dense result below it. On a cropped mesh "auto" decides by DENSE_CROP_PRESSURE_MAX_ENTRIES instead. Keyword-only.	'auto'
sparse_threshold	int | None	unknowns at which "auto" goes sparse; None (the default) is foambryo.junction_graph.SPARSE_SOLVE_MIN_UNKNOWNS (2 000). Keyword-only.	None
diagnostics	bool | str	False (the default), True or "spectrum": also return a foambryo.linear_solves.SolveDiagnostics, last, with one record per solve. Keyword-only.	False

Returns:

Type	Description
dict[int, float] | tuple[dict[int, float], SolveDiagnostics]	dict[int, float]: map cell label (0 = exterior, at base_pressure) -> pressure. With a Laplace method, a cell whose pressure no equation fixes is nan (and UndeterminedPressureWarning is emitted); the variational method returns a number for every cell of an uncropped mesh. With diagnostics on, the tuple (map, SolveDiagnostics).

Raises:

Type	Description
UndeterminedTensionError	on an uncropped mesh, if any tension in dict_tensions is not a finite number -- for example the nan that infer_tensions reports for an interface with no triple line. Checked before any method runs; where every tension is finite the result is bitwise unchanged by the check. See UndeterminedTensionError.
ValueError	on a cropped mesh with a Laplace method, which has no formulation for crop faces (PressureComputationMethod.has_crop_face_formulation); on an invalid solver, sparse_threshold or diagnostics; with the variational method, when dict_tensions does not hold one tension per interface of an uncropped mesh.
KeyError	with a Laplace method, when dict_tensions misses an interface of the mesh.
LinAlgError	if the variational system is singular.

Warns:

Type	Description
UndeterminedPressureWarning	when a cell's pressure is undetermined and reported nan.
CutCellPressureWarning	on a cropped mesh, naming the cut cells reported nan.
SparseSolveFallbackWarning	when lsqr did not converge on a large Laplace system.
DenseSolveMemoryWarning	when solver="dense" is forced on a system too large for the memory available.

infer_pressures_and_residuals

infer_pressures_and_residuals(mesh: DcelData, dict_tensions: dict[tuple[int, int], float], mode: PressureComputationMethod = PressureComputationMethod.Variational, base_pressure: float = 0, *, solver: str = 'auto', sparse_threshold: int | None = None, diagnostics: bool | str = False) -> tuple

Infer the pressure of every cell of a mesh from its interface tensions, with the residuals.

infer_pressures returns this function's second value; see it for the units and for cropped meshes.

Parameters:

Name	Type	Description	Default
mesh	DcelData	Mesh to analyze, in any length unit.	required
dict_tensions	dict[tuple[int, int], float]	interface (label_1, label_2), label_1 < label_2, label 0 the exterior medium -> tension, one entry per interface of the mesh, as foambryo.infer_tensions returns it; all on one scale (tensions from separately normalised pieces of the junction graph are used as given). On an uncropped mesh every value must be finite; on a cropped mesh the crop interfaces may be absent and undetermined tensions nan.	required
mode	PressureComputationMethod	Computation method. Defaults to PressureComputationMethod.Variational.	Variational
base_pressure	float	Pressure of the exterior medium (label 0), returned as its pressure. Defaults to 0.	0
solver	str	"auto" (the default), "dense" or "sparse": how the pressure system is solved (foambryo.linear_solves). "auto" is dense below sparse_threshold unknowns (materials for the Laplace methods, interfaces plus cells for the variational one) and sparse at or above, and bitwise the dense result below it. On a cropped mesh "auto" decides by DENSE_CROP_PRESSURE_MAX_ENTRIES instead. Keyword-only.	'auto'
sparse_threshold	int | None	unknowns at which "auto" goes sparse; None (the default) is foambryo.junction_graph.SPARSE_SOLVE_MIN_UNKNOWNS (2 000). Keyword-only.	None
diagnostics	bool | str	False (the default), True or "spectrum": also return a foambryo.linear_solves.SolveDiagnostics, last, with one record per solve. Keyword-only.	False

Returns:

Type

Description

tuple

tuple[NDArray[np.float64], dict[int, float], NDArray[np.float64] | int]: - with a Laplace method, one value per material in mesh.materials order (the exterior first, at base_pressure), nan where undetermined; with the variational method, the tensions used, in sorted interface order (nan where unusable on a cropped mesh); - map cell label (0 = exterior, at base_pressure) -> pressure. With a Laplace method, a cell whose pressure no equation fixes is nan in this map and in the array (and UndeterminedPressureWarning is emitted); the variational method returns a number for every cell of an uncropped mesh; - with a Laplace method, the squared residual of the solved equations (a length-1 array, or empty); with the variational method, 0; - with diagnostics on, a fourth value: the SolveDiagnostics.

Raises:

Type	Description
UndeterminedTensionError	on an uncropped mesh, if any tension in dict_tensions is not a finite number -- for example the nan that infer_tensions reports for an interface with no triple line. Checked before any method runs; where every tension is finite the result is bitwise unchanged by the check. See UndeterminedTensionError.
ValueError	on a cropped mesh with a Laplace method, which has no formulation for crop faces (PressureComputationMethod.has_crop_face_formulation); on an invalid solver, sparse_threshold or diagnostics; with the variational method, when dict_tensions does not hold one tension per interface of an uncropped mesh.
KeyError	with a Laplace method, when dict_tensions misses an interface of the mesh.
LinAlgError	if the variational system is singular.

Warns:

Type	Description
UndeterminedPressureWarning	when a cell's pressure is undetermined and reported nan.
CutCellPressureWarning	on a cropped mesh, naming the cut cells reported nan.
SparseSolveFallbackWarning	when lsqr did not converge on a large Laplace system.
DenseSolveMemoryWarning	when solver="dense" is forced on a system too large for the memory available.