Welcome to the ZacrosTools documentation

This guide provides comprehensive information on using the ZacrosTools Python library.

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

Key features

Automatic input file generation: Easily create Zacros input files, reducing errors.
Output file parsing: Quickly read, analyze, and process Zacros output data.
Pressure and temperature scans: Streamline the process of performing scans over different pressures and temperatures.
Documentation and examples: Extensive documentation with detailed examples to help users get started and make full use of ZacrosTools.

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

These dependencies will be installed automatically with pip.

Installing from source

To install the latest development version from GitHub:

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

Quick start guide

Get started with ZacrosTools by following these steps:

Define the GasModel, the EnergeticsModel and the ReactionModel from a Python dictionary, a Pandas DataFrame, or a .csv file
Create a default or custom LatticeModel
Combine all previous models to create a KMCModel
Write the input files with KMCModel.create_job_dir() and run Zacros
Parse the results with KMCOutput and visualize the results with plot_functions to gain insights

Detailed instructions for each step are provided in the documentation sections below.

Documentation

The ZacrosTools documentation is organized into the following sections:

Gas model: Learn how to define the gas-phase molecular data.
Energetics model: Define all the terms used in the cluster expansion.
Reaction model: Specify the elementary steps included in the reaction mechanism.
Lattice model: Understand how to set up a lattice model.
Writing_input_files: Integrate all components into a KMC model and write the Zacros input files.
Reading output files: Parse and analyze data from Zacros output files.
Plotting single simulation results: Plot the simulation results, such as surface coverage, molecules produced, or event frequencies.
Plotting heatmaps: Draw heatmap plots from a set of KMC simulations at various operating conditions.
API reference: Detailed API documentation for ZacrosTools modules and classes.

Recent changes

[2.6] - 24-Sep-2025

Changed

Gas-phase molecule parameter update: the deprecated molecule parameter has been replaced by two explicit parameters, molecule_is and molecule_fs, which indicate the presence of gas-phase species in the initial or final state of a step, respectively. Using molecule will trigger a DeprecationWarning.

Added

Bidirectional gas-phase step support: ZacrosTools now accepts the definition of reaction steps involving gas-phase species in either direction (initial or final state). Previously, gas-phase species were only allowed in the initial state (adsorption).
Fixed pre-exponential option: Users can now fix the pre-exponential factor (pre_expon) and ratio (pe_ratio) of selected steps by providing fixed_pre_expon and fixed_pe_ratio dictionaries to ReactionModel.write_mechanism_input(). This bypasses automatic computation.
- Incompatible with stiffness_scalable_steps='all'.
- Incompatible with listing fixed steps in either stiffness_scalable_steps or stiffness_scalable_symmetric_steps.

[2.5] - 30-Jul-2025

Added

Additional keywords support: added an additional_keywords parameter to KMCModel.create_job_dir and write_simulation_input to append additional Zacros keywords to simulation_input.dat.
sign parameter for ∆time heatmaps: introduced a sign argument in plot_dtime ('both', 'positive', or 'negative') to filter ∆time values by sign.
Issue masking in ∆TOF heatmaps: added a check_issues parameter to plot_dtof ('none', 'both', 'main', or 'ref') to mask cells flagged by detect_issues.
Unspecified state support: EnergeticsModel now accepts the & & & placeholder in lattice_state definitions to represent unspecified site states.
Multidentate species support: EnergeticsModel handles adsorbates multidentate surface species occupying multiple site types.

Changed

Surface species name parsing: removed the requirement that species names end with *. Surface species names now stay exactly as typed by the user (i.e. no removal of * at the end).

Fixed

parse_general_output_file crash: fixed a bug that caused a crash when an initial state is provided.
∆TOF docstring & title logic: corrected the relative ∆TOF formula in plot_dtof’s docstring.

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!

Report bugs: Use the issue tracker to report bugs.
Request features: Suggest new features or improvements.
Submit pull requests: Fork the repository and submit pull requests for your contributions.

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