porereax.sample =============== .. py:module:: porereax.sample .. autoapi-nested-parse:: 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 ---------- .. autoapisummary:: porereax.sample.Region Classes ------- .. autoapisummary:: porereax.sample.Sample Module Contents --------------- .. py:type:: Region :canonical: str | Callable[[NDArray[np.float64]], NDArray[np.bool_]] .. py:class:: Sample(atom_lib, masses, trajectory_file, bond_file=None, system=None, start_end_nthframe=(0, -1, 1)) Class to manage sampling of molecular trajectories. .. py:method:: 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. :param atom_lib: Library mapping atom names to types. :type atom_lib: dict :param masses: Dictionary mapping atom names to their masses. :type masses: dict :param trajectory_file: Path to the trajectory file. :type trajectory_file: str :param bond_file: Path to the bond file. :type bond_file: str, optional :param system: System object containing additional information. :type system: object, optional :param start_frame: Starting frame for sampling. :type start_frame: int :param end_frame: Ending frame for sampling. :type end_frame: int :param nth_frame: Step size for frame sampling. :type nth_frame: int :param num_particles: Number of particles in the trajectory. :type num_particles: int :param num_frames: Total number of frames in the trajectory. :type num_frames: int :param box: Simulation box dimensions. :type box: np.ndarray .. py:method:: get_trajectory_data(trajectory_file, bond_file, atom_lib) :staticmethod: Extract trajectory metadata using Ovito. :param trajectory_file: Path to the trajectory file. :type trajectory_file: str :param bond_file: Path to the bond file. :type bond_file: str, optional :param atom_lib: Library mapping atom names to types. :type atom_lib: dict :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. .. py:method:: add_molecule_structure_sampling(name_out: str, region: Region = 'Box') Add sampling for molecule structures to analyse the bonding of atoms and identify substructures. :param name_out: Name of the output directory and object file of the sampler data :type name_out: str :param region: 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,). :type region: Region, optional .. py:method:: 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. :param name_out: Name of the output directory and object file of the sampler data :type name_out: str :param atoms: 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. :type atoms: list :param region: 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,). :type region: Region, optional :param num_bins: Number of bins for the histogram. Default is 800. :type num_bins: int, optional :param range: Range (min, max) in e for which to compute the histogram. Default is (-2.0, 2.0). :type range: tuple, optional .. py:method:: 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. :param name_out: Name of the output directory and object file of the sampler data :type name_out: str :param atoms: 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. :type atoms: list :param dimension: 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. :type dimension: str :param region: 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,). :type region: Region, optional :param num_bins: Number of bins for position sampling. Not used for time sampling. :type num_bins: int, optional :param direction: Direction along which to sample. Options depending on the dimension: - For "Cartesian1D": use ("x", "y", or "z"). - For "Cartesian2D": use ("xy", "xz", or "yz"). :type direction: str, optional :param conditions: 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. :type conditions: dict, optional .. py:method:: 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. :param name_out: Name of the output directory and object file of the sampler data :type name_out: str :param atoms: 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. :type atoms: list :param region: 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,). :type region: Region, optional :param num_bins: Number of bins for the histogram. Default is 180. :type num_bins: int, optional :param angle: 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. :type angle: str, optional .. py:method:: 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. :param name_out: Name of the output directory and object file of the sampler data :type name_out: str :param bonds: 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. :type bonds: list :param dimension: 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. :type dimension: str :param region: 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,). :type region: Region, optional :param num_bins: Number of bins for position sampling. Not used for time sampling. :type num_bins: int, optional :param direction: Direction along which to sample. Options depending on the dimension: - For "Cartesian1D": use ("x", "y", or "z"). - For "Cartesian2D": use ("xy", "xz", or "yz"). :type direction: str, optional :param conditions: Dictionary of conditions to filter bonds during sampling. Supported conditions: - "Bond Length": tuple (min_len, max_len) to filter bonds by bond length. :type conditions: dict, optional .. py:method:: 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. :param name_out: Name of the output directory and object file of the sampler data :type name_out: str :param bonds: 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. :type bonds: list :param dimension: Sampling dimension. Supported: "Bond Length" and "Bond Order" :type dimension: str :param region: 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,). :type region: Region, optional :param num_bins: Number of bins for the histogram. Default is 200. :type num_bins: int, optional :param range: 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. :type range: tuple, optional .. py:method:: 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. :param name_out: Name of the output directory and object file of the sampler data :type name_out: str :param pairs: 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. :type pairs: list :param region: 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,). :type region: Region, optional :param num_bins: Number of bins for the histogram. Default is 200. :type num_bins: int, optional :param r_max: 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. :type r_max: float, optional .. py:method:: 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. :param name_out: Name of the output directory and object file of the sampler data :type name_out: str :param reactions: 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. :type reactions: list :param dimension: 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. :type dimension: str :param region: 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,). :type region: Region, optional :param num_bins: Number of bins for position sampling. Default is 200. :type num_bins: int, optional :param direction: Direction along which to sample. Options depending on the dimension: - For "Cartesian1D": use ("x", "y", or "z"). - For "Cartesian2D": use ("xy", "xz", or "yz"). :type direction: str, optional :param position: 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. :type position: str, optional .. py:method:: init_samplers(sampler_inputs, process_id) Initialize samplers based on provided configurations. :param sampler_inputs: Dictionary of sampler input configurations. :type sampler_inputs: dict :param process_id: Process ID for parallel sampling. :type process_id: int .. py:method:: sample(is_parallel=True, num_cores=0) Execute the sampling process. :param is_parallel: Whether to use parallel processing. :type is_parallel: bool, optional :param num_cores: Number of CPU cores to use for parallel processing. :type num_cores: int, optional .. py:method:: init_subprocess_sampler(atom_lib, masses, trajectory_file, bond_file, system, start_end_nthframe, sampler_inputs, process_id, num_particles, num_frames, box) :staticmethod: Initialize and run sampling in a subprocess. This static method is designed to be called within a subprocess for parallel sampling. :param atom_lib: Library mapping atom names to types. :type atom_lib: dict :param masses: Dictionary mapping atom names to their masses. :type masses: dict :param trajectory_file: Path to the trajectory file. :type trajectory_file: str :param bond_file: Path to the bond file. :type bond_file: str, optional :param system: System object containing additional information. :type system: object, optional :param start_end_nthframe: Tuple specifying (start_frame, end_frame, nth_frame) for sampling. :type start_end_nthframe: tuple :param sampler_inputs: Dictionary of sampler input configurations. :type sampler_inputs: dict :param process_id: Process ID for parallel sampling. :type process_id: int :param num_particles: Number of particles in the trajectory. :type num_particles: int :param box: Simulation box dimensions. :type box: np.ndarray :returns: Completion message for the subprocess. :rtype: str .. py:method:: sample_helper() Helper function to perform the sampling process.