### Full example: create, modify, and write EnergeticsModel Source: https://github.com/hprats/zacrostools/blob/main/docs/source/energetics_model.md Complete example demonstrating creation from a dictionary, adding a cluster, removing a cluster, writing the energetics input file, and accessing the DataFrame. ```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) ``` -------------------------------- ### Install ZacrosTools from GitHub Source: https://github.com/hprats/zacrostools/blob/main/docs/source/index.md Installs the latest development version of ZacrosTools directly from the GitHub repository. ```bash git clone https://github.com/hprats/ZacrosTools.git cd ZacrosTools pip install . ``` -------------------------------- ### Full GasModel creation and modification example Source: https://github.com/hprats/zacrostools/blob/main/docs/source/gas_model.md Complete example showing creation of a GasModel from a dictionary, adding a species, removing a species, and accessing the internal 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) ``` -------------------------------- ### Full ReactionModel creation and modification example Source: https://github.com/hprats/zacrostools/blob/main/docs/source/reaction_model.md Complete example showing creation of a `ReactionModel` from a dictionary, adding and removing steps, writing a mechanism input file, and accessing the DataFrame. Requires a `GasModel` from CSV and writes to `kmc_simulation` at 500 K with 8 significant figures. ```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) ``` -------------------------------- ### Install ZacrosTools from PyPI Source: https://github.com/hprats/zacrostools/blob/main/docs/source/index.md Installs the ZacrosTools package from PyPI. Requires Python 3.8 or higher, Scipy, and Pandas. ```bash pip install zacrostools ``` -------------------------------- ### LatticeModel.from_file Source: https://github.com/hprats/zacrostools/blob/main/docs/source/lattice_model.md Documentation for the LatticeModel.from_file class method, including parameters, notes, and an example. ```APIDOC ## LatticeModel.from_file ### Description Creates a LatticeModel by reading a previously created `lattice_input.dat` file. Useful for reusing lattice configurations or when the lattice file was provided by another user. ### Method `from_file(input_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') ``` ``` -------------------------------- ### ReactionModel.from_dict with fixed_pre_expon and fixed_pe_ratio Source: https://github.com/hprats/zacrostools/blob/main/docs/source/reaction_model.md Example of creating a ReactionModel with user-specified pre-exponential factors. The parameters fixed_pre_expon and fixed_pe_ratio must be provided together and are incompatible with certain stiffness scaling settings. ```APIDOC ## ReactionModel.from_dict ### Description Creates a ReactionModel from a dictionary of reaction data. This example demonstrates fixing the forward pre-exponential factor and pre-exponential ratio. ### Method from_dict ### Parameters #### Dictionary Keys (reaction_data) - **activ_eng** (float) - Required - Activation energy. - **area_site** (float) - Required - Area of the site. - **initial** (list of str) - Required - Initial state composition. - **final** (list of str) - Required - Final state composition. - **molecule_is** (str) - Required - Molecule in initial state. - **prox_factor** (float) - Required - Proximity factor. - **site_types** (str) - Required - Site type. - **vib_energies_is** (list of float) - Required - Vibrational energies of initial state. - **vib_energies_fs** (list of float) - Required - Vibrational energies of final state. - **fixed_pre_expon** (float) - Optional - User-specified forward pre-exponential factor. Must be provided together with fixed_pe_ratio. - **fixed_pe_ratio** (float) - Optional - User-specified pre-exponential ratio. Must be provided together with fixed_pre_expon. ### Constraints - Both fixed_pre_expon and fixed_pe_ratio must be provided together. - Incompatible with stiffness_scalable_steps="all", including a fixed step in stiffness_scalable_steps, or including a fixed step in stiffness_scalable_symmetric_steps. If violated, a ReactionModelError is raised. ### Request Example ```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) ``` ### Response No explicit response is documented. The method returns a ReactionModel instance. ``` -------------------------------- ### LatticeModel Constructor Source: https://github.com/hprats/zacrostools/blob/main/docs/source/lattice_model.md Documentation for the LatticeModel class constructor, including parameters and usage examples for creating a lattice model via default lattice, custom periodic cell, or from file. ```APIDOC ## LatticeModel ### Description Creates a lattice model for use in Zacros simulations. Supports three creation methods: using a default lattice, defining a custom periodic cell, or loading from an existing lattice input file. ### Constructor `LatticeModel(lattice_type, default_lattice_type=None, lattice_constant=None, copies=None, cell_vectors=None, sites=None, coordinate_type='direct', neighboring_structure=None, max_distances=None)` ### Parameters - **lattice_type** (str) - Required - Must be `'default_choice'` or `'periodic_cell'`. - **default_lattice_type** (str) - Required if `lattice_type='default_choice'` - Choose from `'triangular_periodic'`, `'rectangular_periodic'`, or `'hexagonal_periodic'`. - **lattice_constant** (float) - Required if `lattice_type='default_choice'` - The lattice constant in Å. - **copies** (List[int]) - Required - Number of repetitions along the horizontal and vertical directions. - **cell_vectors** (Tuple[Tuple[float, float], Tuple[float, float]]) - Required if `lattice_type='periodic_cell'` - Two vectors defining the unit cell. - **sites** (Dict[str, Union[Tuple[float, float], List[Tuple[float, float]]]]) - Required if `lattice_type='periodic_cell'` - Mapping of site types to their coordinates within the unit cell. - **coordinate_type** (str, optional) - `'direct'` or `'cartesian'`. Defaults to `'direct'`. - **neighboring_structure** (Union[str, Dict[str, Union[str, List[str]]]]) - Required if `lattice_type='periodic_cell'` - Defines neighboring relationships. If `'from_distances'`, `max_distances` must be provided. If a dictionary, maps site pairs to relationship keywords. - **max_distances** (Dict[str, float]) - Required if `neighboring_structure='from_distances'` - Maximum distances for neighbor pairs. ### Example: Default lattice ```python from zacrostools.lattice_model import LatticeModel lattice_model = LatticeModel( lattice_type='default_choice', default_lattice_type='triangular_periodic', lattice_constant=2.5, copies=[10, 10] ) ``` ### Example: Custom periodic cell with explicit neighboring structure ```python from zacrostools.lattice_model import LatticeModel cell_vectors = ((3.27, 0.0), (0.0, 3.27)) sites = { 'tC': [(0.25, 0.25)], 'tM': [(0.75, 0.75)] } neighboring_structure = { '1-2': ['self'], '1-1': ['north', 'east'], '2-1': ['north', 'east', 'northeast'], '2-2': ['north', 'east'] } lattice_model = LatticeModel( lattice_type='periodic_cell', cell_vectors=cell_vectors, sites=sites, coordinate_type='direct', copies=[10, 10], neighboring_structure=neighboring_structure ) ``` ### Example: Custom periodic cell with automatic neighboring structure ```python from zacrostools.lattice_model import LatticeModel cell_vectors = ((3.27, 0.0), (0.0, 3.27)) sites = { 'tC': [(0.25, 0.25)], 'tM': [(0.75, 0.75)] } max_distances = { 'tC-tC': 3.0, 'tM-tM': 3.0, 'tC-tM': 3.0 } lattice_model = LatticeModel( lattice_type='periodic_cell', cell_vectors=cell_vectors, sites=sites, coordinate_type='direct', copies=[10, 10], neighboring_structure='from_distances', max_distances=max_distances ) ``` ``` -------------------------------- ### Create ReactionModel from dictionary with ReactionModel.from_dict Source: https://github.com/hprats/zacrostools/blob/main/docs/source/reaction_model.md Defines a dictionary where each key is a cluster name and each value is a dictionary of elementary step properties. The example includes steps for CO adsorption, O2 adsorption, CO+O to CO2, and CO2 adsorption. Note the comment recommending to define the forward direction as the adsorption for CO2_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) ``` -------------------------------- ### Create KMCModel instance with gas, reaction, energetics, and lattice models Source: https://github.com/hprats/zacrostools/blob/main/docs/source/writing_input_files.md This example shows how to assemble a complete KMC model by loading gas, reaction, and energetics models from CSV files, defining a periodic lattice with specific cell vectors and site types, and combining them into a KMCModel instance. The lattice uses a 'from_distances' neighboring structure with maximum distances for site pairs. ```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 ) ``` -------------------------------- ### Generate Zacros input files with create_job_dir Source: https://github.com/hprats/zacrostools/blob/main/docs/source/writing_input_files.md Creates a job directory with all four Zacros input files. Required parameters are job_path, temperature, and pressure; optional parameters control reporting, stopping criteria, manual scaling, stiffness scaling, significant figures, and random seed. The example sets a temperature of 1000 K, partial pressures for CO, O2, and CO2, and various optional settings. ```python kmc_model.create_job_dir( job_path='kmc_simulation', temperature=1000.0, pressure={'CO': 1.0, 'O2': 0.001, 'CO2': 0.0}, reporting_scheme={ 'snapshots': 'on event 10000', 'process_statistics': 'on event 10000', 'species_numbers': 'on event 10000'}, stopping_criteria={ 'max_steps': 'infinity', 'max_time': 'infinity', 'wall_time': 86400}, manual_scaling={ 'CO_diffusion': 1.0e-1, 'O_diffusion': 1.0e-2}, stiffness_scaling_algorithm=None, sig_figs_energies=8, sig_figs_pe=8, ) ``` -------------------------------- ### Build a multi-panel heatmap figure with plot_tof, plot_coverage, plot_phasediagram, plot_selectivity, plot_finaltime, and plot_dtof Source: https://github.com/hprats/zacrostools/blob/main/docs/source/plotting_heatmaps.md Creates a 4x3 grid of heatmaps (TOF, coverage, phase diagram, selectivity, final time, and dTOF) using a common scan and analysis window. Requires simulation results in 'simulation_results' and a reference scan in 'simulation_results_reference' for the dTOF panel. The example sets analysis_range to ignore the first 50% of simulated time 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() ``` -------------------------------- ### Plot selectivity heatmap with plot_selectivity Source: https://github.com/hprats/zacrostools/blob/main/docs/source/plotting_heatmaps.md Creates a selectivity heatmap using plot_selectivity. Requires main_product and side_products; min_molec sets the minimum combined production (default 0). The example uses min_molec=100 and saves the figure as selectivity_heatmap.png. ```python import matplotlib.pyplot as plt from zacrostools.heatmaps.selectivity import plot_selectivity fig, axs = plt.subplots(1, figsize=(4.3, 3.5)) plot_selectivity( ax=axs, scan_path='simulation_results', x='pressure_CH4', y='pressure_CO2', main_product='H2', side_products=['H2O'], min_molec=100, analysis_range=[50, 100], range_type='time', auto_title=True, show_points=False, show_colorbar=True ) plt.tight_layout() plt.savefig('selectivity_heatmap.png', dpi=300, bbox_inches='tight', transparent=False) plt.show() ``` -------------------------------- ### Plot TOF heatmap with plot_tof Source: https://github.com/hprats/zacrostools/blob/main/docs/source/plotting_heatmaps.md Creates a TOF heatmap using plot_tof. Requires a scan_path with simulation results and a gas_spec key like 'H2'. The example sets min_molec=0, an analysis_range of [50, 100] with range_type='time', and log-spaced contour levels. The output is saved as 'tof_heatmap.png'. ```python import numpy as np import matplotlib.pyplot as plt from zacrostools.heatmaps.tof import plot_tof fig, axs = plt.subplots(1, figsize=(4.3, 3.5)) plot_tof( ax=axs, scan_path='simulation_results', x='pressure_CH4', y='pressure_CO2', gas_spec='H2', min_molec=0, analysis_range=[50, 100], range_type='time', levels=np.logspace(-1, 4, num=11), auto_title=True, show_points=False, show_colorbar=True ) plt.tight_layout() plt.savefig('tof_heatmap.png', dpi=300, bbox_inches='tight', transparent=False) plt.show() ``` -------------------------------- ### Plot phase diagram heatmap with plot_phasediagram Source: https://github.com/hprats/zacrostools/blob/main/docs/source/plotting_heatmaps.md Creates a phase diagram heatmap using plot_phasediagram from zacrostools.heatmaps.phasediagram. The example sets tick_labels to group surface species for the colorbar, uses scan_path='simulation_results', and specifies x='pressure_CH4' and y='pressure_CO2'. It sets min_coverage=50.0, site_type='tC', analysis_range=[50, 100], range_type='time', and weights='time'. The resulting figure is saved as 'phasediagram_heatmap.png' with dpi=300 and transparent=False. ```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 = { # for phase diagram plots '$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() ``` -------------------------------- ### Plot coverage heatmap with plot_coverage Source: https://github.com/hprats/zacrostools/blob/main/docs/source/plotting_heatmaps.md Creates a coverage heatmap using plot_coverage. surf_spec can be a species or 'all' for total coverage; site_type defaults to 'StTp1' but is set to 'tC' here. The example saves the figure as coverage_heatmap.png. ```python import matplotlib.pyplot as plt from zacrostools.heatmaps.coverage import plot_coverage fig, axs = plt.subplots(1, figsize=(4.3, 3.5)) plot_coverage( ax=axs, scan_path='simulation_results', x='pressure_CH4', y='pressure_CO2', surf_spec='all', site_type='tC', analysis_range=[50, 100], range_type='time', weights='time', auto_title=True, show_points=False, show_colorbar=True ) plt.tight_layout() plt.savefig('coverage_heatmap.png', dpi=300, bbox_inches='tight', transparent=False) plt.show() ``` -------------------------------- ### Plot final time heatmap with plot_finaltime Source: https://github.com/hprats/zacrostools/blob/main/docs/source/plotting_heatmaps.md Creates a heatmap of final time using the plot_finaltime function. The example sets contour levels with np.logspace, uses pressure_CH4 and pressure_CO2 as axes, and saves the figure as finaltime_heatmap.png. ```python import numpy as np import matplotlib.pyplot as plt from zacrostools.heatmaps.finaltime import plot_finaltime fig, axs = plt.subplots(1, figsize=(4.3, 3.5)) plot_finaltime( ax=axs, scan_path='simulation_results', x='pressure_CH4', y='pressure_CO2', levels=np.logspace(-5, 7, num=13), auto_title=True, show_points=False, show_colorbar=True ) plt.tight_layout() plt.savefig('finaltime_heatmap.png', dpi=300, bbox_inches='tight', transparent=False) plt.show() ``` -------------------------------- ### Plot energy slope heatmap with plot_energyslope Source: https://github.com/hprats/zacrostools/blob/main/docs/source/plotting_heatmaps.md Creates a heatmap of energy slope using the plot_energyslope function. The example uses range_type='nevents' 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() ``` -------------------------------- ### Override restart maxima with zacros.x CLI flags Source: https://github.com/hprats/zacrostools/blob/main/examples/DRM_on_PtHfC/simulation_results_reference/CH4_1.000e+01 Command-line arguments to override the maximum number of events or simulation time when restarting a finished simulation. The example shows setting max_steps to -2 and max_time to 1e7. ```bash zacros.x --max_steps=-2 zacros.x --max_time=1.0000000E+07 ``` -------------------------------- ### Create LatticeModel with custom periodic cell and explicit neighboring structure Source: https://github.com/hprats/zacrostools/blob/main/docs/source/lattice_model.md Creates a LatticeModel for a custom periodic cell by explicitly defining the neighboring structure as a dictionary mapping site pairs to relationship keywords. Uses lattice_type='periodic_cell', cell_vectors, sites, coordinate_type='direct', copies, and neighboring_structure. This example models a HfC(001) surface. ```python from zacrostools.lattice_model import LatticeModel # Define cell vectors cell_vectors = ((3.27, 0.0), (0.0, 3.27)) # Define site positions sites = { 'tC': [(0.25, 0.25)], 'tM': [(0.75, 0.75)] } # Define neighboring structure directly neighboring_structure = { '1-2': ['self'], '1-1': ['north', 'east'], '2-1': ['north', 'east', 'northeast'], '2-2': ['north', 'east'] } # Create the LatticeModel instance lattice_model = LatticeModel( lattice_type='periodic_cell', cell_vectors=cell_vectors, sites=sites, coordinate_type='direct', copies=[10, 10], neighboring_structure=neighboring_structure ) ``` -------------------------------- ### Create LatticeModel with custom periodic cell and automatic neighboring structure Source: https://github.com/hprats/zacrostools/blob/main/docs/source/lattice_model.md Creates a LatticeModel for a custom periodic cell by automatically generating the neighboring structure from maximum distances. Requires lattice_type='periodic_cell', cell_vectors, sites, coordinate_type='direct', copies, neighboring_structure='from_distances', and max_distances mapping site pairs to distance thresholds. This example models a HfC(001) surface. ```python from zacrostools.lattice_model import LatticeModel # Define cell vectors cell_vectors = ((3.27, 0.0), (0.0, 3.27)) # Define site positions sites = { 'tC': [(0.25, 0.25)], 'tM': [(0.75, 0.75)] } # Define maximum distances for neighbor pairs max_distances = { 'tC-tC': 3.0, 'tM-tM': 3.0, 'tC-tM': 3.0 } # Create the LatticeModel instance lattice_model = LatticeModel( lattice_type='periodic_cell', cell_vectors=cell_vectors, sites=sites, coordinate_type='direct', copies=[10, 10], neighboring_structure='from_distances', max_distances=max_distances ) ``` -------------------------------- ### Plot issues heatmap with plot_issues Source: https://github.com/hprats/zacrostools/blob/main/docs/source/plotting_heatmaps.md Creates a heatmap of detected issues using plot_issues. The example sets analysis_range to [50, 100], enables verbose output, 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() ``` -------------------------------- ### Plot TOF difference heatmap with plot_dtof Source: https://github.com/hprats/zacrostools/blob/main/docs/source/plotting_heatmaps.md Creates a TOF difference heatmap using plot_dtof. Requires both scan_path and scan_path_ref for main and reference simulations. The example uses difference_type='absolute' (∆TOF = TOF(main) − TOF(ref)) and saves the output as 'dtof_heatmap.png'. ```python import numpy as np import matplotlib.pyplot as plt from zacrostools.heatmaps.dtof import plot_dtof fig, axs = plt.subplots(1, figsize=(4.3, 3.5)) plot_dtof( ax=axs, scan_path='simulation_results', scan_path_ref='simulation_results_reference', x='pressure_CH4', y='pressure_CO2', gas_spec='H2', difference_type='absolute', min_molec=0, analysis_range=[50, 100], range_type='time', levels=np.logspace(-1, 4, num=11), auto_title=True, show_points=False, show_colorbar=True ) plt.tight_layout() plt.savefig('dtof_heatmap.png', dpi=300, bbox_inches='tight', transparent=False) plt.show() ``` -------------------------------- ### Customize TOF heatmap text sizes and colorbar with Matplotlib Source: https://github.com/hprats/zacrostools/blob/main/docs/source/plotting_heatmaps.md Customizes tick sizes, label fonts, and title placement for a single TOF heatmap subplot using standard Matplotlib APIs. The example creates a colorbar and adjusts its tick label size, then saves the figure as 'tof_heatmap_custom.png' with a resolution of 300 dpi. ```python import numpy as np import matplotlib.pyplot as plt from zacrostools.heatmaps.tof import plot_tof fig, axs = plt.subplots(1, figsize=(4.3, 3.5)) cp = plot_tof( ax=axs, scan_path='simulation_results', x='pressure_CH4', y='pressure_CO2', gas_spec='H2', min_molec=0, analysis_range=[50, 100], range_type='time', levels=np.logspace(-1, 4, num=11), auto_title=True, show_points=False, show_colorbar=False ) # Adjust size of axis ticks axs.tick_params(axis='both', which='major', labelsize=14) # Adjust font size of axis labels axs.set_xlabel(axs.get_xlabel(), fontsize=18) axs.set_ylabel(axs.get_ylabel(), fontsize=18) # Adjust font size and position of axis title axs.set_title(axs.get_title(), fontsize=20, loc='center', pad=-170) # Create colorbar and adjust the size of its tick labels cbar = plt.colorbar(cp, ax=axs) cbar.ax.tick_params(labelsize=14) plt.tight_layout() plt.savefig('tof_heatmap_custom.png', dpi=300, bbox_inches='tight', transparent=False) plt.show() ``` -------------------------------- ### Initialize KMCOutput to load simulation data Source: https://github.com/hprats/zacrostools/blob/main/docs/source/reading_output_files.md Creates a KMCOutput object to load and analyze Zacros simulation results. The analysis_range, range_type, and weights parameters control which portion of the simulation is used and how averaging is weighted. ```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') ``` -------------------------------- ### Write mechanism_input.dat with write_mechanism_input Source: https://github.com/hprats/zacrostools/blob/main/docs/source/reaction_model.md Writes the `mechanism_input.dat` file required by Zacros. Requires an `output_dir`, a temperature in Kelvin, and a `GasModel` instance; 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 ) ``` -------------------------------- ### Loop over temperature and pressure to create KMC job directories Source: https://github.com/hprats/zacrostools/blob/main/docs/source/writing_input_files.md Loops over temperature (K) and partial pressures (bar) to create job directories for a kinetic Monte Carlo model. Each job uses a unique path with temperature and pressure values, sets a reporting scheme for snapshots, process statistics, and species numbers, and defines stopping criteria including infinite max steps, a max time of 5.0e+06, and a 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} ) ``` -------------------------------- ### Create EnergeticsModel from dictionary using EnergeticsModel.from_dict Source: https://github.com/hprats/zacrostools/blob/main/docs/source/energetics_model.md Creates an EnergeticsModel instance from a dictionary of cluster properties. The dictionary keys are cluster names and values are dictionaries with cluster_eng, site_types, lattice_state, and optional neighboring and graph_multiplicity. ```python 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) ``` -------------------------------- ### Create GasModel from CSV file with GasModel.from_csv Source: https://github.com/hprats/zacrostools/blob/main/docs/source/gas_model.md Creates a GasModel from a CSV file. The indexes in the CSV must correspond to the species names. ```python from zacrostools.gas_model import GasModel gas_model = GasModel.from_csv('gas_data.csv') ```