pmmoto.io package

Initialize the io subpackage for PMMoTo.

Provides data reading and output utilities accessible directly from pmmoto.io.

pmmoto.io.py_read_lammps_atoms(input_file: str, include_mass: bool = False) → tuple[ndarray[Any, dtype[float64]], ndarray[Any, dtype[uint8]], ndarray[Any, dtype[float64]], ndarray[Any, dtype[float64]]] | tuple[ndarray[Any, dtype[float64]], ndarray[Any, dtype[uint8]], ndarray[Any, dtype[float64]]]

Read atom positions from a LAMMPS file.

Parameters:

input_file (str) – Path to the LAMMPS file.
include_mass (bool, optional) – Whether to include mass data.

Returns:

(atom_position, atom_type, [masses,] domain_data)

atom_position (np.ndarray): Atom positions.
atom_type (np.ndarray): Atom types.
masses (np.ndarray, optional): Atom masses if include_mass is True.
domain_data (np.ndarray): Domain bounding box.

Return type:

tuple

pmmoto.io.read_atom_map(input_file: str) → dict[int, dict[str, str]]

Read the atom mapping file.

File Format:: atom_id, element_name, atom_name

Parameters:: input_file (str) – Path to the atom map file.
Returns:: Mapping from atom ID to element and atom name.
Return type:: dict

pmmoto.io.read_binned_distances_rdf(input_folder: str) → tuple[dict[int, dict[str, str]], dict[int, RDF]]

Read a folder containing binned RDF data.

Folder must contain:

atom_map.txt
Files for all listed atoms named ‘atom_name’.rdf

Each .rdf file format:

radial distance, rdf(r)

Parameters:

input_folder (str) – Path to the folder.

Returns:

(atom_map, rdf_out)

atom_map (dict): Atom mapping.
rdf_out (dict): Mapping from atom ID to RDF object.

Return type:

tuple

pmmoto.io.read_lammps_atoms(input_file: str, type_map: None | dict[tuple[int, float], int] = None) → tuple[ndarray[Any, dtype[float64]], ndarray[Any, dtype[uint8]], ndarray[Any, dtype[float64]], float]

Read atom positions and types from a LAMMPS file using C++ backend.

Parameters:

input_file (str) – Path to the LAMMPS file.
type_map (dict, optional) – Mapping of (type, charge) pairs to new types. Example: {(1, 0.4): 2, (1, -0.4): 3}

Returns:

(positions, types, domain, timestep)

Return type:

tuple

pmmoto.io.read_rdf(input_folder: str) → tuple[dict[int, dict[str, str]], dict[int, RDF]]

Read a folder containing radial distribution function (RDF) data.

Folder must contain:

atom_map.txt
Files for all listed atoms named ‘atom_name’.rdf

Each .rdf file format:

radial distance, rdf(r)

Parameters:

input_folder (str) – Path to the folder.

Returns:

(atom_map, rdf_out)

atom_map (dict): Atom mapping.
rdf_out (dict): Mapping from atom ID to RDF object.

Return type:

tuple

pmmoto.io.read_sphere_pack_xyzr_domain(input_file: str) → tuple[ndarray[Any, dtype[float64]], tuple[tuple[float, float], ...]]

Read a sphere pack file with x, y, z, radius and domain bounding box.

Input File Format:: x_min x_max y_min y_max z_min z_max x1 y1 z1 r1 x2 y2 z2 r2 …

Parameters:

input_file (str) – Path to the input file.

Returns:

(sphere_data, domain_data)

sphere_data (np.ndarray): Array of shape (N, 4) for sphere positions
and radii.
domain_data (tuple): Domain bounding box as ((x_min, x_max), …).

Return type:

tuple

pmmoto.io.save_extended_img_data_parallel(file_name: str, subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, img: ndarray[Any, dtype[T]], extension: tuple[tuple[int, int], ...] = ((0, 0), (0, 0), (0, 0)), additional_img: None | dict[str, ndarray[Any, dtype[T]]] = None) → None

Save an image where img.shape > subdomain.voxels.

Parameters:

file_name (str) – Output file base name.
subdomain – Subdomain object.
img (np.ndarray) – Image array.
extension (tuple, optional) – Extension for each dimension.
additional_img (dict, optional) – Additional images to save.

Save image(s).

Parameters:

file_name (str) – Output file base name.
subdomain (dict) – Dictionary of subdomain objects.
img (dict) – Dictionary of image arrays.
**kwargs – Additional keyword arguments.

pmmoto.io.save_particle_data(file_name: str, subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, particles: ndarray[Any, dtype[floating[Any]]], **kwargs: Any) → None

Save particle data as VTK PolyData.

Parameters:

file_name (str) – Output file base name.
subdomain – Subdomain object with rank attribute.
particles (np.ndarray) – Particle data array.
**kwargs – Additional keyword arguments.

Subpackages

pmmoto.io.evtk package

Submodules

pmmoto.io.data_read module

dataRead.py

Provides functions for reading various simulation and atomistic data formats used in PMMoTo, including sphere packs, LAMMPS files, atom maps, and RDF data.

pmmoto.io.data_read.py_read_lammps_atoms(input_file: str, include_mass: bool = False) → tuple[ndarray[Any, dtype[float64]], ndarray[Any, dtype[uint8]], ndarray[Any, dtype[float64]], ndarray[Any, dtype[float64]]] | tuple[ndarray[Any, dtype[float64]], ndarray[Any, dtype[uint8]], ndarray[Any, dtype[float64]]]

Read atom positions from a LAMMPS file.

Parameters:

input_file (str) – Path to the LAMMPS file.
include_mass (bool, optional) – Whether to include mass data.

Returns:

(atom_position, atom_type, [masses,] domain_data)

atom_position (np.ndarray): Atom positions.
atom_type (np.ndarray): Atom types.
masses (np.ndarray, optional): Atom masses if include_mass is True.
domain_data (np.ndarray): Domain bounding box.

Return type:

tuple

pmmoto.io.data_read.read_atom_map(input_file: str) → dict[int, dict[str, str]]

Read the atom mapping file.

File Format:: atom_id, element_name, atom_name

Parameters:: input_file (str) – Path to the atom map file.
Returns:: Mapping from atom ID to element and atom name.
Return type:: dict

pmmoto.io.data_read.read_binned_distances_rdf(input_folder: str) → tuple[dict[int, dict[str, str]], dict[int, RDF]]

Read a folder containing binned RDF data.

Folder must contain:

atom_map.txt
Files for all listed atoms named ‘atom_name’.rdf

Each .rdf file format:

radial distance, rdf(r)

Parameters:

input_folder (str) – Path to the folder.

Returns:

(atom_map, rdf_out)

atom_map (dict): Atom mapping.
rdf_out (dict): Mapping from atom ID to RDF object.

Return type:

tuple

pmmoto.io.data_read.read_lammps_atoms(input_file: str, type_map: None | dict[tuple[int, float], int] = None) → tuple[ndarray[Any, dtype[float64]], ndarray[Any, dtype[uint8]], ndarray[Any, dtype[float64]], float]

Read atom positions and types from a LAMMPS file using C++ backend.

Parameters:

input_file (str) – Path to the LAMMPS file.
type_map (dict, optional) – Mapping of (type, charge) pairs to new types. Example: {(1, 0.4): 2, (1, -0.4): 3}

Returns:

(positions, types, domain, timestep)

Return type:

tuple

pmmoto.io.data_read.read_rdf(input_folder: str) → tuple[dict[int, dict[str, str]], dict[int, RDF]]

Read a folder containing radial distribution function (RDF) data.

Folder must contain:

atom_map.txt
Files for all listed atoms named ‘atom_name’.rdf

Each .rdf file format:

radial distance, rdf(r)

Parameters:

input_folder (str) – Path to the folder.

Returns:

(atom_map, rdf_out)

atom_map (dict): Atom mapping.
rdf_out (dict): Mapping from atom ID to RDF object.

Return type:

tuple

pmmoto.io.data_read.read_sphere_pack_xyzr_domain(input_file: str) → tuple[ndarray[Any, dtype[float64]], tuple[tuple[float, float], ...]]

Read a sphere pack file with x, y, z, radius and domain bounding box.

Input File Format:: x_min x_max y_min y_max z_min z_max x1 y1 z1 r1 x2 y2 z2 r2 …

Parameters:

input_file (str) – Path to the input file.

Returns:

(sphere_data, domain_data)

sphere_data (np.ndarray): Array of shape (N, 4) for sphere positions
and radii.
domain_data (tuple): Domain bounding box as ((x_min, x_max), …).

Return type:

tuple

pmmoto.io.io_utils module

Ineput/Output Utility Functions

pmmoto.io.io_utils.check_file(file_name: str) → None: Check file name

pmmoto.io.io_utils.check_file_path(file_name: str, create_folder: bool = True, extra_info: None | str = None) → None

Ensure the directory path(s) for the given file_name exist, creating them .

Parameters:

file_name (str) – The full file path or just a file name. If it contains directories, those directories will be checked and created if missing.
create_folder (bool, optional) – If True, also creates a folder with the name formed by concatenating file_name and extra_info (if provided), defaults to True.
extra_info (str or None, optional) – Optional string appended to file_name to form an additional directory path to create.

Notes

If file_name contains no directory component (i.e., just a file name), no directory will be created for the file itself, but if create_folder is True and extra_info is provided, a directory named file_name + extra_info will be created.

pmmoto.io.io_utils.check_folder(folder_name: str) → None: Check to make sure folder exists

pmmoto.io.io_utils.check_num_files(num_files: int, size: int) → None: Check makesure num_files is equal to mpi.size

pmmoto.io.output module

Output utilities for saving PMMoTo simulation data.

This module provides functions to save particle and image data in VTK formats, supporting both serial and parallel output.

pmmoto.io.output.save_extended_img_data_parallel(file_name: str, subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, img: ndarray[Any, dtype[T]], extension: tuple[tuple[int, int], ...] = ((0, 0), (0, 0), (0, 0)), additional_img: None | dict[str, ndarray[Any, dtype[T]]] = None) → None

Save an image where img.shape > subdomain.voxels.

Parameters:

file_name (str) – Output file base name.
subdomain – Subdomain object.
img (np.ndarray) – Image array.
extension (tuple, optional) – Extension for each dimension.
additional_img (dict, optional) – Additional images to save.

Save image(s).

Parameters:

file_name (str) – Output file base name.
subdomain (dict) – Dictionary of subdomain objects.
img (dict) – Dictionary of image arrays.
**kwargs – Additional keyword arguments.

pmmoto.io.output.save_particle_data(file_name: str, subdomain: Subdomain | PaddedSubdomain | VerletSubdomain, particles: ndarray[Any, dtype[floating[Any]]], **kwargs: Any) → None

Save particle data as VTK PolyData.

Parameters:

file_name (str) – Output file base name.
subdomain – Subdomain object with rank attribute.
particles (np.ndarray) – Particle data array.
**kwargs – Additional keyword arguments.