5. Assembling the KMC Model and Writing the Input Files

The KMCModel class represents the complete KMC simulation model for Zacros.

Properties

1. GasModel: Contains gas-phase species definitions, including their molecular weights and energies.

2. ReactionModel: Details elementary reaction steps, including initial/final states, activation energies, and vibrational energies.

3. EnergeticsModel: Lists clusters and their energies, reflecting the cluster expansion used for energy calculations.

4. LatticeModel: Describes the lattice structure, site types, and spatial arrangement of sites.

How to create the KMC Model

Create it in the same way as shown in the example below.

from zacrostools.kmc_model import KMCModel
from zacrostools.gas_model import GasModel
from zacrostools.reaction_model import ReactionModel
from zacrostools.energetics_model import EnergeticsModel
from zacrostools.lattice_model import LatticeModel

# Assume you have already prepared these data files
gas_model = GasModel.from_csv('gas_data.csv')
reaction_model = ReactionModel.from_csv('mechanism_data.csv')
energetics_model = EnergeticsModel.from_csv('energetics_data.csv')

# Define a lattice model
lattice_model = LatticeModel(
    lattice_type='periodic_cell',
    cell_vectors=((3.27, 0), (0, 3.27)),
    sites={'tC': (0.25, 0.25), 'tM': (0.75, 0.75)},
    copies=[10, 10],
    neighboring_structure='from_distances',
    max_distances={'tC-tC': 4.0, 'tC-tM': 4.0, 'tM-tM': 4.0},
)

# Create the KMCModel instance, integrating all components
kmc_model = KMCModel(
    gas_model=gas_model,
    reaction_model=reaction_model,
    energetics_model=energetics_model,
    lattice_model=lattice_model
)

---

Writing the input files

Once the KMCModel is created, you can generate the Zacros input files by calling the create_job_dir method.

Required parameters:

• job_path (str): Directory where the input files will be written.

• temperature (float or int): Simulation temperature in Kelvin.

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

• reporting_scheme (dict, optional): Controls how often Zacros writes snapshots, process statistics, and species counts.

• stopping_criteria (dict, optional): Conditions to end the simulation (max steps, max time, wall time).

• manual_scaling (dict, optional): Apply scaling factors to specific reaction steps.

• stiffness_scaling_algorithm (str, optional): Algorithm for handling stiffness scaling ('legacy' or 'prats2024').

• stiffness_scalable_steps (list of str, 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.

• stiffness_scalable_symmetric_steps: (list of str, optional): Steps that will be marked as 'stiffness_scalable_symmetric' in mechanism_input.dat

• stiffness_scaling_tags (dict, optional): Parameters controlling the dynamic scaling algorithm.

• sig_figs_energies (int, optional): Significant figures for energies written to input files.

• sig_figs_pe (int, optional): Significant figures for pre-exponential factors.

• sig_figs_lattice (int, optional): Significant figures for coordinates.

• random_seed (int, optional): Seed for Zacros’s random number generator.

• 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). Default is 5.0.

kmc_model.create_job_dir(
    job_path='kmc_simulation',
    temperature=1000.0,
    pressure={'CO': 1.0, 'O2': 0.001, 'CO2': 0.0},
    reporting_scheme={
      'snapshots': 'on event 10000', 
      'process_statistics': 'on event 10000', 
      'species_numbers': 'on event 10000'},
    stopping_criteria={
      'max_steps': 'infinity', 
      'max_time': 'infinity', 
      'wall_time': 86400},
    manual_scaling={
      'CO_diffusion': 1.0e-1, 
      'O_diffusion': 1.0e-2},
    stiffness_scaling_algorithm=None,
    sig_figs_energies=8,
    sig_figs_pe=8,
)

The specified directory (kmc_simulation) will be created, containing all four Zacros input files.

Looping over pressure and temperature values

for temperature in [600, 700, 800]: # in K
    for pCO in [0.01, 0.1, 1.0, 10]:  # in bar
        for pO2 in [0.01, 0.1, 1.0, 10]:  # in bar
            kmc_model.create_job_dir(
                job_path=f'temp_{temperature}K_pCO_{pCO}bar_pO2_{pO2}bar',
                temperature=temperature,
                pressure={'CO': pCO, 'O2': pO2, 'CO2': 0.0},
                reporting_scheme={
                    'snapshots': 'on event 100000',
                    'process_statistics': 'on event 100000',
                    'species_numbers': 'on event 100000'},
                stopping_criteria={
                    'max_steps': 'infinity',
                    'max_time': 5.0e+06,
                    'wall_time': 250000}
            )

---