ofex.state

class ofex.state.BinaryFockVector(inp: Sequence[int | bool])

Bases: tuple

Represents a binary Fock vector, a tuple-like structure used to describe quantum states in terms of occupation numbers of either qubits or spin orbitals.

property num_qubits: int

Returns: int: The number of qubits (or bits) represented by this BinaryFockVector.

property num_spin_orbitals: int

Returns: int: The number of spin orbitals, equal to the number of qubits.

property num_spatial_orbitals: int

Returns: int: The number of spatial orbitals, calculated as half the number of spin orbitals. Assumes that the total number of spin orbitals is even.

to_int() → int

Converts the BinaryFockVector to its integer representation.

Returns:

Integer equivalent of the binary Fock vector.

Return type:

int

marginal_check(qubits: Sequence[int], idx: int | Sequence[int | bool]) → bool

Checks if the marginal state of the given qubits matches the provided index.

Parameters:

• qubits (Sequence[int]) – Indices of qubits to check against.

• idx (Union[int, Sequence[Union[int, bool]]]) – Expected marginal state, either as an integer or a sequence of binary values.

Returns:

True if the given qubits’ state matches the index, else False.

Return type:

bool

apply_pauli(pauli: Tuple[Tuple[int, str], ...]) → Tuple[BinaryFockVector, complex]

Applies a Pauli operator to the BinaryFockVector, modifying its state and calculating any associated phase change.

Parameters:

pauli (SinglePauli) – A Pauli operator to apply, which contains indices and operation types (X, Y, Z, or I) (e.g. ((0, “X”), (1, “Y”))).

Returns:

A new BinaryFockVector representing the updated state and the complex phase factor introduced by the Pauli operations.

Return type:

Tuple[BinaryFockVector, complex]

pretty_string(fermion: bool = False) → str

Generates a human-readable string representation of the BinaryFockVector.

Parameters:

fermion (bool) – If True, represents the state in a fermionic format. Otherwise, uses a raw binary representation.

Returns:

A string representation of the BinaryFockVector.

Return type:

str

ofex.state.int_to_fock(idx: int, num_qubits: int) → BinaryFockVector

Converts an integer to a BinaryFockVector, suited for a specified number of qubits.

Parameters:

• idx (int) – The integer index representing the state.

• num_qubits (int) – The number of qubits the state should span.

Returns:

The corresponding binary Fock vector representation.

Return type:

BinaryFockVector

Raises:

IndexError – If the integer index exceeds the state space for the given number of qubits.

ofex.state.fock_to_int(fock: BinaryFockVector) → int

Converts a BinaryFockVector to its integer representation.

Parameters:

fock (BinaryFockVector) – The binary Fock vector to convert.

Returns:

The corresponding integer representation.

Return type:

int

ofex.state.state_tools

This module provides utilities for working with quantum states, including state transformations, normalization, sparsity computations, and comparison.

It supports multiple state formats: dense arrays, sparse dictionaries, and Scipy sparse matrices. Additionally, it includes functions for Fock vector conversions and pretty-printed representations of quantum states.

ofex.state.state_tools.get_num_qubits(state: ndarray | Dict[BinaryFockVector, Number] | lil_matrix) → int

Determines the number of qubits in the given quantum state.

Parameters:

state (State) – The quantum state, which can be dense, sparse, or a Scipy sparse type.

Returns:

The number of qubits in the state.

Return type:

int

Raises:

• ValueError – If the dimension of the state is not a power of 2.

• OfexTypeError – If the state type is unsupported.

ofex.state.state_tools.get_state_dim(state: ndarray | Dict[BinaryFockVector, Number] | lil_matrix) → int

Retrieves the dimension of the quantum state.

Parameters:

state (State) – The quantum state in dense, sparse, or Scipy sparse format.

Returns:

The dimension of the state.

Return type:

int

Raises:

OfexTypeError – If the state type is unsupported.

ofex.state.state_tools.get_sparsity(state: ndarray | Dict[BinaryFockVector, Number] | lil_matrix) → int

Computes the sparsity of the given quantum state.

Parameters:

state (State) – The quantum state to analyze.

Returns:

The number of nonzero components in the state.

Return type:

int

Raises:

OfexTypeError – If the state type is unsupported.

ofex.state.state_tools.pretty_print_state(state: ndarray | Dict[BinaryFockVector, Number] | lil_matrix, fermion=False) → str

Returns a string representation of the quantum state with coefficients and basis states.

Parameters:

• state (State) – The quantum state to represent.

• fermion (bool, optional) – If True, uses the fermionic representation. Defaults to False.

Returns:

The pretty-printed representation of the state.

Return type:

str

Raises:

OfexTypeError – If the state type is unsupported.

ofex.state.state_tools.compare_states(state_1: ndarray | Dict[BinaryFockVector, Number] | lil_matrix, state_2: ndarray | Dict[BinaryFockVector, Number] | lil_matrix, str_len=40, atol=1e-08, fermion=False) → str

Compares two quantum states and returns a description of their differences.

Parameters:

• state_1 (State) – The first quantum state.

• state_2 (State) – The second quantum state.

• str_len (int, optional) – String length limit for individual differences. Defaults to 40.

• atol (float, optional) – Absolute tolerance for comparison. Defaults to EQ_TOLERANCE.

• fermion (bool, optional) – If True, uses the fermionic representation. Defaults to False.

Returns:

A string describing the differences between the states.

Return type:

str

ofex.state.state_tools.to_dense(state: ndarray | Dict[BinaryFockVector, Number] | lil_matrix) → ndarray

Converts a quantum state to its dense representation.

Parameters:

state (State) – The quantum state to convert.

Returns:

The dense representation of the state.

Return type:

DenseState

Raises:

OfexTypeError – If the state type is unsupported or cannot be converted.

ofex.state.state_tools.to_scipy_sparse(state: ndarray | Dict[BinaryFockVector, Number] | lil_matrix) → lil_matrix

Converts a quantum state to a Scipy sparse representation.

Parameters:

state (State) – The quantum state to convert.

Returns:

The Scipy sparse representation of the state.

Return type:

ScipySparse

Raises:

OfexTypeError – If the state type is unsupported or cannot be converted.

ofex.state.state_tools.to_sparse_dict(state: ndarray | Dict[BinaryFockVector, Number] | lil_matrix, atol=1e-08) → Dict[BinaryFockVector, Number]

Converts a quantum state into a sparse dictionary format.

Parameters:

• state (State) – The quantum state to convert.

• atol (float, optional) – Absolute tolerance for nonzero values. Defaults to EQ_TOLERANCE.

Returns:

The sparse dictionary representation of the state.

Return type:

SparseStateDict

Raises:

OfexTypeError – If the state type is unsupported or cannot be converted.

ofex.state.state_tools.state_type_transform(state: ndarray | Dict[BinaryFockVector, Number] | lil_matrix, target_type: str) → ndarray | Dict[BinaryFockVector, Number] | lil_matrix

Transforms the quantum state into a specified representation type.

Parameters:

• state (State) – The quantum state to transform.

• target_type (str) – The target representation type (‘dense’, ‘sparse_dict’, ‘scipy_sparse’).

Returns:

The transformed quantum state in the specified format.

Return type:

State

Raises:

ValueError – If the target type is unknown.

ofex.state.state_tools.fock_vector_to_dense_state(fock: BinaryFockVector) → ndarray

Converts a binary Fock vector into a dense quantum state.

Parameters:

fock (BinaryFockVector) – The Fock vector to convert.

Returns:

The dense quantum state corresponding to the Fock vector.

Return type:

DenseState

ofex.state.state_tools.fock_vector_to_scipy_state(fock: BinaryFockVector) → lil_matrix

Converts a binary Fock vector into a Scipy sparse quantum state.

Parameters:

fock (BinaryFockVector) – The Fock vector to convert.

Returns:

The Scipy sparse state corresponding to the Fock vector.

Return type:

ScipySparse

ofex.state.state_tools.state_to_fock_vector(state: ndarray | Dict[BinaryFockVector, Number] | lil_matrix) → BinaryFockVector

Converts a quantum state to a binary Fock vector.

Parameters:

state (State) – The quantum state to convert. The state must represent exactly one Fock vector in sparse dictionary format.

Returns:

The binary Fock vector representation of the state.

Return type:

BinaryFockVector

Raises:

ValueError – If the state does not represent a single Fock vector.

ofex.state.state_tools.compress_sparse(state: Dict[BinaryFockVector, Number] | lil_matrix, atol=1e-08, out_normalize=False) → Dict[BinaryFockVector, Number] | lil_matrix

Compresses a sparse quantum state by removing elements below a tolerance and optionally normalizing it.

Parameters:

• state (Union[SparseStateDict, ScipySparse]) – The sparse quantum state.

• atol (float, optional) – Absolute tolerance for nonzero values. Defaults to EQ_TOLERANCE.

• out_normalize (bool, optional) – If True, normalizes the resulting state. Defaults to False.

Returns:

The compressed (and optionally normalized) sparse state.

Return type:

Union[SparseStateDict, ScipySparse]

Raises:

OfexTypeError – If the state type is unsupported.

ofex.state.state_tools.state_allclose(state_1: ndarray | Dict[BinaryFockVector, Number] | lil_matrix, state_2: ndarray | Dict[BinaryFockVector, Number] | lil_matrix, atol=1e-08, ignore_global_phase: bool = False) → bool

Checks if two quantum states are approximately equal within a tolerance.

Parameters:

• state_1 (State) – The first quantum state.

• state_2 (State) – The second quantum state.

• atol (float, optional) – Absolute tolerance for comparison. Defaults to EQ_TOLERANCE.

• ignore_global_phase (bool, optional) – If True, ignores the global phase of the states. Defaults to False.

Returns:

True if the states are approximately equal, False otherwise.

Return type:

bool

ofex.state.state_tools.norm(state: ndarray | Dict[BinaryFockVector, Number] | lil_matrix) → float

Calculates the L2 norm of the quantum state.

Parameters:

state (State) – The quantum state to compute the norm for.

Returns:

The L2 norm of the state.

Return type:

float

Raises:

OfexTypeError – If the state type is unsupported.

ofex.state.state_tools.normalize(state: ndarray | Dict[BinaryFockVector, Number] | lil_matrix, inplace: bool = False) → ndarray | Dict[BinaryFockVector, Number] | lil_matrix

Normalizes the quantum state to have unit norm.

Parameters:

• state (State) – The quantum state to normalize.

• inplace (bool, optional) – If True, modifies the state in place. Defaults to False.

Returns:

The normalized quantum state.

Return type:

State

Raises:

• ValueError – If the state is a zero state.

• OfexTypeError – If the state type is unsupported.

ofex.state.state_tools.is_zero(state: ndarray | Dict[BinaryFockVector, Number] | lil_matrix) → bool

Checks if the quantum state is effectively a zero state.

Parameters:

state (State) – The quantum state to check.

Returns:

True if the state is a zero state, False otherwise.

Return type:

bool

ofex.state.chem_ref_state

Module containing functions and utilities for manipulating quantum chemical states.

This module provides methods to compute Hartree Fock ground states, configuration interaction (CISD) wavefunctions, and generate configuration state functions (CSFs) for quantum chemistry. It integrates tools for handling fermionic and qubit states, as well as utilities for processing molecular data.

ofex.state.chem_ref_state.hf_ground(mol: MolecularData, active_idx: List[int] | None = None) → Dict[BinaryFockVector, Number]

Generate the Hartree-Fock ground state as a sparse state dictionary.

Parameters:

• mol – An instance of MolecularData which contains molecule information.

• active_idx – List of indices specifying the active orbitals. If None, all orbitals are active.

Returns:

A dictionary representing the Hartree-Fock ground state.

Return type:

SparseStateDict

ofex.state.chem_ref_state.cisd_ground(mol: MolecularData) → Dict[BinaryFockVector, Number]

Compute the CISD (Configuration Interaction with Single and Double excitations) ground state as a sparse state dictionary.

Parameters:

mol – An instance of MolecularData with molecule information.

Returns:

A dictionary representing the CISD ground state.

Return type:

SparseStateDict

ofex.state.chem_ref_state.csf_states(n_orbital: int, n_electrons: int, multiplicity: int = 1, projected_spin: float = 0.0, n_open: int | None = None, cs_excitation: int = 0, os_excitation: int = 0) → List[Dict[BinaryFockVector, Number]]

Generate Configuration State Functions (CSFs) based on specified spin and electron constraints. Refer to Helgaker, T., et al. (2000). Spin in Second Quantization. In Molecular Electronic-Structure Theory. https://doi.org/10.1002/9781119019572.ch2

Parameters:

• n_orbital – Number of spatial orbitals.

• n_electrons – Total number of electrons in the system.

• multiplicity – Spin multiplicity of the states (e.g., 1 for singlet, 3 for triplet).

• projected_spin – Projected value of the total spin (M_s), in half-integer steps.

• n_open – Number of open shells. If None, defaults to multiplicity - 1.

• cs_excitation – Number of excited closed shell electrons.

• os_excitation – Number of excited open shell electrons.

Returns:

A list of sparse state dictionaries representing the CSFs.

Return type:

List[SparseStateDict]

ofex.state.types

This module defines custom types and utility functions to classify and identify different quantum state representations used in physics simulations.

It supports three state representations: 1. Dense states (NumPy 1-dimensional arrays). 2. Sparse dictionary-based states (mapping BinaryFockVector to numerical values). 3. SciPy sparse matrix-based states.

Functions are provided for type checking and classification of these state types.

ofex.state.types.DenseState

alias of ndarray

ofex.state.types.ScipySparse

alias of lil_matrix

ofex.state.types.is_dense_state(state: Any) → bool

Checks if a given state is a dense state (1-dimensional NumPy array).

Parameters:

state (Any) – The state to check.

Returns:

True if the state is a 1-dimensional NumPy array, False otherwise.

Return type:

bool

ofex.state.types.is_sparse_state(state: Any) → bool

Checks if a given state is a sparse state represented as a dictionary.

Parameters:

state (Any) – The state to check.

Returns:

True if the state is a dictionary with keys as BinaryFockVector instances and values as Numbers, False otherwise.

Return type:

bool

ofex.state.types.is_scipy_sparse_state(state: Any) → bool

Checks if a given state is a sparse state represented as a SciPy sparse matrix.

Parameters:

state (Any) – The state to check.

Returns:

True if the state is a 1-row SciPy sparse matrix, False otherwise.

Return type:

bool

ofex.state.types.type_state(state: Any) → str

Determines the type of a given state.

Parameters:

state (Any) – The state to identify.

Returns:

The type of the state, one of “dense”, “sparse_dict”, or “scipy_sparse”.

Return type:

str

Raises:

OfexTypeError – If the state does not match any recognized type.