API Reference

zacrostools.kmc_model.KMCModel(gas_model: GasModel, reaction_model: ReactionModel, energetics_model: EnergeticsModel, lattice_model: LatticeModel)[source]

Represents a Kinetic Monte Carlo (KMC) model.

Parameters:

  • gas_model (GasModel) – An instance containing information about the gas molecules.

  • reaction_model (ReactionModel) – An instance containing information about the reaction model.

  • energetics_model (EnergeticsModel) – An instance containing information about the energetic model.

  • lattice_model (LatticeModel) – An instance containing information about the lattice model.

zacrostools.kmc_model.KMCModel.create_job_dir(self, job_path: str, temperature: float | int, pressure: dict, reporting_scheme: dict | None = None, stopping_criteria: dict | None = None, manual_scaling: dict | None = None, stiffness_scaling_algorithm: str | None = None, stiffness_scalable_steps: list | str | None = None, stiffness_scalable_symmetric_steps: list | None = None, stiffness_scaling_tags: dict | None = None, additional_keywords: list | None = None, sig_figs_energies: int = 8, sig_figs_pe: int = 8, sig_figs_lattice: int = 8, random_seed: int | None = None, version: float | int = 5.0)

Create a job directory and write the necessary input files for the KMC simulation.

Parameters:

  • job_path (str) – The path for the job directory where input files will be written.

  • temperature (float or int) – Reaction temperature (in K).

  • pressure (dict) – Partial pressures of all gas species (in bar), e.g., {‘CO’: 1.0, ‘O2’: 0.001}.

  • reporting_scheme (dict, optional) –

    Reporting scheme in Zacros format. Must contain the following keys: ‘snapshots’, ‘process_statistics’, and ‘species_numbers’. Default is {‘snapshots’: ‘on event 10000’,

    ’process_statistics’: ‘on event 10000’, ‘species_numbers’: ‘on event 10000’}.

  • stopping_criteria (dict, optional) –

    Stopping criteria in Zacros format. Must contain the following keys: ‘max_steps’, ‘max_time’, and ‘wall_time’. Default is {‘max_steps’: ‘infinity’,

    ’max_time’: ‘infinity’, ‘wall_time’: 86400}.

  • manual_scaling (dict, optional) – Dictionary mapping step names to their corresponding manual scaling factors, e.g., {‘CO_diffusion’: 1.0e-1, ‘O_diffusion’: 1.0e-2}. Default is {}.

  • stiffness_scaling_algorithm (str, optional) – Algorithm used for stiffness scaling. Allowed values are None (default), ‘legacy’, or ‘prats2024’.

  • stiffness_scalable_steps (list of str or 'all', optional) – Steps that will be marked as ‘stiffness_scalable’ in mechanism_input.dat. Can be provided as a list of step names or the string ‘all’ to indicate that all steps (except those specified in stiffness_scalable_symmetric_steps) are stiffness scalable. Default is [].

  • stiffness_scalable_symmetric_steps (list of str, optional) – Steps that will be marked as ‘stiffness_scalable_symmetric’ in mechanism_input.dat. Default is [].

  • stiffness_scaling_tags (dict, optional) – Keywords controlling the dynamic stiffness scaling algorithm and their corresponding values, e.g., {‘check_every’: 500, ‘min_separation’: 400.0, …}. The correct types are: integer for ‘check_every’ and ‘min_noccur’, and float for all others. Default is {}

  • additional_keywords (list of str, optional) – Additional keywords to append to simulation_input.dat that are currently not supported by zacrostools, e.g., [‘event_report on’]. Each keyword will be written on its own line. Default is None.

  • sig_figs_energies (int, optional) – Number of significant figures for energy values in input files. Default is 8.

  • sig_figs_pe (int, optional) – Number of significant figures for pre-exponential factors in mechanism_input.dat. Default is 8.

  • sig_figs_lattice (int, optional) – Number of significant figures for coordinates in lattice_input.dat. Default is 8.

  • random_seed (int, optional) – The seed for the random number generator. If not specified, a random seed will be generated. Default is None.

  • version (float or int, optional) – The Zacros version. Can be a single integer (e.g. 4) or float (e.g. 4.2 or 5.1).

zacrostools.lattice_model.LatticeModel(lattice_type: str, default_lattice_type: str | None = None, lattice_constant: float | None = None, copies: List[int] | None = None, cell_vectors: Tuple[Tuple[float, float], Tuple[float, float]] | None = None, sites: Dict[str, Tuple[float, float] | List[Tuple[float, float]]] | None = None, coordinate_type: str = 'direct', neighboring_structure: str | Dict[str, str | List[str]] | None = None, max_distances: Dict[str, float] | None = None)[source]

Represents a KMC lattice model for Zacros.

Parameters:

  • lattice_type (str) – Type of lattice structure. Must be one of the following: - ‘default_choice’ - ‘periodic_cell’ - ‘explicit’

  • default_lattice_type (str, optional) – Required if lattice_type is ‘default_choice’. One of ‘triangular_periodic’, ‘rectangular_periodic’, ‘hexagonal_periodic’.

  • lattice_constant (float, optional) – Required if lattice_type is ‘default_choice’. The lattice constant.

  • copies (list of int, optional) – Required for ‘default_choice’ and ‘periodic_cell’. Number of copies in horizontal and vertical directions, e.g., [10, 10].

  • cell_vectors (tuple of float, optional) – Required if lattice_type is ‘periodic_cell’. Two unit vectors defining the unit cell, e.g., ((2.5, 0.0), (0.0, 2.5)).

  • sites (dict, optional) –

    Required if lattice_type is ‘periodic_cell’. Dictionary mapping site types to their coordinates. Values can be either a single tuple or a list of tuples. Example: ``` {

    ’A’: [(0.0, 0.0)], ‘B’: [(0.5, 0.5)]

  • coordinate_type (str, optional) – Required if lattice_type is ‘periodic_cell’. Coordinate system used for site positions: ‘direct’ or ‘cartesian’. Defaults to ‘direct’.

  • neighboring_structure (Union[str, dict], optional) –

    Required if lattice_type is ‘periodic_cell’. - If a dictionary, it maps site pair strings to a list of relationship keywords.

    Example: {‘1-2’: [‘self’], ‘1-1’: [‘north’, ‘east’]}

    • If ‘from_distances’, the user must provide a max_distances dictionary to generate the neighboring structure automatically.

  • max_distances (dict, optional) – Required if neighboring_structure=’from_distances’. Dictionary mapping site type pairs to maximum allowed distances. Example: {‘A-A’: 3.0, ‘A-B’: 3.0, ‘B-B’: 3.0}

Examples

Default Choice Lattice

```python lattice_model = LatticeModel(

lattice_type=’default_choice’, default_lattice_type=’triangular_periodic’, lattice_constant=2.5, copies=[20, 20]

)

Periodic Cell Lattice

```python lattice_model = LatticeModel(

lattice_type=’periodic_cell’, cell_vectors=((2.5, 0.0), (0.0, 2.5)), sites={

‘A’: [(0.0, 0.0)], ‘B’: [(0.5, 0.5)]

}, coordinate_type=’direct’, copies=[10, 10], neighboring_structure=’from_distances’, max_distances={

‘A-A’: 3.0, ‘A-B’: 3.0, ‘B-B’: 3.0

}

)

Alternatively, when specifying the neighboring_structure directly:

```python neighboring_structure = {

‘1-1’: [‘north’, ‘east’], ‘1-2’: [‘self’], ‘2-1’: [‘north’, ‘east’, ‘northeast’], ‘2-2’: [‘north’, ‘east’]

}

lattice_model = LatticeModel(

lattice_type=’periodic_cell’, cell_vectors=((3.27, 0.0), (0.0, 3.27)), sites={

‘tC’: [(0.25, 0.25)], ‘tM’: [(0.75, 0.75)]

}, coordinate_type=’direct’, copies=[10, 10], neighboring_structure=neighboring_structure

)

zacrostools.kmc_output.KMCOutput(job_path: str = None, analysis_range: list | None = None, range_type: str = 'time', weights: str | None = None, **kwargs)[source]

A class that represents a KMC (Kinetic Monte Carlo) simulation output.

zacrostools.kmc_output.area

Lattice surface area (in Ų).

Type:

float

zacrostools.kmc_output.av_coverage

Average coverage of surface species (in %). Example: KMCOutput.av_coverage[‘CO’].

Type:

Dict[str, float]

zacrostools.kmc_output.av_coverage_per_site_type

Average coverage of surface species per site type (in %).

Type:

Dict[str, Dict[str, float]]

zacrostools.kmc_output.av_energy

Average lattice energy (in eV·Å⁻²).

Type:

float

zacrostools.kmc_output.av_total_coverage

Average total coverage of surface species (in %).

Type:

float

zacrostools.kmc_output.av_total_coverage_per_site_type

Average total coverage of surface species per site type (in %).

Type:

Dict[str, float]

zacrostools.kmc_output.coverage

Coverage of surface species over time (in %). Example: KMCOutput.coverage[‘CO’].

Type:

Dict[str, np.ndarray]

zacrostools.kmc_output.coverage_per_site_type

Coverage of surface species per site type over time (in %).

Type:

Dict[str, Dict[str, np.ndarray]]

zacrostools.kmc_output.cpu_time

Final elapsed cpu time (in seconds).

Type:

float

zacrostools.kmc_output.dominant_ads

Most dominant surface species, used for plotting kinetic phase diagrams.

Type:

str

zacrostools.kmc_output.dominant_ads_per_site_type

Most dominant surface species per site type, used for plotting kinetic phase diagrams.

Type:

Dict[str, str]

zacrostools.kmc_output.energy

Lattice energy (in eV·Å⁻²).

Type:

np.ndarray

zacrostools.kmc_output.final_energy

Final lattice energy (in eV·Å⁻²).

Type:

float

zacrostools.kmc_output.finaltime

Final simulated time (in seconds).

Type:

float

zacrostools.kmc_output.gas_specs_names

Gas species names.

Type:

List[str]

zacrostools.kmc_output.n_gas_species

Number of gas species.

Type:

int

zacrostools.kmc_output.n_sites

Total number of lattice sites.

Type:

int

zacrostools.kmc_output.n_surf_species

Number of surface species.

Type:

int

zacrostools.kmc_output.nevents

Number of events occurred.

Type:

np.ndarray

zacrostools.kmc_output.production

Gas species produced over time. Example: KMCOutput.production[‘CO’].

Type:

Dict[str, np.ndarray]

zacrostools.kmc_output.surf_specs_names

Surface species names.

Type:

List[str]

zacrostools.kmc_output.time

Simulated time (in seconds).

Type:

np.ndarray

zacrostools.kmc_output.tof

TOF (Turnover Frequency) of gas species (in molecules·s⁻¹·Å⁻²). Example: KMCOutput.tof[‘CO2’].

Type:

Dict[str, float]

zacrostools.kmc_output.total_coverage

Total coverage of surface species over time (in %).

Type:

np.ndarray

zacrostools.kmc_output.total_coverage_per_site_type

Total coverage of surface species per site type over time (in %). Example: KMCOutput.total_coverage_per_site_type[‘top’].

Type:

Dict[str, np.ndarray]

zacrostools.kmc_output.total_production

Total number of gas species produced. Example: KMCOutput.total_production[‘CO’].

Type:

Dict[str, float]

zacrostools.kmc_output.KMCOutput.get_selectivity(self, main_product: str, side_products: list)

Calculate the selectivity of the main product over side products.

Parameters:

  • main_product (str) – Name of the main product.

  • side_products (List[str]) – Names of the side products.

Returns:

The selectivity of the main product (in %) over the side products.

Return type:

float

Notes

The selectivity is calculated as:

selectivity = (TOF_main_product / (TOF_main_product + sum(TOF_side_products))) * 100

If the total TOF is zero, the selectivity is returned as NaN.