Skip to content

geope.utils¤

geope.utils.trace_dot_jit(x, y) ¤

Compute the trace of the matrix product \(\mathrm{Tr}(xy)\).

JIT-compiled for use inside scan loops.

Parameters:

Name Type Description Default
x Array

First matrix Array.

 required
y Array

Second matrix Array.

 required

Returns:

Type Description
Array

A scalar trace Array.

geope.utils.traces(b_1, b_2) ¤

Compute the trace inner-product Gram matrix between two basis sets.

Returns a matrix \(G_{ij} = \mathrm{Tr}(B^{(1)}_i B^{(2)}_j)\) for all pairs of basis elements.

Parameters:

Name Type Description Default
b_1 ndarray

First basis tensor np.ndarray of shape (K1, d, d).

 required
b_2 ndarray

Second basis tensor np.ndarray of shape (K2, d, d).

 required

Returns:

Type Description
Array

A complex Array of shape (K1, K2).

geope.utils.check_xy_comb(comb) ¤

Check whether a Pauli index combination is valid for XY-type interactions.

Allows single-body terms and two-body terms with identical non-identity Pauli indices (XX, YY), but not ZZ or mixed two-body terms.

Parameters:

Name Type Description Default
comb tuple[int, ...]

Tuple of integers (0=I, 1=X, 2=Y, 3=Z).

 required

Returns:

Type Description
bool

True if the combination is allowed.

geope.utils.check_Heisenberg_comb(comb) ¤

Check whether a Pauli index combination is valid for Heisenberg interactions.

Allows single-body terms and two-body terms with identical non-identity Pauli indices (XX, YY, ZZ).

Parameters:

Name Type Description Default
comb tuple[int, ...]

Tuple of integers (0=I, 1=X, 2=Y, 3=Z).

 required

Returns:

Type Description
bool

True if the combination is allowed.

geope.utils.check_2_local_comb(comb) ¤

Check whether a Pauli index combination is at most 2-local.

Allows any term acting on at most two qubits.

Parameters:

Name Type Description Default
comb tuple[int, ...]

Tuple of integers (0=I, 1=X, 2=Y, 3=Z).

 required

Returns:

Type Description
bool

True if the combination involves at most two non-identity
bool

Pauli operators.

geope.utils.restriction_function(restriction) ¤

Create a filter function from a list of allowed interaction strings.

Each string in restriction encodes an allowed Pauli combination using characters 'x', 'y', 'z'.

Parameters:

Name Type Description Default
restriction list[str]

List of strings, e.g. ['xx', 'yy', 'zz'].

 required

Returns:

Type Description
Callable[[tuple[int, ...]], bool]

A Callable[[tuple[int, ...]], bool] that accepts a Pauli
Callable[[tuple[int, ...]], bool]

index tuple and returns True if it matches any allowed pattern.

geope.utils.restriction_order_function(n, restriction) ¤

Create an ordered restriction filter from a dictionary.

Parameters:

Name Type Description Default
n int

Number of qubits.

 required
restriction dict[int | tuple[int, ...], list[str]]

Dictionary mapping qubit indices (or tuples) to lists of interaction label strings.

 required

Returns:

Type Description
Callable[[tuple[int, ...]], bool]

A Callable[[tuple[int, ...]], bool] that accepts a Pauli
Callable[[tuple[int, ...]], bool]

index tuple and returns True if it matches the restriction.

geope.utils.construct_restricted_pauli_basis(n, restriction) ¤

Construct a Pauli basis restricted by allowed interactions.

Parameters:

Name Type Description Default
n int

Number of qubits.

 required
restriction list[str] | dict[int | tuple[int, ...], list[str]]

Either a list of allowed interaction strings or a dictionary mapping qubit indices to interaction labels.

 required

Returns:

Type Description
Basis

A Basis instance containing only the allowed Pauli strings.

geope.utils.construct_Heisenberg_pauli_basis(n) ¤

Construct the Pauli basis for a Heisenberg-type Hamiltonian.

Includes all single-body Pauli terms and two-body terms of the form XX, YY, ZZ on any pair of qubits.

Parameters:

Name Type Description Default
n int

Number of qubits.

 required

Returns:

Type Description
Basis

A Basis instance.

geope.utils.construct_two_body_pauli_basis(n) ¤

Construct the full two-body Pauli basis.

Includes all Pauli strings acting on at most two qubits.

Parameters:

Name Type Description Default
n int

Number of qubits.

 required

Returns:

Type Description
Basis

A Basis instance.

geope.utils.construct_full_pauli_basis(n) ¤

Construct the full \(n\)-qubit Pauli basis (excluding identity).

Contains all \(4^n - 1\) non-identity Pauli strings.

Parameters:

Name Type Description Default
n int

Number of qubits.

 required

Returns:

Type Description
Basis

A Basis instance.

geope.utils.creation_annihilation_operators(boson_truncation) ¤

Build truncated bosonic creation and annihilation operators.

Parameters:

Name Type Description Default
boson_truncation int

Maximum occupation number.

 required

Returns:

Type Description
ndarray

A tuple (a_0, a_minus, a_plus) where a_0 is the identity,
ndarray

a_minus is the lowering operator, and a_plus is the
ndarray

raising operator, each of dimension boson_truncation + 1.

geope.utils.construct_full_spin_boson_basis(n_spins, n_bosons, boson_truncation=3) ¤

Construct the full spin-boson Pauli-like basis.

Combines all \(n\)-qubit Pauli strings with bosonic position (\(q\)) and momentum (\(p\)) operators on each bosonic mode.

Parameters:

Name Type Description Default
n_spins int

Number of spin (qubit) degrees of freedom.

 required
n_bosons int

Number of bosonic modes.

 required
boson_truncation int

Fock-space truncation level. Defaults to 3.

 3

Returns:

Type Description
Basis

A Basis instance.

geope.utils.construct_restricted_spin_boson_basis(n_spins, n_bosons, restriction, boson_truncation=3) ¤

Construct a restricted spin-boson basis.

Like construct_full_spin_boson_basis but only includes Pauli strings matching the given restriction.

Parameters:

Name Type Description Default
n_spins int

Number of spin (qubit) degrees of freedom.

 required
n_bosons int

Number of bosonic modes.

 required
restriction list[str] | dict[int | tuple[int, ...], list[str]]

Either a list of allowed interaction strings or a dictionary mapping qubit indices to interaction labels.

 required
boson_truncation int

Fock-space truncation level. Defaults to 3.

 3

Returns:

Type Description
Basis

A Basis instance.

geope.utils.prepare_random_parameters(proj_indices, expander=None, spread=1.0, key=Array((), dtype=key<fry>) overlaying:[0 0]) ¤

Generate a random parameter vector for the projected subspace.

Samples uniform random values in \([-\text{spread}, \text{spread}]\) and optionally expands them through a constraint matrix.

Parameters:

Name Type Description Default
proj_indices ndarray

Boolean np.ndarray mask indicating projected parameter positions.

 required
expander ndarray | None

Optional constraint expansion np.ndarray.

 None
spread float

Half-width of the uniform sampling range. Defaults to 1.0.

 1.0
key Array

JAX random key. Defaults to jax.random.key(0).

 Array((), dtype=key<fry>) overlaying: [0 0]

Returns:

Type Description
ndarray

A parameter np.ndarray of the same length as proj_indices
ndarray

with random values at projected positions and zeros elsewhere.

geope.utils.construct_commuting_ansatz_matrix(params, sols) ¤

Construct the commuting-ansatz substitution matrix.

Builds a matrix that encodes how free parameters map to the full parameter vector through the symbolic solutions.

Parameters:

Name Type Description Default
params list

List of symbolic parameter names (or 0 / falsy for absent parameters).

 required
sols dict

Dictionary mapping dependent parameter names to symbolic expressions.

 required

Returns:

Type Description
ndarray

A square numpy array of shape (len(params), len(params)).

geope.utils.remove_solution_free_parameters(params, sols) ¤

Identify which parameters are free (not determined by solutions).

Parameters:

Name Type Description Default
params list

List of symbolic parameter names.

 required
sols dict

Dictionary of solved dependent parameters.

 required

Returns:

Type Description
list[int]

A list of 0s and 1s; 1 indicates a free parameter.

geope.utils.multikron(matrices) ¤

Compute the Kronecker product of a list of matrices.

Parameters:

Name Type Description Default
matrices list[ndarray]

List of 2-D arrays.

 required

Returns:

Type Description
ndarray

The iterated Kronecker product.

geope.utils.multicontrol_unitary(local_unitary, num_controls) ¤

Embed a single-qubit unitary as a multi-controlled gate.

Places local_unitary in the bottom-right \(2 \times 2\) block of a \(2^{n+1} \times 2^{n+1}\) identity matrix, where \(n\) is num_controls.

Parameters:

Name Type Description Default
local_unitary ndarray

A \(2 \times 2\) unitary matrix.

 required
num_controls int

Number of control qubits.

 required

Returns:

Type Description
ndarray

The full multi-controlled unitary matrix.

geope.utils.qft_unitary(num_qubits) ¤

Construct the Quantum Fourier Transform unitary.

Parameters:

Name Type Description Default
num_qubits int

Number of qubits.

 required

Returns:

Type Description
ndarray

A \(2^n \times 2^n\) QFT unitary matrix.

geope.utils.golden_section_search_np(f, a, b, tol=1e-05) ¤

Golden-section search using NumPy.

Finds the minimum of a unimodal function f on the interval \([a, b]\) to within tolerance tol.

Parameters:

Name Type Description Default
f Callable[[float], float]

Scalar-valued unimodal callable.

 required
a float

Left endpoint of the search interval.

 required
b float

Right endpoint of the search interval.

 required
tol float

Convergence tolerance. Defaults to 1e-5.

 1e-05

Returns:

Type Description
float

A tuple (x_min, f_min) of the approximate minimiser
float

and its function value.
Example 
f = lambda x: (x - 2) ** 2
x_min, f_min = golden_section_search_np(f, 1, 5)
References

Golden-section search

JIT-compatible golden-section search using JAX.

Finds the minimum of a unimodal function f on the interval \([a, b]\) using jax.lax.while_loop, making it compatible with JIT compilation.

Parameters:

Name Type Description Default
f Callable[[Array], Array]

Scalar-valued unimodal callable.

 required
a_init float | Array

Left endpoint of the search interval.

 required
b_init float | Array

Right endpoint of the search interval.

 required
tol float

Convergence tolerance. Defaults to 1e-5.

 1e-05

Returns:

Type Description
Array

A tuple (x_min, f_min) of the approximate minimiser
Array

and its function value.
Example 
f = lambda x: (x - 2) ** 2
x_min, f_min = golden_section_search(f, 1.0, 5.0)
References

Golden-section search

JIT-compatible 1-D Adam line search using JAX.

Minimises a scalar function f on the interval \([a, b]\) by running a fixed number of Adam steps on the scalar variable t, clipping t back into the interval after every step. Uses jax.lax.fori_loop (fixed step count), making it compatible with JIT compilation.

The gradient df/dt is obtained either by a finite-difference secant from successive evaluations (finite_difference=True; derivative-free, one f evaluation per step) or by jax.value_and_grad (finite_difference=False; exact, but differentiates through f). f must map a real scalar to a real scalar.

Adam is not monotone, so the best iterate visited is tracked and returned — the result is never worse than f(t_init).

Parameters:

Name Type Description Default
f Callable[[Array], Array]

Scalar-valued callable (real -> real).

 required
a_init float | Array

Left endpoint of the search interval.

 required
b_init float | Array

Right endpoint of the search interval.

 required
lr float

Adam learning rate. Defaults to 0.05.

 0.05
num_steps int

Number of Adam iterations. Defaults to 30.

 30
finite_difference bool

If True (default), estimate the gradient with a finite-difference secant; otherwise use jax.value_and_grad.

 True
fd_step float

Probe size for the finite-difference bootstrap. Defaults to 1e-3.

 0.001
beta1 float

First-moment decay. Defaults to 0.9.

 0.9
beta2 float

Second-moment decay. Defaults to 0.999.

 0.999
eps float

Numerical-stability term. Defaults to 1e-8.

 1e-08
t_init float | Array

Starting point for t. Defaults to 0.0.

 0.0

Returns:

Type Description
Array

A tuple (t_best, f_best) of the best minimiser found and its
Array

function value, matching the (x_min, f_min) contract of
tuple[Array, Array]

func:golden_section_search.
Example 
f = lambda x: (x - 2.0) ** 2
x_min, f_min = adam_line_search(f, 0.0, 5.0, lr=0.1, num_steps=200)
References

Adam

geope.utils.merge_constraints(constraints, rtol=1e-09, atol=1e-12) ¤

Merge overlapping linear equality constraints.

Iteratively merges rows of the constraint matrix that share non-zero entries, verifying consistency of the overlap.

Parameters:

Name Type Description Default
constraints list[ndarray]

List of 1-D arrays (all same length) representing linear constraints.

 required
rtol float

Relative tolerance for consistency check. Defaults to 1e-9.

 1e-09
atol float

Absolute tolerance for consistency check. Defaults to 1e-12.

 1e-12

Returns:

Type Description
list[list[float]]

A list of merged constraint vectors with no overlapping
list[list[float]]

non-zero entries.

Raises:

Type Description
ValueError

If overlapping constraints are inconsistent.