Skip to main content

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. 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 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.12 or 3.13 (>=3.12,<3.14). 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.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sage-lib 0.1.10.6
File Size Uploaded Provenance Actions
sage_lib-0.1.10.6.tar.gz 12.7 MB Without provenance Details for sage_lib-0.1.10.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sage-lib 0.1.10.6
File Interpreter ABI Platform Actions
sage_lib-0.1.10.6-py3-none-any.whl Python 3 none any Details for sage_lib-0.1.10.6-py3-none-any.whl

Total release size: 25.9 MB

Release files / sage_lib-0.1.10.6.tar.gz

Download URL sage_lib-0.1.10.6.tar.gz
Size 12.7 MB
Tags Source
SHA-256 checksum
How to use checksums
e6f7330b5c2028341c5c27d3721450bf64a9101b6e144ed0d91bc9686a7b315c
BLAKE2b-256 checksum
How to use checksums
3719ad74b4d3e89f4e47519a1f17b07ffb1181025659ba4289e75a09bd04803c
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.6-py3-none-any.whl

Download URL sage_lib-0.1.10.6-py3-none-any.whl
Size 13.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
06babdb6024bc177cb0517b11908c2c2135bf553f38f9c535a80a71dd9d752c3
BLAKE2b-256 checksum
How to use checksums
ee03ed24af11aacd4b1148960e155bad2a9dca89f91394439f9607a0bd556e98
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.6

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.

Release history Release notifications | RSS feed

This release

0.1.10.6 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page