How jageo/lobsterpy works
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: cli.py CLI · quality/analyze.py Quality analyze · utils.py Utils · cohp/analyze.py COHP analyze
Components 18
Entry points
User-facing orchestration and package metadata.
- CLI · Command-line dispatcher for description, plotting, DOS plotting, and input generation.
src/lobsterpy/cli.py - Package init · Top-level exports and package wiring.
src/lobsterpy/__init__.py
Analysis engines
Bonding, quality, structure, and featurization subsystems.
- COHP analyze · Core COHP bonding interpretation and ranking logic.
src/lobsterpy/cohp/analyze.py - COHP describe · Human-readable COHP summaries.
src/lobsterpy/cohp/describe.py - COXX analyze · Shared analysis engine for COHP, COOP, and COBI observables.
src/lobsterpy/coxx/analyze.py - COXX describe · Shared descriptive layer for bonding observables.
src/lobsterpy/coxx/describe.py - Quality analyze · Calculation-quality assessment, including optional VASP context.
src/lobsterpy/quality/analyze.py - Quality describe · Readable quality-report generation.
src/lobsterpy/quality/describe.py - Structure graph · Builds graph representations of bonding relationships.
src/lobsterpy/structuregraph/graph.py - Feature core · Feature definitions and transformations for ML-ready outputs.
src/lobsterpy/featurize/core.py - Batch featurize · Batch processing over many calculations.
src/lobsterpy/featurize/batch.py - Featurize utils · Shared helpers for feature generation.
src/lobsterpy/featurize/utils.py
Presentation
Plotting and human-readable output helpers.
- Plot layouts · Matplotlib styles and layout dictionaries for bonding and DOS plots.
src/lobsterpy/plotting/layout_dicts.py - Plot style · Base Matplotlib style settings.
src/lobsterpy/plotting/lobsterpy_base.mplstyle
Support
Shared utilities and external calculation inputs.
- LOBSTER files · Calculation-folder inputs such as COHPCAR, ICOHPLIST, CHARGE, DOSCAR, and structure files.
- VASP files · Optional VASP-derived context used mainly for quality checks.
- Utils · Cross-cutting helpers used across the package.
src/lobsterpy/utils.py - Version · Package version metadata.
src/lobsterpy/_version.py
Connections 22
- 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.