AEGISS

Atomic Orbital and Entropy based Guided Inference for Space Selection

AEGISS automates active space selection for multireference quantum chemistry calculations. It combines two complementary screening strategies:

• Entropy screening — ranks orbitals by their single-orbital entanglement entropy obtained from a DMRG wavefunction. Orbitals with high entanglement are strongly correlated and belong in the active space.
• AO projection — projects molecular orbitals onto a user-defined set of atomic orbitals (e.g. the C 2p_z shell of a conjugated system). Orbitals with large projection weights are chemically relevant to the target fragment.

The two criteria can be used independently or combined. In select_aegiss they are applied sequentially — entropy screening first narrows the candidate set, then AO projection refines it further — so an orbital must satisfy both criteria to appear in the final active space. Both functions can also be called individually for custom workflows.

Installation

AEGISS requires Python ≥ 3.12 and uses uv for dependency management.

git clone https://github.com/Algorithmiq/AEGISS.git
cd AEGISS
uv sync --extra viz          # add --all-groups for the test, docs and notebook tools
source .venv/bin/activate

The viz extra is only needed for MolTagger, the interactive tool for picking atoms and generating ao_labels.

See docs/installation.md for the environment variables that control threads, memory and scratch space, and for logging setup.

Quick start — benzene π system

from aegiss.active_space.aegiss import select_aegiss
from aegiss.config_dataclasses import DMRGConfig, EntropyConfig, OutputConfig, ProjectionConfig
from aegiss.initial_guess import build_mol, run_scf

mol = build_mol("docs/tutorials/data/benzene.xyz", basis="ccpvdz", symmetry=False)
mf = run_scf(mol, method="RHF")

active_indices = select_aegiss(
    mol,
    mf,
    dmrg_config=DMRGConfig(ncas=30, nelecas=30, max_bond_dim=200, symm_type="SZ"),
    entropy_config=EntropyConfig(fraction=0.1, fraction_type="r", ranking="global"),
    projection_config=ProjectionConfig(
        ao_labels=["C 2pz"], contribution=0.5, contribution_type="a", ranking="global"
    ),
    output_config=OutputConfig(saving_prefix="benzene_aegiss", save_orb=False),
)

select_aegiss runs the full pipeline — DMRG in a CAS(30, 30) window around the Fermi level → entropy screening → projection onto the carbon 2p_z orbitals — and returns the 0-based indices of the selected orbitals. main.py is the same example as a runnable script; expect a few minutes of runtime, dominated by the DMRG step.

AEGISS can also start from localized or natural orbitals (see localize in the localization API). Keep in mind that the DMRG window is taken by orbital index, which is a Fermi-level window only for canonical orbitals.

Documentation

The documentation sources live in docs/ and are built with MkDocs (see docs/README.md):

• Methodology — the six steps of the AEGISS workflow.
• Tutorials — Jupyter notebooks covering SCF and localization, DMRG and entropies, AO projection, the full pipeline, and UHF references.
• Orbital index base — printing and passing orbital indices 0- or 1-based (aegiss config set-base, AEGISS_ORB_BASE).
• Unrestricted (UHF) references — spin-summed vs. spin-resolved entropies.
• MolTagger — interactive atom tagging.
• API reference — generated from the docstrings.

Development

just build --all-groups --all-extras   # or: uv sync --all-groups --all-extras
uv run prek install
just test -m "not slow"
uv run mkdocs serve                    # docs preview at http://127.0.0.1:8000

just with no arguments lists every recipe.

Code style is enforced by ruff and ty; both run as git hooks (via prek) and in CI on every pull request. See CONTRIBUTING.md for the full workflow.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for the development setup, branch and commit conventions, and testing requirements, and note that all contributions require agreement to the Contributor License Agreement. All interactions in this repository are covered by our Code of Conduct.

Bugs and feature requests go through the issue templates. Please do not open public issues for security problems; see SECURITY.md.

Releases

Work lands on main through squash-merged pull requests, each minor release is stabilised on a release/X.Y branch that only receives backported bug fixes, and a release bot tags the release candidates and releases, writes CHANGELOG.md and publishes to PyPI. Only the newest release is supported. The contributing guide describes the process.

The release automation is shared with the other Algorithmiq repositories through Algorithmiq/release-tools, whose README describes the process in full: release.yml, backport.yml and pr-checks.yml are short stubs calling its reusable workflows, deploy.yml uses its release actions, and the changelog comes from its cliff.toml, all pinned to the same release-tools tag, which Dependabot updates.

Citation

If you use AEGISS in your work, please cite the paper:

@misc{tarocco2025aegissatomicorbital,
      title={AEGISS -- Atomic orbital and Entropy-based Guided Inference for Space Selection -- A novel semi-automated active space selection workflow for quantum chemistry and quantum computing applications},
      author={Fabio Tarocco and Pi A. B. Haase and Fabijan Pavošević and Vijay Krishna and Leonardo Guidoni and Stefan Knecht and Martina Stella},
      year={2025},
      eprint={2508.10671},
      archivePrefix={arXiv},
      primaryClass={physics.chem-ph},
      url={https://arxiv.org/abs/2508.10671},
}

AEGISS builds on DMRG (White 1992, White 1993, Chan & Head-Gordon 2002), run with block2 (Zhai et al. 2023, Zhai & Chan 2021), and on AVAS (Sayfutyarova et al. 2017). It screens on the single-orbital entropy (Legeza & Sólyom 2003, Rissler et al. 2006, Boguslawski et al. 2012, Boguslawski & Tecmer 2015), is built on PySCF (Sun et al. 2018, Sun et al. 2020), and MolTagger uses ASE (Larsen et al. 2017). Please cite them as well; docs/citing.md has the BibTeX for all of them.

Machine-readable metadata for the software, the paper and these references is in CITATION.cff — GitHub's "Cite this repository" widget reads it directly.

License

AEGISS is released under the Apache License 2.0.