Fermionic Hamiltonians#

Class and methods to easily build general Fermion Hamiltonians.

class ferrmion.hamiltonians.FermionHamiltonian(*, terms: dict[str, ndarray[tuple[int, ...], dtype[_ScalarType_co]]] = {}, constant_energy: float = 0.0)[source]#

Bases: object

Class for building Fermionic Hamiltonians.

add_constant(constant_energy: float) → FermionHamiltonian[source]#

Add a constant term to the Hamiltonian.

annihilation() → FermionHamiltonian[source]#

Add an annihilation term.

creation() → FermionHamiltonian[source]#

Add a creation term.

property signatures_and_coefficients: tuple[list[str], list[ndarray[tuple[int, ...], dtype[_ScalarType_co]]]]#

Return the signature and coefficient of all terms.

with_coefficients(coefficients: ndarray[tuple[int, ...], dtype[_ScalarType_co]]) → FermionHamiltonian[source]#

Add coefficients to the Hamiltonian terms.

class ferrmion.hamiltonians.QubitHamiltonian[source]#

Bases: dict[str, complex]

Mapping from Pauli strings to complex coefficients.

Subclasses dict so all standard mapping operations (q[key], q.items(), len(q), q.get(...)) work as expected, and adds Clifford-based optimisation methods that return a new QubitHamiltonian.

clifford_heuristic(temperature: float | None = None, coefficient_weighted: bool = False, seed: int | None = None, clifford_subset: str = 'chs') → QubitHamiltonian[source]#

Optimise this Hamiltonian via Clifford-heuristic simulated annealing.

Parameters:

  • temperature – Initial annealing temperature. Defaults to 2 * n_qubits.

  • coefficient_weighted – If True, minimise coefficient-weighted Pauli weight.

  • seed – Seed for the RNG. Defaults to 1017 when omitted.

  • clifford_subset – Gate families to sample from. One of "all", "c", "ch", "cs", "chs" (default), or "vp" (vacuum-preserving: uniform pick between a single S or a single CNOT, which together stabilise the |0…0⟩ vacuum of any ternary-tree-derived encoding).

Returns:

The optimised Hamiltonian.

Return type:

QubitHamiltonian

property n_qubits: int#

Number of qubits, inferred from the length of any Pauli key.

randomised_subsystem_descent(iterations: int, subsystem_dimension: int, temperature: float | None = None, coefficient_weighted: bool = False, sampler: str = 'hamming', seed: int | None = None, clifford_subset: str = 'chs') → QubitHamiltonian[source]#

Iteratively optimise this Hamiltonian via Clifford-heuristic simulated annealing.

Parameters:

  • iterations – Number of subsystem-local Clifford descents to perform.

  • subsystem_dimension – Number of qubits in each sampled subsystem.

  • temperature – Annealing temperature for each descent. Defaults to 2 * n_qubits.

  • coefficient_weighted – If True, minimise coefficient-weighted Pauli weight.

  • sampler – Subsystem sampling strategy: "full_system", "uniform", or "hamming".

  • seed – Seed for the RNG. Defaults to 1017 when omitted.

  • clifford_subset – Gate families to sample from. One of "all", "c", "ch", "cs", "chs" (default), or "vp" (vacuum-preserving: uniform pick between a single S or a single CNOT).

Returns:

The optimised Hamiltonian.

Return type:

QubitHamiltonian

ferrmion.hamiltonians.cube_lattice_adjacency_matrix(shape: tuple[int, int, int], periodic: bool) → ndarray[tuple[int, ...], dtype[bool]][source]#

Creates an adjacency matrix for a 3D square lattice Hubbard Hamiltonian.

Parameters:

  • shape (tuple[int, int, int]) – The number of sites.

  • periodic (bool) – If true, periodic boundary conditions are used.

Returns:

Adjacency matrix for lattice sites.

Return type:

np.ndarray[bool]

ferrmion.hamiltonians.hubbard_coefficients(n_modes: int, adjacency_matrix: ndarray[tuple[int, ...], dtype[_ScalarType_co]], onsite_term: float, hopping_term: float = 1.0, spinless: bool = False) → tuple[ndarray, ndarray][source]#

Coefficients to fill a Hubbard Hamiltonian Template.

Parameters:

  • n_modes (int) – Number of fermion modes in the system.

  • adjacency_matrix (npt.NDArray) – Adjacency matrix of lattice sites.

  • onsite_term (float) – Onsite interaction term.

  • hopping_term (float) – Kinetic term.

  • spinless (bool) – Set to True to use single spin Hamiltonian.

Returns:

one and two electron coefficients.

Return type:

tuple

ferrmion.hamiltonians.hubbard_hamiltonian(adjacency_matrix: ndarray[tuple[int, ...], dtype[_ScalarType_co]], onsite_term: float, hopping_term: float = 1.0, spinless: bool = False) → FermionHamiltonian[source]#

Return a Hubbard model Hamiltonian.

As the Hubbard Hamiltonian has the same signature as the Chemists’ Molecular Hamiltonian (+-, +-+-), the molecular Hamiltonian functions are reused internally.

Parameters:

  • adjacency_matrix (npt.NDArray) – Adjacency matrix of lattice sites.

  • onsite_term (float) – Onsite two-electron term.

  • hopping_term (float) – Kinetic term coefficient.

  • physicist_notation (bool) – Set to False for Chemist Notation.

  • spinless (bool) – Set to True to use single spin Hamiltonian.

Returns:

A qubit Hamiltonian.

Return type:

dict[str, float]

Example

>>> import numpy as np
>>> from ferrmion.hamiltonians import hubbard_hamiltonian, linear_adjacency_matrix
>>> adjacency = linear_adjacency_matrix(4, periodic=False)
>>> fham = hubbard_hamiltonian(adjacency, onsite_term=2.0)
>>> fham.n_modes
8
ferrmion.hamiltonians.linear_adjacency_matrix(length: int, periodic: bool) → ndarray[tuple[int, ...], dtype[bool]][source]#

Creates an adjacency matrix for a linear Hubbard Hamiltonian.

Parameters:

  • length (int) – The number of sites.

  • periodic (bool) – If true, periodic boundary conditions are used.

Returns:

Adjacency matrix for lattice sites.

Return type:

np.ndarray[bool]

ferrmion.hamiltonians.molecular_hamiltonian(one_e_coeffs: ndarray[tuple[int, ...], dtype[_ScalarType_co]], two_e_coeffs: ndarray[tuple[int, ...], dtype[_ScalarType_co]], constant_energy: float = 0.0, physicist_notation: bool = True) → FermionHamiltonian[source]#

Return a molecular electronic structure Hamiltonian.

Parameters:

  • one_e_coeffs (NDArray) – One electron hamiltonian coefficients in spinorb format.

  • two_e_coeffs (NDArray) – Two electron hamiltonian coefficients in spinorb format.

  • constant_energy (float) – Constant energy offset.

  • physicist_notation (bool) – Set to False for Chemist Notation.

Example

>>> import numpy as np
>>> from ferrmion.hamiltonians import molecular_hamiltonian
>>> one_e = np.eye(2)
>>> two_e = np.zeros((2, 2, 2, 2))
>>> fham = molecular_hamiltonian(one_e, two_e, 0.0)
>>> fham.n_modes
2
ferrmion.hamiltonians.square_lattice_adjacency_matrix(shape: tuple[int, int], periodic: bool) → ndarray[tuple[int, ...], dtype[bool]][source]#

Creates an adjacency matrix for a 2D square lattice Hubbard Hamiltonian.

Parameters:

  • shape (tuple[int, int]) – The number of sites.

  • periodic (bool) – If true, periodic boundary conditions are used.

Returns:

Adjacency matrix for lattice sites.

Return type:

np.ndarray[bool]