Hamiltonians#

Factory functions to easily build general Fermion and Qubit Hamiltonians.

The QubitHamiltonian and FermionHamiltonian types are implemented in Rust and re-exported here from ferrmion.core.

class ferrmion.hamiltonians.FermionHamiltonian(*, terms=None, constant_energy=0.0)[source]#

Bases: object

Builder for fermionic Hamiltonians, backed by the Rust [FermionHamiltonian] type.

Terms map ladder-operator signatures (e.g. "+-", "++--") to dense float64 coefficient tensors with one square dimension per signature character.

add_constant(constant_energy)#

Add a constant term to the Hamiltonian.

annihilation()#

Append an annihilation operator to the term being built.

constant_energy#
creation()#

Append a creation operator to the term being built.

n_modes#

Number of fermionic modes, or 0 if no terms have been set.

signatures_and_coefficients#

The signature and coefficients of all terms, as parallel lists.

terms#

The terms as a dict mapping signatures to coefficient arrays.

to_majorana_sparse()#

Convert to a sparse Majorana representation.

Returns:

The sparse Majorana representation of this Hamiltonian.

Return type:

MajoranaSparse

to_sparse_majorana()#

Convert to a sparse Majorana representation.

Returns:

Dictionary mapping tuples of Majorana indices to complex coefficients.

with_coefficients(coefficients)#

Set the coefficients for the accumulated operator signature.

class ferrmion.hamiltonians.QubitHamiltonian(data=None)[source]#

Bases: object

Mapping from Pauli strings to complex coefficients, backed by the Rust [QubitHamiltonian] type.

Supports the standard mapping operations (q[key], q.items(), len(q), q.get(…), dict(q)) and adds Clifford-based optimisation methods that return a new QubitHamiltonian.

clifford_heuristic(temperature=None, coefficient_weighted=False, seed=None, clifford_subset=Ellipsis)#

Optimise this Hamiltonian via Clifford-heuristic simulated annealing.

Parameters:

  • temperature – Initial annealing temperature. Defaults to 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".

Returns:

The optimised Hamiltonian.

Return type:

QubitHamiltonian

coeff_pauli_weight()#

Pauli weight of each term multiplied by its coefficient magnitude.

get(key, default=None)#
items()#
keys()#
n_qubits#

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

pauli_weight()#

Total number of non-identity Pauli operators across all terms.

randomised_subsystem_descent(iterations, subsystem_dimension, temperature=None, coefficient_weighted=False, sampler=Ellipsis, seed=None, clifford_subset=Ellipsis)#

Iteratively optimise by Clifford descent on randomly sampled subsystems.

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 n_qubits.

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

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

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

  • clifford_subset – Gate families to sample from.

Returns:

The optimised Hamiltonian.

Return type:

QubitHamiltonian

to_dict()#

Return the Hamiltonian as a plain dict.

values()#
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.

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

Returns:

The Hubbard model Hamiltonian.

Return type:

FermionHamiltonian

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]