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; 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 (MIT licence).
What it does
- Structures and databases.
Partitionis 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) andsage render. - Agents.
sage mcpis a Model Context Protocol 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
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:
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:
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
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; the server's tool profiles and options are in 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.
Documentation
| Page | Content |
|---|---|
| docs/mcp_server.md | Running, tuning and measuring the MCP server, tool profiles, optimising structures with EZGA |
| docs/agent_setup.md | sage setup-agent and sage doctor-agent |
| docs/mcp_internals.md | How the MCP server and the in-app assistant are built |
| docs/cinematic_renders.md | Path-traced renders: styles, presets, Python API |
| docs/motif_studio.md | Motif Studio (EZGA motifs) |
| docs/known_bugs.md | Known bugs, each pinned by a test that is expected to fail until it is fixed |
| CHANGELOG.md | What changed |
| CLAUDE.md | Architecture and the rules that bit, for people and agents who change the code |
Development
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.
Citing
If you use SAGE in your work, please cite it as in CITATION.cff.
License
SAGE is distributed under the MIT 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.
Metadata
Release files for sage-lib 0.1.10.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sage_lib-0.1.10.5.tar.gz | 12.3 MB | Without provenance | Details for sage_lib-0.1.10.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sage_lib-0.1.10.5-py3-none-any.whl | Python 3 | none | any | Details for sage_lib-0.1.10.5-py3-none-any.whl |
Total release size: 25.1 MB
Release files / sage_lib-0.1.10.5.tar.gz
| Download URL | sage_lib-0.1.10.5.tar.gz |
|---|---|
| Size | 12.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a5a4be914fbd2b52e5d8b973199397ec9b7f280d5a70a42510fac2ebc4f27691
|
|
BLAKE2b-256 checksum How to use checksums |
79cfe890e273c59ea960a0ce027511677459d0c4da27f09f42d72bf0b3ee5378
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / sage_lib-0.1.10.5-py3-none-any.whl
| Download URL | sage_lib-0.1.10.5-py3-none-any.whl |
|---|---|
| Size | 12.8 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
61a91ca981e9e717beba6d61b97304bf17219f123410b8bf95a3a280b7f527c8
|
|
BLAKE2b-256 checksum How to use checksums |
4f16958ae74468146300fe113a63e383a0906b76dfa9f212f05c3a1111ccbde8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for sage-lib 0.1.10.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.