2. Creating the Energetics Model

The EnergeticsModel stores information about each cluster included in the cluster expansion.

Properties

• cluster_eng (float): Cluster formation energy (eV).

• lattice_state (list[str]): Cluster configuration (e.g., ['1 CO* 1', '2 CO* 1']).

• site_types (str, optional): Site types (required if lattice_type='periodic_cell').

• neighboring (str, optional): Connectivity between sites (e.g., '1-2'; default = None).

• angles (str, optional): Angle constraints (e.g., '1-2-3:180'; default = None).

• graph_multiplicity (int, optional): Graph multiplicity (default = None).

How to create it

You can provide a dictionary where each key is a cluster name and each value is a dictionary of cluster properties:

from zacrostools.energetics_model import EnergeticsModel

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']
    },
    'CO2_point': {
        'cluster_eng': -1.571,
        'site_types': 'top',
        'lattice_state': ['1 CO2* 1']
    },
    'C_point': {
        'cluster_eng': 2.442,
        'site_types': 'top',
        'lattice_state': ['1 C* 1']
    },
    'CO+O_pair': {
        'cluster_eng': -0.032,
        'site_types': 'top top',
        'lattice_state': ['1 CO* 1', '2 O* 1'],
        'neighboring': '1-2'
    },
    'O+O_pair': {
        'cluster_eng': 0.033,
        'site_types': 'top top',
        'lattice_state': ['1 O* 1', '2 O* 1'],
        'neighboring': '1-2',
        'graph_multiplicity': 2.0
    }
}

energetics_model = EnergeticsModel.from_dict(clusters_data)

Alternatively, it can also be created from a CSV file. In this case, the indexes must correspond to the cluster names:

from zacrostools.energetics_model import EnergeticsModel

energetics_model = EnergeticsModel.from_csv('energetics_data.csv')

Finally, it can also be created from a Pandas dataframe:

import pandas as pd
from zacrostools.energetics_model import EnergeticsModel

df = pd.read_csv("energetics_data.csv")  # or create dataframe directly
energetics_model = EnergeticsModel.from_df(df)

---

Adding and removing clusters

Use the add_cluster method to add a new cluster:

new_cluster = {
    'cluster_name': 'new_cluster',
    'cluster_eng': 1.0,
    'site_types': 'top top',
    'lattice_state': ['1 CO* 1', '2 C* 1'],
    'neighboring': '1-2'
}

energetics_model.add_cluster(cluster_info=new_cluster)

Use the remove_clusters method to remove clusters by name:

energetics_model.remove_clusters(['CO2_point'])

---

Writing the energetics_input.dat file

The EnergeticsModel can generate the energetics_input.dat file required by Zacros:

Required parameters:

• output_dir (str or Path): Directory where the file will be written.

• sig_figs_energies (int, optional): Number of significant figures for cluster energies.

energetics_model.write_energetics_input(output_dir='kmc_simulation', sig_figs_energies=3)

This will generate a file named energetics_input.dat in the kmc_simulation directory.

---

Accessing energetics data

The cluster data is stored internally as a Pandas DataFrame, accessible via the df attribute.

print(energetics_model.df)

Full example

Below is an example demonstrating the creation and modification of an EnergeticsModel:

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)

---