### Development Setup with uv

Source: https://github.com/ddmms/ml-peg/blob/main/README.md

Sets up the development environment for ML-PEG using 'uv' for dependency management. This includes cloning the repository, installing dependencies, activating a virtual environment, installing pre-commit hooks, and running tests.

```shell
git clone https://github.com/ddmms/ml-peg
cd ml-peg
uv sync # Create a virtual environment and install dependencies
source .venv/bin/activate
pre-commit install  # Install pre-commit hooks
pytest -v  # Discover and run all tests
```

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

### Build and Run ML-PEG with Docker

Source: https://context7.com/ddmms/ml-peg/llms.txt

Instructions for deploying the ML-PEG application using Docker. This includes pulling a pre-built image, building from source, downloading application data, and running the container. It also covers using Docker Compose for a multi-container setup.

```bash
# Pull the latest pre-built image
docker pull ghcr.io/ddmms/ml-peg-app:latest

# Or build locally from source
git clone https://github.com/ddmms/ml-peg.git
cd ml-peg
docker build -t ml-peg-app -f containers/Dockerfile .

# Download application data
ml_peg download --key app/data/data.tar.gz --filename data.tar.gz
tar -xzf data.tar.gz -C ml_peg/app/

# Run the container with mounted data
docker run -d \
    --name ml-peg \
    --volume ./ml_peg/app/data:/app/ml_peg/app/data \
    --publish 8050:8050 \
    ml-peg-app

# Access the application at http://localhost:8050

# Alternative: use Docker Compose
docker compose -f containers/compose.yml up -d
```

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

### Run ML-PEG Web Application (CLI)

Source: https://context7.com/ddmms/ml-peg/llms.txt

Starts the interactive Dash-based visualization dashboard for exploring benchmark results. Supports custom ports, model selection, and category filtering. Debug mode is available.

```bash
# Run the app on default port 8050
ml_peg app

# Run on custom port with specific models
ml_peg app --port 8080 --models "mace-mp-0a,orb-v3-consv-inf-omat"

# Run for a specific benchmark category only
ml_peg app --category bulk_crystal --debug
```

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

### Benchmark Calculation Script Setup (Python)

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/tutorials/python/adding_benchmark.ipynb

This Python script demonstrates the initial setup for a benchmark calculation. It includes necessary imports, loading models, and defining paths for data and outputs. This structure is common across most benchmark scripts.

```python
"""Run calculations for X23 tests."""

from __future__ import annotations

from copy import copy
from pathlib import Path
from typing import Any

from ase import units
from ase.io import read, write
import numpy as np
import pytest

from ml_peg.calcs.utils.utils import download_s3_data
from ml_peg.models.get_models import load_models
from ml_peg.models.models import current_models

MODELS = load_models(current_models)

DATA_PATH = Path(__file__).parent / "data"
OUT_PATH = Path(__file__).parent / "outputs"

```

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

### Install and Sync Dependencies with uv

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/get_started.md

Installs project dependencies for Python 3.12 and activates the virtual environment. It also demonstrates how to install optional dependencies like MACE, Orb, and torch-dftd using uv's extra feature.

```shell
uv sync -p 3.12
source .venv/bin/activate
```

```shell
uv sync --extra mace --extra orb --extra d3
```

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

### Install Pre-commit Hooks

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/tutorials/python/adding_benchmark.ipynb

Installs pre-commit hooks to ensure code contributions adhere to project guidelines. This command requires additional dependencies that are typically installed via `uv sync`.

```bash
! pre-commit install
```

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

### Install ML-PEG from PyPI using pip

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/user_guide/get_started.md

Installs the latest stable release of ML-PEG and its dependencies from the Python Package Index (PyPI). This is the recommended method for most users.

```bash
python3 -m pip install ml-peg
```

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

### Install ML-PEG from GitHub using pip

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/user_guide/get_started.md

Installs the latest changes of ML-PEG directly from its GitHub repository. This is useful for developers who want to test the most recent updates.

```bash
python3 -m pip install git+https://github.com/ddmms/ml-peg.git
```

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

### Set Up Automatic Code Style Checks with pre-commit

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/get_started.md

Installs the pre-commit hook to automatically format and lint code before each commit. This setup utilizes ruff for linting and formatting, and numpydoc for docstring validation.

```shell
pre-commit install
```

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

### Setting Up and Syncing Fork with Upstream

Source: https://github.com/ddmms/ml-peg/blob/main/contributing.md

This guide demonstrates how to set up both your local fork and the upstream remote. It covers cloning your fork, adding the upstream remote, and then syncing your local main branch with the upstream main branch.

```shell
# clone your fork
$ git clone git@github.com:username/ml-peg.git ml-peg-username
pushd ml-peg-username
# add a remote for upstream
$ git remote add upstream git@github.com:ddmms/ml-peg.git

# get the latest commits from upstream
$ git fetch upstream
# ensure you are in the main branch of your fork
$ git checkout main
# merge your main branch into the main branch of upstream
$ git merge upstream/main
# push these changes back to the remote of your fork (origin)
$ git push
```

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

### Equivalent Pytest Command for Calculations

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/running.md

Shows the direct pytest command equivalent to the `ml_peg calc` example. This clarifies the underlying test execution for calculations.

```bash
pytest -vvv ml_peg/calcs/surfaces/S24/calc_S24.py --models mace-mp-0b3
```

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

### Run Development Server with Debugging

Source: https://context7.com/ddmms/ml-peg/llms.txt

Starts the ML-PEG development server with debugging enabled. The 'category' argument can be set to '*' for all categories or a specific category name. The 'port' specifies the server port, and 'debug' enables debugging mode.

```python
run_app(
    category="*",  # "*" for all categories, or specific like "bulk_crystal"
    port=8050,
    debug=True,
)
```

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

### Build Documentation with Sphinx

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/get_started.md

Cleans the existing documentation build and generates new HTML documentation using Sphinx. This process requires the 'docs' dependency group and pandoc to be installed.

```shell
cd docs
make clean; make html
```

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

### Run Dash Application Programmatically

Source: https://context7.com/ddmms/ml-peg/llms.txt

Provides a utility function to programmatically start and run a Dash web application. This is useful for development, testing, or deploying the application directly from Python scripts.

```python
from ml_peg.app.run_app import run_app

# Example usage (assuming 'app' is a Dash instance):
# run_app(app)

```

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

### Run ML-PEG with Docker Compose

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/user_guide/get_started.md

Starts the ML-PEG application using Docker Compose, based on the provided compose.yml file. This is a convenient way to manage the application's lifecycle and dependencies.

```bash
docker compose -f containers/compose.yml up -d
```

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

### Define MLIP Models in models.yml

Source: https://context7.com/ddmms/ml-peg/llms.txt

Example structure for defining Machine Learning Interatomic Potential (MLIP) models in the `models.yml` configuration file. This file specifies parameters for various models like MACE, Orb, and PET-MAD, including their modules, class names, device, and optional keyword arguments.

```yaml
# ml_peg/models/models.yml

# MACE model configuration
mace-mp-0a:
  module: mace.calculators
  class_name: mace_mp
  device: "auto"           # "auto", "cpu", or "cuda"
  default_dtype: float32
  trained_on_d3: false     # Whether model includes D3 dispersion
  level_of_theory: PBE     # Training data level of theory
  kwargs:
    model: "medium"

# Orb model configuration
orb-v3-consv-inf-omat:
  module: orb_models.forcefield
  class_name: OrbCalc
  device: "cpu"
  default_dtype: float32-high
  trained_on_d3: false
  level_of_theory: PBE
  kwargs:
    name: "orb_v3_conservative_inf_omat"

# PET-MAD model with D3 correction parameters
pet-mad:
  module: pet_mad.calculator
  class_name: PETMADCalculator
  device: "cpu"
  default_dtype: float32
  trained_on_d3: false
  level_of_theory: PBEsol
  kwargs:
    version: "v1.0.2"
  d3_kwargs:
    xc: pbesol            # D3 XC functional
```

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

### Equivalent Pytest Command for Analysis

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/running.md

Provides the direct pytest command equivalent for the `ml_peg analyse` example, illustrating the underlying test execution for analysis tasks.

```bash
pytest -vvv ml_peg/analysis/surfaces/OC157/analyse_OC157.py --models mace-mp-0b3,orb-v3-consv-inf-omat
```

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

### Download Data from S3 (CLI)

Source: https://context7.com/ddmms/ml-peg/llms.txt

Downloads pre-computed benchmark data from the public S3 bucket for use with the web application. Supports specifying the S3 key, local filename, and custom bucket/endpoint configurations.

```bash
# Download the latest application data
ml_peg download --key app/data/data.tar.gz --filename data.tar.gz

# Download with custom bucket and endpoint
ml_peg download --key results/output.csv --filename output.csv \
    --bucket ml-peg-data --endpoint https://s3.echo.stfc.ac.uk
```

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

### Launch ml-peg Interactive Application

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/running.md

Starts the interactive application using the `ml_peg app` command. This command allows specifying models, categories, the port to run on, and enables/disables Dash debugging.

```bash
ml_peg app --models mace-mp-0b3 --category surfaces --port 8050 --debug
```

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

### ML-PEG App Building - Python Script Setup

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/tutorials/python/adding_benchmark.ipynb

This Python script serves as a template for building interactive Dash applications within the ML-PEG framework. It includes necessary imports for Dash components, utility functions, and data loading. Key configurations like benchmark name, documentation URL, and data path need to be customized for each specific benchmark.

```python
"""Run X23 app."""

from __future__ import annotations

from dash import Dash
from dash.html import Div

from ml_peg.app import APP_ROOT
from ml_peg.app.base_app import BaseApp
from ml_peg.app.utils.build_callbacks import (
    plot_from_table_column,
    struct_from_scatter,
)
from ml_peg.app.utils.load import read_plot
from ml_peg.models.get_models import get_model_names
from ml_peg.models.models import current_models

```

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

### Run ML-PEG Benchmark Calculations (CLI)

Source: https://context7.com/ddmms/ml-peg/llms.txt

Executes benchmark calculations for specified MLIP models, organized by category and test name. Options include running all calculations, specific models, categories, tests, and including slow calculations.

```bash
# Run all calculations for all models
ml_peg calc

# Run calculations for specific models (comma-separated)
ml_peg calc --models "mace-mp-0a,mace-mp-0b3"

# Run calculations for a specific category and test
ml_peg calc --category bulk_crystal --test elasticity

# Include slow calculations (enabled by default)
ml_peg calc --run-slow --run-very-slow
```

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

### Install ML-PEG and Dependencies in Google Colab

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/tutorials/python/adding_benchmark.ipynb

Installs ML-PEG with specific dependencies (MACE, Orb, torch-dftd) and manages NumPy and PyTorch versions for compatibility. It also includes commands to clone the repository and set up the environment.

```python
# ! git clone https://github.com/ddmms/ml-peg
# %cd ml-peg

# import locale
# locale.getpreferredencoding = lambda: "UTF-8"

# ! pip uninstall numpy -y # Uninstall pre-installed numpy

# ! pip uninstall torch torchaudio torchvision transformers -y # Uninstall pre-installed torch
# ! uv pip install torch==2.5.1 # Install pinned version of torch

# ! uv pip install ml-peg[mace,orb,d3] --system # Install ML-PEG with MACE, Orb, and torch-dftd

# get_ipython().kernel.do_shutdown(restart=True) # Restart kernel to update libraries. This may warn that your session has crashed.
```

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

### Run ML-PEG Analysis (CLI)

Source: https://context7.com/ddmms/ml-peg/llms.txt

Processes calculation results to generate metrics, plots, and summary tables for the web application. Analysis can be run for all models, specific models, categories, and tests, with verbose output option.

```bash
# Run all analysis
ml_peg analyse

# Run analysis for specific models
ml_peg analyse --models "mace-mp-0a,orb-v3-consv-inf-omat"

# Run analysis for a specific category and test
ml_peg analyse --category bulk_crystal --test elasticity --verbose
```

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

### Upload Data to S3 (CLI)

Source: https://context7.com/ddmms/ml-peg/llms.txt

Uploads calculation results or data to an S3 bucket, requiring credentials. Allows specifying the S3 key, local filename, credentials path, and access control lists (ACLs).

```bash
# Upload results file to S3
ml_peg upload --key results/my_results.csv --filename my_results.csv \
    --credentials /path/to/credentials.json

# Upload with custom ACL
ml_peg upload --key public/data.json --filename data.json \
    --credentials creds.json --acl public-read
```

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

### Upload Application Data to S3 using ML-PEG CLI

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/data.md

This bash command uploads a compressed archive of application data to the S3 bucket. It specifies the key for the application data and the filename. This is used to update the data required for running the live version of the application.

```bash
ml_peg upload --key app/data/data.tar.gz  --filename data.tar.gz --credentials credentials.json
```

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

### Download ML-PEG Data

Source: https://github.com/ddmms/ml-peg/blob/main/README.md

Downloads a compressed zip file containing ML-PEG data using the 'ml_peg download' command. This is a convenient way to obtain the necessary data for the application.

```shell
ml_peg download --key app/data/data.tar.gz  --filename data.tar.gz
```

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

### Run Unit Tests with pytest

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/get_started.md

Executes all unit tests for the ML-PEG project using the pytest framework. This command requires the 'dev' dependency group to be installed.

```shell
pytest -v
```

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

### Download Benchmark Data from Cloud and Git

Source: https://context7.com/ddmms/ml-peg/llms.txt

Facilitates downloading benchmark datasets from various sources, including S3 buckets and GitHub releases. It supports direct downloads, cached downloads, and automatic extraction of zip archives. Credentials can be provided for private S3 buckets.

```python
from ml_peg.data.data import download
from ml_peg.calcs.utils.utils import download_s3_data, download_github_data
from pathlib import Path

# Download directly from S3 bucket
download(
    key="app/data/data.tar.gz",
    filename="./data/data.tar.gz",
    bucket="ml-peg-data",
    endpoint="https://s3.echo.stfc.ac.uk",
    credentials=None,  # None for public data
)

# Download with caching to ~/.cache/ml_peg/
data_path = download_s3_data(
    key="benchmarks/elasticity.zip",
    filename="elasticity.zip",
    force=False,  # Use cached version if available
)
print(f"Data extracted to: {data_path}")

# Download from GitHub with automatic extraction
data_dir = download_github_data(
    filename="benchmark_data.zip",
    github_uri="https://github.com/ddmms/ml-peg/releases/download/v0.2.0",
    force=False,
)
```

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

### Build Custom Dash Benchmark Application

Source: https://context7.com/ddmms/ml-peg/llms.txt

Enables the creation of custom benchmark visualization pages using the Dash framework. It involves extending a base application class, defining the layout with Dash components (Div, H2, P, DataTable, Graph), and registering callbacks for interactivity.

```python
from ml_peg.app.base_app import BaseApp
from dash.html import Div, H2, P
from dash.dcc import Graph
from dash.dash_table import DataTable
import json

# Define benchmark layout and callbacks
class MyBenchmarkApp(BaseApp):
    def __init__(self):
        super().__init__(
            name="My Benchmark",
            description="Custom benchmark for testing new properties",
        )

    def build_layout(self):
        # Load precomputed results
        with open("results/my_benchmark_metrics.json") as f:
            metrics_data = json.load(f)

        # Create table from metrics
        table = DataTable(
            id="my-benchmark-table",
            data=metrics_data["table_data"],
            columns=[{"name": c, "id": c} for c in metrics_data["columns"]],
            sort_action="native",
        )
        self.table = table

        # Build layout
        self.layout = Div([
            H2("My Custom Benchmark"),
            P("Description of what this benchmark tests"),
            table,
            Graph(id="my-benchmark-figure"),
        ])

    def register_callbacks(self):
        # Register interactive callbacks here
        pass

def get_app():
    app = MyBenchmarkApp()
    app.build_layout()
    return app
```

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

### Example Category Directory Structure

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/add_category.md

Illustrates the required directory structure for adding a new category and test within the 'calcs' directory. This structure is essential for the automatic inference of categories by the ML-PEG system.

```default
ml_peg/calcs/new_category/new_test/calc_new_test.py
```

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

### Load MLIP Models (Python API)

Source: https://context7.com/ddmms/ml-peg/llms.txt

Loads machine learning interatomic potential (MLIP) models from the ML-PEG registry. Supports loading all models or specific ones by name, retrieving model names, and obtaining ASE calculators for use in simulations.

```python
from ml_peg.models.get_models import load_models, get_model_names

# Load all available models
all_models = load_models()
print(f"Loaded {len(all_models)} models")

# Load specific models by name (comma-separated string or list)
selected_models = load_models("mace-mp-0a,mace-mp-0b3")

# Get just the model names without loading
model_names = get_model_names()
# Returns: ['mace-mp-0a', 'mace-mp-0b3', 'mace-mpa-0', 'orb-v3-consv-inf-omat', ...]

# Get an ASE calculator from a loaded model
model = selected_models["mace-mp-0a"]
calc = model.get_calculator()

# Use the calculator with ASE
from ase.build import bulk
atoms = bulk("Cu", "fcc", a=3.6)
atoms.calc = calc
energy = atoms.get_potential_energy()
forces = atoms.get_forces()
print(f"Energy: {energy:.4f} eV, Max force: {forces.max():.4f} eV/A")
```

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

### Upload Data to S3 using ML-PEG CLI

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/data.md

This bash command uploads a file to an S3 bucket managed by ML-PEG. It requires specifying the key (destination path within the bucket), the filename, and credentials. This is used for making data available for download via S3.

```bash
ml_peg upload --key inputs/surfaces/S24/S24.zip  --filename S24.zip --credentials credentials.json
```

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

### Optional Category Configuration YAML

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/add_category.md

Provides an example of a YAML file used to define a human-friendly name and description for a category. This file, when placed in the 'ml_peg/app/[category]' directory and named '[category].yml', customizes the category's display in the ML-PEG application.

```yaml
title: New category
description: New category description
```

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

### Download Data from S3 using ML-PEG CLI

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/data.md

This bash command downloads a file from an S3 bucket managed by ML-PEG. It requires specifying the key (source path within the bucket) and the filename. This is used for retrieving data stored in S3.

```bash
ml_peg download --key inputs/surfaces/S24/S24.zip  --filename S24.zip
```

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

### Download Data from GitHub using Python

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/data.md

This Python function downloads data from a specified GitHub repository and saves it to a local cache. It automatically handles unzipping of downloaded files. This is useful for accessing datasets required for calculations and analysis.

```python
from ml_peg.calcs.utils.utils import download_github_data

data_dir = download_github_data(
    filename="LNCI16_data.zip",
    github_uri="https://raw.githubusercontent.com/joehart2001/mlipx/main/benchmark_data/",
)
```

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

### Run Elasticity Benchmark with ML Models

Source: https://context7.com/ddmms/ml-peg/llms.txt

Executes an elasticity benchmark to assess bulk and shear modulus predictions from ML models against DFT data. It requires loading models, configuring relaxation parameters, and specifying output directories. Results are saved to a CSV file.

```python
from pathlib import Path
from ml_peg.calcs.bulk_crystal.elasticity.calc_elasticity import run_elasticity_benchmark
from ml_peg.models.get_models import load_models

# Load model and get calculator
models = load_models("mace-mp-0a")
calc = models["mace-mp-0a"].get_calculator()

# Run elasticity benchmark
run_elasticity_benchmark(
    calc=calc,
    model_name="mace-mp-0a",
    out_dir=Path("./elasticity_results/mace-mp-0a"),
    n_jobs=4,  # Parallel workers
    norm_strains=(-0.1, -0.05, 0.05, 0.1),
    shear_strains=(-0.02, -0.01, 0.01, 0.02),
    relax_structure=True,
    relax_deformed_structures=True,
    use_checkpoint=True,  # Enable checkpointing for long runs
    fmax=0.05,  # Force threshold for relaxation
)

# Results saved to ./elasticity_results/mace-mp-0a/moduli_results.csv
```

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

### Instantiate X23 Benchmark App (Python)

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/tutorials/python/adding_benchmark.ipynb

This Python function, `get_app`, instantiates the `X23App` class, configuring the benchmark application. It takes global variables, a description, documentation URL, and data table path as input. It also specifies placeholder IDs for extra interactive components like the scatter plot and structure visualization.

```python
def get_app() -> X23App:
    """
    Get X23 benchmark app layout and callback registration.

    Returns
    -------
    X23App
        Benchmark layout and callback registration.
    """
    return X23App(
        name=BENCHMARK_NAME,
        description="Lattice energies for 23 organic molecular crystals.",
        docs_url=DOCS_URL,
        table_path=DATA_PATH / "x23_metrics_table.json",
        extra_components=[
            Div(id=f"{BENCHMARK_NAME}-figure-placeholder"),
            Div(id=f"{BENCHMARK_NAME}-struct-placeholder"),
        ],
    )
```

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

### Build ML-PEG Docker Image

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/user_guide/get_started.md

Builds a Docker image for the ML-PEG application using the provided Dockerfile. This allows for self-contained deployment and execution.

```bash
docker build -t ml-peg-app -f containers/Dockerfile .
```

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

### Run ML-PEG Analysis via CLI

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/tutorials/python/adding_benchmark.ipynb

This command initiates an analysis using the ML-PEG CLI. It requires specifying a category and a test identifier. Refer to the official CLI documentation for more details on available options and parameters.

```bash
ml_peg analyse --category molecular_crystal --test X23
```

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

### Run ML-PEGs Dash Application

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/tutorials/python/adding_benchmark.ipynb

This Python code snippet demonstrates how to create and run a Dash application for ML-PEGs. It initializes the Dash app, sets its layout using a pre-defined app object, registers necessary callbacks, and then runs the application on a specified port (8055) with debugging enabled. This is useful for local testing and development.

```python
if __name__ == "__main__":
    # Create Dash app
    full_app = Dash(__name__, assets_folder=DATA_PATH.parent.parent)

    # Construct layout and register callbacks
    x23_app = get_app()
    full_app.layout = x23_app.layout
    x23_app.register_callbacks()

    # Run app
    full_app.run(port=8055, debug=True)
```

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

### Get Labels for Structures - Python

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/add_benchmarks.md

Retrieves a list of labels from structure data. It reads structure information from a specified file path and extracts the 'label' from each structure's info dictionary. Assumes the existence of a 'read' function and a 'CALC_PATH' variable.

```python
from ml_peg.analysis.utils.decorators import build_table, plot_parity
from ml_peg.analysis.utils.utils import mae
from ml_peg.app import APP_ROOT
from ml_peg.calcs import CALCS_ROOT
from ml_peg.models.get_models import get_model_names
from ml_peg.models.models import current_models

MODELS = get_model_names(current_models)
CALC_PATH = CALCS_ROOT / [category] / [benchmark_name] / "outputs"
OUT_PATH = APP_ROOT / "data" / [category] / [benchmark_name]

REF_VALUES = {"path_b": 0.27, "path_c": 2.5}

def labels() -> list:
    """
    Get list of labels.

    Returns
    -------
    list
        List of all energy labels.
    """
    structs = read(CALC_PATH / "structs.xyz", index=":")
    return [struct.info["label"] for struct in structs]
```

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

### Run ML-PEG Docker Container

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/user_guide/get_started.md

Runs the ML-PEG application as a Docker container, mounting local data and publishing the application port. This command assumes the Docker image has already been built.

```bash
docker run --volume ./ml_peg/app/data:/app/ml_peg/app/data  --publish 8050:8050 ml-peg-app
```

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

### Create and Checkout New Branch Locally

Source: https://github.com/ddmms/ml-peg/blob/main/contributing.md

These commands first clone the repository (if not already present), navigate into the directory, create a new branch named 'fix-xyz', and then checkout that new branch. This is part of the 'branch, fix, merge' workflow.

```sh
# clone the repository, if you already have a local repository this is not nessecary
$ git clone git@github.com:username/ml-peg.git ml-peg-fix-xyz
$ pushd ml-peg-fix-xyz
# create and checkout a new branch (this is equivalent to git branch followed by git checkout)
$ git checkout -b fix-xyz
# create a remote tracking branch for you to push your changes to
$ git push -u origin fix-xyz
```

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

### Add D3 Dispersion Correction (Python API)

Source: https://context7.com/ddmms/ml-peg/llms.txt

Applies D3 dispersion corrections to ASE calculators for MLIP models not inherently trained with dispersion. This function checks if a model requires D3 correction and returns a SumCalculator with the correction applied if necessary.

```python
from ml_peg.models.get_models import load_models
from ase.build import molecule

# Load a model not trained with D3
models = load_models("mace-mp-0a")
model = models["mace-mp-0a"]

# Check if model needs D3 correction
print(f"Trained on D3: {model.trained_on_d3}")  # False

# Get base calculator
base_calc = model.get_calculator()

# Add D3 dispersion correction (returns SumCalculator if needed)
d3_calc = model.add_d3_calculator(base_calc)

# Use corrected calculator
atoms = molecule("H2O")
atoms.calc = d3_calc
energy = atoms.get_potential_energy()
print(f"Energy with D3: {energy:.4f} eV")
```

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

### Basic Git Workflow: Add, Commit, Push

Source: https://github.com/ddmms/ml-peg/blob/main/contributing.md

This snippet covers the fundamental Git commands to stage changes, commit them with a message, and push them to the remote repository. It's the standard workflow for saving and sharing code modifications.

```shell
# add the new things
$ git add <filename|folder>
# commit the changes with a clear and brief message
$ git commit -m "<commit message>"
# push the commit to origin
$ git push
```

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

### Analysis Utilities for Benchmark Metrics

Source: https://context7.com/ddmms/ml-peg/llms.txt

Provides functions to compute common error metrics (MAE, RMSE), normalize scores to a [0, 1] range, and calculate weighted scores for benchmark results. It utilizes pandas DataFrames and configuration files for thresholds and weights.

```python
from ml_peg.analysis.utils.utils import (
    mae, rmse, normalize_metric,
    calc_table_scores, load_metrics_config
)
from pathlib import Path
import pandas as pd

# Calculate error metrics
reference = [100, 150, 200, 250, 300]
predictions = [105, 148, 210, 245, 295]

mae_value = mae(reference, predictions)
rmse_value = rmse(reference, predictions)
print(f"MAE: {mae_value:.2f}, RMSE: {rmse_value:.2f}")
# Output: MAE: 6.00, RMSE: 6.32

# Normalize a metric value to [0, 1] range
# Good threshold maps to 1.0, bad threshold maps to 0.0
score = normalize_metric(value=5.0, good_threshold=0.0, bad_threshold=20.0)
print(f"Normalized score: {score:.2f}")  # 0.75

# Load metrics configuration from YAML
config_path = Path("ml_peg/analysis/bulk_crystal/elasticity/metrics.yml")
thresholds, tooltips, weights = load_metrics_config(config_path)
print(f"Metrics: {list(thresholds.keys())}")
# Output: Metrics: ['Bulk modulus MAE', 'Shear modulus MAE']

# Calculate weighted scores for table data
table_data = [
    {"MLIP": "mace-mp-0a", "Bulk modulus MAE": 8.5, "Shear modulus MAE": 6.2},
    {"MLIP": "mace-mp-0b3", "Bulk modulus MAE": 7.8, "Shear modulus MAE": 5.9},
]
scored_data = calc_table_scores(table_data, weights=weights, thresholds=thresholds)
for row in scored_data:
    print(f"{row['MLIP']}: Score = {row['Score']:.3f}")
```

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

### Load Benchmark Configuration Defaults in Python

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/scoring_and_normalisation.md

This Python code snippet shows how to load default thresholds, tooltips, and weights for benchmark metrics using the `load_metrics_config` function. These defaults are typically stored in a configuration file specified by `METRICS_CONFIG_PATH` and are essential for consistent metric processing.

```python
DEFAULT_THRESHOLDS, DEFAULT_TOOLTIPS, DEFAULT_WEIGHTS = load_metrics_config(METRICS_CONFIG_PATH)
```

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

### Apply Benchmark Configuration with @build_table Decorator in Python

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/scoring_and_normalisation.md

This Python code illustrates how to use the `@build_table` decorator to apply loaded benchmark configurations, including metric tooltips, thresholds, and weights. This decorator is used in analysis files to generate metric tables, ensuring that the scoring and normalisation adhere to the specified settings. It requires parameters like `filename`, `metric_tooltips`, `thresholds`, `mlip_name_map`, and `weights`.

```python
@build_table(
    filename=OUT_PATH / "x23_metrics_table.json",
    metric_tooltips=DEFAULT_TOOLTIPS,
    thresholds=DEFAULT_THRESHOLDS,
    mlip_name_map=D3_MODEL_NAMES,
    weights=DEFAULT_WEIGHTS,
)
```

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

### Download Data from S3 using Python

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/data.md

This Python function downloads data from the ML-PEG S3 bucket using a specified key and filename. It automatically handles unzipping of downloaded files and returns the path to the cached data. This is useful for accessing datasets for calculations and analysis.

```python
from ml_peg.calcs.utils.utils import download_s3_data

data_dir = download_s3_data(filename="S24.zip", key="inputs/surfaces/S24/S24.zip")
```

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

### Run Benchmark Calculations with Pytest

Source: https://github.com/ddmms/ml-peg/blob/main/docs/source/developer_guide/add_benchmarks.md

This Python script demonstrates how to run benchmark calculations for multiple MLIP models using pytest parametrization. It loads models, reads structural data, sets up calculators, performs energy calculations, and writes results to output directories. Dependencies include pytest, ml_peg.models, and Path.

```python
from ml_peg.models.get_models import load_models
from ml_peg.models.models import current_models
from pathlib import Path
from ase.io import read, write
import pytest
from typing import Any

MODELS = load_models(current_models)
DATA_PATH = Path(__file__).parent / "data"
OUT_PATH = Path(__file__).parent / "outputs"


@pytest.mark.parametrize("mlip", MODELS.items()) # type: ignore
def test_benchmark(mlip: tuple[str, Any]) -> None:
    """
    Run calculations required for lithium diffusion along path B.

    Parameters
    ----------
    mlip
        Name of model use and model to get calculator.
    """
    model_name, model = mlip

    struct = read(DATA_PATH / "struct.xyz")
    struct.calc = model.get_calculator()

    struct.get_potential_energy()

    write_dir = OUT_PATH / model_name
    write_dir.mkdir(parents=True, exist_ok=True)
    write(write_dir / "struct.xyz", struct)
```