### Install kMCpy from source using pip

Source: https://github.com/caneparesearch/kmcpy/blob/master/docs/source/install.md

Installs kMCpy from its source code after cloning the repository. Navigate to the root directory of the kMCpy repository before running this command.

```shell
pip install .
```

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

### Build kMCpy documentation locally

Source: https://github.com/caneparesearch/kmcpy/blob/master/docs/source/install.md

Builds the kMCpy documentation locally. This involves synchronizing documentation-related dependencies using UV and then executing a Python script to generate the documentation.

```shell
uv sync --extra doc
python scripts/build_doc.py
```

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

### Install kMCpy from source using UV

Source: https://github.com/caneparesearch/kmcpy/blob/master/docs/source/install.md

Installs kMCpy from its source code using the UV package manager, recommended for use with virtual environments. This command synchronizes project dependencies.

```shell
uv sync
```

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

### Install kMCpy GUI dependencies using UV

Source: https://github.com/caneparesearch/kmcpy/blob/master/docs/source/install.md

Installs the additional dependencies required for kMCpy's graphical user interface (GUI) using UV. This command synchronizes dependencies with the 'gui' extra.

```shell
uv sync --extra gui
```

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

### Run kMCpy from Command Line

Source: https://github.com/caneparesearch/kmcpy/blob/master/README.md

Examples of running kMCpy simulations from the command line using the provided wrapper script. Includes running a simulation with an input file and printing help arguments.

```shell
run_kmc input.json

```

```shell
run_kmc --help

```

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

### Start kMCpy GUI

Source: https://github.com/caneparesearch/kmcpy/blob/master/README.md

Command to launch the graphical user interface for kMCpy. This allows users to select input files and run simulations through a visual interface.

```shell
start_kmcpy_gui

```

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

### Install kMCpy from Source using UV

Source: https://github.com/caneparesearch/kmcpy/blob/master/README.md

Instructions for installing kMCpy from source using the UV package manager. This includes standard installation, development mode installation with extra dependencies, and installation for GUI support.

```shell
uv sync

```

```shell
uv sync --extra dev
uv pip install -e . # this makes the installation using the editable mode

```

```shell
uv sync --extra gui

```

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

### Install kMCpy using pip

Source: https://github.com/caneparesearch/kmcpy/blob/master/docs/source/install.md

Installs the latest version of kMCpy from PyPI. It is recommended to perform this installation within a virtual environment to avoid dependency conflicts.

```shell
pip install kmcpy
```

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

### Install kMCpy from source in editable mode using UV

Source: https://github.com/caneparesearch/kmcpy/blob/master/docs/source/install.md

Installs kMCpy from source in editable mode using UV. This allows for development with immediate changes reflected. It also synchronizes dependencies with the 'dev' extra.

```shell
uv sync --extra dev
uv pip install -e . # this makes the installation using the editable mode
```

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

### Create and activate a virtual environment using venv

Source: https://github.com/caneparesearch/kmcpy/blob/master/docs/source/install.md

Creates a virtual environment named 'kmcpy-env' and activates it. This isolates project dependencies. The activation command differs between operating systems.

```shell
python -m venv kmcpy-env
source kmcpy-env/bin/activate  # On Windows use `kmcpy-env\Scripts\activate`
```

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

### Install kMCpy from source in editable mode using pip

Source: https://github.com/caneparesearch/kmcpy/blob/master/docs/source/install.md

Installs kMCpy from source in editable mode, allowing for immediate reflection of code changes without reinstallation. Useful for development.

```shell
pip install -e ".[dev]"
```

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

### Install kMCpy GUI dependencies using pip

Source: https://github.com/caneparesearch/kmcpy/blob/master/docs/source/install.md

Installs additional dependencies required for kMCpy's graphical user interface (GUI), which is based on wxpython. GTK may need to be installed separately for wxpython.

```shell
pip install -e ".[gui]"
```

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

### Set up KMC Simulation Configuration

Source: https://github.com/caneparesearch/kmcpy/blob/master/example/NASICON.ipynb

Configures a KMC simulation using the SimulationConfig.create method. This involves specifying various input files for structure, cluster expansion, fitting results, and events, along with simulation parameters like mobile ion, temperature, KMC passes, and cell shape. It also includes settings for initial state, site immutability, and random seeding.

```python
config = SimulationConfig.create(
    structure_file=f"{file_path}/nasicon.cif",
    cluster_expansion_file=f"{file_path}/input/lce.json",
    fitting_results_file=f"{file_path}/input/fitting_results.json",
    cluster_expansion_site_file=f"{file_path}/input/lce.json",
    fitting_results_site_file=f"{file_path}/input/fitting_results_site.json",
    event_file=f"{file_path}/input/events.json",
    initial_state_file=f"{file_path}/input/initial_state.json",
    mobile_ion_specie="Na",
    temperature=298,
    attempt_frequency=5e12,
    elementary_hop_distance=3.47782,
    equilibration_passes=10,
    kmc_passes=1000,
    supercell_shape=(2, 1, 1),
    immutable_sites=("Zr", "O", "Zr4+", "O2-"),
    convert_to_primitive_cell=True,
    random_seed=12345,
    name="NASICON_KMC"
)
```

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

### Create and activate a Python virtual environment using venv

Source: https://github.com/caneparesearch/kmcpy/blob/master/README.md

Demonstrates the process of creating a new Python virtual environment using the `venv` module and activating it. This isolates project dependencies. The commands differ slightly between Unix-based systems and Windows.

```shell
python -m venv kmcpy-env
source kmcpy-env/bin/activate  # On Windows use `kmcpy-env\Scripts
```

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

### Run KMCpy Simulations from Command Line

Source: https://context7.com/caneparesearch/kmcpy/llms.txt

Demonstrates how to run KMCpy simulations using the command line interface, either by providing a configuration file or by specifying arguments directly.

```bash
# Run simulation from configuration file
run_kmc --input simulation.yaml

# Run with command line arguments
run_kmc \
  --structure_file nasicon.cif \
  --supercell_shape "[2,2,2]" \
  --cluster_expansion_file lce.json \
  --cluster_expansion_site_file lce_site.json \
  --fitting_results_file fitting_results.json \
  --fitting_results_site_file fitting_results_site.json \
  --event_file events.json \
  --temperature 573 \
  --attempt_frequency 1e13

# Launch GUI interface
start_kmcpy_gui
```

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

### Build kMCpy Documentation Locally

Source: https://github.com/caneparesearch/kmcpy/blob/master/README.md

Steps to build the kMCpy documentation locally. This involves synchronizing documentation-specific dependencies using UV and then running a Python script to generate the documentation.

```shell
uv sync --extra doc
python scripts/build_doc.py

```

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

### Run KMC Simulation and Display Results (Python)

Source: https://github.com/caneparesearch/kmcpy/blob/master/example/NASICON.ipynb

Initializes a KMC simulation from configuration, runs it, retrieves results, and prints formatted simulation parameters like time, temperature, and diffusivity. It includes error handling for unexpected result vector lengths. Dependencies: KMC library (assumed).

```python
import KMC

config = {}
kmc = KMC.from_config(config)
kmc_tracker = kmc.run(config)
results = kmc_tracker.return_current_info()
print("KMC simulation completed.")
print("Simulation Results:")

if len(results) >= 7:
    time, temperature, diffusivity, conductivity, msd, correlation_factor, tracer_diffusivity = results[:7]
    print(f"  - Simulation time: {time:.2e} s")
    print(f"  - Temperature: {temperature:.1f} K")
    print(f"  - Diffusivity: {diffusivity:.2e} cm2/s")
    print(f"  - Conductivity: {conductivity:.2e} S/cm")
    print(f"  - MSD: {msd:.2e}")
    print(f"  - Correlation factor: {correlation_factor:.3f}")
    print(f"  - Tracer diffusivity: {tracer_diffusivity:.2e} cm2/s")
else:
    print(f"Results vector has {len(results)} elements (expected 7)")
```

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

### Set up Local Cluster Expansion Model with kMCpy

Source: https://github.com/caneparesearch/kmcpy/blob/master/example/NASICON.ipynb

Builds a Local Cluster Expansion (LCE) model for a given crystal structure (e.g., NASICON) to facilitate rapid energy calculations within KMC simulations. This involves loading the structure, defining local lattice properties and basis functions, and then constructing and saving the LCE model.

```python
from kmcpy.models.local_cluster_expansion import LocalClusterExpansion
from kmcpy.structure.local_lattice_structure import LocalLatticeStructure
from kmcpy.external.structure import StructureKMCpy

# Load NASICON primitive structure
structure = StructureKMCpy.from_cif(
    filename=f"{file_path}/nasicon.cif",
    primitive=True
)
print(f"Loaded NASICON primitive structure with {len(structure)} atoms.")

# Define local lattice structure around Na site 0
local_lattice_structure = LocalLatticeStructure(
    template_structure=structure,
    center=0,
    cutoff=4.0,
    specie_site_mapping={
        "Na": ["Na", "X"],    # Na or vacancy
        "Zr": "Zr",
        "Si": ["Si", "P"],
        "O": "O"
    },
    basis_type="chebyshev",
    is_write_basis=True,
    exclude_species=["O2-", "O", "Zr4+", "Zr"]
)
print("Local lattice structure created.")
```

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

### Configure and Run KMC Simulation (Python)

Source: https://github.com/caneparesearch/kmcpy/blob/master/example/NASICON.ipynb

Sets up and executes a complete kinetic Monte Carlo simulation workflow using SimulationConfig and KMC classes. This enables the analysis of transport properties like diffusivity and conductivity.

```python
from kmcpy.simulator.config import SimulationConfig
from kmcpy.simulator.kmc import KMC

import numpy as np
import os

import logging

## for more detailed information, we set the logging level to DEBUG
logging.basicConfig(
    level=logging.INFO, # Set to DEBUG to see everything
    format='%(asctime)s - %(name)-28s - %(levelname)-8s - %(message)s',
    datefmt='%Y-%m-%d %H:%M',
    filename='output.log',  # Log to a file named output.log
    filemode='w',  # Overwrite the log file each time
)
```

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

### Run kMC Simulation with Configuration

Source: https://context7.com/caneparesearch/kmcpy/llms.txt

Initializes and runs a kinetic Monte Carlo simulation using a provided configuration object. It requires system and model definitions, along with simulation parameters. Outputs include diffusivity, conductivity, and mean squared displacement.

```python
from kmcpy import KMC, SimulationConfig

# Create configuration with all simulation parameters
config = SimulationConfig.create(
    # System definition
    structure_file="nasicon.cif",
    supercell_shape=[2, 2, 2],
    mobile_ion_specie="Na",
    mobile_ion_charge=1.0,
    elementary_hop_distance=3.47,
    dimension=3,

    # Model files
    cluster_expansion_file="lce.json",
    cluster_expansion_site_file="lce_site.json",
    fitting_results_file="fitting_results.json",
    fitting_results_site_file="fitting_results_site.json",
    event_file="events.json",

    # Simulation conditions
    temperature=573.0,  # Kelvin
    attempt_frequency=1e13,  # Hz
    equilibration_passes=1000,
    kmc_passes=10000,
    random_seed=42,
    name="NaSICON_573K"
)

# Initialize and run simulation
kmc = KMC.from_config(config)
tracker = kmc.run(config)

# Extract results
print(f"Diffusivity: {tracker.diffusivity[-1]} cm²/s")
print(f"Conductivity: {tracker.conductivity[-1]} S/cm")
print(f"MSD: {tracker.msd[-1]} Ų")
```

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

### Build and Save Cluster Expansion Model (Python)

Source: https://github.com/caneparesearch/kmcpy/blob/master/example/NASICON.ipynb

Builds a local cluster expansion model using provided lattice structure and cutoff parameters. The built model is then saved to a JSON file. This process is crucial for defining the energetic landscape of the system for KMC simulations.

```python
from kmcpy.cluster_expansion import LocalClusterExpansion

# Assume local_lattice_structure and file_path are defined elsewhere
cluster_expansion = LocalClusterExpansion()
cluster_expansion.build(
    local_lattice_structure=local_lattice_structure,
    mobile_ion_identifier_type="label",
    mobile_ion_specie_identifier="Na1",
    cutoff_cluster=[6, 6, 0],  # 2-body and 3-body clusters
    cutoff_region=5,
    convert_to_primitive_cell=True,
)
print("Cluster expansion built.")

# Save cluster expansion model to file
output_file = f"{file_path}/lce.json"
cluster_expansion.to_json(output_file)
print(f"Cluster expansion saved to: {output_file}")
```

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

### Custom KMCpy Simulation State Management

Source: https://context7.com/caneparesearch/kmcpy/llms.txt

Illustrates how to create and manage custom simulation states using the SimulationState class, including setting initial occupations, applying events, and checkpointing the state.

```python
from kmcpy.simulator.state import SimulationState
import numpy as np

# Create initial state with specific occupation pattern
initial_occupations = np.zeros(num_sites, dtype=int)
initial_occupations[mobile_sites] = 1  # Occupy specific sites

state = SimulationState(
    occupations=initial_occupations,
    time=0.0,
    total_steps=0
)

# Apply event and update state
event = event_lib.events[0]
state.apply_event(event, dt=1e-9)  # dt in seconds

print(f"Simulation time: {state.time:.9e} s")
print(f"Total steps: {state.total_steps}")
print(f"Current occupations: {state.occupations}")

# Save/load state for checkpointing
state.to_json("checkpoint.json")
state = SimulationState.from_json("checkpoint.json")
```

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

### Fit Energy Parameters (Python)

Source: https://github.com/caneparesearch/kmcpy/blob/master/example/NASICON.ipynb

Fits cluster expansion parameters to reference energy data using the Fitting class. It takes various input files (energy data, weights, correlations) and outputs fitting results and statistics. This step is essential for accurate energy predictions in KMC simulations.

```python
from kmcpy.fitting import Fitting
import numpy as np

# Create fitting object
local_cluster_expansion_fit = Fitting()

# Run energy parameter fitting for EKRA
y_predicted, y_true = local_cluster_expansion_fit.fit(
    alpha=1.5,
    max_iter=1000000,
    ekra_fname=f"{file_path}/local_cluster_expansion/e_kra.txt",
    keci_fname=f"{file_path}/local_cluster_expansion/keci.txt",
    weight_fname=f"{file_path}/local_cluster_expansion/weight.txt",
    corr_fname=f"{file_path}/local_cluster_expansion/correlation_matrix.txt",
    fit_results_fname=f"{file_path}/fitting_results.json",
)
print("EKRA fitting completed.")

# Calculate fitting statistics
residuals = y_predicted - y_true
rmse = np.sqrt(np.mean(residuals**2))
mae = np.mean(np.abs(residuals))
max_error = np.max(np.abs(residuals))

print(f"Fitting quality metrics:")
print(f"  - RMSE: {rmse:.4f} meV")
print(f"  - MAE:  {mae:.4f} meV")
print(f"  - Max error: {max_error:.4f} meV")
print(f"  - Data points: {len(y_true)}")

# Validate fitting quality
fitting_quality = np.allclose(y_predicted, y_true, rtol=0.3, atol=10.0)
print("Fitting quality: GOOD" if fitting_quality else "⚠ Fitting quality: NEEDS ATTENTION")


# Run energy parameter fitting for Esite
y_predicted, y_true = local_cluster_expansion_fit.fit(
    alpha=1.5,
    max_iter=1000000,
    ekra_fname=f"{file_path}/local_cluster_expansion_site/e_site.txt",
    keci_fname=f"{file_path}/local_cluster_expansion_site/keci.txt",
    weight_fname=f"{file_path}/local_cluster_expansion_site/weight.txt",
    corr_fname=f"{file_path}/local_cluster_expansion_site/correlation_matrix.txt",
    fit_results_fname=f"{file_path}/fitting_results_site.json",
)
print("\nEsite fitting completed.")

# Calculate fitting statistics
residuals = y_predicted - y_true
rmse = np.sqrt(np.mean(residuals**2))
mae = np.mean(np.abs(residuals))
max_error = np.max(np.abs(residuals))

print(f"Fitting quality metrics:")
print(f"  - RMSE: {rmse:.4f} meV")
print(f"  - MAE:  {mae:.4f} meV")
print(f"  - Max error: {max_error:.4f} meV")
print(f"  - Data points: {len(y_true)}")

# Validate fitting quality
fitting_quality = np.allclose(y_predicted, y_true, rtol=0.3, atol=10.0)
print("Fitting quality: GOOD" if fitting_quality else "⚠ Fitting quality: NEEDS ATTENTION")
```

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

### Analyze KMCpy Simulation Results with Tracker

Source: https://context7.com/caneparesearch/kmcpy/llms.txt

Shows how to use the Tracker class to access and analyze simulation results, including transport properties, Haven ratio, and trajectory data. Also demonstrates exporting and plotting results.

```python
from kmcpy.simulator.tracker import Tracker
import matplotlib.pyplot as plt

# Access results after simulation
tracker = kmc.run(config)

# Transport properties at each pass
diffusivities = tracker.diffusivity  # cm²/s
conductivities = tracker.conductivity  # S/cm
msd_values = tracker.msd  # ų
times = tracker.time  # seconds

# Haven ratio (correlation factor)
haven_ratio = tracker.haven_ratio[-1]

# Trajectory data
positions = tracker.position_history  # Ion positions over time
occupations = tracker.occupation_history  # Site occupancies

# Export results
tracker.write_results(
    final_occupations=kmc.simulation_state.occupations,
    label="NaSICON_573K"
)

# Plot results
plt.loglog(times, msd_values)
plt.xlabel("Time (s)")
plt.ylabel("MSD (ų)")
plt.savefig("msd_vs_time.png")
```

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

### Load Parameters and Compute Probability in KMCpy

Source: https://context7.com/caneparesearch/kmcpy/llms.txt

Loads fitted parameters for barrier and site models, creates a composite model, and computes the migration probability for an event. Requires pre-defined event1, lce_barrier, and lce_site objects.

```python
from kmcpy.simulator.condition import SimulationCondition
from kmcpy.simulator.state import SimulationState

# Load fitted parameters
lce_barrier.load_parameters_from_file("fitting_results.json")
lce_site.load_parameters_from_file("fitting_results_site.json")

# Create composite model for probability calculations
model = CompositeLCEModel()
model.set_barrier_model(lce_barrier)
model.set_site_model(lce_site)

# Compute migration probability for an event
condition = SimulationCondition(temperature=573.0, attempt_frequency=1e13)
state = SimulationState(occupations=[1, 0, 1, 1, 0, 1])  # Site occupancies

probability = model.compute_probability(
    event=event1,
    simulation_condition=condition,
    simulation_state=state
)
print(f"Hop probability: {probability:.6e} Hz")
```

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

### KMCpy Simulation Configuration File Format

Source: https://context7.com/caneparesearch/kmcpy/llms.txt

Defines the structure of a YAML configuration file for KMCpy simulations, specifying system details, model files, and simulation parameters.

```yaml
# simulation.yaml
kmc:
  type: default
  default:
    # System definition
    template_structure_fname: "nasicon.cif"
    supercell_shape: [2, 2, 2]
    mobile_ion_specie: "Na"
    dimension: 3
    q: 1
    elem_hop_distance: 3.47782
    convert_to_primitive_cell: true
    immutable_sites: ["Zr", "O"]

    # Model files
    lce_fname: "lce.json"
    lce_site_fname: "lce_site.json"
    fitting_results: "fitting_results.json"
    fitting_results_site: "fitting_results_site.json"
    event_fname: "events.json"
    event_dependencies: "dependencies.json"
    initial_state: "initial_state.json"

    # Simulation parameters
    temperature: 573
    v: 1.0e13
    equilibration_pass: 1000
    kmc_pass: 10000
    random_seed: 42
    name: "NaSICON Simulation"
```

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

### Generate Ionic Hopping Events with kMCpy EventGenerator

Source: https://github.com/caneparesearch/kmcpy/blob/master/example/NASICON.ipynb

Generates hopping events for mobile ions (e.g., Na+) in a crystal structure like NASICON using kMCpy's EventGenerator. It requires structure file paths, mobile ion identifiers, and environment cutoffs. The output includes event files and dependency statistics, crucial for KMC simulations.

```python
from kmcpy.event import EventGenerator
import os

# Define file paths and parameters
file_path = f"{os.getcwd()}/files"
structure_file = f"{file_path}/nasicon.cif"
mobile_ion_identifier_type = "label"
mobile_ion_identifiers = ("Na1", "Na2")
local_env_cutoff_dict = {("Na+", "Na+"): 4, ("Na+", "Si4+"): 4}

# Create EventGenerator instance
generator = EventGenerator()

# Generate events for supercell configuration
generator.generate_events(
    structure_file=structure_file,
    local_env_cutoff_dict=local_env_cutoff_dict,
    mobile_ion_identifier_type=mobile_ion_identifier_type,
    mobile_ion_identifiers=mobile_ion_identifiers,
    species_to_be_removed=["O2-", "O", "Zr4+", "Zr"],
    distance_matrix_rtol=0.01,
    distance_matrix_atol=0.01,
    find_nearest_if_fail=False,
    convert_to_primitive_cell=False,
    export_local_env_structure=True,
    supercell_shape=[2, 1, 1],
    event_file=f"{file_path}/events.json",
    event_dependencies_file=f"{file_path}/event_dependencies.csv"
)

from kmcpy.event import EventLib

event_lib = EventLib.from_json(f"{file_path}/events.json")
print(f"Number of unique local environment types: {len(event_lib.events)}")

print(f"Event dependency: {event_lib.get_dependency_statistics()}")
```

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

### Decompress Gzip Files (Shell)

Source: https://github.com/caneparesearch/kmcpy/blob/master/example/NASICON.ipynb

This command decompresses all files ending with the .gz extension in the current directory. It's a common utility for handling compressed data archives. Dependencies: gunzip utility.

```shell
!gunzip *.gz
```

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

### Display CSV File Content (Shell)

Source: https://github.com/caneparesearch/kmcpy/blob/master/example/NASICON.ipynb

This command displays the content of the 'results_NASICON_KMC.csv' file to standard output. It's useful for inspecting raw data before or after processing. Dependencies: cat utility.

```shell
!cat results_NASICON_KMC.csv
```

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

### Fit Migration Barriers from DFT Data

Source: https://context7.com/caneparesearch/kmcpy/llms.txt

Fits cluster expansion coefficients to migration barrier data obtained from DFT calculations using Lasso regression. It requires pre-computed migration barriers, correlation matrices, and weights as input files. The output includes predicted vs. true barrier values, RMSE, and Leave-One-Out Cross-Validation (LOOCV) error.

```python
from kmcpy.fitting import Fitting
import numpy as np

# Prepare training data
# e_kra: DFT-calculated migration barriers (meV)
# correlation_matrix: Cluster correlations for each barrier
# weight: Fitting weights for each data point
np.savetxt("e_kra.txt", dft_barriers)
np.savetxt("correlation_matrix.txt", correlations)
np.savetxt("weight.txt", weights)

# Fit cluster expansion coefficients using Lasso regression
fitter = Fitting()
y_pred, y_true = fitter.fit(
    alpha=0.01,  # Regularization strength
    max_iter=1000000,
    ekra_fname="e_kra.txt",
    keci_fname="keci.txt",
    weight_fname="weight.txt",
    corr_fname="correlation_matrix.txt",
    fit_results_fname="fitting_results.json"
)

# Evaluate fit quality
rmse = np.sqrt(np.mean((y_true - y_pred)**2))
print(f"RMSE: {rmse:.2f} meV")
print(f"LOOCV: {fitter.loocv:.2f} meV")
```

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

### Generate and Manage kMC Events

Source: https://context7.com/caneparesearch/kmcpy/llms.txt

Creates an event library by defining possible ion hops between sites and their associated local environments. It generates a dependency matrix for efficient event updates and provides statistics on event dependencies. The event library can be saved to a JSON file for use in simulations.

```python
from kmcpy.event import Event, EventLib

# Create event library
event_lib = EventLib()

# Define migration events (mobile ion hops)
event1 = Event(
    mobile_ion_indices=(42, 87),  # Hop between sites 42 and 87
    local_env_indices=(10, 15, 23, 45, 67)  # Neighboring sites
)
event2 = Event(
    mobile_ion_indices=(87, 120),
    local_env_indices=(15, 23, 45, 67, 89)
)

# Add events to library
event_lib.add_event(event1)
event_lib.add_event(event2)

# Generate dependency matrix for efficient updates
event_lib.generate_event_dependencies()
stats = event_lib.get_dependency_statistics()
print(f"Total events: {stats['total_events']}")
print(f"Average dependencies per event: {stats['avg_dependencies_per_event']:.1f}")

# Save for simulation
event_lib.to_json("events.json")
```

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

### Build Local Cluster Expansion Model

Source: https://context7.com/caneparesearch/kmcpy/llms.txt

Constructs a Local Cluster Expansion (LCE) model by analyzing the local environment around mobile ion sites in a crystal structure. It uses specified cutoffs to define clusters and saves the resulting model to a JSON file. The output indicates the number of symmetry-unique cluster orbits generated.

```python
from kmcpy import LocalClusterExpansion
from kmcpy.structure import LocalLatticeStructure
from kmcpy.external.structure import StructureKMCpy

# Load crystal structure
structure = StructureKMCpy.from_file("nasicon.cif")

# Define local environment around mobile ion site
local_lattice = LocalLatticeStructure()
local_lattice.build(
    structure=structure,
    cutoff_region=10.0,  # Angstroms
    center_site_index=0,  # Mobile ion site
    exclude_species=["O"]
)

# Build cluster expansion model
lce = LocalClusterExpansion()
lce.build(
    local_lattice_structure=local_lattice,
    cutoff_cluster=[6, 6, 6]  # [pair, triplet, quadruplet] cutoffs
)

# Save model for fitting
lce.to_json("lce_model.json")
print(f"Generated {len(lce.orbits)} symmetry-unique cluster orbits")
```

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

### Load Fitted Cluster Expansion Models

Source: https://context7.com/caneparesearch/kmcpy/llms.txt

Loads previously fitted Local Cluster Expansion (LCE) models from JSON files. This allows for the reuse of trained models for energy calculations or further analysis in kMC simulations. It supports loading multiple LCE models, potentially for different aspects like barrier heights and site occupations.

```python
from kmcpy.models import CompositeLCEModel, LocalClusterExpansion

# Load cluster expansion models
lce_barrier = LocalClusterExpansion.from_json("lce.json")
lce_site = LocalClusterExpansion.from_json("lce_site.json")
```

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

### Plot MSD vs Time from CSV (Python)

Source: https://github.com/caneparesearch/kmcpy/blob/master/example/NASICON.ipynb

Reads simulation results from a CSV file ('results_NASICON_KMC.csv') into a Pandas DataFrame and generates a plot of Mean Squared Displacement (MSD) against time using Matplotlib. Dependencies: pandas, matplotlib.

```python
import matplotlib.pyplot as plt
import pandas as pd

data = pd.read_csv('results_NASICON_KMC.csv')

plt.figure(figsize=(6, 4))
plt.plot(data['time'], data['msd'], 'o', label='MSD')
plt.xlabel('Time (s)')
plt.ylabel('Mean Squared Displacement (MSD)')
plt.title('MSD vs Time')
plt.legend()
plt.tight_layout()
plt.show()
```

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

### Deactivate Python virtual environment

Source: https://github.com/caneparesearch/kmcpy/blob/master/README.md

Command to exit and deactivate the currently active Python virtual environment, returning the shell to the system's default Python environment.

```shell
deactivate
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.