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.

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

pip install zacrostools

These dependencies will be installed automatically with pip.

To install the latest development version from GitHub:

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

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.

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.

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.

Analysis of output files:
- Renamed window_percent to analysis_range
- Renamed window_type to range_type

Full details are available in the ZacrosTools CHANGELOG.

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.

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

Contents