pmmoto.domain_generation package

Initialize the domain_generation subpackage for PMMoTo.

Provides porous media, multiphase, and domain generation utilities.

pmmoto.domain_generation.deconstruct_img(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, img: ndarray[Any, dtype[T]], subdomains: tuple[int, ...], rank: None | int = None, pad: tuple[int, ...] = (1, 1, 1), reservoir_voxels: int = 0) → tuple[PaddedSubdomain | dict[int, PaddedSubdomain], ndarray[Any, dtype[T]] | dict[int, ndarray[Any, dtype[T]]]]

Deconstruct and image from a single process to multiple subdomains and images

The shape of the img must equal subdomain.domain.voxels!

pmmoto.domain_generation.gen_img_linear(shape: tuple[int, ...], dim: int) → ndarray[Any, dtype[float64]]

Generate an image that varies linearly from 0 to N-1 along a given dimension.

Parameters:

  • shape (tuple) – Shape of the output image.

  • dim (int) – Dimension along which to vary.

Returns:

Linear image.

Return type:

np.ndarray

pmmoto.domain_generation.gen_img_random_binary(shape: tuple[int, ...], p_zero: float = 0.5, seed: None | int = None) → ndarray[Any, dtype[uint8]]

Generate a random binary grid with specified probability for zeros.

Parameters:

  • shape (tuple) – Shape of the binary grid (e.g., (depth, rows, columns)).

  • p_zero (float) – Probability of a 0 occurring. Probability of a 1 is 1 - p_zero.

  • seed (int, optional) – Seed for the random number generator.

Returns:

Random binary grid.

Return type:

np.ndarray

pmmoto.domain_generation.gen_img_smoothed_random_binary(shape: tuple[int, ...], p_zero: float = 0.5, smoothness: float = 1.0, seed: None | int = None) → ndarray[Any, dtype[uint8]]

Generate a smoothed random binary grid.

Parameters:

  • shape (tuple) – Shape of the binary grid.

  • p_zero (float) – Probability of a 0 occurring.

  • smoothness (float) – Controls the smoothness of the output grid.

  • seed (int, optional) – Seed for the random number generator.

Returns:

Smoothed random binary grid.

Return type:

np.ndarray

pmmoto.domain_generation.gen_mp_constant(porous_media: PorousMedia, fluid_phase: int = 1) → Multiphase[uint8]

Set the pore space to a specific fluid phase.

Parameters:

  • porous_media – PorousMedia object.

  • fluid_phase (int, optional) – Fluid phase to assign.

Returns:

Initialized multiphase object.

Return type:

Multiphase

pmmoto.domain_generation.gen_pm_atom_domain(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, atom_locations: ndarray[Any, dtype[floating[Any]]], atom_radii: ndarray[Any, dtype[floating[Any]]], atom_types: ndarray[Any, dtype[integer[Any]]], kd: bool = False) → PorousMedia

Generate binary porous media domain from atom data.

Parameters:

  • subdomain – Subdomain object.

  • atom_locations – Atom coordinates.

  • atom_radii – Atom radii.

  • atom_types – Atom types.

  • kd (bool, optional) – Use KD-tree for efficiency.

Returns:

Initialized porous media object.

Return type:

PorousMedia

pmmoto.domain_generation.gen_pm_atom_file(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, lammps_file: str, atom_radii: ndarray[Any, dtype[floating[Any]]], type_map: None | dict[tuple[int, float], int] = None, add_periodic: bool = False, kd: bool = False) → PorousMedia

Generate binary porous media domain from a LAMMPS atom file.

Parameters:

  • subdomain – Subdomain object.

  • lammps_file (str) – Path to LAMMPS atom file.

  • atom_radii – Atom radii.

  • type_map (dict, optional) – Mapping of atom types.

  • add_periodic (bool, optional) – Add periodic atoms.

  • kd (bool, optional) – Use KD-tree for efficiency.

Returns:

Initialized porous media object.

Return type:

PorousMedia

pmmoto.domain_generation.gen_pm_cylinders(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, cylinders: ndarray[Any, dtype[floating[Any]]], kd: bool = False) → PorousMedia

Generate binary porous media domain from cylinder data.

Parameters:

  • subdomain – Subdomain object.

  • cylinders – Cylinder data array.

  • kd (bool, optional) – Use KD-tree for efficiency.

Returns:

Initialized porous media object.

Return type:

PorousMedia

pmmoto.domain_generation.gen_pm_inkbottle(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, r_y: float = 1.0, r_z: float = 1.0) → PorousMedia

Generate an inkbottle-shaped porous media with reservoirs.

Parameters:

  • subdomain – Subdomain object.

  • r_y (float, optional) – Elliptical scaling in y.

  • r_z (float, optional) – Elliptical scaling in z.

Returns:

Initialized porous media object.

Return type:

PorousMedia

pmmoto.domain_generation.gen_pm_spheres_domain(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, spheres: ndarray[Any, dtype[floating[Any]]], kd: bool = False, invert: bool = False) → PorousMedia

Generate binary porous media domain from sphere data.

Parameters:

  • subdomain – Subdomain object.

  • spheres – Sphere data array.

  • kd (bool, optional) – Use KD-tree for efficiency.

  • invert – (bool, optional): Treat spheres as pores

Returns:

Initialized porous media object.

Return type:

PorousMedia

Submodules

pmmoto.domain_generation.domain_generation module

domain_generation.py

Functions for generating random, smoothed, and structured porous media images, as well as initializing PorousMedia and Multiphase objects for PMMoTo.

pmmoto.domain_generation.domain_generation.deconstruct_img(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, img: ndarray[Any, dtype[T]], subdomains: tuple[int, ...], rank: None | int = None, pad: tuple[int, ...] = (1, 1, 1), reservoir_voxels: int = 0) → tuple[PaddedSubdomain | dict[int, PaddedSubdomain], ndarray[Any, dtype[T]] | dict[int, ndarray[Any, dtype[T]]]]

Deconstruct and image from a single process to multiple subdomains and images

The shape of the img must equal subdomain.domain.voxels!

pmmoto.domain_generation.domain_generation.gen_img_linear(shape: tuple[int, ...], dim: int) → ndarray[Any, dtype[float64]]

Generate an image that varies linearly from 0 to N-1 along a given dimension.

Parameters:

  • shape (tuple) – Shape of the output image.

  • dim (int) – Dimension along which to vary.

Returns:

Linear image.

Return type:

np.ndarray

pmmoto.domain_generation.domain_generation.gen_img_random_binary(shape: tuple[int, ...], p_zero: float = 0.5, seed: None | int = None) → ndarray[Any, dtype[uint8]]

Generate a random binary grid with specified probability for zeros.

Parameters:

  • shape (tuple) – Shape of the binary grid (e.g., (depth, rows, columns)).

  • p_zero (float) – Probability of a 0 occurring. Probability of a 1 is 1 - p_zero.

  • seed (int, optional) – Seed for the random number generator.

Returns:

Random binary grid.

Return type:

np.ndarray

pmmoto.domain_generation.domain_generation.gen_img_smoothed_random_binary(shape: tuple[int, ...], p_zero: float = 0.5, smoothness: float = 1.0, seed: None | int = None) → ndarray[Any, dtype[uint8]]

Generate a smoothed random binary grid.

Parameters:

  • shape (tuple) – Shape of the binary grid.

  • p_zero (float) – Probability of a 0 occurring.

  • smoothness (float) – Controls the smoothness of the output grid.

  • seed (int, optional) – Seed for the random number generator.

Returns:

Smoothed random binary grid.

Return type:

np.ndarray

pmmoto.domain_generation.domain_generation.gen_mp_constant(porous_media: PorousMedia, fluid_phase: int = 1) → Multiphase[uint8]

Set the pore space to a specific fluid phase.

Parameters:

  • porous_media – PorousMedia object.

  • fluid_phase (int, optional) – Fluid phase to assign.

Returns:

Initialized multiphase object.

Return type:

Multiphase

pmmoto.domain_generation.domain_generation.gen_pm_atom_domain(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, atom_locations: ndarray[Any, dtype[floating[Any]]], atom_radii: ndarray[Any, dtype[floating[Any]]], atom_types: ndarray[Any, dtype[integer[Any]]], kd: bool = False) → PorousMedia

Generate binary porous media domain from atom data.

Parameters:

  • subdomain – Subdomain object.

  • atom_locations – Atom coordinates.

  • atom_radii – Atom radii.

  • atom_types – Atom types.

  • kd (bool, optional) – Use KD-tree for efficiency.

Returns:

Initialized porous media object.

Return type:

PorousMedia

pmmoto.domain_generation.domain_generation.gen_pm_atom_file(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, lammps_file: str, atom_radii: ndarray[Any, dtype[floating[Any]]], type_map: None | dict[tuple[int, float], int] = None, add_periodic: bool = False, kd: bool = False) → PorousMedia

Generate binary porous media domain from a LAMMPS atom file.

Parameters:

  • subdomain – Subdomain object.

  • lammps_file (str) – Path to LAMMPS atom file.

  • atom_radii – Atom radii.

  • type_map (dict, optional) – Mapping of atom types.

  • add_periodic (bool, optional) – Add periodic atoms.

  • kd (bool, optional) – Use KD-tree for efficiency.

Returns:

Initialized porous media object.

Return type:

PorousMedia

pmmoto.domain_generation.domain_generation.gen_pm_cylinders(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, cylinders: ndarray[Any, dtype[floating[Any]]], kd: bool = False) → PorousMedia

Generate binary porous media domain from cylinder data.

Parameters:

  • subdomain – Subdomain object.

  • cylinders – Cylinder data array.

  • kd (bool, optional) – Use KD-tree for efficiency.

Returns:

Initialized porous media object.

Return type:

PorousMedia

pmmoto.domain_generation.domain_generation.gen_pm_inkbottle(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, r_y: float = 1.0, r_z: float = 1.0) → PorousMedia

Generate an inkbottle-shaped porous media with reservoirs.

Parameters:

  • subdomain – Subdomain object.

  • r_y (float, optional) – Elliptical scaling in y.

  • r_z (float, optional) – Elliptical scaling in z.

Returns:

Initialized porous media object.

Return type:

PorousMedia

pmmoto.domain_generation.domain_generation.gen_pm_spheres_domain(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, spheres: ndarray[Any, dtype[floating[Any]]], kd: bool = False, invert: bool = False) → PorousMedia

Generate binary porous media domain from sphere data.

Parameters:

  • subdomain – Subdomain object.

  • spheres – Sphere data array.

  • kd (bool, optional) – Use KD-tree for efficiency.

  • invert – (bool, optional): Treat spheres as pores

Returns:

Initialized porous media object.

Return type:

PorousMedia

pmmoto.domain_generation.lattice_packings module

lattice_packings.py

Defines classes for generating common lattice packings (SC, BCC, FCC) for PMMoTo.

class pmmoto.domain_generation.lattice_packings.BodyCenteredCubic(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, lattice_constant: float)

Bases: Lattice

Body Centered Cubic (BCC) lattice.

Initialize a Lattice.

Parameters:

  • subdomain – Subdomain object.

  • lattice_constant (float) – Lattice constant (unit cell size).

get_basis_vectors() → ndarray[Any, dtype[T]]

Return basis vectors for BCC lattice (corner and body center).

get_coordination_number() → float

Return coordination number for BCC lattice.

get_packing_efficiency() → float

Return packing efficiency (percent) for BCC lattice.

get_radius() → float

Return sphere radius for BCC lattice.

class pmmoto.domain_generation.lattice_packings.FaceCenteredCubic(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, lattice_constant: float)

Bases: Lattice

Face Centered Cubic (FCC) lattice.

Initialize a Lattice.

Parameters:

  • subdomain – Subdomain object.

  • lattice_constant (float) – Lattice constant (unit cell size).

get_basis_vectors() → ndarray[Any, dtype[T]]

Return basis vectors for FCC lattice.

get_coordination_number() → float

Return coordination number for FCC lattice.

get_packing_efficiency() → float

Return packing efficiency (percent) for FCC lattice.

get_radius() → float

Return sphere radius for FCC lattice.

class pmmoto.domain_generation.lattice_packings.Lattice(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, lattice_constant: float)

Bases: object

Base class for generating common lattice packings.

Note

This currently adds more objects than needed.

Initialize a Lattice.

Parameters:

  • subdomain – Subdomain object.

  • lattice_constant (float) – Lattice constant (unit cell size).

generate_lattice() → ndarray[Any, dtype[T]]

Generate a lattice for a given unit cell size and lattice type.

Returns:

Array of shape (N, 4) of lattice points and sphere radius.

Return type:

np.ndarray

get_basis_vectors() → ndarray[Any, dtype[T]]

Return the basis vectors for the lattice.

Returns:

Array of basis vectors.

Return type:

np.ndarray

get_radius() → float

Return the sphere radius for the lattice.

Returns:

Sphere radius.

Return type:

float

class pmmoto.domain_generation.lattice_packings.SimpleCubic(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, lattice_constant: float)

Bases: Lattice

Simple Cubic (SC) lattice.

Initialize a Lattice.

Parameters:

  • subdomain – Subdomain object.

  • lattice_constant (float) – Lattice constant (unit cell size).

get_basis_vectors() → ndarray[Any, dtype[T]]

Return basis vectors for SC lattice.

get_coordination_number() → float

Return coordination number for SC lattice.

get_packing_efficiency() → float

Return packing efficiency (percent) for SC lattice.

get_radius() → float

Return sphere radius for SC lattice.

pmmoto.domain_generation.multiphase module

multiphase.py

Defines the Multiphase class for handling multiphase images and related calculations.

class pmmoto.domain_generation.multiphase.Multiphase(porous_media: PorousMedia, img: ndarray[Any, dtype[T]], num_phases: int)

Bases: Generic[T]

Class for handling multiphase images and phase calculations.

Initialize a Multiphase object.

Parameters:

  • porous_media – PorousMedia object.

  • img (np.ndarray) – Multiphase image.

  • num_phases (int) – Number of phases.

static get_pc(radius: float, gamma: float = 1) → float

Return the capillary pressure given a surface tension and radius.

Parameters:

  • radius (float) – Probe radius.

  • gamma (float, optional) – Surface tension. Defaults to 1.

Returns:

Capillary pressure.

Return type:

float

static get_probe_radius(pc: float, gamma: float = 1, contact_angle: float = 0) → float

Return the probe radius.

Parameters:

  • pc (float) – Capillary pressure.

  • gamma (float, optional) – Surface tension. Defaults to 1.

  • contact_angle (float, optional) – Contact angle in degrees. Defaults to 0.

Returns:

Probe radius.

Return type:

float

get_saturation(phase: int, img: None | ndarray[Any, dtype[T]] = None) → float

Calculate the saturation of a multiphase image.

Parameters:

  • phase (int) – The phase ID to compute the saturation for.

  • img (np.ndarray, optional) – Image to use. Defaults to self.img.

Returns:

The saturation of the specified phase.

Return type:

float

get_volume_fraction(phase: int, img: None | ndarray[Any, dtype[T]] = None) → float

Calculate the volume fraction of a given phase in a multiphase image.

Parameters:

  • phase (int) – The phase ID to compute the volume fraction for.

  • img (np.ndarray, optional) – Image to use. Defaults to self.img.

Returns:

The volume fraction of the specified phase.

Return type:

float

update_img(img: ndarray[Any, dtype[T]]) → None

Update the multiphase image.

Parameters:

img (np.ndarray) – New multiphase image.

pmmoto.domain_generation.porousmedia module

porousmedia.py

Defines the PorousMedia class for representing and analyzing porous media, including porosity and distance transform calculations.

class pmmoto.domain_generation.porousmedia.PorousMedia(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, img: ndarray[Any, dtype[uint8]])

Bases: object

Porous media class for storing image data and computing properties.

Initialize a PorousMedia object.

Parameters:

  • subdomain – Subdomain object.

  • img (np.ndarray) – Binary image of the porous medium.

property distance: ndarray[Any, dtype[float32]]

Get the Euclidean distance transform of the porous medium.

Returns:

Distance transform array.

Return type:

np.ndarray

property max_distance: float

Get the maximum distance from the distance transform.

Returns:

Maximum distance value.

Return type:

float

property porosity: float

Get the porosity of the porous medium.

Returns:

Porosity value (fraction of pore voxels).

Return type:

float

set_distance() → None

Calculate and set the Euclidean distance transform.

set_porosity() → None

Calculate and set the porosity of the porous medium.

pmmoto.domain_generation.porousmedia.gen_pm(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, img: ndarray[Any, dtype[uint8]]) → PorousMedia

Initialize the PorousMedia class and set inlet/outlet/wall boundary conditions.

Parameters:

  • subdomain – Subdomain object.

  • img (np.ndarray) – Binary image of the porous medium.

Returns:

Initialized porous media object.

Return type:

PorousMedia

pmmoto.domain_generation.rdf module

rdf.py

Radial distribution function (RDF) utilities for PMMoTo. Provides classes and functions for reading, generating, and binning RDF data.

pmmoto.domain_generation.rdf.bin_distances(subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, probe_atom_list: PyAtomList, atoms: AtomMap, bins: Bins) → None

Find atoms within a radius of probe atom and bin the distances.

Parameters:

  • subdomain – Subdomain object containing rank information.

  • probe_atom_list – List of probe atoms to calculate RDF from.

  • atoms – AtomMap containing target atoms.

  • bins – RDFBins object containing binning information.

Returns:

None. Updates bins in-place with binned counts from all processes.