# jageo/lobsterpy architecture

> Architecture diagram of the GitHub repository jageo/lobsterpy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jageo/lobsterpy
- Repository: https://github.com/jageo/lobsterpy

## Overview

1. **What this repo is**
   LobsterPy is a Python analysis toolkit for **LOBSTER calculation outputs**. Its runtime architecture is centered on turning a directory of LOBSTER-generated files into: bond/bonding summaries, plots, quality metrics, structure graphs, and machine-learning-ready features.

2. **Primary boundary: file-based scientific inputs**
   The main input boundary is a calculation folder containing files such as `COHPCAR.lobster`, `ICOHPLIST.lobster`, `CHARGE.lobster`, `COOPCAR.lobster`, `COBICAR.lobster`, `DOSCAR.lobster`, `MadelungEnergies.lobster`, and structure files like `CONTCAR` or `POSCAR.lobster`. Some workflows also use VASP files like `vasprun.xml` and `POTCAR`, but only for the VASP-specific parts of quality analysis.

3. **CLI as the top-level orchestration layer**
   `src/lobsterpy/cli.py` is the user-facing entry point. It exposes commands for automated description, plotting, DOS plotting, and input generation. The CLI sits above the analysis modules and dispatches to the appropriate subsystem based on flags such as COHP/COBI/COOP mode and “all bonds” vs filtered analysis.

4. **Core bond-analysis subsystem**
   The `cohp` package is the main analysis engine for COHP-based bonding interpretation, while `coxx` generalizes the same pattern to COHP/COOP/COBI-style quantities. Each package has an `analyze.py` module for computation and a `describe.py` module for human-readable summaries. The data flow here is: parsed LOBSTER bond data in, ranked/filtered bond sets and descriptive output out.

5. **Bond-type abstraction**
   `coxx` is the architectural abstraction layer that lets the same analysis flow apply to COHPs, COBIs, and COOPs. That matters for the diagram because the repo is not “COHP-only”; it is built around a shared “bonding curve” concept with pluggable observable types.

6. **Quality-assessment subsystem**
   `src/lobsterpy/quality/analyze.py` and `describe.py` implement calculation-quality analysis. This subsystem is partly decoupled from the core bond analysis because it can incorporate additional VASP-derived context (`vasprun.xml`, `POTCAR`) to report on basis-set and DOS-related quality checks. This is the only major area explicitly called out as VASP-limited in the README.

7. **Structure graph subsystem**
   `src/lobsterpy/structuregraph/graph.py` builds graph-based representations of bonding relationships. This is a separate boundary from textual descriptions: it translates bonding information into graph structures for downstream reasoning or visualization.

8. **Featurization pipeline**
   The `featurize` package turns LOBSTER-derived data into feature tables for machine learning. `core.py` likely contains the main feature definitions, `batch.py` handles processing many calculations, and `utils.py` provides shared helpers. Architecturally, this is a batch-oriented pipeline that consumes calculation folders or preprocessed JSON-like inputs and emits structured feature data rather than plots or prose.

9. **Plotting as a presentation layer**
   `src/lobsterpy/plotting` contains styling and layout helpers, not the scientific logic itself. It provides Matplotlib style settings and layout dictionaries used by the analysis/CLI layer to render COHP/COBI/COOP and DOS visualizations consistently.

10. **Shared utilities and package glue**
    `src/lobsterpy/utils.py` and `__init__.py`/`_version.py` form the small shared support layer: versioning, common helpers, and package-wide exports. These are cross-cutting dependencies used by multiple subsystems rather than standalone flows.

11. **Outputs and persistence**
    The repository supports multiple output shapes: textual summaries, plots, JSON artifacts, and feature datasets. The presence of example JSON files and reference plot data in `tests/test_data` shows that the package serializes analysis results for reproducibility and regression testing, not just interactive use.

12. **Repository support structure**
    `examples/` demonstrates end-to-end runs over representative calculation folders like NaCl and CdF. `docs/` is a substantial Sphinx/Jupyter-based documentation layer. `tests/` mirrors the runtime modules and uses many fixture directories of real LOBSTER outputs, which indicates the architecture is heavily file-driven and validated against archived scientific calculations.

13. **External ecosystem dependencies that shape the architecture**
    The runtime is built around **Python**, **LOBSTER outputs**, and the scientific materials stack, especially **pymatgen**; the README also mentions **ChemEnv** for cation/anion logic fallback and optional **atomate2** workflow integration. Those external tools define key boundaries: LobsterPy analyzes what LOBSTER produced, occasionally enriching it with structure/chemistry context from these libraries.

Main entry points: [`src/lobsterpy/cli.py`](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/cli.py) (CLI), [`src/lobsterpy/quality/analyze.py`](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/quality/analyze.py) (Quality analyze), [`src/lobsterpy/utils.py`](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/utils.py) (Utils), [`src/lobsterpy/cohp/analyze.py`](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/cohp/analyze.py) (COHP analyze)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_package_init["Package init<br/>package glue<br/>[__init__.py]"]
end

subgraph group_analysis["Analysis engines"]
  node_cohp_analyze["COHP analyze<br/>bond analysis<br/>[analyze.py]"]
  node_cohp_describe["COHP describe<br/>summary output<br/>[describe.py]"]
  node_coxx_analyze["COXX analyze<br/>bond analysis<br/>[analyze.py]"]
  node_coxx_describe["COXX describe<br/>summary output<br/>[describe.py]"]
  node_quality_analyze["Quality analyze<br/>quality checks<br/>[analyze.py]"]
  node_quality_describe["Quality describe<br/>quality summary<br/>[describe.py]"]
  node_structure_graph(("Structure graph<br/>graph builder<br/>[graph.py]"))
  node_featurize_core["Feature core<br/>feature defs<br/>[core.py]"]
  node_featurize_batch["Batch featurize<br/>pipeline<br/>[batch.py]"]
  node_featurize_utils["Featurize utils<br/>helpers<br/>[utils.py]"]
end

subgraph group_presentation["Presentation"]
  node_plot_layouts["Plot layouts<br/>style/layout<br/>[layout_dicts.py]"]
  node_plot_style["Plot style<br/>style file"]
end

subgraph group_support["Support"]
  node_lobster_inputs[("LOBSTER files<br/>input boundary")]
  node_vasp_inputs[("VASP files<br/>quality inputs")]
  node_utils["Utils<br/>shared helpers<br/>[utils.py]"]
  node_version["Version<br/>metadata<br/>[_version.py]"]
end

node_cli -->|"reads"| node_lobster_inputs
node_cli -->|"dispatches"| node_cohp_analyze
node_cli -->|"dispatches"| node_coxx_analyze
node_cli -->|"checks"| node_quality_analyze
node_cli -->|"formats"| node_plot_layouts
node_cohp_analyze -->|"summarizes"| node_cohp_describe
node_cohp_analyze -->|"specializes"| node_coxx_analyze
node_coxx_analyze -->|"summarizes"| node_coxx_describe
node_coxx_analyze -->|"parses"| node_lobster_inputs
node_quality_analyze -->|"uses"| node_vasp_inputs
node_quality_analyze -->|"reports"| node_quality_describe
node_quality_analyze -->|"inspects"| node_lobster_inputs
node_structure_graph -->|"maps"| node_lobster_inputs
node_featurize_batch -->|"applies"| node_featurize_core
node_featurize_batch -->|"supports"| node_featurize_utils
node_featurize_core -->|"derives from"| node_lobster_inputs
node_plot_layouts -->|"styles"| node_plot_style
node_package_init -->|"exports"| node_version
node_utils -.->|"supports"| node_cohp_analyze
node_utils -.->|"supports"| node_quality_analyze
node_utils -.->|"supports"| node_featurize_core
node_utils -.->|"supports"| node_cli

click node_cli "https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/cli.py"
click node_package_init "https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/__init__.py"
click node_cohp_analyze "https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/cohp/analyze.py"
click node_cohp_describe "https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/cohp/describe.py"
click node_coxx_analyze "https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/coxx/analyze.py"
click node_coxx_describe "https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/coxx/describe.py"
click node_quality_analyze "https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/quality/analyze.py"
click node_quality_describe "https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/quality/describe.py"
click node_structure_graph "https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/structuregraph/graph.py"
click node_featurize_core "https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/featurize/core.py"
click node_featurize_batch "https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/featurize/batch.py"
click node_featurize_utils "https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/featurize/utils.py"
click node_plot_layouts "https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/plotting/layout_dicts.py"
click node_plot_style "https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/plotting/lobsterpy_base.mplstyle"
click node_utils "https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/utils.py"
click node_version "https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/_version.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_package_init toneBlue
class node_cohp_analyze,node_cohp_describe,node_coxx_analyze,node_coxx_describe,node_quality_analyze,node_quality_describe,node_structure_graph,node_featurize_core,node_featurize_batch,node_featurize_utils toneAmber
class node_plot_layouts,node_plot_style toneMint
class node_lobster_inputs,node_vasp_inputs,node_utils,node_version toneRose
```

## Components

### Entry points

User-facing orchestration and package metadata.

- [CLI](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/cli.py): entrypoint · Command-line dispatcher for description, plotting, DOS plotting, and input generation. · `src/lobsterpy/cli.py`
- [Package init](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/__init__.py): package glue · Top-level exports and package wiring. · `src/lobsterpy/__init__.py`

### Analysis engines

Bonding, quality, structure, and featurization subsystems.

- [COHP analyze](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/cohp/analyze.py): bond analysis · Core COHP bonding interpretation and ranking logic. · `src/lobsterpy/cohp/analyze.py`
- [COHP describe](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/cohp/describe.py): summary output · Human-readable COHP summaries. · `src/lobsterpy/cohp/describe.py`
- [COXX analyze](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/coxx/analyze.py): bond analysis · Shared analysis engine for COHP, COOP, and COBI observables. · `src/lobsterpy/coxx/analyze.py`
- [COXX describe](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/coxx/describe.py): summary output · Shared descriptive layer for bonding observables. · `src/lobsterpy/coxx/describe.py`
- [Quality analyze](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/quality/analyze.py): quality checks · Calculation-quality assessment, including optional VASP context. · `src/lobsterpy/quality/analyze.py`
- [Quality describe](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/quality/describe.py): quality summary · Readable quality-report generation. · `src/lobsterpy/quality/describe.py`
- [Structure graph](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/structuregraph/graph.py): graph builder · Builds graph representations of bonding relationships. · `src/lobsterpy/structuregraph/graph.py`
- [Feature core](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/featurize/core.py): feature defs · Feature definitions and transformations for ML-ready outputs. · `src/lobsterpy/featurize/core.py`
- [Batch featurize](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/featurize/batch.py): pipeline · Batch processing over many calculations. · `src/lobsterpy/featurize/batch.py`
- [Featurize utils](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/featurize/utils.py): helpers · Shared helpers for feature generation. · `src/lobsterpy/featurize/utils.py`

### Presentation

Plotting and human-readable output helpers.

- [Plot layouts](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/plotting/layout_dicts.py): style/layout · Matplotlib styles and layout dictionaries for bonding and DOS plots. · `src/lobsterpy/plotting/layout_dicts.py`
- [Plot style](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/plotting/lobsterpy_base.mplstyle): style file · Base Matplotlib style settings. · `src/lobsterpy/plotting/lobsterpy_base.mplstyle`

### Support

Shared utilities and external calculation inputs.

- **LOBSTER files**: input boundary · Calculation-folder inputs such as COHPCAR, ICOHPLIST, CHARGE, DOSCAR, and structure files.
- **VASP files**: quality inputs · Optional VASP-derived context used mainly for quality checks.
- [Utils](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/utils.py): shared helpers · Cross-cutting helpers used across the package. · `src/lobsterpy/utils.py`
- [Version](https://github.com/jageo/lobsterpy/blob/main/src/lobsterpy/_version.py): metadata · Package version metadata. · `src/lobsterpy/_version.py`

## Connections

- CLI → LOBSTER files: reads · CLI commands operate on calculation folders containing LOBSTER outputs.
- CLI → COHP analyze: dispatches · Routes COHP-oriented analysis commands to the core bonding engine.
- CLI → COXX analyze: dispatches · Routes COOP/COBI/generalized bonding commands to the shared engine.
- CLI → Quality analyze: checks · Invokes quality analysis workflows.
- CLI → Plot layouts: formats · Uses plotting layout/style helpers for rendered output.
- COHP analyze → COHP describe: summarizes · Produces readable bonding descriptions from analyzed COHP data.
- COHP analyze → COXX analyze: specializes · COHP analysis is the specialized bonding path within the shared COXX pattern.
- COXX analyze → COXX describe: summarizes · Shared observable-specific analysis feeds human-readable summaries.
- COXX analyze → LOBSTER files: parses · Consumes LOBSTER bond files and structure context.
- Quality analyze → VASP files: uses · Optionally incorporates VASP-derived files for basis-set and DOS checks.
- Quality analyze → Quality describe: reports · Transforms checks into narrative quality output.
- Quality analyze → LOBSTER files: inspects · Analyzes LOBSTER output files for quality metrics.
- Structure graph → LOBSTER files: maps · Converts bonding information into graph form from calculation outputs.
- Batch featurize → Feature core: applies · Batch pipeline uses the core feature definitions.
- Batch featurize → Featurize utils: supports · Shared feature helpers support batch processing.
- Feature core → LOBSTER files: derives from · Features are derived from LOBSTER-calculation data.
- Plot layouts → Plot style: styles · Layout definitions are rendered with the base plotting style.
- Package init → Version: exports · Package initialization exposes version metadata.
- Utils → COHP analyze: supports · Shared helpers are used by analysis modules.
- Utils → Quality analyze: supports · Shared helpers are used by quality analysis.
- Utils → Feature core: supports · Shared helpers are used by featurization.
- Utils → CLI: supports · Common helpers support command-line workflows.
