porereax.sample

Module providing the Sample class for molecular trajectory sampling.

This module defines the Sample class, which manages the sampling of molecular trajectories using various samplers. It supports parallel processing using the multiprocessing module and integrates with the Ovito library for trajectory handling. The Sample class allows users to add different samplers, configure sampling parameters, and execute the sampling process either in parallel or serially.

Attributes

Region

Classes

Sample

Class to manage sampling of molecular trajectories.

Module Contents

type porereax.sample.Region = str | Callable[[NDArray[np.float64]], NDArray[np.bool_]]

class porereax.sample.Sample(atom_lib, masses, trajectory_file, bond_file=None, system=None, start_end_nthframe=(0, -1, 1))

Class to manage sampling of molecular trajectories.

init_helper(atom_lib, masses, trajectory_file, bond_file, system, start_frame, end_frame, nth_frame, num_particles, num_frames, box)

Helper function to initialize Sample instance.

Parameters:

• atom_lib (dict) – Library mapping atom names to types.

• masses (dict) – Dictionary mapping atom names to their masses.

• trajectory_file (str) – Path to the trajectory file.

• bond_file (str, optional) – Path to the bond file.

• system (object, optional) – System object containing additional information.

• start_frame (int) – Starting frame for sampling.

• end_frame (int) – Ending frame for sampling.

• nth_frame (int) – Step size for frame sampling.

• num_particles (int) – Number of particles in the trajectory.

• num_frames (int) – Total number of frames in the trajectory.

• box (np.ndarray) – Simulation box dimensions.

static get_trajectory_data(trajectory_file, bond_file, atom_lib)

Extract trajectory metadata using Ovito.

Parameters:

• trajectory_file (str) – Path to the trajectory file.

• bond_file (str, optional) – Path to the bond file.

• atom_lib (dict) – Library mapping atom names to types.

Returns:

• num_particles (int) – Number of particles in the trajectory.

• num_frames (int) – Total number of frames in the trajectory.

• box (np.ndarray) – Simulation box dimensions.

add_molecule_structure_sampling(name_out: str, region: Region = 'Box')

Add sampling for molecule structures to analyse the bonding of atoms and identify substructures.

Parameters:

• name_out (str) – Name of the output directory and object file of the sampler data

• region (Region, optional) – Region of the box to sample. Supported: “Box”, “Reservoir”, “Pore”, “Wall”, or a user-defined function that takes atom positions (N, 3) as input and returns a boolean mask (N,).

add_charge_sampling(name_out: str, atoms: list[dict], region: Region = 'Box', num_bins=800, range=(-2.0, 2.0))

Add sampling for charge distribution of the central atom in the specified atom structures.

Parameters:

• name_out (str) – Name of the output directory and object file of the sampler data

• atoms (list) – List of atom structures to sample. Each atom structure is defined as a dictionary in the format: {“atom”: “a”, “bonds”: [b, b, c, …]}, where a is the central atom and b, c, … are the bonded atoms. With a, b, c being atom identifiers. The order of atoms in the “bonds” list does not matter. The “bonds” list can be empty to indicate that the atom is not bonded to any other atoms. If the dictionary does not contain the “bonds” key, every atom of type a will be sampled regardless of its bonding environment.

• region (Region, optional) – Region of the box to sample. Supported: “Box”, “Reservoir”, “Pore”, “Wall”, or a user-defined function that takes atom positions (N, 3) as input and returns a boolean mask (N,).

• num_bins (int, optional) – Number of bins for the histogram. Default is 800.

• range (tuple, optional) – Range (min, max) in e for which to compute the histogram. Default is (-2.0, 2.0).

add_density_sampling(name_out: str, atoms: list[dict], dimension: str, region: Region = 'Box', num_bins=200, direction='z', conditions={})

Add sampling for time or position density distribution of the specified atom structures. For positional sampling the position of the central atom is used.

Parameters:

• name_out (str) – Name of the output directory and object file of the sampler data

• atoms (list) – List of atom structures to sample. Each atom structure is defined as a dictionary in the format: {“atom”: “a”, “bonds”: [b, b, c, …]}, where a is the central atom and b, c, … are the bonded atoms. With a, b, c being atom identifiers. The order of atoms in the “bonds” list does not matter. The “bonds” list can be empty to indicate that the atom is not bonded to any other atoms. If the dictionary does not contain the “bonds” key, every atom of type a will be sampled regardless of its bonding environment.

• dimension (str) – Sampling dimension. Supported: “Time”, “Cartesian1D”, “Cartesian2D”. - “Time”: Samples the amount of atom structures over time. - “Cartesian1D”: Samples the amount of atom structures along a specified direction (x, y, or z) in the simulation box. - “Cartesian2D”: Samples the amount of atom structures in a 2D plane (xy, xz, or yz) in the simulation box.

• region (Region, optional) – Region of the box to sample. Supported: “Box”, “Reservoir”, “Pore”, “Wall”, or a user-defined function that takes atom positions (N, 3) as input and returns a boolean mask (N,).

• num_bins (int, optional) – Number of bins for position sampling. Not used for time sampling.

• direction (str, optional) – Direction along which to sample. Options depending on the dimension: - For “Cartesian1D”: use (“x”, “y”, or “z”). - For “Cartesian2D”: use (“xy”, “xz”, or “yz”).

• conditions (dict, optional) – Dictionary of conditions to filter atoms during sampling. Supported conditions: - “Charge”: tuple (min_charge, max_charge) to filter atoms by charge. - “Angle”: tuple (min_angle, max_angle) to filter atoms by angle formed with bonded atoms.

add_angle_sampling(name_out: str, atoms: list[dict], region: Region = 'Box', num_bins=180, angle='all')

Add sampling for angle distribution of the specified atom structures. The angle is defined by the central atom and its bonded atoms.

Parameters:

• name_out (str) – Name of the output directory and object file of the sampler data

• atoms (list) – List of atom structures to sample. Each atom structure is defined as a dictionary in the format: {“atom”: “a”, “bonds”: [b, b, c, …]}, where a is the central atom and b, c, … are the bonded atoms. With a, b, c being atom identifiers. The order of atoms in the “bonds” list does not matter. The “bonds” list can be empty to indicate that the atom is not bonded to any other atoms. If the dictionary does not contain the “bonds” key, every atom of type a will be sampled regardless of its bonding environment.

• region (Region, optional) – Region of the box to sample. Supported: “Box”, “Reservoir”, “Pore”, “Wall”, or a user-defined function that takes atom positions (N, 3) as input and returns a boolean mask (N,).

• num_bins (int, optional) – Number of bins for the histogram. Default is 180.

• angle (str, optional) – Angle of interested atoms. Supported: “all”, “a-b-c” - “all”: Samples all angles formed by the central atom and all of its bonded atoms. - “a-b-c”: Samples only the angle formed by the central atom (b) and two specific bonded atoms (a and c), regardless of other bonded atoms d, … With a, b, c being atom identifiers.

add_bond_density_sampling(name_out: str, bonds: list[dict], dimension: str, region: Region = 'Box', num_bins=200, direction='z', conditions={})

Add sampling for time or position density distribution of the specified bonds. For positional sampling the position of the bond center is used.

Parameters:

• name_out (str) – Name of the output directory and object file of the sampler data

• bonds (list) – List of bonds to sample. Each bond is defined as a dictionary in the format: {“bond”: “a-b”, “bonds_A”: [c, …], “bonds_B”: [d, …]}, where a and b are the bonded atoms, and c, d, … are the atoms bonded to A and B, respectively. With a, b, c, d being atom identifiers. Atom b/a does not need to be added to the “bonds_A”/”bonds_B” list. The order of atoms in the “bonds_A” and “bonds_B” lists does not matter. The “bonds_A” and “bonds_B” lists can be empty to indicate that the atoms a and b are not bonded to any other atoms. If the dictionary does not contain the “bonds_A” or “bonds_B” keys, every bond of type a-b will be sampled regardless of its bonding environment.

• dimension (str) – Sampling dimension. Supported: “Time”, “Cartesian1D”, “Cartesian2D”. - “Time”: Samples the amount of the specified bonds over time. - “Cartesian1D”: Samples the amount of the specified bonds along a specified direction (x, y, or z) in the simulation box. - “Cartesian2D”: Samples the amount of the specified bonds in a 2D plane (xy, xz, or yz) in the simulation box.

• region (Region, optional) – Region of the box to sample. Supported: “Box”, “Reservoir”, “Pore”, “Wall”, or a user-defined function that takes atom positions (N, 3) as input and returns a boolean mask (N,).

• num_bins (int, optional) – Number of bins for position sampling. Not used for time sampling.

• direction (str, optional) – Direction along which to sample. Options depending on the dimension: - For “Cartesian1D”: use (“x”, “y”, or “z”). - For “Cartesian2D”: use (“xy”, “xz”, or “yz”).

• conditions (dict, optional) – Dictionary of conditions to filter bonds during sampling. Supported conditions: - “Bond Length”: tuple (min_len, max_len) to filter bonds by bond length.

add_bond_length_sampling(name_out: str, bonds: list[dict], dimension: str, region: Region = 'Box', num_bins=200, range=(0.0, 3.0))

Add sampling for bond length or bond order distribution of the specified bonds.

Parameters:

• name_out (str) – Name of the output directory and object file of the sampler data

• bonds (list) – List of bonds to sample. Each bond is defined as a dictionary in the format: {“bond”: “a-b”, “bonds_A”: [c, …], “bonds_B”: [d, …]}, where a and b are the bonded atoms, and c, d, … are the atoms bonded to A and B, respectively. With a, b, c, d being atom identifiers. Atom b/a does not need to be added to the “bonds_A”/”bonds_B” list. The order of atoms in the “bonds_A” and “bonds_B” lists does not matter. The “bonds_A” and “bonds_B” lists can be empty to indicate that the atoms a and b are not bonded to any other atoms. If the dictionary does not contain the “bonds_A” or “bonds_B” keys, every bond of type a-b will be sampled regardless of its bonding environment.

• dimension (str) – Sampling dimension. Supported: “Bond Length” and “Bond Order”

• region (Region, optional) – Region of the box to sample. Supported: “Box”, “Reservoir”, “Pore”, “Wall”, or a user-defined function that takes atom positions (N, 3) as input and returns a boolean mask (N,).

• num_bins (int, optional) – Number of bins for the histogram. Default is 200.

• range (tuple, optional) – Range (min, max) for which to compute the histogram. Default is (0.0, 3.0). - For “Bond Length”: range is in Angstroms. - For “Bond Order”: range is in bond order units defined by the ReaxFF force field.

add_rdf_sampling(name_out: str, pairs: list[tuple[dict, dict]], region: Region = 'Box', num_bins=200, r_max=7.0)

Add sampling for radial distribution function (RDF) of the specified atom pairs.

Parameters:

• name_out (str) – Name of the output directory and object file of the sampler data

• pairs (list) – List of atom pairs to sample. Each pair is defined as a tuple of two dictionaries in the format: ({“atom”: “a”, “bonds”: […]}, {“atom”: “b”, “bonds”: […]}) where a and b are atom identifiers, and bonds are lists of atom identifiers that atoms a and b are bonded to, respectively. Each dictionary works the same way as other samplers, with atoms as a parameter.

• region (Region, optional) – Region of the box to sample. Supported: “Box”, “Reservoir”, “Pore”, “Wall”, or a user-defined function that takes atom positions (N, 3) as input and returns a boolean mask (N,).

• num_bins (int, optional) – Number of bins for the histogram. Default is 200.

• r_max (float, optional) – Maximum distance in Angstroms for which to compute the histogram. Default is 7.0. Be aware that the maximum distance significantly affects the computation time.

add_reaction_sampling(name_out: str, reactions: list[tuple], dimension: str, region: Region = 'Box', num_bins=200, direction='z', position='center')

Add sampling for reaction events of the specified reactions.

Parameters:

• name_out (str) – Name of the output directory and object file of the sampler data

• reactions (list) – List of reactions to sample. Each reaction is defined as a tuple of two dictionaries in the format: ({“atom”: “a”, “bonds”: […]}, {“atom”: “b”, “bonds”: […]}) where a and b are atom identifiers, and bonds are lists of atom identifiers that atoms a and b are bonded to, respectively. Each dictionary works the same way as other samplers, with atoms as a parameter.

• dimension (str) – Sampling dimension. Supported: “Time”, “Cartesian1D”, “Cartesian2D”. - “Time”: Samples the amount of the specified reactions over time. - “Cartesian1D”: Samples the amount of the specified reactions along a specified direction (x, y, or z) in the simulation box. - “Cartesian2D”: Samples the amount of the specified reactions in a 2D plane (xy, xz, or yz) in the simulation box.

• region (Region, optional) – Region of the box to sample. Supported: “Box”, “Reservoir”, “Pore”, “Wall”, or a user-defined function that takes atom positions (N, 3) as input and returns a boolean mask (N,).

• num_bins (int, optional) – Number of bins for position sampling. Default is 200.

• direction (str, optional) – Direction along which to sample. Options depending on the dimension: - For “Cartesian1D”: use (“x”, “y”, or “z”). - For “Cartesian2D”: use (“xy”, “xz”, or “yz”).

• position (str, optional) – Position of the reaction event to sample. Supported: “center”, “reactant”, “product” - “center”: Samples the position of the reaction event at the center between the reactant and product atoms. - “reactant”: Samples the position of the reaction event at the position of the reactant atoms. - “product”: Samples the position of the reaction event at the position of the product atoms.

init_samplers(sampler_inputs, process_id)

Initialize samplers based on provided configurations.

Parameters:

• sampler_inputs (dict) – Dictionary of sampler input configurations.

• process_id (int) – Process ID for parallel sampling.

sample(is_parallel=True, num_cores=0)

Execute the sampling process.

Parameters:

• is_parallel (bool, optional) – Whether to use parallel processing.

• num_cores (int, optional) – Number of CPU cores to use for parallel processing.

static init_subprocess_sampler(atom_lib, masses, trajectory_file, bond_file, system, start_end_nthframe, sampler_inputs, process_id, num_particles, num_frames, box)

Initialize and run sampling in a subprocess.

This static method is designed to be called within a subprocess for parallel sampling.

Parameters:

• atom_lib (dict) – Library mapping atom names to types.

• masses (dict) – Dictionary mapping atom names to their masses.

• trajectory_file (str) – Path to the trajectory file.

• bond_file (str, optional) – Path to the bond file.

• system (object, optional) – System object containing additional information.

• start_end_nthframe (tuple) – Tuple specifying (start_frame, end_frame, nth_frame) for sampling.

• sampler_inputs (dict) – Dictionary of sampler input configurations.

• process_id (int) – Process ID for parallel sampling.

• num_particles (int) – Number of particles in the trajectory.

• box (np.ndarray) – Simulation box dimensions.

Returns:

Completion message for the subprocess.

Return type:

str

sample_helper()

Helper function to perform the sampling process.