### Linux Installation with uv

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/install.org

Install uv and then add chemparseplot for the fastest installation on Linux.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
uv add chemparseplot
```

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

### macOS Installation with Homebrew

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/install.org

Install Python using Homebrew and then install chemparseplot using pip.

```bash
brew install python
pip install chemparseplot
```

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

### Install chemparseplot

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/faq.org

Basic installation using pip. For plotting capabilities, install with the '[plot]' extra. To include all optional dependencies, use '[all]'.

```bash
# Basic installation
pip install chemparseplot

# With plotting dependencies
pip install "chemparseplot[plot]"

# With all optional dependencies
pip install "chemparseplot[all]"
```

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

### Development Installation

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/install.org

Clone the repository and install chemparseplot in editable mode with all dependencies for development.

```bash
# Clone repository
git clone https://github.com/HaoZeke/chemparseplot
cd chemparseplot

# Install in editable mode with all dependencies
uv sync --all-extras

# Run tests
uv run pytest
```

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

### Include Examples in Docstrings

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/dev/best_practices.org

Enhance documentation by including runnable examples within docstrings to illustrate function usage.

```python
def plot_profile(data, output):
    """Plot energy profile.

    Parameters
    ----------
    data : dict
        Parsed NEB data
    output : Path
        Output file path

    Example
    -------
    >>> data = parse_orca_neb("job")
    >>> plot_profile(data, "profile.pdf")
    """
    ...
```

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

### Install chemparseplot with All Optional Extras

Source: https://github.com/haozeke/chemparseplot/blob/main/doc/source/installation.md

Install chemparseplot with all available optional extras.

```bash
pip install "chemparseplot[all]"
```

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

### Development Install for chemparseplot

Source: https://github.com/haozeke/chemparseplot/blob/main/doc/source/installation.md

Set up the development environment for chemparseplot by cloning the repository and installing with all development dependencies.

```bash
git clone https://github.com/HaoZeke/chemparseplot
cd chemparseplot
# Install with all dev dependencies
uv sync --all-extras
```

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

### Install JAX for GP Surface Fitting

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/troubleshooting.org

Install JAX if you need Gaussian Process (GP) surface fitting for landscape plots. Choose the appropriate installation command based on whether you need CPU or GPU support.

```bash
pip install "jax[cpu]"  # CPU-only
```

```bash
pip install "jax[cuda12]"  # With CUDA support
```

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

### Install Chemparseplot

Source: https://github.com/haozeke/chemparseplot/blob/main/readme_src.org

Install the library using pip. Use extras for plotting or all features.

```bash
pip install chemparseplot
```

```bash
# With plotting support
pip install "chemparseplot[plot]"
```

```bash
# Everything
pip install "chemparseplot[all]"
```

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

### Set Up Development Environment

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/dev/contributing.org

Install project dependencies using uv or pip. The uv command syncs all extras, while the pip command installs the package in editable mode with all extras and test dependencies.

```bash
# Using uv (recommended)
uv sync --all-extras

# Or using pip
python -m venv .venv
source .venv/bin/activate
pip install -e ".[all,test]"
```

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

### conda Installation

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/install.org

Install chemparseplot from the conda-forge channel using conda.

```bash
conda install -c conda-forge chemparseplot
```

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

### Troubleshoot Permission Error with User Install

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/install.org

If installation fails with a permission error, use the --user flag to install chemparseplot.

```bash
pip install --user chemparseplot
```

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

### Install chemparseplot

Source: https://github.com/haozeke/chemparseplot/blob/main/doc/source/installation.md

Use this command for basic installation of the chemparseplot library. It automatically installs rgpycrumbs as a dependency.

```bash
pip install chemparseplot
```

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

### Install chemparseplot with 3D Structure Rendering

Source: https://github.com/haozeke/chemparseplot/blob/main/doc/source/installation.md

Install chemparseplot with optional extras for 3D structure rendering.

```bash
pip install "chemparseplot[xyzrender]"
```

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

### Verify Installation

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/install.org

Check if chemparseplot is installed correctly by printing its version number.

```bash
python -c "import chemparseplot; print(chemparseplot.__version__)"
```

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

### Install chemparseplot

Source: https://context7.com/haozeke/chemparseplot/llms.txt

Install chemparseplot with optional support for plotting or NEB calculations.

```bash
pip install chemparseplot
# With plotting support
pip install "chemparseplot[plot]"
# With NEB support (ASE, h5py, polars)
pip install "chemparseplot[neb]"
# Everything
pip install "chemparseplot[all]"
```

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

### Install chemparseplot with Plotting Support

Source: https://github.com/haozeke/chemparseplot/blob/main/doc/source/installation.md

Install chemparseplot with optional extras for plotting, including matplotlib and cmcrameri colormaps.

```bash
pip install "chemparseplot[plot]"
```

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

### Install chemparseplot

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/index.org

Install the library using pip. Use the optional plot extra for plotting capabilities and orca-pi for ORCA NEB support.

```bash
pip install chemparseplot
```

```bash
pip install "chemparseplot[plot]"
```

```bash
pip install orca-pi
```

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

### uv Installation

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/install.org

Add chemparseplot to your project using the uv package manager.

```bash
uv add chemparseplot
```

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

### Python Function with Docstring and Example

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/dev/contributing.org

Illustrates a Python function with a comprehensive docstring including parameters and an example usage. All public functions require docstrings.

```python
def plot_energy_profile(
    data: dict[str, Any],
    output: Path,
    width: float = 5.37,
) -> None:
    """Plot NEB energy profile.

    Parameters
    ----------
    data
        Parsed NEB data from parse_orca_neb()
    output
        Output file path
    width
        Figure width in inches

    Example
    -------
    >>> data = parse_orca_neb("job")
    >>> plot_energy_profile(data, "profile.pdf")
    """
    ...
```

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

### Install chemparseplot with NEB Analysis Support

Source: https://github.com/haozeke/chemparseplot/blob/main/doc/source/installation.md

Install chemparseplot with optional extras for NEB analysis, including ase, h5py, and polars.

```bash
pip install "chemparseplot[neb]"
```

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

### ORCA 6.1+ Support Installation

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/install.org

Install the official ORCA Python Interface for parsing ORCA 6.1+ JSON output.

```bash
pip install orca-pi
```

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

### Verify Python Environment and Install

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/faq.org

Check the current Python executable path to ensure installation in the correct environment. If 'ModuleNotFoundError' occurs, reinstall using the correct Python interpreter.

```bash
# Check Python path
python -c "import sys; print(sys.executable)"

# Install in correct environment
/path/to/python -m pip install chemparseplot
```

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

### Setup Publication Theme

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/create_neb_figures.org

Applies a theme optimized for publications, including line width, spine removal, and DPI defaults. Use this for final figures.

```python
from chemparseplot.plot.theme import setup_publication_theme

theme = get_theme("ruhi")
setup_publication_theme(theme)
```

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

### Troubleshoot Permission Error with Virtual Environment

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/install.org

If installation fails with a permission error, create and activate a virtual environment before installing chemparseplot.

```bash
python -m venv .venv
source .venv/bin/activate
pip install chemparseplot
```

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

### pixi Installation

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/install.org

Add chemparseplot to your project using the pixi package manager.

```bash
pixi add chemparseplot
```

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

### Plotting Theme System

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/dev/contributing.org

Example of how to access and use a plotting theme from the 'theme' module. Themes allow for consistent styling across plots.

```python
from chemparseplot.plot.theme import get_theme
theme = get_theme("ruhi")
```

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

### Setup Global Theme

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/create_neb_figures.org

Applies a built-in theme globally to all subsequent plots. Requires importing `get_theme` and `setup_global_theme` from `chemparseplot.plot.theme`.

```python
from chemparseplot.plot.theme import get_theme, setup_global_theme


```

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

### Troubleshoot Module Not Found

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/install.org

If 'ModuleNotFoundError' occurs, verify the Python environment and install in the correct one.

```bash
# Check which Python is being used
which python
python --version

# Install in correct environment
/path/to/python -m pip install chemparseplot
```

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

### Render Structure Strip with xyzrender Backend

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/create_neb_figures.org

Renders a structure strip using the 'xyzrender' backend for ray-traced images. Requires installation of 'xyzrender'. Pass the axes, list of atoms, and labels to the function.

```python
# Requires: pip install 'xyzrender>=0.1.3'
plot_structure_strip(
    ax, atoms_list, labels,
    renderer="xyzrender",
)
```

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

### ORCA Input File Configuration

Source: https://github.com/haozeke/chemparseplot/blob/main/doc/source/tutorials/orca/geomscan.md

Example ORCA input file configuration for a geometry scan of H2, specifying optimization parameters and scan details.

```yaml
!OPT UHF def2-SVP
%geom Scan
 # B <atmid1> <atmid2> = init, final, npoints
 # Converted from Angstrom to Bohr
 B 0 1 = 7.5589039543, 0.2116708996, 33
 end
end
*xyzfile 0 1 h2_base.xyz
```

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

### Install chemparseplot Package

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/troubleshooting.org

Use this command to install the chemparseplot package if you encounter a 'No module named chemparseplot' error. Ensure you are in the correct Python environment.

```bash
which python
python --version
python -m pip install chemparseplot
```

```bash
/path/to/python -m pip install chemparseplot
```

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

### Install chemparseplot with Conda/Pixi

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/faq.org

Install chemparseplot using package managers like pixi or conda. For conda, the package is available on conda-forge.

```bash
# Using pixi
pixi add chemparseplot

# Using conda (via conda-forge)
conda install -c conda-forge chemparseplot
```

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

### Python Function with Type Hints

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/dev/contributing.org

Example of a Python function with type hints for parameters and return values. All public functions should have type hints to achieve 90%+ coverage.

```python
def parse_orca_neb(
    basename: str,
    working_dir: Path | None = None,
) -> dict[str, Any]:
    """Parse ORCA NEB calculation."""
    ...
```

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

### Run Pure Python Tests

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/dev/index.org

Execute the pure Python tests using pytest. Ensure you have the necessary dependencies installed.

```bash
uv run pytest -m pure
```

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

### Run ORCA NEB Calculation

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/tutorials/orca_neb.org

This snippet shows the ORCA input file for a NEB calculation and the bash command to run it. Ensure ORCA 6.1+ is installed and on your PATH.

```text
! B3LYP def2-SVP NEB-CI
%neb
  nimages = 7
  Product "prod.xyz"
end
*xyzfile 0 1 react.xyz
```

```bash
orca job.inp > job.out
```

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

### Unit-Aware Quantity Creation and Conversion with pint

Source: https://github.com/haozeke/chemparseplot/blob/main/ARCHITECTURE.md

Demonstrates how to create quantities with units using Q_ and perform automatic unit conversions. This is crucial for ensuring dimensional consistency in physical calculations.

```python
from chemparseplot.units import Q_

energy = Q_(-123.456, "hartree")
print(energy.to("kcal/mol"))  # Automatic conversion
```

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

### Add and Manage Data with Units

Source: https://context7.com/haozeke/chemparseplot/llms.txt

Demonstrates adding datasets with physical units using Q_ and XYData, dynamically changing units, and removing data by label. Ensure Q_ and XYData are imported.

```python
x_data = Q_(np.linspace(0.5, 3.0, 15), "bohr")
y_data = Q_(np.exp(-(x_data.m - 2.0)**2) * 0.5, "hartree")
plotter.add_data(XYData(label="Ground State", x=x_data, y=y_data))

x_excited = Q_(np.linspace(0.5, 3.0, 15), "bohr")
y_excited = Q_(np.exp(-(x_excited.m - 2.5)**2) * 0.3 + 0.2, "hartree")
plotter.add_data(XYData(label="Excited State", x=x_excited, y=y_excited))

plotter.set_units("bohr", "hartree")

plotter.rmdat("Excited State")

plotter.fig.savefig("interactive_plot.png", dpi=200)
```

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

### Run Jupyter Lab for Tutorials

Source: https://github.com/haozeke/chemparseplot/blob/main/doc/source/tutorials/contribdoc.md

Use this command to launch Jupyter Lab with remote access enabled and a specific port, typically for development environments.

```bash
uv run jupyter lab --ServerApp.allow_remote_access=1 \
    --ServerApp.open_browser=False --port=8889
```

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

### Clone the Repository

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/dev/contributing.org

Clone the chemparseplot repository and navigate into the project directory.

```bash
git clone https://github.com/your-username/chemparseplot
cd chemparseplot
```

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

### Execute ORCA Scan and Compress Output

Source: https://github.com/haozeke/chemparseplot/blob/main/doc/source/tutorials/orca/geomscan.md

Shell commands to set up the ORCA environment, run the geometry scan, and compress the output file for easier handling.

```bash
export PATH=$PATH:/blah/orca_5_0_4_linux_x86-64_openmpi411/
mkdir uhf
cp orca.inp h2_base.xyz uhf
cd uhf
($(which orca) orca.inp 2>&1) | tee scan_uhf
```

```bash
gzip -9 -c scan_uhf > scanuhf.gz
mv scanuhf.gz ../data/
```

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

### Import necessary libraries for ChemGP plotting

Source: https://github.com/haozeke/chemparseplot/blob/main/doc/source/tutorials/chemgp/convergence.md

Imports required libraries such as h5py, numpy, pandas, and specific plotting functions from chemparseplot.plot.chemgp. Ensure these libraries are installed.

```python
import h5py
import numpy as np
import pandas as pd
from pathlib import Path

from chemparseplot.plot.chemgp import (
    plot_convergence_curve,
    plot_rff_quality,
    plot_energy_profile,
    plot_fps_projection,
)
```

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

### Render Structure Strip (Gallery)

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/create_neb_figures.org

Creates a horizontal gallery of atomic structures below an energy profile. Requires a list of atomic structures, corresponding labels, and optionally zoom, rotation, theme color, and max columns. Supports 'ase' or 'xyzrender' backends.

```python
from chemparseplot.plot.neb import plot_structure_strip

fig, (ax_energy, ax_struct) = plt.subplots(
    2, 1, figsize=(7, 6), height_ratios=[3, 1]
)

plot_structure_strip(
    ax_struct,
    atoms_list=[atoms_list[0], atoms_list[3], atoms_list[-1]],
    labels=["Reactant", "TS", "Product"],
    zoom=0.3,
    rotation="0x,90y,0z",
    theme_color="black",
    max_cols=6,
    renderer="ase",          # or "xyzrender" for ray-traced images
)
```

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

### Parse ORCA NEB Output with Python

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/tutorials/orca_neb.org

Parses ORCA NEB calculation output using the `parse_orca_neb` function from `chemparseplot`. Requires ORCA output files and `orca-pi` to be installed.

```python
# SKIP-DOCTEST -- requires ORCA output files
from pathlib import Path
from chemparseplot.parse.orca.neb import parse_orca_neb

# Parse the ORCA NEB calculation
data = parse_orca_neb("job", working_dir=Path("."))

# Inspect the parsed data
print(f"Number of images: {data['n_images']}")
print(f"Converged: {data['converged']}")
print(f"Energies (eV): {data['energies']}")
print(f"Barrier (forward): {data['barrier_forward']:.2f} eV")
print(f"Barrier (reverse): {data['barrier_reverse']:.2f} eV")
```

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

### Create NLL Hyperparameter Landscape Plots

Source: https://context7.com/haozeke/chemparseplot/llms.txt

Visualizes negative log-likelihood landscapes for GP hyperparameter optimization. Requires numpy.

```python
import numpy as np
from chemparseplot.plot.chemgp import plot_nll_landscape

# Create hyperparameter grid
log_sigma2 = np.linspace(-3, 3, 50)
log_theta = np.linspace(-3, 3, 50)
X, Y = np.meshgrid(log_sigma2, log_theta)

# Simulated NLL surface (quadratic bowl with noise)
NLL = (X - 0.5)**2 + (Y + 1)**2 + np.random.normal(0, 0.1, X.shape)

# Gradient norm (optional overlay)
grad_norm = np.sqrt(2*(X - 0.5)**2 + 2*(Y + 1)**2)

# Plot NLL landscape with optimum marker
fig = plot_nll_landscape(
    X, Y, NLL,
    grid_grad_norm=grad_norm,  # Dashed contour overlay
    optimum=(0.5, -1.0),  # Mark the optimum location
    width=6.0,
    height=5.0,
)

fig.savefig("nll_landscape.pdf", dpi=300, bbox_inches='tight')
```

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

### Initialize and configure a TwoDimPlot object

Source: https://github.com/haozeke/chemparseplot/blob/main/doc/source/worklog/graphTrials.md

Sets up a TwoDimPlot object, defining labels and units for the axes. This prepares the plot for adding data points.

```python
twodim_plot = TwoDimPlot()
twodim_plot.set_labels('Distance', 'Energy')
twodim_plot.set_units('angstrom', 'hartree')
```

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

### Optimize Landscape Plotting Performance

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/troubleshooting.org

Improve landscape plotting performance by reducing the number of points or using simpler methods like 'rbf' with fewer inducing points. This example shows using 'rbf' with `n_inducing=100`.

```python
plot_orca_neb_landscape(
    data, "landscape.pdf",
    method="rbf",  # Faster than GP methods
    n_inducing=100  # Fewer inducing points
)
```

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

### Convert Energy Units

Source: https://github.com/haozeke/chemparseplot/blob/main/doc/source/tutorials/orca/geomscan.md

Demonstrates converting the extracted energy data to Angstrom units using pint for consistent unit management.

```python
act_energy[0].to('angstrom')
```

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

### Pin Dependencies in Production

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/dev/best_practices.org

Specify exact version ranges for dependencies in production environments using `pyproject.toml` to ensure reproducible builds.

```toml
# pyproject.toml
[project]
dependencies = [
    "chemparseplot>=0.2.0,<0.3.0",
]
```

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

### Run CI Checks Locally

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/dev/contributing.org

Locally run pytest for tests, ruff for formatting checks, and a tutorial test script using uv.

```bash
# Run tests
uv run pytest

# Check formatting
uv run ruff format --check .
uv run ruff check .

# Test tutorials
uv run python3 /tmp/test_tutorial.py
```

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

### Create H2 molecule and write to XYZ

Source: https://github.com/haozeke/chemparseplot/blob/main/doc/source/tutorials/orca/geomscan.md

Constructs an H2 molecule using ASE and writes it to a plain XYZ file, removing metadata for ORCA compatibility.

```python
h2 = molecule("H2")
h2.write("data/h2_base.xyz", comment="\n")
```

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

### Run Full Coverage Analysis (pixi)

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/dev_testing.org

Utilize pixi to manage multiple environments with different optional dependencies for comprehensive test coverage. The 'cov' task combines results from all environments.

```shell
pixi run cov
```

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

### Initialize and configure TwoDimPlot

Source: https://github.com/haozeke/chemparseplot/blob/main/doc/source/quickstart.md

Sets up a TwoDimPlot object and defines the units for the axes. This is useful for creating unit-aware plots.

```python
from chemparseplot.plot.structs import TwoDimPlot, EnergyPath

plot = TwoDimPlot()
plot.set_units("angstrom", "hartree")
```

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

### Format and Check Code with Ruff

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/dev/contributing.org

Format the codebase using 'ruff format .' and check for code style issues with 'ruff check .'. These commands ensure code consistency.

```bash
uv run ruff format .
uv run ruff check .
```

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

### Run Individual Environment Tests (pixi)

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/dev_testing.org

Execute tests for specific environments using pixi. This is useful for isolating tests related to particular dependency sets.

```shell
pixi run -e test test-base     # base tests only
```

```shell
pixi run -e plot test-plot     # with jax + cmcrameri
```

```shell
pixi run -e chemgp test-chemgp # with pandas + plotnine
```

```shell
pixi run -e plumed test-plumed # plumed tests only
```

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

### Use Context Managers for File Operations

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/dev/best_practices.org

Employ context managers when specifying working directories for file operations to ensure proper handling and cleanup.

```python
from pathlib import Path

work_dir = Path("calculation")
data = parse_orca_neb("job", working_dir=work_dir)
```

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

### Run Tests with Single Environment (uv)

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/dev_testing.org

Use this command for basic development testing without conda-gated dependencies. It covers approximately 86% of the codebase.

```shell
cd chemparseplot
uv sync --extra test
uv run pytest tests/ --ignore=tests/tutorials
```

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

### Lazy Import for Optional Dependencies

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/dev/contributing.org

Demonstrates how to use lazy imports for optional dependencies in Python, ensuring that optional packages are only imported when needed.

```python
from rgpycrumbs._aux import ensure_import

def _get_optional_dep():
    global _dep
    if _dep is None:
        _dep = ensure_import("optional_package")
    return _dep
```

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

### Unit Registry and Quantity Handling

Source: https://context7.com/haozeke/chemparseplot/llms.txt

Utilizes a pre-configured pint unit registry with chemistry-specific units for consistent quantity handling. Requires pint and numpy.

```python
from chemparseplot.units import ureg, Q_
import numpy as np

# Create quantities with units
energy_hartree = Q_(np.array([-76.4, -76.2, -75.8]), "hartree")
distance_bohr = Q_(np.array([1.8, 2.0, 2.5]), "bohr")

# Convert to common chemistry units
energy_ev = energy_hartree.to("eV")
energy_kcal = energy_hartree.to("kcal/mol")
distance_angstrom = distance_bohr.to("angstrom")

print(f"Energies: {energy_ev.m} eV")
print(f"Distances: {distance_angstrom.m} Angstrom")

# Custom unit: kcal_mol (per molecule, not per mole)
energy_kcm = energy_hartree.to("kcal_mol")
print(f"Energy per molecule: {energy_kcm.m} kcal/molecule")

# Use with matplotlib (requires plot extras)
from chemparseplot.plot import ureg as plot_ureg
plot_ureg.setup_matplotlib(True)
plot_ureg.mpl_formatter = "{:~P}"  # Compact unit format
```

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

### Open and Validate HDF5 File Structure

Source: https://context7.com/haozeke/chemparseplot/llms.txt

Opens an HDF5 file, validates its structure against required groups, and reads metadata, convergence table, energy grid, NEB path, and stationary points.

```python
import h5py

# Open HDF5 file and validate structure
with h5py.File("chemgp_output.h5", "r") as f:
    # Validate file has expected groups
    validate_hdf5_structure(f, required_groups=["grids", "table"])

    # Read metadata
    metadata = read_h5_metadata(f)
    print(f"Metadata: {metadata}")

    # Read convergence table as DataFrame
    df = read_h5_table(f, "table")
    print(f"Convergence data:\n{df.head()}")

    # Read 2D energy grid with axis coordinates
    energy, x_coords, y_coords = read_h5_grid(f, "energy_surface")
    print(f"Grid shape: {energy.shape}")
    print(f"X range: {x_coords.min():.2f} to {x_coords.max():.2f}")

    # Read NEB path coordinates
    path = read_h5_path(f, "neb_path")
    print(f"Path coordinates: x={path['x'].shape}, y={path['y'].shape}")

    # Read stationary points
    points = read_h5_points(f, "minima")
    print(f"Minima locations: {points}")
```

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

### Handle Missing Energy Data Gracefully

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/dev/best_practices.org

Implement checks to gracefully handle cases where energy data might be missing or empty after parsing.

```python
energies = data.get("energies")
if energies is None or len(energies) == 0:
    print("No energy data available")
    return
```

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

### Import necessary libraries

Source: https://github.com/haozeke/chemparseplot/blob/main/doc/source/tutorials/orca/geomscan.md

Imports required modules for file handling, molecular construction, plotting, and ORCA geometry scan parsing.

```python
import gzip
from pathlib import Path
from ase.build import molecule
import matplotlib.pyplot as plt

from chemparseplot.parse.orca import geomscan
```

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

### Safe TOML Parsing with tomllib

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/dev/best_practices.org

Demonstrates safe parsing of TOML configuration files using the tomllib library. Ensure the file is opened in binary read mode ('rb').

```python
import tomllib
with open(config_file, "rb") as f:
    config = tomllib.load(f)
```

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

### Generate HTML Coverage Report (uv)

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/dev_testing.org

Create an HTML version of the coverage report for easier navigation and analysis. Open the 'htmlcov/index.html' file in your browser.

```shell
uv run coverage html
```

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

### Plot 2D Landscape Surface with Gradient-Enhanced Matern

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/create_neb_figures.org

Generates a 2D landscape surface using the Gradient-Enhanced Matern method. Requires RMSD (reactant and product), gradients, z-data, and step data. Can project the NEB path onto the surface.

```python
from chemparseplot.plot.neb import plot_landscape_surface, plot_landscape_path_overlay

fig, ax = plt.subplots(figsize=(5.37, 5.37), dpi=200)

plot_landscape_surface(
    ax,
    rmsd_r=df["r"].to_numpy(),
    rmsd_p=df["p"].to_numpy(),
    grad_r=df["grad_r"].to_numpy(),
    grad_p=df["grad_p"].to_numpy(),
    z_data=df["z"].to_numpy(),
    step_data=df["step"].to_numpy(),
    method="grad_matern",
    cmap="viridis",
    show_pts=True,
    variance_threshold=0.05,
    project_path=True,       # reaction valley projection
)

# Overlay the colored NEB path
plot_landscape_path_overlay(
    ax,
    r=latest_r, p=latest_p, z=latest_z,
    cmap="viridis",
    z_label="Energy (eV)",
    project_path=True,
)
```

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

### Plot Energy and Convergence Profiles

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/create_neb_figures.org

Generates plots for energy profiles and convergence, including eigenvalues, using trajectory data. This helps visualize the optimization progress.

```python
from chemparseplot.plot.optimization import plot_optimization_profile, plot_convergence_panel

fig, (ax_e, ax_ev) = plt.subplots(1, 2, figsize=(10, 4))
dat = traj.dat_df
plot_optimization_profile(
    ax_e,
    dat["iteration"].to_numpy(),
    dat["delta_e"].to_numpy(),
    eigenvalues=dat["eigenvalue"].to_numpy(),
    ax_eigen=ax_ev,
)
```

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

### Generate Coverage Report (uv)

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/dev_testing.org

After running tests, generate a coverage report to view missing lines. This command uses uv to run the coverage tool.

```shell
uv run coverage report --show-missing
```

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

### Set Up Publication Themes for Matplotlib

Source: https://context7.com/haozeke/chemparseplot/llms.txt

Applies publication-quality matplotlib themes with scientific colormaps and consistent styling using built-in themes or custom configurations.

```python
from chemparseplot.plot import (
    setup_publication_theme,
    setup_global_theme,
    get_theme,
    PlotTheme,
    RUHI_THEME,
    RUHI_COLORS,
)
import matplotlib.pyplot as plt

# Use the built-in RUHI theme for publications
setup_publication_theme(RUHI_THEME)

# Or get a theme with customizations
theme = get_theme("ruhi", font_size=14, facecolor="white")
setup_global_theme(theme)

# Access color palette
print(f"Available colors: {list(RUHI_COLORS.keys())}")
# Output: ['coral', 'sunshine', 'teal', 'sky', 'magenta']

# Create figure with theme applied
fig, ax = plt.subplots(figsize=(3.2, 2.5))
ax.plot([0, 1, 2], [0, 1, 0.5], color=RUHI_COLORS['teal'], linewidth=1.8)
ax.set_xlabel("Reaction coordinate")
ax.set_ylabel("Energy (eV)")
plt.savefig("themed_plot.pdf", dpi=300, bbox_inches='tight')
plt.close()
```

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

### Load sample surface data from HDF5

Source: https://github.com/haozeke/chemparseplot/blob/main/doc/source/tutorials/chemgp/surfaces.md

Loads energy grids, variance data, NEB paths, stationary points, training points, and GP progression grids from a sample HDF5 file. This data is used for various plotting functions.

```python
DATA = Path("data")

# --- Surface data ---
with h5py.File(DATA / "sample_surface.h5") as f:
    eg = f["grids/energy"]
    x_range = np.linspace(*eg.attrs["x_range"], eg.attrs["x_length"])
    y_range = np.linspace(*eg.attrs["y_range"], eg.attrs["y_length"])
    energy = eg[:]
    X, Y = np.meshgrid(x_range, y_range)

    # Variance grid
    variance = f["grids/variance"][:]

    # NEB path
    path_x = f["paths/neb/x"][:]
    path_y = f["paths/neb/y"][:]

    # Stationary points
    min_x = f["points/minima/x"][:]
    min_y = f["points/minima/y"][:]
    sad_x = f["points/saddles/x"][:]
    sad_y = f["points/saddles/y"][:]

    # Training points
    train_x = f["points/training/x"][:]
    train_y = f["points/training/y"][:]

    # GP progression grids
    gp_grids = {}
    for n_train in [5, 10, 20]:
        gp_mean = f[f"grids/gp_mean_{n_train}"][:]
        tx = f[f"points/training_{n_train}/x"][:]
        ty = f[f"points/training_{n_train}/y"][:]
        gp_grids[n_train] = {"gp_mean": gp_mean, "train_x": tx, "train_y": ty}

print(f"Grid shape: {energy.shape}, {len(gp_grids)} GP snapshots loaded")
```

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

### CLI: Plot Minimization Profile

Source: https://github.com/haozeke/chemparseplot/blob/main/docs/orgmode/howto/create_neb_figures.org

Command-line shortcut to generate an optimization profile plot for minimization jobs. Specify the job directory and plot type.

```shell
# Minimization profile
rgpycrumbs eon plt-min --job-dir min_job/ --plot-type profile
```

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

### Import necessary modules for eOn saddle search parsing

Source: https://github.com/haozeke/chemparseplot/blob/main/doc/source/tutorials/eon/saddle.md

Imports the required modules from pathlib, chemparseplot, and rgpycrumbs for parsing eOn saddle search results and handling spin IDs.

```python
from pathlib import Path
from chemparseplot.parse.eon.saddle_search import parse_eon_saddle
from rgpycrumbs.basetypes import SpinID
```

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

### Plot Convergence Curves

Source: https://context7.com/haozeke/chemparseplot/llms.txt

Generates log-scale convergence plots showing oracle calls versus force, colored by optimization method. Requires pandas DataFrame and plotnine. Can use a single threshold or per-method thresholds.

```python
import pandas as pd
from chemparseplot.plot.chemgp import plot_convergence_curve

data = {
    "oracle_calls": list(range(1, 51)) * 2,
    "max_fatom": [1.0 * 0.9**i for i in range(50)] + [1.2 * 0.85**i for i in range(50)],
    "method": ["GP-BFGS"] * 50 + ["GP-Fire"] * 50,
}
df = pd.DataFrame(data)

fig = plot_convergence_curve(
    df,
    x="oracle_calls",
    y="max_fatom",
    color="method",
    log_y=True,
    conv_tol=0.01,  # Single threshold line
    width=4.0,
    height=3.0,
)

fig.save("convergence.pdf", dpi=300)

thresholds = {"GP-BFGS": 0.01, "GP-Fire": 0.02}
fig = plot_convergence_curve(df, conv_tol=thresholds)
fig.save("convergence_multi_threshold.pdf")
```

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

### chemparseplot Package Structure Overview

Source: https://github.com/haozeke/chemparseplot/blob/main/ARCHITECTURE.md

Illustrates the directory structure of the chemparseplot library, highlighting the separation between the 'parse' and 'plot' subpackages.

```tree
chemparseplot/
├── __init__.py
├── units.py           # pint unit registry
├── parse/
│   ├── __init__.py
│   ├── converter.py   # Unit conversion helpers
│   ├── file_.py       # File discovery utilities
│   ├── neb_utils.py   # Common NEB parsing utilities
│   ├── patterns.py    # Regular expression patterns
│   ├── orca/
│   │   ├── __init__.py
│   │   ├── geomscan.py
│   │   └── neb/
│   │       └── interp.py
│   ├── eon/
│   │   ├── __init__.py
│   │   ├── neb.py
│   │   ├── saddle_search.py
│   │   ├── gprd.py
│   │   └── minimization.py
│   ├── sella/
│   │   └── saddle_search.py
│   └── trajectory/
│       ├── __init__.py
│       ├── hdf5.py
│       └── neb.py
└── plot/
    ├── __init__.py
    ├── theme.py       # Scientific color maps
    ├── structs.py     # Structure rendering
    ├── geomscan.py
    ├── neb.py
    └── chemgp.py
```

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

### Read ChemGP HDF5 Data Files

Source: https://context7.com/haozeke/chemparseplot/llms.txt

Provides utilities for reading structured data from ChemGP HDF5 output files. Supports reading tables, grids, paths, points, and metadata, as well as validating the HDF5 structure.

```python
import h5py
from chemparseplot.parse.chemgp_hdf5 import (
    read_h5_table,
    read_h5_grid,
    read_h5_path,
    read_h5_points,
    read_h5_metadata,
    validate_hdf5_structure,
)
```