Metadata-Version: 2.2
Name: symmetrix-xl
Version: 0.1.0
Summary: Symmetrix — a package for functions equivariant under: translation, rotation, inversion, and exchange of particles.
Keywords: symmetry,equivariance,machine-learning,interatomic-potentials,molecular-dynamics
Author: William C. Witt
Maintainer: William C. Witt
License: MIT License
         
         Copyright (c) 2024-2025 William C Witt
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Project-URL: Homepage, https://github.com/bonan-group/symmetrix-xl
Project-URL: Repository, https://github.com/bonan-group/symmetrix-xl
Project-URL: Issues, https://github.com/bonan-group/symmetrix-xl/issues
Requires-Python: >=3.10
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: ase
Provides-Extra: mace
Requires-Dist: torch>=2.5; extra == "mace"
Requires-Dist: mace-torch; extra == "mace"
Provides-Extra: dispersion
Requires-Dist: torch-dftd; extra == "dispersion"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: torch>=2.5; extra == "test"
Requires-Dist: mace-torch; extra == "test"
Provides-Extra: docs
Requires-Dist: furo>=2024.8.6; extra == "docs"
Requires-Dist: myst-parser>=4.0; extra == "docs"
Requires-Dist: sphinx>=8.0; extra == "docs"
Description-Content-Type: text/markdown

# Symmetrix-XL

Symmetrix-XL provides native CPU and GPU inference for MACE and
MACEField models. The published distribution is named `symmetrix-xl`; the
Python import namespace and command-line interface remain `symmetrix`.

This package is a fork of the original
[`symmetrix`](https://github.com/wcwitt/symmetrix) project. Symmetrix-XL adds
two execution strategies:

1. **Edge streaming.** Edge messages are consumed immediately instead of being
   fully materialized in DRAM.
2. **Specialized code generation.** Source for critical operations is generated
   from the model architecture and parameters, enabling compiler specialization
   and vectorization.

The base distribution contains the Python frontend and an x86-64-v3
CPU/OpenMP backend, which requires AVX2, FMA, and the other x86-64-v3 features.
CUDA and HIP backends are installed as separate, architecture-qualified
packages so that they can coexist without overwriting the frontend or CPU
extension.

## Installation

Symmetrix-XL supports CPython 3.10 through 3.14 on Linux x86-64.

```bash
python -m pip install symmetrix-xl
```

Install a GPU package whose architecture exactly matches the target device.
For example:

```bash
python -m pip install symmetrix-xl-cuda12-sm80
python -m pip install symmetrix-xl-cuda13-sm120
```

GPU packages depend on the matching version of `symmetrix-xl`, so installing a
GPU backend also installs the frontend and CPU fallback. CUDA runtime, cuBLAS,
and NVRTC libraries are supplied by declared NVIDIA Python packages. A
compatible NVIDIA driver remains a host requirement.

Inspect the installed backends and verify the selected runtime in a fresh
process:

```bash
symmetrix backend list
symmetrix backend show
symmetrix doctor
```

The frontend loads exactly one native backend per process. Without an explicit
selection, it chooses an installed accelerator backend only when its
architecture exactly matches a visible device; otherwise it uses CPU. Select a
backend before importing a calculator when more than one usable backend is
installed:

```bash
SYMMETRIX_BACKEND=cuda13-sm120 python calculation.py
```

An extension compiled for one GPU architecture must not be used on another
architecture. NVRTC specializes model kernels at runtime, but Kokkos and
SpheriCart device code is compiled ahead of time into the backend extension.

## Source installation

Clone the repository with its submodules, create an environment, and use the
build frontend from the repository root:

```bash
git clone --recursive https://github.com/bonan-group/symmetrix-xl.git
cd symmetrix-xl
uv venv
source .venv/bin/activate
python tools/symmetrix_build.py install --backend cpu --cpu-target native
```

Use `--cpu-target x86-64-v3` for a portable x86-64-v3 CPU build. A native build
is optimized for the build host and should not be copied to heterogeneous
machines.

Build an exact CUDA backend with a matching development toolkit:

```bash
python tools/symmetrix_build.py install \
    --backend cuda --arch sm120 --cuda-root /usr/local/cuda-13.3
```

Build HIP in a separate environment and build directory:

```bash
python tools/symmetrix_build.py install \
    --backend hip --arch gfx1151 --rocm-root /opt/rocm
```

Source builds require Python 3.10 or newer, CMake 3.27 or newer, a C++20
compiler, and a recursive checkout. CPU builds additionally require a Fortran
compiler and optimized BLAS. CUDA builds require `nvcc`; HIP builds require
`hipcc`. Do not reuse a build directory across CPU, CUDA, and HIP backends.

The maintained build and cluster instructions are in the
[installation guide](https://github.com/bonan-group/symmetrix-xl/blob/main/docs/user/installation.md)
and
[developer build guide](https://github.com/bonan-group/symmetrix-xl/blob/main/docs/developer/build_and_test.md).

## Model conversion

Compact Symmetrix JSON is the preferred deployment format. JSON evaluation does
not require PyTorch or `mace-torch`; those packages are needed only when
loading or converting an upstream checkpoint.

Install the optional converter dependencies and export a checkpoint:

```bash
python -m pip install "symmetrix-xl[mace]"
symmetrix_extract_mace \
    --model mace-omat-0-medium.model \
    --chemical-symbols Sr Ti O \
    --output srtio3-mace.json
```

The converter retains all compatible prediction heads. Use `--head` to select
the default head without discarding the others:

```bash
symmetrix_extract_mace \
    --model MACEField-MH-0-omat-dielectric.model \
    --chemical-symbols Sr Ti O \
    --head mp-dielectric \
    --output srtio3-macefield.json
```

MACEField checkpoints must be converted before use. Passing an original
MACEField checkpoint directly to the calculator is rejected rather than
silently delegating evaluation to PyTorch.

See the
[model guide](https://github.com/bonan-group/symmetrix-xl/blob/main/docs/user/models.md)
for supported model families, multi-head models, precision, and conversion
options.

## ASE calculator

Use the compact model with the normal ASE calculator interface:

```python
from ase.spacegroup import crystal
from symmetrix import Symmetrix

a = 3.905
atoms = crystal(
    symbols=["Sr", "Ti", "O"],
    basis=[(0, 0, 0), (0.5, 0.5, 0.5), (0.5, 0.5, 0)],
    spacegroup=221,
    cellpar=[a, a, a, 90, 90, 90],
)
atoms.calc = Symmetrix("srtio3-mace.json")

energy = atoms.get_potential_energy()
forces = atoms.get_forces()
stress = atoms.get_stress()
```

Model evaluation defaults to FP32. Request FP64 explicitly when needed:

```python
atoms.calc = Symmetrix("srtio3-mace.json", dtype="float64")
```

Direct model-specialized execution is the default for supported compact
models. It compiles or reuses a precision- and backend-specific artifact and
fails clearly when the required artifact cannot be produced or loaded. Use
`streamed_edges="non-compiled"` only as a compiler-free compatibility or
diagnostic mode.

A cold CPU specialization requires a C++20 compiler at runtime. CUDA
specialization uses NVRTC from the backend package's declared NVIDIA
dependencies and still requires a compatible host driver.

Runtime artifacts are stored in a private per-user cache. Set
`SYMMETRIX_JIT_CACHE` before starting Python to choose an explicit location:

```bash
export SYMMETRIX_JIT_CACHE=/path/to/private/symmetrix-jit-cache
symmetrix_prepare_jit_host_artifact \
    --model srtio3-mace.json --precision float32
```

The cache contains executable code and must not be writable by other users.
Generated artifacts are specific to the model contract, precision, backend,
compiler/runtime identity, and host or GPU target.

## MACEField

MACEField models expose energy, forces, stress, polarization, Born effective
charges, and polarizability. Set the electric field on the calculator or in the
ASE structure:

```python
import numpy as np
from symmetrix import Symmetrix

atoms.info["electric_field"] = np.array([0.01, -0.02, 0.03])
atoms.calc = Symmetrix("srtio3-macefield.json", dtype="float64")

energy = atoms.get_potential_energy()
forces = atoms.get_forces()
polarization = atoms.calc.get_property("polarization", atoms)
becs = atoms.calc.get_property("becs", atoms)
polarizability = atoms.calc.get_property("polarizability", atoms)
```

Response properties are computed only when requested. Calculator instances are
stateful and should not be called concurrently from multiple host threads.

## Model ensembles

`SymmetrixEnsemble` evaluates compatible models sequentially in one process and
returns the member mean through ordinary ASE properties. Member values use the
`_comm` suffix and population variances use `_var`:

```python
from symmetrix import SymmetrixEnsemble

atoms.calc = SymmetrixEnsemble(["model-1.json", "model-2.json"])
mean_energy = atoms.get_potential_energy()
member_forces = atoms.calc.get_property("forces_comm", atoms)
force_variance = atoms.calc.get_property("forces_var", atoms)
```

Ensemble members must agree on model type, species, cutoff, precision, backend,
and execution mode.

## LAMMPS

LAMMPS integration is provided by `pair_symmetrix`. It does not embed Python or
compile model-specific code at runtime, so required host or device artifacts
must be prepared before launch. See the
[LAMMPS guide](https://github.com/bonan-group/symmetrix-xl/blob/main/docs/user/lammps.md)
for installation, artifact preparation, precision, and MPI requirements.

## Troubleshooting

Always diagnose the exact environment used for evaluation:

```bash
symmetrix backend list
symmetrix backend show --probe
symmetrix doctor --json
```

For CPU deployments, `doctor` checks OpenMP runtime identity and worker
participation. For CUDA and HIP, it checks device compatibility and launches a
sentinel kernel. Set `SYMMETRIX_OPENMP_RUNTIME_CHECK=strict` for production CPU
qualification.

When reporting a failure, include the backend selector, model hash, precision,
compiler or toolkit version, and the JSON output from `symmetrix doctor`.
Detailed diagnostic guidance is available in the
[troubleshooting guide](https://github.com/bonan-group/symmetrix-xl/blob/main/docs/user/troubleshooting.md).

## Documentation

- [User guide](https://github.com/bonan-group/symmetrix-xl/blob/main/docs/user/index.md)
- [Python API](https://github.com/bonan-group/symmetrix-xl/blob/main/docs/reference/python_api.md)
- [Backend and diagnostics guide](https://github.com/bonan-group/symmetrix-xl/blob/main/docs/user/backends.md)
- [Execution modes and artifacts](https://github.com/bonan-group/symmetrix-xl/blob/main/docs/user/execution.md)
- [Developer guide](https://github.com/bonan-group/symmetrix-xl/blob/main/docs/developer/index.md)

## Development

From a recursive source checkout:

```bash
uv venv
source .venv/bin/activate
uv pip install -e "./symmetrix[test]"
pytest symmetrix/test
uvx pre-commit run --all-files
```

Keep CPU, CUDA, HIP, and LAMMPS builds in separate environments and build
directories.

## License

Symmetrix-XL is distributed under the
[MIT License](https://github.com/bonan-group/symmetrix-xl/blob/main/LICENSE).
`pair_symmetrix` is GPLv2 to remain compatible with LAMMPS.
