Tensions and pressures together¶

Tensions and pressures in one call: infer_forces, and infer_tensions_then_pressures for front ends.

infer_forces runs infer_tensions then infer_pressures and raises when either refuses; infer_tensions_then_pressures makes the same two calls, keeps the tensions when the pressure solve refuses them, and returns the refusal as an InferenceOutcome instead of raising it.

Sacha Ichbiah 2021 Matthieu Perez 2024

InferenceOutcome `dataclass` ¶

InferenceOutcome(tensions: dict[tuple[int, int], float] | None, pressures: dict[int, float] | None, records: list = list(), status: str = INFERENCE_COMPLETE, error: str | None = None, library_call: str = '')

What infer_tensions_then_pressures computed, and what the library refused.

Attributes:

Name	Type	Description
`tensions`	`dict[tuple[int, int], float] \| None`	interface -> tension, or `None` when the tension solve was refused.
`pressures`	`dict[int, float] \| None`	material -> pressure, or `None` when the pressure solve was refused, never ran, or was not asked for (`with_pressures=False`).
`records`	`list`	the solve records (`foambryo.linear_solves.SolveRecord`), tensions first; empty without diagnostics.
`status`	`str`	`"complete"`, `"pressures refused"` (the tensions hold an undetermined value, so the pressure solve refused them) or `"failed"` (the library refused the options or the mesh).
`error`	`str \| None`	the library's message when the status is not `"complete"`, else `None`.
`library_call`	`str`	the `infer_forces` call that computes the same numbers, as text.

infer_forces ¶

infer_forces(mesh: DcelData, mean_tension: float = 1, base_pressure: float = 0, mode_tension: TensionComputationMethod = TensionComputationMethod.YoungDupre, mode_pressure: PressureComputationMethod = PressureComputationMethod.Variational, *, solver: str = 'auto', sparse_threshold: int | None = None, diagnostics: bool | str = False) -> tuple

Infer the relative tensions, then the pressures, of a 3D mesh.

infer_tensions(mesh, mean_tension, mode_tension, ...) then infer_pressures(mesh, tensions, mode_pressure, base_pressure, ...), with the same solver options; see those two functions for every convention, warning and failure.

Parameters:

Name	Type	Description	Default
`mesh`	`DcelData`	Mesh to analyze, in any length unit.	required
`mean_tension`	`float`	The normalisation: the tensions are normalised so that their mean is `mean_tension`, exactly, in each connected piece of the junction graph (see `foambryo.infer_tensions`). Defaults to 1.	`1`
`base_pressure`	`float`	Pressure of the exterior medium (label 0). Defaults to 0.	`0`
`mode_tension`	`TensionComputationMethod`	Method for tension computation. Defaults to `TensionComputationMethod.YoungDupre`.	`YoungDupre`
`mode_pressure`	`PressureComputationMethod`	Method for pressure computation. Defaults to `PressureComputationMethod.Variational`.	`Variational`
`solver`	`str`	`"auto"` (the default), `"dense"` or `"sparse"`, passed to both the tension and the pressure solves (`foambryo.linear_solves`). `"auto"` is dense below `sparse_threshold` unknowns and sparse at or above, and bitwise the dense result below it. `"sparse"` raises `ValueError` for a tension method with no sparse path (`Equilibrium`, `Variational`, `ForceBalance*`). 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` holding the records of the tension solves then of the pressure solve. Keyword-only.	`False`

Returns:

Type Description

tuple

tuple[dict[tuple[int, int], float], dict[int, float]]: - map of interface (label_1, label_2), label_1 < label_2 -> relative tension on this interface. An undetermined interface (for example one with no triple line at all) is float("nan"); a triple-junction graph in several pieces gives tensions normalised separately in each piece, which are not on the same scale (see foambryo.tension_inference.infer_tensions's return value, and foambryo.tension_inference.infer_tensions_by_junction_component for the per-piece alternative). - map of cell label (0 = exterior, at base_pressure) -> pressure, in the unit of the tensions divided by the mesh's length unit; nan for a cell whose pressure is undetermined or that the crop cuts. - with diagnostics on, a third value: the SolveDiagnostics.

Raises:

Type	Description
`UndeterminedTensionError`	on an uncropped mesh, if any inferred tension is not finite, which is the case on a mesh with an interface that has no triple line. The pressure solve couples every cell to every tension, so such a tension would make nearly every pressure non-finite; pressures are refused instead. Call `infer_tensions` for the tensions alone (or `infer_tensions_then_pressures`, which keeps them), and `infer_tensions_by_junction_component` to see which interfaces are undetermined.
`ValueError`	on an invalid solver option; as `infer_tensions` for the tension method; on a cropped mesh with a Laplace pressure method.
`MalformedTripleLineError`	as `infer_tensions`.
`LinAlgError`	as `infer_pressures`.

Warns:

Type	Description
`JunctionGraphGaugeWarning`	as `infer_tensions`.
`DegenerateWedgeWarning`	as `infer_tensions`.
`UndeterminedPressureWarning`	as `infer_pressures`.
`CutCellPressureWarning`	as `infer_pressures`, on a cropped mesh.
`SparseSolveFallbackWarning`	as `infer_tensions` and `infer_pressures`.
`DenseSolveMemoryWarning`	as `infer_tensions` and `infer_pressures`.

infer_tensions_then_pressures ¶

infer_tensions_then_pressures(mesh: DcelData, mean_tension: float = 1, base_pressure: float = 0, mode_tension: TensionComputationMethod = TensionComputationMethod.YoungDupre, mode_pressure: PressureComputationMethod = PressureComputationMethod.Variational, *, solver: str = 'auto', diagnostics: bool | str = False, with_pressures: bool = True) -> InferenceOutcome

The tensions then the pressures, by the two calls infer_forces makes, keeping what succeeds.

infer_forces runs infer_tensions then infer_pressures with these arguments and raises when either is refused. This function makes the same two calls itself, so that the tensions survive a pressure solve that refuses them (UndeterminedTensionError), and returns the refusal instead of raising it: what the foambryo infer command and the napari plugin need to report a partial result. The numbers are bitwise those of infer_forces with the same arguments. Every default is infer_forces's.

With with_pressures=False only the first call is made (infer_tensions with the same arguments, so the tensions are bitwise those of infer_forces), base_pressure and mode_pressure are not used, the outcome's pressures is None with the status "complete", and library_call is that infer_tensions call.

sparse_threshold is not an argument: the default threshold (2 000 unknowns) always applies.