morphogen.models.base

Base classes of morphological models and of their realizations (microstructures).

A Model holds the parameters of a random set (or of a deterministic architecture). model.generate(domain, seed) returns a Microstructure, the explicit (“vector”) description of one realization, which can be voxelized at any resolution, queried point-wise, turned into level-set fields and exported.

morphogen.models.base.param(default=<dataclasses._MISSING_TYPE object>, *, doc: str, kind: str = 'float', unit: str = '', kw_only: bool = False)[source]

Dataclass field carrying the metadata used by configs, the CLI and the GUI.

kind is one of: float, int, bool, str, fraction, distribution, distributions (a list of them), orientation, vector, floats, ints, json (nested lists), model (a model given as a mapping with a type key), models (a list of them), anisotropy (an affine anisotropy, morphogen.models.affine).

morphogen.models.base.register(cls: type[Model]) → type[Model][source]

Class decorator adding a model to the registry under cls.name.

morphogen.models.base.get_model(name: str) → type[Model][source]

The class of a registered model, by its name (list_models()).

morphogen.models.base.list_models() → list[str][source]

The names of the registered models, sorted.

morphogen.models.base.model_from_config(cfg: dict) → Model[source]

Build a model from a mapping {"type": name, **parameters}.

class morphogen.models.base.Model[source]

Bases: ABC

Morphological model (random set or deterministic architecture).

phases: ClassVar[dict[int, str]] = {0: 'matrix', 1: 'inclusions'}

Meaning of the phase indices of the voxel images.

supports_periodic: ClassVar[bool] = True

False for models that cannot be periodic (e.g. infinite Poisson fibres).

has_level_set: ClassVar[bool] = True

Whether one level set, that of the phase 1, describes the realizations (two phases: the extended finite elements, the contours of the sections). False for the models of more phases, or of other phases than 0 and 1 (cells of a tessellation, coated inclusions, osteons…): each of their phases has its implicit function (Microstructure.phase_level_set()), from which they are meshed conformingly.

meshed_by_grains: ClassVar[bool] = False

True for models whose realizations are meshed grain by grain from exact cells (Voronoi and Laguerre tessellations, see morphogen.mesh.polycrystal).

count_label: ClassVar[str] = ''

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

path_parameters: ClassVar[tuple[str, ...]] = ()

The parameters that are paths of files (or the keys of parameters that are mappings: texture.file): a configuration file gives them from its own folder (morphogen.config.load_config()).

abstractmethod generate(domain: Domain, seed: int | SeedSequence | Generator | None = None) → Microstructure[source]

One realization of the model in domain.

theory(domain: Domain | None = None) → dict[str, float][source]

Theoretical morphological characteristics known in closed form (may be empty).

Some values depend on the domain (e.g. the intensity implied by a number of cells).

active_phases() → dict[int, str][source]

Phases the realizations of this model can contain, with their names (the phases of the model, unless its parameters choose them).

expected_count(domain: Domain) → float | None[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).

to_config() → dict[source]
classmethod parameters() → list[dict][source]

Description of the parameters (name, kind, default, unit, doc).

morphogen.models.base.register_kind(cls: type[Microstructure]) → type[Microstructure][source]

Registers a kind of microstructure (a class decorator), which Microstructure.from_dict() then reads back.

class morphogen.models.base.Microstructure(domain: Domain, *, model: Model | None = None, seed: dict | None = None, metadata: dict | None = None)[source]

Bases: ABC

One realization of a model in a domain.

grid(shape=None, *, voxel_size=None, grid: Grid | None = None) → Grid[source]

Resolve the voxel grid from shape, voxel_size or an explicit grid.

abstractmethod voxelize(shape=None, *, voxel_size=None, grid: Grid | None = None, supersampling: int = 1) → VoxelImage[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]

Field negative inside phase 1, positive outside and zero on its boundary.

implicit_phases() → list[int][source]

The phases of the realization, each described by an implicit function (phase_level_set()), in increasing order: phase 1 and what surrounds it (the structures of more phases, or of others, say theirs).

phase_level_set(phase: int, shape=None, *, voxel_size=None, grid: Grid | None = None) → VoxelImage[source]

The implicit function of a phase: a field negative inside phase, positive outside and zero on its boundary, at the centres of the voxels of a grid. The interfaces are those of the model (see morphogen.models.implicit): the conforming meshes, the surfaces and the sections of the phase are cut from it. Phase 1 is level_set(); the other phase of a structure of two phases, its opposite; the structures of more phases give each of theirs.

implicit_at(phase: int, points, band: float) → ndarray | None[source]

The implicit function of one phase at arbitrary points (rows of points), clipped to [-band, band]: that of phase_level_sets_at(); None for the structures whose functions are those of the points of grids only (phase_level_set()), and for a phase they do not have.

implicit_pieces(depth: float = 0.0) → tuple[list, int] | None[source]

The smooth pieces of the phases, for the structures whose implicit functions have folds (the unions of spheres and segments and their coatings, whose surfaces have a sharp edge where two primitives meet): pieces in the order of the cuts of a mesher that follows these edges, and the phase of what they leave (see morphogen.models.pieces). A point belongs to the phase of the first piece that holds it. Two primitives that enter each other by more than depth are in different pieces. None for the other structures.

contains(points) → ndarray[source]

Whether points lie in phase 1.

lipschitz: float = 1.0

A bound of the slope of the functions of phase_level_sets_at() (1 for signed distances, and for their minima and maxima): the adaptive meshes leave unrefined the edges that an interface cannot reach at this slope

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

The function of phase 1 at points of space (level_set() at any point), negative in phase 1, whose zero set is its boundary: the signed distance to it, exact within reach of it and at least reach beyond, when the structure knows it (the others: a function with the same zero set, about a distance near it). The structures of several phases give the function of their phase 1 (phase_level_sets_at()), if they have one.

phase_level_sets_at(points, reach: float = inf) → dict[int, ndarray][source]

The implicit functions of all the phases at points of space (rows of points): {k: phi_k} for each phase k of implicit_phases(), negative in it, positive outside and zero on its boundary, exact within reach of the interfaces and at least reach beyond (or about a distance near them, as level_set_at()). It is phase_level_set() at any point: the same values at the centres of the voxels of a grid, within the band of the grid. Two phases: {1: phi, 0: -phi} of level_set_at(). The exact meshes (morphogen.mesh.exact) cut them, and the curved elements (morphogen.mesh.curved) put their nodes on their zeros. Raises NotImplementedError for the structures whose functions are those of the points of grids only.

property has_labels: bool

Whether labels(...) gives an image of cell indices (cells, grains).

property phase_names: dict[int, str]
image_metadata() → dict[source]
summary() → dict[source]

Counts and sizes describing the realization.

to_dict() → dict[source]
static from_dict(data: dict) → Microstructure[source]