Metadata-Version: 2.1
Name: sage_lib
Version: 0.1.10.0
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
Requires-Python: >=3.11
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[glfw]
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[glfw]; 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[glfw]; 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"

sage_lib

Overview

sage_lib is a versatile library designed for advanced scientific computations and visualization. It enables users to process atomic structures, perform thermodynamic analyses, generate band structures, and handle various tasks commonly required in quantum mechanical and molecular dynamics studies. The primary focus of this library is to simplify complex workflows, enabling researchers to conduct simulations, generate graphical representations, and export data in multiple formats with ease.

Features

Atomic Position Export: Converts atomic position files from one format to another, making data compatible with different simulation tools or visualization software.

Plot Generation: Generates plots based on simulation data, such as band structures or molecular arrangements. This includes support for visualizing results from popular tools like VASP.

Thermodynamic Analysis: Provides methods to calculate thermodynamic properties based on ab initio data. This includes phase diagrams, ensemble analysis, and more.

Blender Integration for Rendering: Uses Blender to render atomic structures and molecular arrangements. Supports customization like resolution, camera angles, and the addition of fog effects.

Dynamic Molecular Analysis: Analyzes molecular dynamics data, tracking species counts, evaluating force fields, and computing properties such as diffusion coefficients and bond distances.

Configuration Generation and Editing: Reads atomic structures and configurations, applies specified editing operations, and exports new structures. This includes operations like creating supercells, rattling atomic positions, and applying compressions.

Solvent Environment Generation: Creates a solvent environment around a given molecular or atomic structure, supporting various solvents and configurations to simulate realistic environments.

Dimer Search and Analysis: Facilitates dimer search to analyze interactions between specific pairs of atoms, which is useful for studying catalytic activity and other atomic-scale interactions.

Surface Disassembly: Generates configurations that allow the disassembly of surfaces, which is particularly useful for understanding surface stability and catalysis.

Customizable File Management: Provides functionalities for handling, reading, and exporting files in different formats including VASP, XYZ, and others.

Installation

To install sage_lib, use the following command:

```bash
python -m venv .venv
# Linux/macOS:
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
```

Requires **Python 3.11 or newer**. The standard installation includes the GUI,
plotting and SciPy dependencies. The full GUI still needs working OpenGL drivers
and a display; `sage webgui -f structure.xyz --classic` works on headless machines.

Optional ML and FAISS dependencies: `python -m pip install "sage_lib[ml,faiss]"`.
The `viz` extra remains available for older installation commands, but the GUI
is included by default. EZGA and Blender integrations require those applications
to be installed separately.

For this unpublished release, install the prepared wheel:

```bash
python -m pip install ./release_artifacts/sage_lib-0.1.9.31-py3-none-any.whl
```

Usage

sage_lib can be used from the command line or programmatically.

Codex and Claude Code

After installing SAGE, configure one or both clients with the shared interface:

```bash
sage setup-agent --client codex
sage setup-agent --client claude
sage setup-agent --client both
# Existing shortcuts: sage setup-codex / sage setup-claude
```

`both` is the default. Codex receives skills in
`.agents/skills/`, the `sage` MCP server in `.codex/config.toml`, and SAGE guidance
in `AGENTS.md`. Claude Code receives skills in `.claude/skills/`, the `/sage`
command, the server in `.mcp.json`, and guidance in `CLAUDE.md`. Other servers,
settings, comments and instructions are kept. The canonical skills live in
`sage_lib/agent_assets/skills/`; both clients get ordinary directory copies from
that source. The repository's `.agents/skills` and `.claude/skills` use links to
the canonical directories so their instructions stay synchronized.

Project, interpreter and data can be configured separately:

```bash
sage setup-agent --client both --path /path/to/project \
  --python /path/to/environment/bin/python --data-root /path/to/data
```

`--python` defaults to the interpreter running setup, without resolving away
virtual environments. `--data-root` defaults to the project or its previously
configured data root; relative paths resolve against the project. The selected
environment must import SAGE and its MCP dependencies. EZGA is optional for
SAGE's MCP and required only for EZGA features.

Client configuration and `.sage/agent-settings.json` contain machine-specific
paths. Setup adds Git ignore rules for these private files and refuses to change
them if they are already tracked, even with `--force`; it never changes the Git
index. Keep these files local and rerun setup on each machine. Skills and project
guidance can be shared. Existing client settings are preserved.

When creating a new `CLAUDE.md`, setup imports an existing `AGENTS.md` so its
project rules remain available to Claude. Existing `CLAUDE.md` content is kept.

Setup verifies MCP initialization, published tools and the selected data root.
It also reads the small XYZ bundled in the installed package through the selected
Python/MCP in an isolated temporary workspace, which is removed afterwards.
The data folder can be outside the project and read-only. This check
does not call a model or require a Codex/Claude account. It checks SAGE's backend;
the client still needs to be installed and authenticated for conversations.

Open the project in your client, review its trust/MCP approval prompt, and start
a new session. Codex loads project configuration only for trusted projects;
Claude Code asks to approve project MCP servers. Use `/mcp` to inspect the
connection, then ask, for example, “Use SAGE to inspect trajectory.xyz and show
the five lowest-energy frames.”

Repeat the diagnostic without modifying project or data files:

```bash
sage doctor-agent --client both --path /path/to/project
sage setup-agent --client both --path /path/to/project --check --json
```

The result distinguishes a verified backend, installed client executable and
client authorization, which must still be reviewed in Codex/Claude Code. It does
not authenticate accounts or call models. Claude Desktop uses different
configuration and is not configured by these commands.

Use `--dry-run` to preview without writing files or starting Python/MCP processes,
`--mcp-read-only` to omit writing tools, `--no-mcp` to install only skills and
guidance, or `--no-verify` to skip the backend check. `--timeout` controls the
diagnostic deadline. Private hashes allow unedited old skills/guidance to update
automatically; user edits are kept unless `--force`. Differing SAGE transports
require `--force`, for example after moving the Python environment. Other clients'
files and unrelated servers are never replaced. Failed diagnostics or conflicting
SAGE transports produce a nonzero exit status. `both` preflights both clients
before making changes.

See the official [Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp?surface=cli),
[Codex skill discovery](https://learn.chatgpt.com/docs/build-skills),
[Claude Code MCP](https://code.claude.com/docs/en/mcp) and
[Claude Code skills](https://code.claude.com/docs/en/skills) documentation.

Command Line Usage

The library includes a console command sage which can be used to execute various subcommands:

sage export --path ./data --source VASP --output_path ./converted --output_source PDB

This command will convert atomic position files from VASP format to PDB format, saving the output in the ./converted directory.

Another example for generating a plot:

sage plot --path ./data --plot bands --fermi 5.0 --output_path ./plots

This command generates a band structure plot using the data found in the specified directory.

Programmatic Usage

Below is a Python example that demonstrates how to use sage_lib programmatically:

from sage_lib.partition.Partition import Partition

# Initialize a Partition object
PT = Partition(path='./data')

# Read files from a specified location
PT.read_files(file_location='./data', source='VASP', verbose=True)

# Export files in a different format
PT.export_files(file_location='./output', source='PDB', verbose=True)
PT.close()

This example initializes a Partition object, reads files from a directory, and exports them to a different format.

Dependencies

sage_lib requires the following packages:

numpy: for numerical operations

matplotlib: for plotting and visualization

scipy: for scientific computations

imageio: for managing image files

Optional dependencies include:

pytest: for testing

flake8: for code linting

sphinx: for generating documentation

License

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

VS Code

Install `sage_lib` in the Python environment used by VS Code, then install the
SAGE Viewer extension. For an unpublished extension:

```bash
code --install-extension ./release_artifacts/sage-viz-0.1.1.vsix
```

Opening an XYZ or another supported structure file in VS Code uses SAGE Viewer
by default. Use **Reopen Editor With… → Text Editor** to edit the raw text.
See the [extension guide](vscode-extension/README.md) for installation and remote
environments.

Development and releases

```bash
python -m pip install -e ".[dev,ml,faiss]" ase build twine
python -m pytest test/ -q
python -m build
python -m twine check dist/*
```

GitLab CI runs tests on Python 3.11 and 3.12, checks the extension and builds
Python distributions and the VSIX. Its packaging job installs the wheel into
a clean environment and checks imports, bundled assets and CLI entry points.
See [CHANGELOG.md](CHANGELOG.md) and the [release guide](docs/releasing.md).
Generated run outputs and release backups are ignored; source, tests,
documentation, configuration and input fixtures belong in the repository.

Contributing

Contributions are welcome at the [GitLab repository](https://thgitlab.rz-berlin.mpg.de/lombardi/sage).

Contact

For questions, please contact the author via email: lombardi@fhi-berlin.mpg.de

For bug reports or feature requests, visit the issues page.
