ZacrosTools

https://zacrostools.readthedocs.io/en/latest/
Admin
ZacrosTools is a versatile toolkit designed to simplify the preparation and analysis of Kinetic...
Tokens:53,949
Snippets:277
Trust Score:9.6
Update:6 days ago
Show doc for...
Tokens:
Raw
### Install latest development version from GitHub

Source: https://zacrostools.readthedocs.io/en/latest/index.html

Clone the repository and install the latest development version. Use this to get unreleased features and fixes.

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

```

--------------------------------

### Full example: create and modify a ReactionModel

Source: https://zacrostools.readthedocs.io/en/latest/_sources/reaction_model.md.txt

Complete example demonstrating creation of a ReactionModel from a dictionary, adding a step, removing a step, writing the mechanism input file, and accessing the DataFrame.

```python
from zacrostools.reaction_model import ReactionModel
from zacrostools.gas_model import GasModel

# Assume gas_model is already defined
gas_model = GasModel.from_csv('gas_data.csv')

# Initial reaction steps data
steps_data = {
    'CO_adsorption': {
        'activ_eng': 0.0,
        'area_site': 5.34,
        'initial': ['1 * 1'],
        'final': ['1 CO* 1'],
        'molecule_is': 'CO',
        'prox_factor': 0.0,
        'site_types': 'top',
        'vib_energies_is': [263.427],
        'vib_energies_fs': [240.497, 82.738, 60.132, 60.080, 7.271, 6.553],
    }
}

# Create the ReactionModel instance
reaction_model = ReactionModel.from_dict(steps_data)

# Add a new step
reaction_model.add_step(step_info={
        'step_name': 'CO_diffusion',
        'activ_eng': 1.156,
        'initial': ['1 CO* 1', '2 * 1'],
        'final': ['1 * 1', '2 CO* 1'],
        'neighboring': '1-2',
        'graph_multiplicity': 2.0,
        'site_types': 'top top',
        'vib_energies_is': [240.497, 82.738, 60.133, 60.080, 7.272, 6.553],
        'vib_energies_ts': [218.382, 53.527, 47.612, 28.580, 6.600],
        'vib_energies_fs': [240.497, 82.738, 60.133, 60.080, 7.272, 6.553],
    })


# Remove an existing step
reaction_model.remove_steps(['CO_diffusion'])

# Write the mechanism input file
reaction_model.write_mechanism_input(
    output_dir='kmc_simulation',
    temperature=500,
    gas_model=gas_model,
    sig_figs_energies=8,
    sig_figs_pe=8
)

# Access the DataFrame
print(reaction_model.df)
```

--------------------------------

### Full example of GasModel creation and modification

Source: https://zacrostools.readthedocs.io/en/latest/gas_model.html

Complete example demonstrating creation of a GasModel from a dictionary, adding a species, removing a species, and accessing the DataFrame.

```python
from zacrostools.gas_model import GasModel

# Initial gas species data
species_data = {
    'CO': {
        'type': 'linear',
        'gas_molec_weight': 28.01,
        'sym_number': 1,
        'degeneracy': 1,
        'inertia_moments': [8.973],
        'gas_energy': 1.9544267
    },
    'O2': {
        'type': 'linear',
        'gas_molec_weight': 32.00,
        'sym_number': 2,
        'degeneracy': 3,
        'inertia_moments': [12.178],
        'gas_energy': 2.6131292
    }
}

# Create the GasModel instance
gas_model = GasModel.from_dict(species_data)

# Add a new species
gas_model.add_species(species_info={
    'species_name': 'CO2',
    'type': 'linear',
    'gas_molec_weight': 44.01,
    'sym_number': 2,
    'degeneracy': 1,
    'inertia_moments': [44.317],
    'gas_energy': 0.00
})

# Remove an existing species
gas_model.remove_species(['O2'])

# Access the DataFrame
print(gas_model.df)
```

--------------------------------

### Install ZacrosTools via pip

Source: https://zacrostools.readthedocs.io/en/latest/index.html

Install the stable release of ZacrosTools from PyPI. Requires Python 3.8 or higher, Scipy, and Pandas.

```bash
pip install zacrostools

```

--------------------------------

### Read single simulation output with KMCOutput

Source: https://zacrostools.readthedocs.io/en/latest/_sources/reading_output_files.md.txt

Example of using KMCOutput to read a simulation output, print TOF of gas-phase species, compute selectivity of CH4, and print average coverages.

```python
from zacrostools.kmc_output import KMCOutput

# Read simulation output
kmc_output = KMCOutput(
    path='temp_600K',
    analysis_range=[50, 100],
    range_type='time',
    weights='time')

# Print TOF of all gas-phase species
for gas_spec in kmc_output.gas_specs_names:
    tof = kmc_output.tof[gas_spec]
    print(f"{gas_spec}: {tof:.3e} molec·s⁻¹·Å⁻²")

# Compute selectivity of CH4 vs CO2 and CH3OH
select_ch4 = kmc_output.get_selectivity(
    main_product='CH4',
    side_products=['CO2', 'CH3OH'])
print(f"Selectivity of CH4: {select_ch4:.2f}%")

# Print average coverage of all surface species
for surf_spec in kmc_output.surf_specs_names:
    avg_cov = kmc_output.av_coverage[surf_spec]
    print(f"{surf_spec}: {avg_cov:.2f}%")
```

--------------------------------

### Create ReactionModel from dictionary with ReactionModel.from_dict

Source: https://zacrostools.readthedocs.io/en/latest/reaction_model.html

Builds a ReactionModel from a Python dictionary where each key is a cluster name and each value is a dictionary of elementary step properties. The example defines four steps: CO_adsorption, O2_adsorption, CO+O_to_CO2, and CO2_adsorption, with properties such as activ_eng, area_site, initial/final site lists, and vibrational energies. The comment on CO2_adsorption recommends defining the forward direction as the adsorption.

```python
from zacrostools.reaction_model import ReactionModel

steps_data = {
    'CO_adsorption': {
        'activ_eng': 0.0,
        'area_site': 5.34,
        'initial': ['1 * 1'],
        'final': ['1 CO* 1'],
        'molecule_is': 'CO',
        'prox_factor': 0.0,
        'site_types': 'top',
        'vib_energies_is': [263.427],
        'vib_energies_fs': [240.497, 82.738, 60.132, 60.080, 7.271, 6.553],
    },
    'O2_adsorption': {
        'activ_eng': 0.742,
        'area_site': 5.34,
        'initial': ['1 * 1, 2 * 1'],
        'final': ['1 O* 1, 2 O* 1'],
        'neighboring': '1-2',
        'molecule_is': 'O2',
        'prox_factor': 0.5,
        'site_types': 'top',
        'vib_energies_is': [263.427],
        'vib_energies_ts': [244.692, 81.168, 53.342, 30.084, 2.234],
        'vib_energies_fs': [240.497, 82.738, 60.132, 60.080, 7.271, 6.553],
    }, 
    'CO+O_to_CO2': {
        'activ_eng': 1.693,
        'initial': ['1 CO* 1', '2 O* 1'],
        'final': ['1 CO2* 1', '2 * 1'],
        'neighboring': '1-2',
        'site_types': 'top top',
        'vib_energies_is': [171.188, 145.669, 96.964, 86.255, 56.201, 52.376, 35.933, 24.343, 21.025],
        'vib_energies_ts': [217.941, 81.362, 66.833, 56.918, 50.342, 37.430, 19.074, 12.356],
        'vib_energies_fs': [240.497, 82.738, 60.133, 60.080, 7.272, 6.553, 78.662, 40.796, 40.349],
    },
    'CO2_adsorption': {  # recommended to define the forward direction as the adsorption
        'activ_eng': 0.0,
        'area_site': 5.34,
        'initial': ['1 * 1'],
        'final': ['1 CO2* 1'],
        'molecule_is': 'CO2',
        'prox_factor': 0.0,
        'site_types': 'top',
        'vib_energies_is': [293.279, 163.686, 78.019, 77.959],
        'vib_energies_fs': [171.188, 145.668, 96.961, 86.214, 56.201, 52.375, 35.932, 24.343, 21.022],
    }
}

reaction_model = ReactionModel.from_dict(steps_data)

```

--------------------------------

### Full EnergeticsModel creation and modification example

Source: https://zacrostools.readthedocs.io/en/latest/_sources/energetics_model.md.txt

Complete workflow showing creation of an EnergeticsModel from a dictionary, adding a cluster, removing a cluster, writing the energetics input file, and accessing the internal DataFrame. Use this as a template for typical model modification tasks.

```python
from zacrostools.energetics_model import EnergeticsModel

# Initial cluster data
clusters_data = {
    'CO_point': {
        'cluster_eng': 0.230,
        'site_types': 'top',
        'lattice_state': ['1 CO* 1']
    },
    'O_point': {
        'cluster_eng': -1.326,
        'site_types': 'top',
        'lattice_state': ['1 O* 1']
    }
}

# Create the EnergeticsModel instance
energetics_model = EnergeticsModel.from_dict(clusters_data)

# Add a new cluster
energetics_model.add_cluster(cluster_info={
    'cluster_name': 'CO2_point',
    'cluster_eng': -1.571,
    'site_types': 'top',
    'lattice_state': ['1 CO2* 1']
})

# Remove an existing cluster
energetics_model.remove_clusters(['O_point'])

# Write the energetics input file
energetics_model.write_energetics_input(output_dir='kmc_simulation')

# Access the DataFrame
print(energetics_model.df)
```

--------------------------------

### Read KMC output and compute selectivity

Source: https://zacrostools.readthedocs.io/en/latest/reading_output_files.html

Example of using KMCOutput to read a single simulation, print TOFs, compute selectivity with get_selectivity(), and print average coverages. Requires the zacrostools package and a simulation output in the specified path.

```python
from zacrostools.kmc_output import KMCOutput

# Read simulation output
kmc_output = KMCOutput(
    path='temp_600K',
    analysis_range=[50, 100],
    range_type='time',
    weights='time')

# Print TOF of all gas-phase species
for gas_spec in kmc_output.gas_specs_names:
    tof = kmc_output.tof[gas_spec]
    print(f"{gas_spec}: {tof:.3e} molec·s⁻¹·Å⁻²")

# Compute selectivity of CH4 vs CO2 and CH3OH
select_ch4 = kmc_output.get_selectivity(
    main_product='CH4',
    side_products=['CO2', 'CH3OH'])
print(f"Selectivity of CH4: {select_ch4:.2f}%")

# Print average coverage of all surface species
for surf_spec in kmc_output.surf_specs_names:
    avg_cov = kmc_output.av_coverage[surf_spec]
    print(f"{surf_spec}: {avg_cov:.2f}%")


```

--------------------------------

### Create ReactionModel from dictionary with step properties

Source: https://zacrostools.readthedocs.io/en/latest/_sources/reaction_model.md.txt

Builds a ReactionModel from a dictionary where each key is a cluster name and each value is a dictionary of elementary step properties. The example defines four steps (CO adsorption, O2 adsorption, CO+O to CO2, and CO2 adsorption) with activation energies, vibrational energies, site types, and optional fields like neighboring and prox_factor. Note the deprecation of the old 'molecule' column, which is treated as 'molecule_is' with a warning.

```python
from zacrostools.reaction_model import ReactionModel

steps_data = {
    'CO_adsorption': {
        'activ_eng': 0.0,
        'area_site': 5.34,
        'initial': ['1 * 1'],
        'final': ['1 CO* 1'],
        'molecule_is': 'CO',
        'prox_factor': 0.0,
        'site_types': 'top',
        'vib_energies_is': [263.427],
        'vib_energies_fs': [240.497, 82.738, 60.132, 60.080, 7.271, 6.553],
    },
    'O2_adsorption': {
        'activ_eng': 0.742,
        'area_site': 5.34,
        'initial': ['1 * 1, 2 * 1'],
        'final': ['1 O* 1, 2 O* 1'],
        'neighboring': '1-2',
        'molecule_is': 'O2',
        'prox_factor': 0.5,
        'site_types': 'top',
        'vib_energies_is': [263.427],
        'vib_energies_ts': [244.692, 81.168, 53.342, 30.084, 2.234],
        'vib_energies_fs': [240.497, 82.738, 60.132, 60.080, 7.271, 6.553],
    }, 
    'CO+O_to_CO2': {
        'activ_eng': 1.693,
        'initial': ['1 CO* 1', '2 O* 1'],
        'final': ['1 CO2* 1', '2 * 1'],
        'neighboring': '1-2',
        'site_types': 'top top',
        'vib_energies_is': [171.188, 145.669, 96.964, 86.255, 56.201, 52.376, 35.933, 24.343, 21.025],
        'vib_energies_ts': [217.941, 81.362, 66.833, 56.918, 50.342, 37.430, 19.074, 12.356],
        'vib_energies_fs': [240.497, 82.738, 60.133, 60.080, 7.272, 6.553, 78.662, 40.796, 40.349],
    },
    'CO2_adsorption': {  # recommended to define the forward direction as the adsorption
        'activ_eng': 0.0,
        'area_site': 5.34,
        'initial': ['1 * 1'],
        'final': ['1 CO2* 1'],
        'molecule_is': 'CO2',
        'prox_factor': 0.0,
        'site_types': 'top',
        'vib_energies_is': [293.279, 163.686, 78.019, 77.959],
        'vib_energies_fs': [171.188, 145.668, 96.961, 86.214, 56.201, 52.375, 35.932, 24.343, 21.022],
    }
}

reaction_model = ReactionModel.from_dict(steps_data)
```

--------------------------------

### Create GasModel from dictionary using GasModel.from_dict

Source: https://zacrostools.readthedocs.io/en/latest/gas_model.html

Creates a GasModel instance from a dictionary where each key is a species name and each value is a dictionary of properties. The example includes species data for CO, O2, and CO2.

```python
from zacrostools.gas_model import GasModel

species_data = {
    'CO': {
        'type': 'linear',
        'gas_molec_weight': 28.01,
        'sym_number': 1,
        'degeneracy': 1,
        'inertia_moments': [8.973],
        'gas_energy': 1.954
    },
    'O2': {
        'type': 'linear',
        'gas_molec_weight': 32.00,
        'sym_number': 2,
        'degeneracy': 3,
        'inertia_moments': [12.178],
        'gas_energy': 2.613
    },
    'CO2': {
        'type': 'linear',
        'gas_molec_weight': 44.01,
        'sym_number': 2,
        'degeneracy': 1,
        'inertia_moments': [44.317],
        'gas_energy': 0.00
    }
}

gas_model = GasModel.from_dict(species_data)
```

--------------------------------

### Full LatticeModel example for Pt4/HfC

Source: https://zacrostools.readthedocs.io/en/latest/_sources/lattice_model.md.txt

Creates a lattice model for a Pt4 cluster on HfC(001). Shows creating a periodic_cell LatticeModel, repeating, changing site types, removing a site, setting copies, and writing the output file.

```python
from zacrostools.lattice_model import LatticeModel

# Create a unit cell for PtHfC unit cell from a 4x4 cell of HfC
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, 'Pt-Pt': 4.0, 'Pt-tC': 4.0, 'Pt-tM': 4.0},
)
lattice_model.repeat_lattice_model(4, 4)

# Replace four tC sites by Pt sites
for coordinates in [(0.3125, 0.3125), (0.3125, 0.5625), (0.5625, 0.3125), (0.5625, 0.5625)]:
    lattice_model.change_site_type(direct_coords=coordinates, new_site_type='Pt') 

# Remove the tM site in the middle of the four Pt sites
lattice_model.remove_site(direct_coords=(0.4375, 0.4375)) 

# Define the number of copies of the unit cell for the simulation
lattice_model.copies = [3, 3]

# Write the lattice_input.dat file in a folder named 'PtHfC'
lattice_model.write_lattice_input(output_dir='PtHfC')
```

--------------------------------

### Create KMCOutput object with analysis range and time-weighted averaging

Source: https://zacrostools.readthedocs.io/en/latest/_sources/reading_output_files.md.txt

Instantiate a KMCOutput object to load Zacros output files from a directory. The example sets analysis_range to [50, 100] to consider the last 50% of the simulation time and applies time-weighted averaging via weights='time'.

```python
from zacrostools.kmc_output import KMCOutput

# Here, we consider the last 50% of the simulation time and apply time-weighted averaging.
kmc_output = KMCOutput(path='/path/to/simulation_files', analysis_range=[50, 100], range_type='time', weights='time')
```

--------------------------------

### Create GasModel from Pandas DataFrame using GasModel.from_df

Source: https://zacrostools.readthedocs.io/en/latest/gas_model.html

Creates a GasModel instance from a Pandas DataFrame. The example reads the CSV file into a DataFrame, but a DataFrame can also be created directly.

```python
import pandas as pd
from zacrostools.gas_model import GasModel

df = pd.read_csv("gas_data.csv")  # or create dataframe directly
gas_model = GasModel.from_df(df)
```

--------------------------------

### Create a 4x3 multi-panel heatmap figure with ZacrosTools

Source: https://zacrostools.readthedocs.io/en/latest/_sources/plotting_heatmaps.md.txt

Combines TOF, coverage, phase diagram, selectivity, final time, and differential TOF heatmaps into a single figure. Uses a common scan path and analysis range. The example hides intermediate axis labels and saves the figure as 'multiple_heatmaps.png'.

```python
import numpy as np
import matplotlib.pyplot as plt
from zacrostools.heatmaps.tof import plot_tof
from zacrostools.heatmaps.dtof import plot_dtof
from zacrostools.heatmaps.selectivity import plot_selectivity
from zacrostools.heatmaps.coverage import plot_coverage
from zacrostools.heatmaps.phasediagram import plot_phasediagram
from zacrostools.heatmaps.finaltime import plot_finaltime

# Plot parameters
scan_path = 'simulation_results'
x_variable = 'pressure_CH4'
y_variable = 'pressure_CO2'

analysis_range = [50, 100]      # Ignore first 50 % of total simulated time (equilibration)
range_type = 'time'
weights = 'time'

min_molec_tof = 0               # For TOF and selectivity
min_molec_selectivity = 100     # For TOF and selectivity
min_coverage = 50               # (in %) To plot phase diagrams

auto_title = True
show_points = False
show_colorbar = True

# Define labels for phase diagram heatmaps
tick_labels = { 
    '$CH_{x}$': ['CH3*', 'CH3_Pt*', 'CH2*', 'CH2_Pt*', 'CH*', 'CH_Pt*', 'C*', 'C_Pt*'],
    '$CHO/COH$': ['CHO*', 'CHO_Pt*', 'COH*', 'COH_Pt*'],
    '$CO$': ['CO*', 'CO_Pt*'],
    '$COOH$': ['COOH*', 'COOH_Pt*'],
    '$CO_{2}$': ['CO2*', 'CO2_Pt*'],
    '$H$': ['H*', 'H_Pt*'],
    '$H_{2}O$': ['H2O*', 'H2O_Pt*'],
    '$OH$': ['OH*', 'OH_Pt*'],
    '$O$': ['O*', 'O_Pt*'],
}

fig, axs = plt.subplots(4, 3, figsize=(8.8, 8), sharey='row', sharex='col')

for n, product in enumerate(['CO', 'H2', 'H2O']):
    plot_tof(
        ax=axs[0, n], scan_path=scan_path, x=x_variable, y=y_variable,
        gas_spec=product, min_molec=min_molec_tof,
        analysis_range=analysis_range, range_type=range_type, levels=np.logspace(-1, 4, num=11),
        auto_title=auto_title, show_points=show_points, show_colorbar=show_colorbar)

for n, site_type in enumerate(['tC', 'tM', 'Pt']):
    plot_coverage(
        ax=axs[1, n], scan_path=scan_path, x=x_variable, y=y_variable,
        surf_spec='all', site_type=site_type,
        analysis_range=analysis_range, range_type=range_type, weights=weights,
        auto_title=auto_title, show_points=show_points, show_colorbar=show_colorbar)

for n, site_type in enumerate(['tC', 'tM', 'Pt']):
    plot_phasediagram(
        ax=axs[2, n], scan_path=scan_path, x=x_variable, y=y_variable,
        min_coverage=min_coverage, site_type=site_type, tick_labels=tick_labels,
        analysis_range=analysis_range, range_type=range_type, weights=weights,
        auto_title=auto_title, show_points=show_points, show_colorbar=show_colorbar)

plot_selectivity(
    ax=axs[3, 0], scan_path=scan_path, x=x_variable, y=y_variable,
    main_product='H2', side_products=['H2O'], min_molec=min_molec_selectivity,
    analysis_range=analysis_range, range_type=range_type,
    auto_title=auto_title, show_points=show_points, show_colorbar=show_colorbar)

plot_finaltime(
    ax=axs[3, 1], scan_path=scan_path, x=x_variable, y=y_variable,
    levels=np.logspace(-7, 7, num=15), auto_title=auto_title, show_points=show_points, show_colorbar=show_colorbar)

plot_dtof(
    ax=axs[3, 2], scan_path=scan_path, x=x_variable, y=y_variable,
    scan_path_ref='simulation_results_reference', gas_spec='H2', min_molec=0, levels=np.logspace(-1, 4, num=11),
    analysis_range=analysis_range, range_type=range_type,
    auto_title=auto_title, show_points=show_points, show_colorbar=show_colorbar)

# Hide axis labels of intermediate subplots
for i in range(3):
    for j in range(3):
        axs[i, j].set_xlabel('')
for i in range(3):
    for j in range(1, 3):
        axs[i, j].set_ylabel('')

plt.tight_layout()
plt.savefig('multiple_heatmaps.png', dpi=300, bbox_inches='tight', transparent=False)
plt.show()

```

--------------------------------

### Create KMCModel instance from data files

Source: https://zacrostools.readthedocs.io/en/latest/_sources/writing_input_files.md.txt

Imports the required classes and creates a KMCModel by loading gas, reaction, and energetics models from CSV files and defining a lattice model with a periodic cell, two site types, and neighbor distances.

```python
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
)
```

--------------------------------

### plot_phasediagram

Source: https://zacrostools.readthedocs.io/en/latest/plotting_heatmaps.html

Documentation for the plot_phasediagram function, including its parameters and a usage example.

```APIDOC
## plot_phasediagram

### Description
Plots a phase diagram heatmap based on simulation results. It identifies dominant surface species based on coverage thresholds and can group species into colorbar tick labels.

### Parameters
- **ax** (matplotlib.axes.Axes) - Required - The axes on which to plot.
- **scan_path** (str) - Required - Path to the directory containing simulation results.
- **x** (str) - Required - The x-axis variable (e.g., 'pressure_CH4').
- **y** (str) - Required - The y-axis variable (e.g., 'pressure_CO2').
- **site_type** (str, optional) - Site type to consider (default = 'StTp1').
- **min_coverage** (float or int, optional) - Minimum total coverage (%) to consider a dominant species (default = 50.0).
- **tick_labels** (dict or None, optional) - Mapping of colorbar tick labels to lists of surface species.
- **analysis_range** (list, optional) - Range for analysis (e.g., [50, 100]).
- **range_type** (str, optional) - Type of range (e.g., 'time').
- **weights** (str, optional) - Weighting scheme (e.g., 'time').
- **auto_title** (bool, optional) - Whether to automatically generate a title.
- **show_points** (bool, optional) - Whether to show data points.
- **show_colorbar** (bool, optional) - Whether to show the colorbar.

### Example
```python
import matplotlib.pyplot as plt
from zacrostools.heatmaps.phasediagram import plot_phasediagram

fig, axs = plt.subplots(1, figsize=(4.3, 3.5))
tick_labels = {
    '$CH_{x}$': ['CH3*', 'CH3_Pt*', 'CH2*', 'CH2_Pt*', 'CH*', 'CH_Pt*', 'C*', 'C_Pt*'],
    '$CHO/COH$': ['CHO*', 'CHO_Pt*', 'COH*', 'COH_Pt*'],
    '$CO$': ['CO*', 'CO_Pt*'],
    '$COOH$': ['COOH*', 'COOH_Pt*'],
    '$CO_{2}$': ['CO2*', 'CO2_Pt*'],
    '$H$': ['H*', 'H_Pt*'],
    '$H_{2}O$': ['H2O*', 'H2O_Pt*'],
    '$OH$': ['OH*', 'OH_Pt*'],
    '$O$': ['O*', 'O_Pt*'],
}
plot_phasediagram(
    ax=axs,
    scan_path='simulation_results',
    x='pressure_CH4',
    y='pressure_CO2',
    min_coverage=50.0,
    site_type='tC',
    tick_labels=tick_labels,
    analysis_range=[50, 100],
    range_type='time',
    weights='time',
    auto_title=True,
    show_points=False,
    show_colorbar=True
)
plt.tight_layout()
plt.savefig('phasediagram_heatmap.png', dpi=300, bbox_inches='tight', transparent=False)
plt.show()
```
```

--------------------------------

### Remove species using GasModel.remove_species

Source: https://zacrostools.readthedocs.io/en/latest/gas_model.html

Removes species from the GasModel by name using the remove_species method. The example removes the species 'CO2'.

```python
gas_model.remove_species(['CO2'])
```

--------------------------------

### Read multiple simulations with read_scan

Source: https://zacrostools.readthedocs.io/en/latest/_sources/reading_output_files.md.txt

Example of using read_scan to read results from all KMC simulations in a scan directory and save them to a CSV file.

```python
from zacrostools.read_scan import read_scan

data_scan = read_scan(
    scan_path='path_to_scan',
    analysis_range=[50, 100],
    range_type='time')
data_scan.to_csv('data_scan.csv', index=True)
```

--------------------------------

### LatticeModel constructor

Source: https://zacrostools.readthedocs.io/en/latest/_sources/lattice_model.md.txt

Creates a LatticeModel instance with specified lattice type, cell vectors, sites, copies, and neighboring structure. Used in the full example.

```APIDOC
## LatticeModel constructor

### Description
Creates a `LatticeModel` instance with the given parameters.

### Method
LatticeModel

### Parameters
- **lattice_type** (`str`) - Required - Type of lattice (e.g., 'periodic_cell').
- **cell_vectors** (`tuple`) - Required - Cell vectors as a tuple of tuples.
- **sites** (`dict`) - Required - Dictionary mapping site types to coordinates.
- **copies** (`list`) - Required - Number of copies of the unit cell.
- **neighboring_structure** (`str`) - Required - Method for determining neighboring structure (e.g., 'from_distances').
- **max_distances** (`dict`) - Required - Dictionary of maximum distances between site types.

### Example
```python
from zacrostools.lattice_model import LatticeModel

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, 'Pt-Pt': 4.0, 'Pt-tC': 4.0, 'Pt-tM': 4.0},
)
```
```

--------------------------------

### ReactionModel with fixed pre-exponential factor and ratio

Source: https://zacrostools.readthedocs.io/en/latest/_sources/reaction_model.md.txt

Shows how to create a ReactionModel with user-specified `fixed_pre_expon` and `fixed_pe_ratio` in the reaction data dictionary. Both parameters must be provided together, and using them is incompatible with `stiffness_scalable_steps="all"`, or including a fixed step in `stiffness_scalable_steps` or `stiffness_scalable_symmetric_steps`, otherwise a `ReactionModelError` is raised.

```python
from zacrostools.reaction_model import ReactionModel

reaction_data = {
    'CO_adsorption': {
        'activ_eng': 0.0,
        'area_site': 5.34,
        'initial': ['1 * 1'],
        'final': ['1 CO* 1'],
        'molecule_is': 'CO',
        'prox_factor': 0.0,
        'site_types': 'top',
        'vib_energies_is': [263.427],
        'vib_energies_fs': [240.497, 82.738, 60.132, 60.080, 7.271, 6.553],
        "fixed_pre_expon": 1.0e13,  # in s^-1 or bar^-1·s^-1 depending on type
        "fixed_pe_ratio": 2.5
    },
}

reaction_model = ReactionModel.from_dict(reaction_data)
```

--------------------------------

### Loop over temperature and pressure values to create KMC job directories

Source: https://zacrostools.readthedocs.io/en/latest/_sources/writing_input_files.md.txt

Use this loop to generate job directories for each combination of temperature (600, 700, 800 K) and partial pressures of CO and O2 (0.01, 0.1, 1.0, 10 bar). The create_job_dir call sets the job path, temperature, pressure dictionary, reporting scheme, and stopping criteria. The stopping criteria include max_steps as 'infinity', max_time of 5.0e+06, and wall_time of 250000.

```python
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}
            )
```

--------------------------------

### KMCModel constructor

Source: https://zacrostools.readthedocs.io/en/latest/_sources/writing_input_files.md.txt

Creates a KMCModel instance by combining gas, reaction, energetics, and lattice models. This is the first step in setting up a KMC simulation.

```APIDOC
## KMCModel(gas_model, reaction_model, energetics_model, lattice_model)

### Description
Creates a complete KMC simulation model by integrating the gas-phase, reaction, energetics, and lattice components.

### Parameters
- **gas_model** (GasModel) - Required - Gas-phase species definitions, including molecular weights and energies.
- **reaction_model** (ReactionModel) - Required - Elementary reaction steps, including initial/final states, activation energies, and vibrational energies.
- **energetics_model** (EnergeticsModel) - Required - Clusters and their energies, reflecting the cluster expansion used for energy calculations.
- **lattice_model** (LatticeModel) - Required - Lattice structure, site types, and spatial arrangement of sites.

### Example
```python
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

gas_model = GasModel.from_csv('gas_data.csv')
reaction_model = ReactionModel.from_csv('mechanism_data.csv')
energetics_model = EnergeticsModel.from_csv('energetics_data.csv')

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},
)

kmc_model = KMCModel(
    gas_model=gas_model,
    reaction_model=reaction_model,
    energetics_model=energetics_model,
    lattice_model=lattice_model
)
```
```

--------------------------------

### Read scan results with read_scan

Source: https://zacrostools.readthedocs.io/en/latest/reading_output_files.html

Example of using read_scan to read results from a scan directory into a Pandas DataFrame and save it as a CSV file. Requires the zacrostools package and a scan directory with simulation outputs.

```python
from zacrostools.read_scan import read_scan

data_scan = read_scan(
    scan_path='path_to_scan',
    analysis_range=[50, 100],
    range_type='time')
data_scan.to_csv('data_scan.csv', index=True)

```

--------------------------------

### Plot energy slope heatmap with plot_energyslope

Source: https://zacrostools.readthedocs.io/en/latest/_sources/plotting_heatmaps.md.txt

Creates an energy slope heatmap using the plot_energyslope function. The example sets scan_path to 'simulation_results', uses pressure_CH4 and pressure_CO2 as x and y axes, and saves the figure as 'energyslope_heatmap.png'.

```python
import matplotlib.pyplot as plt
from zacrostools.heatmaps.energyslope import plot_energyslope

fig, axs = plt.subplots(1, figsize=(4.3, 3.5))
plot_energyslope(
    ax=axs,
    scan_path='simulation_results',
    x='pressure_CH4',
    y='pressure_CO2',
    range_type='nevents',
    auto_title=True,
    show_points=False,
    show_colorbar=True
)
plt.tight_layout()
plt.savefig('energyslope_heatmap.png', dpi=300, bbox_inches='tight', transparent=False)
plt.show()
```

--------------------------------

### LatticeModel.from_file

Source: https://zacrostools.readthedocs.io/en/latest/_sources/lattice_model.md.txt

Creates a LatticeModel by reading a previously created lattice_input.dat file. Useful for reusing lattice configurations or when the file was provided by another user.

```APIDOC
## LatticeModel.from_file

### Description
Creates a `LatticeModel` by reading a previously created `lattice_input.dat` file. This is useful for reusing lattice configurations or when the lattice file was provided by another user.

### Method
from_file

### Parameters
- **input_file** (`str` or `Path`) - Required - Path to the existing `lattice_input.dat` file.

### Notes
- Reads the `lattice` block from the file, which starts with the `lattice` keyword and ends with `end_lattice`.
- Supports `'default_choice'` and `'periodic_cell'` lattice types.
- If the lattice type is `'explicit'`, a `LatticeModelError` will be raised as this type is not yet supported.
- Ignores any content outside the `lattice` block.

### Example
```python
from zacrostools.lattice_model import LatticeModel

lattice_model = LatticeModel.from_file(input_file='path/to/lattice_input.dat')
```
```

--------------------------------

### Plot event frequencies from procstat output

Source: https://zacrostools.readthedocs.io/en/latest/_sources/plotting_single_simulation.md.txt

Plots the frequency of each elementary event type within a chosen time range, using data from the 'procstat_output.txt' file. The example parses the file and then calls plot_event_frequency to generate the plot, which is saved as 'event_frequencies.png'.

```python
import matplotlib.pyplot as plt
from zacrostools.procstat_output import plot_event_frequency, parse_procstat_output_file

df_procstat, delta_time, delta_events, area = parse_procstat_output_file(
    procstat_output_path='simulation_results/CH4_5.179e-04#CO2_6.105e-04',
    analysis_range=[50, 100],
    range_type='time'
)

num_steps = len(df_procstat.index)
fig_height = max(4.0, num_steps * 0.18)

fig1, axs = plt.subplots(1, figsize=(9, fig_height))

plot_event_frequency(
    ax=axs,
    simulation_path='simulation_results/CH4_5.179e-04#CO2_6.105e-04',
    analysis_range=[50, 100],
    range_type='time')

plt.tight_layout(pad=3.0)  # Increased padding for better spacing
plt.savefig('event_frequencies.png', dpi=300, bbox_inches='tight', transparent=False)
plt.show()
```

--------------------------------

### Write mechanism_input.dat with write_mechanism_input

Source: https://zacrostools.readthedocs.io/en/latest/_sources/reaction_model.md.txt

Generates the mechanism_input.dat file required by Zacros. Requires output_dir, temperature, and gas_model; optional parameters include manual_scaling, stiffness_scalable_steps, stiffness_scalable_symmetric_steps, sig_figs_energies, and sig_figs_pe.

```python
from zacrostools.gas_model import GasModel

gas_model = GasModel.from_csv('gas_data.csv')
reaction_model.write_mechanism_input(
    output_dir='kmc_simulation',
    temperature=500,
    gas_model=gas_model,
    sig_figs_energies=8,
    sig_figs_pe=8
)
```

--------------------------------

### Load LatticeModel from file

Source: https://zacrostools.readthedocs.io/en/latest/_sources/lattice_model.md.txt

Creates a LatticeModel by reading an existing lattice_input.dat file. Reads the lattice block between 'lattice' and 'end_lattice', supports 'default_choice' and 'periodic_cell' types, raises LatticeModelError for 'explicit', and ignores content outside the block.

```python
from zacrostools.lattice_model import LatticeModel

lattice_model = LatticeModel.from_file(input_file='path/to/lattice_input.dat')
```

--------------------------------

### Plot issues heatmap with plot_issues

Source: https://zacrostools.readthedocs.io/en/latest/_sources/plotting_heatmaps.md.txt

Creates an issues heatmap using the plot_issues function. The example sets scan_path to 'simulation_results', uses pressure_CH4 and pressure_CO2 as x and y axes, sets analysis_range to [50, 100], enables verbose mode, and saves the figure as 'issues_heatmap.png'.

```python
import matplotlib.pyplot as plt
from zacrostools.heatmaps.issues import plot_issues

fig, axs = plt.subplots(1, figsize=(4.3, 3.5))
plot_issues(
    ax=axs,
    scan_path='simulation_results',
    x='pressure_CH4',
    y='pressure_CO2',
    analysis_range=[50, 100],
    verbose=True,
    auto_title=True,
    show_points=False,
    show_colorbar=True
)
plt.tight_layout()
plt.savefig('issues_heatmap.png', dpi=300, bbox_inches='tight', transparent=False)
plt.show()
```
Tokens:
Raw