Metadata-Version: 2.4
Name: elfes
Version: 0.0.1a0
Summary: Equivariant Learning Framework for Electronic Structure
Author: Feitong Song
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.15,>=3.12
Requires-Dist: accelerate
Requires-Dist: ase
Requires-Dist: e3nn==0.6.0
Requires-Dist: einops
Requires-Dist: h5py
Requires-Dist: numpy
Requires-Dist: omegaconf
Requires-Dist: rich
Requires-Dist: scipy
Requires-Dist: torch==2.12.1
Requires-Dist: torch-geometric==2.8.0
Requires-Dist: typer
Requires-Dist: wandb
Description-Content-Type: text/markdown

# ELFES

ELFES (/ɛlvz/) is a unified **E**quivariant **L**earning **F**ramework for **E**lectronic **S**tructure.

<a href="https://github.com/songfeitong/elfes/actions/workflows/ci.yml"><img alt="Build status" src="https://github.com/songfeitong/elfes/actions/workflows/ci.yml/badge.svg?branch=main"></a>

## Install from source

ELFES requires Python 3.12, 3.13, or 3.14 and a C++ compiler with C++20 support.

From the repository root, install ELFES into a supported Python environment:

```bash
pip install .
```

The default build compiles ELFES's NumPy CPU, PyTorch CPU, and PyTorch CUDA native providers. It requires a CUDA-enabled PyTorch installation, a compatible NVIDIA driver, and a local CUDA toolkit containing `nvcc`; the toolkit and PyTorch CUDA runtime must have the same major version.

For a CPU-only installation, disable the CUDA providers explicitly:

```bash
BUILD_CUDA=0 pip install .
```

Developers can use [uv](https://docs.astral.sh/uv/) to install the exact locked development environment:

```bash
uv sync --locked
```

See [Development](docs/development.md) for running commands in that environment, testing, formatting, type checking, and external test fixtures.

## Run a workflow

Repository-level workflows are executable research programs that compose ELFES's Python APIs for a specific task. From the repository root, a typical workflow is run as:

```bash
uv run python workflows/workflow_name.py [arguments]
```

Each workflow defines its own inputs, parameters, and outputs; consult the script for its actual invocation.

## License

ELFES is distributed under the [BSD 3-Clause License](LICENSE).
