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.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)

Source distribution for sage-lib 0.1.10.5
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)

Table of built distributions (wheels) for sage-lib 0.1.10.5
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.10.5 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