Metadata-Version: 2.4
Name: sage_lib
Version: 0.1.10.5
Summary: A library for advanced scientific calculations and visualization
Author: Lombardi, Juan Manuel
Author-email: lombardi@fhi-berlin.mpg.de
License: MIT
Keywords: scientific calculations visualization computational chemistry quantum mechanics machine learning data analysis
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11,<3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: tqdm>=4.50.0
Requires-Dist: joblib>=1.0.0
Requires-Dist: h5py>=3.6.0
Requires-Dist: ase>=3.22.1
Requires-Dist: tomlkit>=0.12.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: imageio>=2.10.0
Requires-Dist: glfw
Requires-Dist: PyOpenGL
Requires-Dist: PyOpenGL_accelerate
Requires-Dist: imgui-bundle>=1.92.5
Requires-Dist: Pillow
Requires-Dist: PyYAML>=6.0
Requires-Dist: scikit-image>=0.20.0
Provides-Extra: analysis
Requires-Dist: scipy>=1.7.0; extra == "analysis"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: tox; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=0.5.0; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Provides-Extra: ml
Requires-Dist: scikit-learn>=0.24.0; extra == "ml"
Requires-Dist: umap-learn>=0.5.0; extra == "ml"
Requires-Dist: kneed>=0.7.0; extra == "ml"
Requires-Dist: hdbscan>=0.8.0; extra == "ml"
Requires-Dist: dscribe; extra == "ml"
Provides-Extra: faiss
Requires-Dist: faiss-cpu; extra == "faiss"
Provides-Extra: viz
Requires-Dist: scipy>=1.10.0; extra == "viz"
Requires-Dist: matplotlib>=3.4.0; extra == "viz"
Requires-Dist: seaborn>=0.11.0; extra == "viz"
Requires-Dist: imageio>=2.10.0; extra == "viz"
Requires-Dist: glfw; extra == "viz"
Requires-Dist: PyOpenGL; extra == "viz"
Requires-Dist: PyOpenGL_accelerate; extra == "viz"
Requires-Dist: imgui-bundle>=1.92.5; extra == "viz"
Requires-Dist: Pillow; extra == "viz"
Requires-Dist: PyYAML>=6.0; extra == "viz"
Requires-Dist: scikit-image>=0.20.0; extra == "viz"
Provides-Extra: all
Requires-Dist: Pillow; extra == "all"
Requires-Dist: PyOpenGL; extra == "all"
Requires-Dist: PyOpenGL_accelerate; extra == "all"
Requires-Dist: PyYAML>=6.0; extra == "all"
Requires-Dist: black; extra == "all"
Requires-Dist: coverage; extra == "all"
Requires-Dist: dscribe; extra == "all"
Requires-Dist: faiss-cpu; extra == "all"
Requires-Dist: flake8>=3.8; extra == "all"
Requires-Dist: glfw; extra == "all"
Requires-Dist: hdbscan>=0.8.0; extra == "all"
Requires-Dist: imageio>=2.10.0; extra == "all"
Requires-Dist: imgui-bundle>=1.92.5; extra == "all"
Requires-Dist: kneed>=0.7.0; extra == "all"
Requires-Dist: matplotlib>=3.4.0; extra == "all"
Requires-Dist: mypy; extra == "all"
Requires-Dist: myst-parser; extra == "all"
Requires-Dist: pytest>=6.0; extra == "all"
Requires-Dist: scikit-image>=0.20.0; extra == "all"
Requires-Dist: scikit-learn>=0.24.0; extra == "all"
Requires-Dist: scipy>=1.10.0; extra == "all"
Requires-Dist: scipy>=1.7.0; extra == "all"
Requires-Dist: seaborn>=0.11.0; extra == "all"
Requires-Dist: sphinx-autodoc-typehints; extra == "all"
Requires-Dist: sphinx-rtd-theme>=0.5.0; extra == "all"
Requires-Dist: sphinx>=4.0; extra == "all"
Requires-Dist: tox; extra == "all"
Requires-Dist: umap-learn>=0.5.0; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# SAGE (`sage_lib`)

SAGE is an open-source Python library and application for computational chemistry and materials science. It reads, builds, edits, analyses and
visualises atomic structures; sets up and runs DFT and molecular-dynamics workflows (VASP, DFTB+, LAMMPS and others); analyses thermodynamics,
potential-energy surfaces and ensembles; searches for low-energy structures with [EZGA](https://pypi.org/project/ezga-lib/); renders publication-quality
pictures; and lets language-model agents work on a project's data through typed, reviewable operations.

It is used three ways, which share the same operations: a graphical application (`sage gui`), a command line (`sage ...`) and a Python API
(`sage_lib`). The package is on [PyPI](https://pypi.org/project/sage_lib/) (MIT licence).

## What it does

- **Structures and databases.** `Partition` is a database of structures with memory, SQLite and HDF5+SQLite backends. Readers and writers cover VASP,
  DFTB+, LAMMPS, XYZ, CIF, PDB and other formats. Builders make crystals, surfaces and oxide terminations, molecules from SMILES, solvent layers,
  adsorbates, coverage series and conformer sets.
- **Analysis.** Thermodynamics and convex hulls, descriptors and clustering, mean-square displacement and diffusion, a potential-energy-surface
  landscape tool (basins, barriers, hull, proposals for the next calculation), an ensemble analysis window, EZGA motif studies, and a biomolecule
  studio with 36 analyses (pockets, interactions, nucleic acids, conformations and sampling, alignment).
- **Workflows.** A Workflow Studio that builds pipelines (relaxation, EZGA structure search, reports, plots) and runs them; failed runs are diagnosed
  and repaired automatically or with one click.
- **Visualisation and rendering.** An OpenGL application, a browser viewer (`sage webgui`), an editor extension, and a Blender/Cycles path-tracing
  pipeline with live preview, a Python API (`sage_lib.visualization.cinematic.direct`) and `sage render`.
- **Agents.** `sage mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server with read, query, measure, edit, analysis, plotting and
  report tools over a project's datasets, and the in-app assistant proposes operations that you review, apply and can undo. Both are measured with real
  models (`test/mcp_evals`).

## Install

```bash
python3.12 -m venv .venv
source .venv/bin/activate            # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install sage_lib
sage --help
sage gui -f structure.xyz
```

SAGE needs **Python 3.11, 3.12 or 3.13**. The standard installation includes the GUI, plotting, SciPy and ASE. The full GUI needs working OpenGL
drivers and a display; `sage webgui -f structure.xyz --classic` works on headless machines. Optional machine-learning and FAISS dependencies:
`python -m pip install "sage_lib[ml,faiss]"`. EZGA and Blender are separate programs and must be installed separately for the features that use them
(`SAGE_BLENDER` points to a Blender that is not in the usual places).

## Quick start

From the command line:

```bash
sage export --path ./data --source VASP --output_path ./converted --output_source PDB     # convert VASP files to PDB
sage plot --path ./data --plot bands --fermi 5.0 --output_path ./plots                    # band structure plot
sage render --help                                                                         # path-traced pictures and movies
```

From Python:

```python
from sage_lib.partition.Partition import Partition

PT = Partition(path='./data')
PT.read_files(file_location='./data', source='VASP', verbose=True)
PT.export_files(file_location='./output', source='PDB', verbose=True)
PT.close()
```

Open shared databases with `access="ro"` for analysis, and call `close()` when done. The `sage-lib-*` skills in `.claude/skills/` and
`src/sage_lib/agent_assets/skills/` document the patterns for partitions, input and output, building, editing, geometry and analysis.

## Using SAGE with Codex or Claude Code

```bash
sage setup-agent --client both          # or --client codex / --client claude
sage doctor-agent --client both         # repeat the diagnostic without changing files
```

This installs the SAGE skills and registers the `sage` MCP server for your project, then checks that it starts and can read data. Open the project
in your client, approve the MCP server and ask, for example, "Use SAGE to inspect trajectory.xyz and show the five lowest-energy frames." The full
reference is in [docs/agent_setup.md](docs/agent_setup.md); the server's tool profiles and options are in [docs/mcp_server.md](docs/mcp_server.md).

## Editors

`sage setup-editor` installs the SAGE Viewer extension into every supported editor it finds (VS Code, Antigravity IDE, Cursor, VSCodium); a structure
file then opens in the SAGE viewer by default (**Reopen Editor With... > Text Editor** shows the raw text). See the
[extension guide](vscode-extension/README.md).

## Documentation

| Page | Content |
|---|---|
| [docs/mcp_server.md](docs/mcp_server.md) | Running, tuning and measuring the MCP server, tool profiles, optimising structures with EZGA |
| [docs/agent_setup.md](docs/agent_setup.md) | `sage setup-agent` and `sage doctor-agent` |
| [docs/mcp_internals.md](docs/mcp_internals.md) | How the MCP server and the in-app assistant are built |
| [docs/cinematic_renders.md](docs/cinematic_renders.md) | Path-traced renders: styles, presets, Python API |
| [docs/motif_studio.md](docs/motif_studio.md) | Motif Studio (EZGA motifs) |
| [docs/known_bugs.md](docs/known_bugs.md) | Known bugs, each pinned by a test that is expected to fail until it is fixed |
| [CHANGELOG.md](CHANGELOG.md) | What changed |
| [CLAUDE.md](CLAUDE.md) | Architecture and the rules that bit, for people and agents who change the code |

## Development

```bash
git clone https://gitlab.mpcdf.mpg.de/jmlombardi/sage.git
cd sage
python -m pip install -e ".[dev,ml,faiss]"
scripts/run_tests_isolated.sh -- test -q --continue-on-collection-errors \
  --ignore=test/test_faiss_comprehensive --ignore=test/test_faiss_multivector_stress.py --ignore=test/test_faiss_sweep.py
```

Edit only `src/sage_lib/`. Run the tests through `scripts/run_tests_isolated.sh`, which works in a disposable copy of the repository with its own `HOME`
and temporary folder; the layout and the markers are described in [test/README.md](test/README.md).

## Citing

If you use SAGE in your work, please cite it as in [CITATION.cff](CITATION.cff).

## License

SAGE is distributed under the [MIT License](LICENSE), which permits commercial use, modification and redistribution with the copyright and licence notice.

## Contact

Juan Manuel Lombardi, Fritz-Haber-Institut der Max-Planck-Gesellschaft, Berlin: lombardi@fhi-berlin.mpg.de. Bug reports and feature requests go to the
issue tracker of the [GitLab repository](https://gitlab.mpcdf.mpg.de/jmlombardi/sage).
