edlgt 0.2.5

Exact diagonalization tools for lattice gauge theories and quantum many-body Hamiltonians

edlgt

Exact diagonalization tools for lattice gauge theories and quantum many-body Hamiltonians.

Documentation: https://ed-su2.readthedocs.io/en/latest/

pip install edlgt and import edlgt

Supported Python: >=3.10

Installation

PyPI (recommended for users)

pip install edlgt

Optional Simsio workflows (separate install because simsio is Git-only):

pip install edlgt
pip install -r requirements/simsio.txt

From source (development)

git clone --recursive https://github.com/gcataldi96/ed-lgt.git
cd ed-lgt
conda env create -f envs/dev.yml
conda activate edlgt-dev
pip install -e .

Development tools:

pip install -e ".[dev]"

Development tools + Simsio:

pip install -e ".[dev]"
pip install -r requirements/simsio.txt

Quick Start

Check the installation:

python -c "import edlgt; print(edlgt.__version__)"

The best starting point is to run one of the example scripts and adapt it to your model:

python examples/example_QED_static.py
python examples/example_QED_dynamics.py
python examples/example_SU2_static.py
python examples/example_SU2_dynamics.py

Minimal import example:

import edlgt
from edlgt.models import QED_Model, SU2_Model
from edlgt.modeling import diagonalize_density_matrix

Optional Simsio Support

simsio is not currently available on PyPI, so it is intentionally installed separately rather than through a pyproject.toml extra.

If you prefer to install it manually, use one of:

pip install -r requirements/simsio.txt

pip install "git+https://github.com/gcataldi96/simsio.git@daa53e2"

If you work from this repository and use the submodule, also make sure it is present:

git submodule update --init --recursive

This repository pins simsio to the maintained fork commit daa53e2 for edlgt compatibility fixes.

Performance Notes

• For reproducible high-performance runs, prefer a dedicated Conda environment (for example with MKL).
• The pip package stays backend-agnostic for portability.
• After clearing caches, the first run can be slower because Numba recompiles kernels.
• Benchmark Numba-heavy code on a warm run (run twice).

Project Layout

• edlgt/: library source code
• examples/: example scripts for QED, SU2, DFL, Zn, etc.
• validation/: validation scripts/tests
• docs/: documentation sources
• envs/: Conda environments for development, docs, and simsio workflows
• requirements/: pip requirements mirrors for base/dev/docs/simsio installs

Citation

If you use edlgt in research, please cite it using the metadata in:

• CITATION.cff
• CITATION.bib

When Zenodo DOIs are available, use:

• the concept DOI for general software citation
• the version DOI for exact reproducibility

Current Zenodo concept DOI (all versions): 10.5281/zenodo.11145317

Maintenance (for contributors)

Validation Workflow

Run the smallest relevant validation file while you are developing:

pytest -q validation/symmetries/test_symmetry_sector_iterative_consistency.py --threads 1

Run the fast validation subset before a local checkpoint:

pytest -q validation -m "not slow" --threads 1

Run the full validation suite before pushing risky changes:

python validation/run_all.py --threads 1

Enable the repo-local git hooks once per clone:

git config core.hooksPath .githooks

With that enabled:

• .githooks/pre-commit runs the fast non-slow validation subset when staged files touch edlgt/, validation/, examples/example_*.py, or packaging files.
• .githooks/pre-push runs the full validation suite through validation/run_all.py.

Commit / Push Checklist

• Run at least one relevant example/script when changing package code
• Do a warm run before judging performance after Numba/kernel changes
• Check import edlgt after public API/import-path changes
• Keep pyproject.toml and requirements/*.txt aligned when dependencies change
• Add user-facing changes to CHANGELOG.md under Unreleased
• Do not bump the version for normal commits/pushes (only for releases)
• Avoid committing generated artifacts (dist/, __pycache__/, large logs/outputs)

Release Checklist

• Update CHANGELOG.md and choose the next version
• Bump version in pyproject.toml
• Confirm docs metadata picks up the new version from docs/source/conf.py
• Clean build artifacts: rm -rf dist build *.egg-info
• Build package: python -m build
• Check metadata: python -m twine check dist/*
• Test install in a fresh environment
• Upload to TestPyPI, test install, then upload to PyPI
• Tag the release in git (for example v0.1.0)