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:

1. Define the GasModel, the EnergeticsModel and the ReactionModel from a Python dictionary, a Pandas DataFrame, or a .csv file

2. Create a default or custom LatticeModel

3. Combine all previous models to create a KMCModel

4. Write the input files with KMCModel.create_job_dir() and run Zacros

5. 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.2] 20-Dec-2024

Added

• Plot event frequencies: introduced the ability to parse the event frequencies from procstat_output.txt using zacrostools.procstat_output and visualize them.

• Plot stiffness coefficients: added functionality to parse stiffness coefficient information from general_output.txt using zacrostools.parse_general_output_file and generate corresponding plots.

• Examples:

  • DRM_on_PtHfC: Demonstrates how to analyze hundreds of output files to generate heatmaps and plot the event frequencies and stiffness coefficients.

  • custom_lattice_models: Illustrates how to create custom lattice models for Zacros simulations.

Changed

• Analysis of output files:

  • Renamed window_percent to analysis_range

  • Renamed window_type to range_type

Improved

• Documentation: Improved the ZacrosTools Documentation.

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

• Installation
  • Table of Contents
  • Prerequisites
  • Installation via pip
  • Installing from Source
• Gas model
  • Overview
  • Creating a GasModel
  • Adding and removing species
  • Accessing gas-phase data
  • Full example
  • Next steps
• Energetics model
  • Overview
  • Creating an EnergeticsModel
  • Adding and removing clusters
  • Writing the energetics_input.dat file
  • Accessing energetics data
  • Full example
  • Next steps
• Reaction model
  • Overview
  • Creating a ReactionModel
  • Adding and removing steps
  • Writing the mechanism_input.dat file
  • Accessing reaction data
  • Full example
  • Next Steps
• Lattice model
  • Overview
  • Creating a LatticeModel
  • Methods for modifying the lattice
  • Writing the lattice_input.dat file
  • Full example
  • Next steps
• Writing input files
  • Creating a KMCModel
  • Writing the input files
  • Next steps
• Reading output files
  • Overview
  • Creating a KMCOutput object
  • Accessing simulation data
  • Methods
  • Examples of usage
• Plotting single simulation results
  • Surface coverage
  • Number of molecules produced
  • Event frequencies
  • Stiffness scaling coefficients
• Plotting heatmaps
  • Parameters
  • Heatmap types
  • Figure with multiple heatmaps
  • Customization
• API Reference
  • KMCModel()
  • create_job_dir()
  • LatticeModel()
  • KMCOutput()
  • area
  • av_coverage
  • av_coverage_per_site_type
  • av_energy
  • av_total_coverage
  • av_total_coverage_per_site_type
  • coverage
  • coverage_per_site_type
  • cpu_time
  • dominant_ads
  • dominant_ads_per_site_type
  • energy
  • final_energy
  • finaltime
  • gas_specs_names
  • n_gas_species
  • n_sites
  • n_surf_species
  • nevents
  • production
  • surf_specs_names
  • time
  • tof
  • total_coverage
  • total_coverage_per_site_type
  • total_production
  • get_selectivity()