API Reference#
This section contains the complete API documentation for the second_quantization package.
Package Overview#
Core Modules#
Hilbert Space Operations#
The second_quantization.hilbert_space module provides the core functionality for
converting between second-quantized operator expressions and matrix representations.
- second_quantization.hilbert_space.basis_operators(operators, sparse)[source]#
Transform from second quantized operators to matrix representation in the Fock-space.
- Parameters:
- Returns:
A dictionary where the keys are the input operators and the values are their corresponding matrix representations in the Fock-space.
- Return type:
dict[Expr, slice(numpy.ndarray | scipy.sparse._csr.csr_array, None, None)]
Note
The operators list does not require its elements to be FermionOp.
The fermion ordering follows the ordering in the list.
- second_quantization.hilbert_space.parity_operator(operators, sparse)[source]#
Generate the parity operator for a list of fermionic operators.
- Parameters:
- Returns:
A diagonal matrix representing the parity operator, where the diagonal elements are 0 for even parity and 1 for odd parity.
- Return type:
- second_quantization.hilbert_space.to_matrix(expression, operators, sparse, operator_dict=None)[source]#
Transform a sympy expression containing fermionic operators to matrix representation.
Takes a symbolic expression with fermionic operators and converts it to a dictionary containing the matrix representation of each term, grouped by symbolic coefficients.
- Parameters:
- Returns:
A dictionary where the keys are sympy expressions (symbolic coefficients) and the values are the corresponding matrix representations in either dense or sparse format.
- Return type:
Example
```python import sympy as sy from sympy.physics.quantum.fermion import FermionOp from sympy.physics.quantum import Dagger
# Define symbolic parameters and operators t = sy.Symbol(‘t’) c = FermionOp(‘c’) d = FermionOp(‘d’)
# Define an expression expr = t * Dagger(c) * d
# Convert to matrix form matrices = to_matrix(expr, [c, d], sparse=False) ```
- second_quantization.hilbert_space.to_operators(matrix, basis)[source]#
Convert matrices back to symbolic fermionic operator expressions.
- Parameters:
matrix (dict[Expr, ndarray | csr_array] | ndarray | csr_array) – The matrix to be converted. It can be a dictionary with sympy expressions as keys and numpy arrays or scipy sparse arrays as values, or it can be a numpy array or a scipy sparse array directly.
basis (list[Expr]) – A list of sympy expressions representing the basis operators.
- Returns:
The normal ordered operator expression corresponding to the input matrix.
- Return type:
- second_quantization.hilbert_space.find(s, ch)[source]#
Find all indices of a character in a string.
- Parameters:
- Returns:
A list of indices where the character is found.
- Return type:
Note
Taken from: https://stackoverflow.com/questions/11122291/how-to-find-char-in-string-and-get-all-the-indexes Author: Stack Overflow user Lev Levitsky License: CC BY-SA 4.0 (https://creativecommons.org/licenses/by-sa/4.0/)
- second_quantization.hilbert_space.string_basis(fermions)[source]#
Generate a list of bitstrings representing the occupation of fermions.
- Parameters:
- Returns:
List of bitstrings representing all possible occupation states.
- Return type:
Example
For 2 fermions, returns [‘00’, ‘01’, ‘10’, ‘11’] representing the four possible occupation states.
- second_quantization.hilbert_space.symbolic_basis(fermions)[source]#
Generate a list of symbolic fermionic operators corresponding to the occupation of fermions.
This function creates the symbolic representation of all possible occupation states in the fermionic Fock space for the given set of fermionic operators.
- Parameters:
- Returns:
List of symbolic fermionic operators representing all possible occupation states. The first element is always the vacuum state (represented as sympy.S.One), followed by all single-particle states, two-particle states, etc.
- Return type:
Example
For 2 fermions [c, d], returns: - [1, d†, c†, c†*d†] representing vacuum, single occupations, and double occupation.
- second_quantization.hilbert_space.make_dict_callable(hamiltonian_dict)[source]#
Create a callable function from a dictionary of SymPy expressions and NumPy arrays.
This function takes a dictionary where keys are symbolic expressions (containing free symbols) and values are NumPy arrays, and creates a callable function that evaluates the weighted sum of the arrays based on the symbolic expressions.
- Parameters:
hamiltonian_dict (dict[Expr, ndarray]) – A dictionary where keys are SymPy expressions (which may contain free symbols) and values are NumPy arrays of the same shape.
- Returns:
A callable function that takes values for all free symbols found in the dictionary keys and returns the weighted sum: Σ(expr_value * array) where expr_value is the numerical evaluation of each symbolic expression.
- Raises:
ValueError – If any symbol names would be converted to Dummy variables by SymPy’s lambdify function. This typically happens with special characters or reserved names.
- Return type:
callable
Example
```python import sympy as sp import numpy as np
# Define symbolic parameters x, y = sp.symbols(‘x y’)
# Create dictionary with symbolic expressions and matrices ham_dict = {
x: np.array([[1, 0], [0, 0]]), y: np.array([[0, 1], [1, 0]])
}
# Create callable function func = make_dict_callable(ham_dict)
# Evaluate at specific parameter values result = func(x=2.0, y=1.5) # Returns 2.0 * first_matrix + 1.5 * second_matrix ```
- second_quantization.hilbert_space.partial_trace_generators(subset, all_operators, sparse, operator_dict=None)[source]#
Generate the projectors required to compute the partial trace of a subset of operators.
- Parameters:
- Returns:
numpy array with the projectors that trace out the subset of operators specified in the argument. The final trace is taken by projecting a matrix M as np.sum([p[:,i,:] @ M @ p[:,i,:].conj().T for i in range(p.shape[1])]).
- Return type:
Main Functions#
- second_quantization.hilbert_space.to_matrix(expression, operators, sparse, operator_dict=None)[source]#
Transform a sympy expression containing fermionic operators to matrix representation.
Takes a symbolic expression with fermionic operators and converts it to a dictionary containing the matrix representation of each term, grouped by symbolic coefficients.
- Parameters:
- Returns:
A dictionary where the keys are sympy expressions (symbolic coefficients) and the values are the corresponding matrix representations in either dense or sparse format.
- Return type:
Example
```python import sympy as sy from sympy.physics.quantum.fermion import FermionOp from sympy.physics.quantum import Dagger
# Define symbolic parameters and operators t = sy.Symbol(‘t’) c = FermionOp(‘c’) d = FermionOp(‘d’)
# Define an expression expr = t * Dagger(c) * d
# Convert to matrix form matrices = to_matrix(expr, [c, d], sparse=False) ```
- second_quantization.hilbert_space.to_operators(matrix, basis)[source]#
Convert matrices back to symbolic fermionic operator expressions.
- Parameters:
matrix (dict[Expr, ndarray | csr_array] | ndarray | csr_array) – The matrix to be converted. It can be a dictionary with sympy expressions as keys and numpy arrays or scipy sparse arrays as values, or it can be a numpy array or a scipy sparse array directly.
basis (list[Expr]) – A list of sympy expressions representing the basis operators.
- Returns:
The normal ordered operator expression corresponding to the input matrix.
- Return type:
- second_quantization.hilbert_space.make_dict_callable(hamiltonian_dict)[source]#
Create a callable function from a dictionary of SymPy expressions and NumPy arrays.
This function takes a dictionary where keys are symbolic expressions (containing free symbols) and values are NumPy arrays, and creates a callable function that evaluates the weighted sum of the arrays based on the symbolic expressions.
- Parameters:
hamiltonian_dict (dict[Expr, ndarray]) – A dictionary where keys are SymPy expressions (which may contain free symbols) and values are NumPy arrays of the same shape.
- Returns:
A callable function that takes values for all free symbols found in the dictionary keys and returns the weighted sum: Σ(expr_value * array) where expr_value is the numerical evaluation of each symbolic expression.
- Raises:
ValueError – If any symbol names would be converted to Dummy variables by SymPy’s lambdify function. This typically happens with special characters or reserved names.
- Return type:
callable
Example
```python import sympy as sp import numpy as np
# Define symbolic parameters x, y = sp.symbols(‘x y’)
# Create dictionary with symbolic expressions and matrices ham_dict = {
x: np.array([[1, 0], [0, 0]]), y: np.array([[0, 1], [1, 0]])
}
# Create callable function func = make_dict_callable(ham_dict)
# Evaluate at specific parameter values result = func(x=2.0, y=1.5) # Returns 2.0 * first_matrix + 1.5 * second_matrix ```
Basis Generation#
- second_quantization.hilbert_space.basis_operators(operators, sparse)[source]#
Transform from second quantized operators to matrix representation in the Fock-space.
- Parameters:
- Returns:
A dictionary where the keys are the input operators and the values are their corresponding matrix representations in the Fock-space.
- Return type:
dict[Expr, slice(numpy.ndarray | scipy.sparse._csr.csr_array, None, None)]
Note
The operators list does not require its elements to be FermionOp.
The fermion ordering follows the ordering in the list.
- second_quantization.hilbert_space.string_basis(fermions)[source]#
Generate a list of bitstrings representing the occupation of fermions.
- Parameters:
- Returns:
List of bitstrings representing all possible occupation states.
- Return type:
Example
For 2 fermions, returns [‘00’, ‘01’, ‘10’, ‘11’] representing the four possible occupation states.
- second_quantization.hilbert_space.symbolic_basis(fermions)[source]#
Generate a list of symbolic fermionic operators corresponding to the occupation of fermions.
This function creates the symbolic representation of all possible occupation states in the fermionic Fock space for the given set of fermionic operators.
- Parameters:
- Returns:
List of symbolic fermionic operators representing all possible occupation states. The first element is always the vacuum state (represented as sympy.S.One), followed by all single-particle states, two-particle states, etc.
- Return type:
Example
For 2 fermions [c, d], returns: - [1, d†, c†, c†*d†] representing vacuum, single occupations, and double occupation.
- second_quantization.hilbert_space.find(s, ch)[source]#
Find all indices of a character in a string.
- Parameters:
- Returns:
A list of indices where the character is found.
- Return type:
Note
Taken from: https://stackoverflow.com/questions/11122291/how-to-find-char-in-string-and-get-all-the-indexes Author: Stack Overflow user Lev Levitsky License: CC BY-SA 4.0 (https://creativecommons.org/licenses/by-sa/4.0/)
Pauli String Decomposition#
The second_quantization.pauli_strings module provides tools for decomposing
matrices into Pauli string representations.
- second_quantization.pauli_strings.PauliDecomposition(matrix, PauliStringInit='')[source]#
Computes the Pauli decomposition of a square matrix.
Iteratively splits tensor factors off and decomposes those smaller matrices. This is done using submatrices of the original matrix. The Pauli strings are generated in each step.
- Parameters:
matrix – Matrix to be decomposed (Preferably numpy array/scipysparse).
sparse – Whether matrix is in sparse format.
PauliStringInit – For recursive computation.
- Returns:
String of 1XYZ with their factors.
- Return type:
decomposition/outString
- second_quantization.pauli_strings.PauliDecomposition(matrix, PauliStringInit='')[source]#
Computes the Pauli decomposition of a square matrix.
Iteratively splits tensor factors off and decomposes those smaller matrices. This is done using submatrices of the original matrix. The Pauli strings are generated in each step.
- Parameters:
matrix – Matrix to be decomposed (Preferably numpy array/scipysparse).
sparse – Whether matrix is in sparse format.
PauliStringInit – For recursive computation.
- Returns:
String of 1XYZ with their factors.
- Return type:
decomposition/outString