Welcome to the ZacrosTools documentation

ZacrosTools is a versatile toolkit designed to simplify the preparation and analysis of Kinetic Monte Carlo (KMC) simulations with Zacros.

Key features

• Automatize the creation of Zacros input files

• Perform scans over different pressures and temperatures

• Quickly read, analyze, and process Zacros output files

• Easily plot heatmaps from the simulation results

• Extensive documentation with detailed examples to help users get started

How to cite

If you use ZacrosTools in your research, please cite:

Prats, H. ZacrosTools: A Python Library for Automated Preparation, Analysis, and Visualization of Kinetic Monte Carlo Simulations with Zacros. J. Phys. Chem. A 2025, 129, 6608–6614. DOI: 10.1021/acs.jpca.5c02802

Installation

ZacrosTools is available on PyPI and can be installed using pip:

pip install zacrostools

Prerequisites:

• Python 3.8 or higher

• Scipy

• Pandas

Alternatively, the latest development version can be installed from GitHub as follows:

git clone https://github.com/hprats/ZacrosTools.git
cd ZacrosTools
pip install .

Recent changes

Version 2.11 — 2025-11-04

Changed

• Mode rename and new definition in dtof.py:

  • The former difference_type='relative' mode (which computed the ratio |TOF(main)/TOF(ref)|) has been renamed to difference_type='ratio'.

  • A new difference_type='relative' is introduced to compute the percent difference:
    ΔTOF_rel = (TOF(main) − TOF(ref)) / TOF(ref) × 100

Added

• New difference_type options in plot_dtime:

  • Added support for difference_type='ratio':
    Δt = t(main) / t(ref)

    • The colorbar is logarithmic, spanning [10⁻ᴺ, 10⁺ᴺ], and centered at 10⁰.

  • Added support for difference_type='speedup':

    • Uses the same ratio definition as above, but the colorbar spans [10⁰, 10⁺ᴺ], showing only values ≥ 1.

Full details are available in the ZacrosTools CHANGELOG.

What’s next

We plan to continue improving ZacrosTools with additional features, optimizations, and support for more advanced Zacros functionalities. Contributions are welcome!

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributors

• Hector Prats - hector.prats@tuwien.ac.at

Acknowledgements

• Zeyu Wu

Contents

• How to Cite
• 1. Creating the Gas Model
  • Properties
  • How to create it
  • Adding and removing species
  • Accessing gas-phase data
  • Full example
• 2. Creating the Energetics Model
  • Properties
  • How to create it
  • Adding and removing clusters
  • Writing the energetics_input.dat file
  • Accessing energetics data
  • Full example
• 3. Creating the Reaction Model
  • Properties
  • How to create it
  • Adding and removing steps
  • Writing the mechanism_input.dat file
  • Accessing reaction data
  • Full example
  • Fixing pre-exponential factors
• 4. Creating the Lattice Model
  • Allowed lattice types
  • How to create it
  • Repeating the LatticeModel
  • Removing a site
  • Changing the site type
  • Writing the lattice_input.dat file
  • Full example
• 5. Assembling the KMC Model and Writing the Input Files
  • Properties
  • How to create the KMC Model
  • Writing the input files
  • Looping over pressure and temperature values
• Reading output files
  • Extract data from a single simulation
  • Extract data from multiple simulations
• Plotting single simulation results
  • Surface coverage vs simulated time
  • Number of molecules produced
  • Event frequencies
  • Stiffness scaling coefficients
• Plotting heatmaps
  • Common parameters
  • TOF
  • TOF difference
  • Selectivity
  • Coverage
  • Phase diagram
  • Final time
  • Energy slope
  • Issues
  • Building a multi-panel figure
  • Customizing text sizes and colorbars