[![Release CICD](https://github.com/UCL-CCS/ferrmion/actions/workflows/release.yaml/badge.svg)](https://github.com/UCL-CCS/ferrmion/actions/workflows/release.yaml)
[![Documentation Status](https://readthedocs.org/projects/ferrmion/badge/?version=latest)](https://ferrmion.readthedocs.io/en/latest/?badge=latest)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17236185.svg)](https://doi.org/10.5281/zenodo.17236185)

# ferrmion

This codebase contains methods to generate optimised qubit Hamiltonians from fermionic Hamiltonians.

## Why use ferrmion?

### Reduced Circuit Depth
By reducing the average Pauli-weight of operators in the output hamiltonian, circuit depth can be improved without changing the underlying encoding.

<img width="512" height="384" alt="Transpiled circuit depth for the qDRIFT algorithm, showing reductions of 25-30% for various qubit encodings." src="https://github.com/user-attachments/assets/b367a19f-c0a5-47fd-b910-9214d3158914" />

### It's fast!
Hamiltonians up to 40 qubits currently take less than 1 second to optimise.

![runtime against number of modes](docs/source/images/runtime.png)

for more detail see our [paper](https://arxiv.org/abs/2512.13580).

## Interop

Most quantum SDKs will have methods to convert common python types to native objects, so it's usually possible to create an operator using the `.edge_operator` and `number_operator` functions of a `FermionQubitEncoding`.

Please open an issue or pull request on github if you would like to suggest a documented interop.

### Qiskit
`ferrmion` provides a method to convert its narive encoding class `FermionQubitencoding` to a `qiskit_nature.QubitMapper`.

To use this feature, you'll need to install optional dependencies with:
```
pip install ferrmion[qiskit]
```

For more details, see the [interop documentation](https://ferrmion.readthedocs.io/en/latest/interop/).



## Encodings
- Ternary Tree encodings

    Any ternary tree can be generated by adding nodes to a tree structure, and functions exist to easily create standard encodings including: Jordan-Wigner, Parity, Bravyi-Kitaev and JKMN

- MaxNTO encodings

    A non-ternary-tree majorana string encoding with the maximal non-trivial overlap possible.
    Only works for systems with even numbers of modes (i.e. all spin-orbit Hamiltonians)


## Optimizations

### Enumeration Scheme
- $(\lambda+\mu)$ [Evolutionary Algorithm](https://ferrmion.readthedocs.io/en/latest/notebooks/pauli_weight.html#evolutionary-optimisation)
- [Simulated Annealing](https://ferrmion.readthedocs.io/en/latest/notebooks/pauli_weight.html#simulated-annealing)

### Ternary Trees

- [Topology-preserving Hamiltonian Adaptive Ternary Tree](https://ferrmion.readthedocs.io/en/latest/notebooks/topp_hatt.html)
- [Bonsai Algorithm](https://ferrmion.readthedocs.io/en/latest/notebooks/bonsai.html)
- [Reduced Entanglement Ternary Trees](https://ferrmion.readthedocs.io/en/latest/notebooks/rett.html)
- [Huffman-code Ternary Tree](https://ferrmion.readthedocs.io/en/latest/notebooks/huffman.html)
- [Hamiltonian Adaptive Ternary Tree](https://ferrmion.readthedocs.io/en/latest/notebooks/hatt.html)


## Hamiltonians
Arbitrary fermionic Hamiltonians can be built with the `FermionHamiltonian` class in `ferrmion.hamiltonians`. Additionally there are named functions for:

- Molecular Hamiltonian (Born-Oppenheimer Approximation)
- Hubbard Hamiltonian (3D Square lattice)

See the [example notebook](https://ferrmion.readthedocs.io/en/latest/notebooks/encoding_hamiltonians.html#) for more information.

## Development
For information on development, check out the project [documentation](https://ferrmion.readthedocs.io/en/latest/development.html).

If you find an error in the code or documentation, please raise an issue on the [GitHub Repo](https://github.com/UCL-CCS/ferrmion).
