geope.lie

geope.lie.Basis

A Lie algebra basis for quantum Hamiltonian parameterisation.

Wraps a rank-3 tensor of Hermitian basis matrices together with associated labels, interaction metadata, and convenience utilities for building and manipulating Lie-algebraic decompositions.

Attributes:

Name	Type	Description
basis		Array of shape (K, d, d) containing the basis matrices.
labels		List of Pauli-string labels, e.g. ['XI', 'ZZ'].
plot_labels		LaTeX-formatted labels for plotting.
interaction_labels		Compact lower-case interaction labels.
interaction_qubits		Tuple of qubit indices involved in each basis element.
interaction_graph		List of qubit-pair tuples representing interactions.
interaction_map		Dictionary mapping qubit tuples to interaction labels.
n		Number of qubits (\(\log_2 d\)).
local_dim		Local Hilbert-space dimension (default 2).
dim		Total Hilbert-space dimension \(d\).
lie_algebra_dim		Number of basis elements \(K\).
shape		Shape of the underlying basis tensor (K, d, d).

__dict__ class-attribute

__doc__ class-attribute

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__module__ class-attribute

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__weakref__ property

list of weak references to the object

basis property

The rank-3 array of basis matrices.

dim property

Total Hilbert-space dimension.

interaction_graph property

List of qubit-pair tuples representing interactions.

interaction_labels property

Compact lower-case interaction labels.

interaction_map property

Dictionary mapping qubit tuples to interaction labels.

interaction_qubits property

Tuple of qubit indices for each basis element.

labels property

String labels for each basis element, or None.

lie_algebra_dim property

Number of basis elements.

local_dim property

Local Hilbert-space dimension.

n property

Number of qubits.

plot_labels property

LaTeX-formatted labels for plotting.

shape property

Shape of the basis tensor (K, d, d).

__init__(basis, labels=None, local_dim=2, n_qubits=None, interaction_graph=None, interaction_map=None)

Initialise a Basis.

Parameters:

Name	Type	Description	Default
basis	ndarray	Rank-3 np.ndarray of shape (K, d, d) of Hermitian matrices.	required
labels	list[str] | None	Optional list of string labels for each basis element. Defaults to None.	None
local_dim	int	Local Hilbert-space dimension. Defaults to 2.	2
n_qubits	int | None	Optional override for the number of qubits. Useful when the Hilbert-space dimension is not \(2^n\) (e.g. a direct sum of single-qubit blocks). When None (the default), \(n\) is inferred from basis.shape[1] as \(\log_2 d\).	None
interaction_graph	list[tuple[int, ...]] | None	Optional list of qubit-index tuples restricting which interactions to keep.	None
interaction_map	dict[tuple[int, ...], list[str]] | None	Optional dictionary mapping qubit tuples to lists of interaction labels to keep.	None

__len__()

Return the number of basis elements.

apply_interaction_graph(interaction_graph)

Apply an interaction graph to the basis.

Removes any multi-body basis elements whose qubit indices are not present in the supplied interaction graph. Single-body terms are always retained.

Parameters:

Name	Type	Description	Default
interaction_graph	list[tuple[int, ...]]	A list of tuples or lists, each containing the qubit indices of an allowed interaction (e.g. [(1, 2), (2, 3)]).	required

Returns:

Type	Description
list[tuple[int, ...]]	The applied interaction graph as a list of tuples.

apply_interaction_map(interaction_map)

Apply an interaction map to the basis.

Removes basis elements whose qubit-index tuple is not a key in the map, or whose interaction label is not in the corresponding value list.

Parameters:

Name	Type	Description	Default
interaction_map	dict[tuple[int, ...], list[str]]	Dictionary mapping qubit-index tuples to lists of allowed interaction label strings.	required

Returns:

Type	Description
dict[tuple[int, ...], list[str]]	The applied interaction map dictionary.

generate_bounds(bounds_map, piecewise_steps)

Generate lower and upper parameter bounds from a bounds map.

Parameters:

Name	Type	Description	Default
bounds_map	dict[str, tuple[float, float]]	Dictionary whose keys are interaction label strings and whose values are (min, max) tuples.	required
piecewise_steps	int	Number of piecewise gate segments.	required

Returns:

Type	Description
list[list[float]]	A tuple (lower_bounds, upper_bounds) where each element is a
list[list[float]]	nested list of shape (piecewise_steps, K).

generate_parameter_list(parameter_map)

Generate a parameter vector from a human-readable parameter map.

Parameters:

Name	Type	Description	Default
parameter_map	dict[int | tuple[int, ...], dict[str, float]]	Dictionary whose keys are qubit indices (int) or qubit-index tuples, and whose values are dictionaries mapping interaction labels to parameter values.	required

Returns:

Type	Description
list[float]	A list of parameter values aligned with the basis ordering.

linear_span(parameters)

Compute the linear combination of basis matrices.

Parameters:

Name	Type	Description	Default
parameters	ndarray	Coefficient np.ndarray of length K.	required

Returns:

Type	Description
ndarray	A (d, d) np.ndarray equal to \(\sum_k \phi_k B_k\).

overlap(other)

Compute the overlap mask between this basis and another.

Uses trace inner products to determine which elements of other have non-zero overlap with elements of this basis.

Parameters:

Name	Type	Description	Default
other	Basis	Another Basis instance.	required

Returns:

Type	Description
ndarray	A boolean np.ndarray of length other.lie_algebra_dim
ndarray	that is True where an overlap exists.

verify()

Verify that the basis elements are orthogonal under the trace inner product.

Returns:

Type	Description
bool	True if the trace-inner-product Gram matrix is diagonal,
bool	False otherwise.

geope.lie.Hamiltonian

A Hamiltonian defined by a Lie-algebra basis and coefficient vector.

Constructs \(H = \sum_k \phi_k B_k\) and its matrix exponential \(U = e^{iH}\).

Attributes:

Name	Type	Description
basis		The Basis object defining the algebra.
parameters		Coefficient vector \(\boldsymbol{\phi}\).
matrix		The Hamiltonian matrix \(H\).
unitary		A Unitary wrapping \(U = e^{iH}\).

__dict__ class-attribute

__doc__ class-attribute

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__module__ class-attribute

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__weakref__ property

list of weak references to the object

__init__(basis, parameters)

Initialise a Hamiltonian.

Parameters:

Name	Type	Description	Default
basis	Basis	A Basis instance defining the Lie algebra.	required
parameters	ndarray	Coefficient np.ndarray of same length as the basis.	required

fidelity(unitary_matrix)

Compute the fidelity of this Hamiltonian's unitary to a target.

Parameters:

Name	Type	Description	Default
unitary_matrix	ndarray	The target unitary np.ndarray.	required

Returns:

Type	Description
Array	Scalar fidelity Array in \([0, 1]\).

geodesic_hamiltonian(target_unitary)

Compute the geodesic Hamiltonian towards a target unitary.

Parameters:

Name	Type	Description	Default
target_unitary	ndarray	The target unitary np.ndarray.	required

Returns:

Type	Description
Hamiltonian	A Hamiltonian whose exponentiation yields the geodesic
Hamiltonian	rotation from self.unitary to target_unitary.

parameters_from_hamiltonian(hamiltonian, basis) staticmethod

Extract Lie-algebra coefficients from a Hamiltonian matrix.

Parameters:

Name	Type	Description	Default
hamiltonian	ndarray	The Hamiltonian np.ndarray of shape (d, d).	required
basis	Basis	The Basis to decompose into.	required

Returns:

Type	Description
ndarray	A real-valued parameter np.ndarray of length
ndarray	basis.lie_algebra_dim.

geope.lie.Unitary

A unitary matrix acting on \(n\) qubits.

Validates that the input is indeed unitary (\(UU^\dagger = I\)) and exposes convenience methods for fidelity and geodesic computation.

Attributes:

Name	Type	Description
matrix		The unitary matrix of shape (d, d).
n		Number of qubits (\(\log_2 d\)).

__dict__ class-attribute

__doc__ class-attribute

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__module__ class-attribute

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__weakref__ property

list of weak references to the object

__init__(unitary_matrix)

Initialise a Unitary.

Parameters:

Name	Type	Description	Default
unitary_matrix	ndarray	A square unitary np.ndarray of dimension \(2^n imes 2^n\).	required

Raises:

Type	Description
ValueError	If the matrix is not unitary or not square.

__matmul__(other)

fidelity(unitary_matrix)

Compute the fidelity to a target unitary.

Parameters:

Name	Type	Description	Default
unitary_matrix	ndarray	The target unitary np.ndarray.	required

Returns:

Type	Description
Array	Scalar fidelity Array in \([0, 1]\).

geodesic_hamiltonian(basis, target_unitary)

Compute the geodesic Hamiltonian towards a target unitary.

Parameters:

Name	Type	Description	Default
basis	Basis	The Basis for the Hamiltonian decomposition.	required
target_unitary	ndarray	The target unitary np.ndarray.	required

Returns:

Type	Description
Hamiltonian	A Hamiltonian whose exponentiation yields the geodesic
Hamiltonian	rotation from self to target_unitary.

parameters(basis)

Extract Lie-algebra coefficients via the principal matrix logarithm.

Parameters:

Name	Type	Description	Default
basis	Basis	The Basis to decompose into.	required

Returns:

Type	Description
ndarray	A real-valued parameter np.ndarray of length
ndarray	basis.lie_algebra_dim.

parameters_from_unitary(unitary_matrix, basis) staticmethod

Extract Lie-algebra coefficients from a unitary matrix.

Uses the principal matrix logarithm to recover the generator, then decomposes it in the given basis.

Parameters:

Name	Type	Description	Default
unitary_matrix	ndarray	The unitary np.ndarray of shape (d, d).	required
basis	Basis	The Basis to decompose into.	required

Returns:

Type	Description
ndarray	A real-valued parameter np.ndarray of length
ndarray	basis.lie_algebra_dim.

unitary_fidelity(matrixA, matrixB) staticmethod

Compute the fidelity between two unitary matrices.

Parameters:

Name	Type	Description	Default
matrixA	Array	First unitary Array.	required
matrixB	Array	Second unitary Array.	required

Returns:

Type	Description
Array	Scalar fidelity Array in \([0, 1]\).