morphogen.models.combination

Combinations of models: union, intersection, difference and complement of their phase 1, and inclusions overlaid on a matrix (a polycrystal, or any structure).

The components are independent realizations of their models in the same domain, with seeds derived from the seed of the combination. The phase 1 of a union is the union of the phases 1 of the components, and so on; their level sets combine by minimum, maximum and negation, so that combinations of models with level sets are meshed conformingly. Inclusions keep the phases of the first component (the matrix: a polycrystal keeps its cells, their labels and orientations) and give the phase 1 of each further component a phase of its own, the next free index by default; later components cover earlier ones.

For independent stationary random sets A and B of volume fractions p and specific surfaces S (Matheron 1975):

  • union: p = 1 - (1 - pA) (1 - pB), S = SA (1 - pB) + SB (1 - pA);

  • intersection: p = pA pB, S = SA pB + SB pA;

  • complement: p = 1 - pA, S = SA.

A union of a Boolean model with another is the Boolean model of both grains; the intersection of fine inclusions with a coarse random set gives clustered (Cox-like, multiscale) inclusions, cut by the boundary of the set (cox_spheres keeps them whole). A nested combination fills the phase 1 of each model with the next one, whose other phases are kept: hierarchical structures (a gyroid of octet trusses…), its phase 1 being the intersection.

class morphogen.models.combination.Combined(domain: Domain, operation: str, parts, inclusion_phases=None, **kwargs)[source]

Bases: Microstructure

Realization of a combination: its components and how they combine.

property matrix: Microstructure
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**3 sub-samples per voxel).

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

Minimum (union), maximum (intersection) or negation (complement) of the level sets of the components.

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 (see Microstructure.phase_level_set()). Inclusions: a phase is what the matrix has of it outside all the inclusions, and each inclusion of that phase outside the later ones, which cover it. Nested structures: a phase is what each structure has of it inside the phase 1 of all the previous ones.

property lipschitz: float

Convert a string or number to a floating-point number, if possible.

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

The functions of phase_level_set() at the points, from those of the components (phase_level_sets_at()). Inclusions: the visible parts of the inclusions of a phase (each minus the later ones, max(psi_i, -min_{j > i} psi_j)) and the phase of the matrix where no inclusion covers it; nested structures: a phase of each structure inside the phase 1 of all the previous ones; the others (two phases): that of level_set_at(). A component without point-wise functions (a polycrystal matrix of one phase) leaves the combination without them.

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

The level sets of the components at the points, combined as level_set() (inclusions: the function of phase 1, see phase_level_sets_at()).

contains(points) → ndarray[source]

Whether points lie in phase 1.

property has_labels: bool

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

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

Cell labels of the matrix (the inclusions keep the label of their cell).

property orientations
summary() → dict[source]

Counts and sizes describing the realization.

class morphogen.models.combination.Combination(operation: str = 'union', models: tuple = (), inclusion_phases: tuple[int, ...] | None = None)[source]

Bases: Model

Union, intersection, difference or complement of models, or inclusions in a matrix.

phases: ClassVar[dict[int, str]] = {0: 'outside', 1: 'combined phase 1'}

Meaning of the phase indices of the voxel images.

property supports_periodic: bool

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

property has_level_set: bool

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

property phases_of_inclusions: list[int]

Phase of each inclusion model (the next free indices by default).

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).

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

One realization of the model in domain.

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

Volume fraction and specific surface of set operations on independent components, when theirs are known.