`pycommute.loperator`

Linear operators in finite-dimensional Hilbert spaces

Elementary spaces

The following classes wrap libcommute’s base class for elementary spaces as well as its extensions for the special cases of fermions, bosons and spins.

class pycommute.loperator.ElementarySpace

Hilbert space corresponding to one quantum degree of freedom

__eq__(self: pycommute.loperator.ElementarySpace, es2: pycommute.loperator.ElementarySpace) → bool: Equality of elementary spaces (the spaces correspond to the same quantum degree of freedom).

__gt__(self: pycommute.loperator.ElementarySpace, es2: pycommute.loperator.ElementarySpace) → bool: Greater-comparison of elementary spaces (comparison of algebra IDs followed by the algebra-specific comparison rule if the IDs coincide).

__lt__(self: pycommute.loperator.ElementarySpace, es2: pycommute.loperator.ElementarySpace) → bool: Less-comparison of elementary spaces (comparison of algebra IDs followed by the algebra-specific comparison rule if the IDs coincide).

__ne__(self: pycommute.loperator.ElementarySpace, es2: pycommute.loperator.ElementarySpace) → bool: Inequality of elementary spaces (the spaces correspond to different quantum degrees of freedom).

property algebra_id: ID of the algebra this elementary space is associated with.

property dim: Dimension of this elementary space.

property indices: Indices carried by this elementary space.

property n_bits: The minimal number of binary digits needed to represent any state in this elementary space.

class pycommute.loperator.ESpaceFermion

Bases: ElementarySpace

Elementary space generated by one fermionic degree of freedom.

__init__(self: pycommute.loperator.ESpaceFermion, indices: pycommute.expression.Indices) → None

Construct a 2-dimensional elementary space a fermionic creation/annihilation operator acts in.

Parameters:: indices – Index sequence of the corresponding creation/annihilation operator.

property dim: Dimension of this elementary space.

loperator.make_space_fermion(*args) → pycommute.loperator.ESpaceFermion

Make a fermionic elementary space with indices passed as positional arguments.

Parameters:: *args – Indices of the corresponding creation/annihilation operator.

class pycommute.loperator.ESpaceBoson

Bases: ElementarySpace

Truncated elementary space generated by one bosonic degree of freedom.

__init__(self: pycommute.loperator.ESpaceBoson, dim: SupportsInt, indices: pycommute.expression.Indices) → None

Construct an elementary space a bosonic creation/annihilation operator acts in.

Parameters:

dim – Required dimension of the truncated space.
indices – Index sequence of the creation/annihilation operator.

property dim: Dimension of this elementary space.

loperator.make_space_boson(dim: SupportsInt, *args) → pycommute.loperator.ESpaceBoson

Make a bosonic elementary space with indices passed as positional arguments.

Parameters:

dim – Required dimension of the truncated space.
*args – Indices of the corresponding creation/annihilation operator.

class pycommute.loperator.ESpaceSpin

Bases: ElementarySpace

Elementary space generated by one spin degree of freedom.

__init__(self: pycommute.loperator.ESpaceSpin, spin: SupportsFloat, indices: pycommute.expression.Indices) → None

Construct an elementary space spin-\(S\) operators act in.

Parameters:

spin – Integer or half-integer value of spin \(S\).
indices – Index sequence of the corresponding spin operator.

property dim: Dimension of this elementary space.

loperator.make_space_spin(spin: SupportsFloat, *args) → pycommute.loperator.ESpaceSpin

Make a spin elementary space with indices passed as positional arguments.

Parameters:

spin – Integer or half-integer value of spin \(S\).
*args – Indices of the corresponding spin operator.

Full Hilbert spaces

HilbertSpace is a wrapper of libcommute’s Hilbert space class.

class pycommute.loperator.HilbertSpace

Bases: pybind11_object

Hilbert space as a direct product of elementary spaces.

__contains__(self: pycommute.loperator.HilbertSpace, es: pycommute.loperator.ElementarySpace) → bool: Is a given elementary space part of the direct product?

__copy__(self: pycommute.loperator.HilbertSpace) → pycommute.loperator.HilbertSpace

__deepcopy__(self: pycommute.loperator.HilbertSpace, memo: dict) → pycommute.loperator.HilbertSpace

__eq__(self: pycommute.loperator.HilbertSpace, hs: pycommute.loperator.HilbertSpace) → bool: Equivalence of Hilbert spaces.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pycommute.loperator.HilbertSpace) -> None

Construct an empty Hilbert space.

__init__(self: pycommute.loperator.HilbertSpace, elementary_spaces: collections.abc.Sequence[pycommute.loperator.ElementarySpace]) -> None

Construct from a list of elementary spaces.

__init__(self: pycommute.loperator.HilbertSpace, expr: pycommute.expression.ExpressionR, dim_boson: typing.SupportsInt = 2) -> None

Inspect a real polynomial expression and collect elementary spaces associated to every algebra generator found in the expression.

Parameters:

expr – Polynomial expression to inspect.
dim_boson – Dimension of every bosonic elementary space to be constructed.

__init__(self: pycommute.loperator.HilbertSpace, expr: pycommute.expression.ExpressionC, dim_boson: typing.SupportsInt = 2) -> None

Inspect a complex polynomial expression and collect elementary spaces associated to every algebra generator found in the expression.

Parameters:

expr – Polynomial expression to inspect.
dim_boson – Dimension of every bosonic elementary space to be constructed.

__len__(self: pycommute.loperator.HilbertSpace) → int: Number of elementary spaces in the direct product.

__ne__(self: pycommute.loperator.HilbertSpace, hs: pycommute.loperator.HilbertSpace) → bool: Inequivalence of Hilbert spaces.

add(self: pycommute.loperator.HilbertSpace, es: pycommute.loperator.ElementarySpace) → None

Add a new elementary space into the direct product.

Parameters:: es – Elementary space to add.

algebra_bit_range(self: pycommute.loperator.HilbertSpace, algebra_id: SupportsInt) → tuple[int, int]

Bit range (lowest bit, highest bit) spanned by a given algebra ID.

Parameters:: algebra_id – Algebra ID.

basis_state_index(self: pycommute.loperator.HilbertSpace, es: pycommute.loperator.ElementarySpace, n: SupportsInt) → int

Returns index of the product basis state, which decomposes over bases of the elementary spaces as \(|0\rangle |0\rangle \ldots |0\rangle |n\rangle_\text{es} |0\rangle \ldots |0\rangle\).

Parameters:

es – Elementary space corresponding to the selected index in the decomposition.
n – Index of the basis state within the selected elementary space.

bit_range(self: pycommute.loperator.HilbertSpace, es: pycommute.loperator.ElementarySpace) → tuple[int, int]

Bit range (lowest bit, highest bit) spanned by a given elementary space in the direct product.

Parameters:: es – Elementary space.

es_dim(self: pycommute.loperator.HilbertSpace, es: pycommute.loperator.ElementarySpace) → int

Dimension of a given elementary space in the direct product.

Parameters:: es – Elementary space.

foreach_elementary_space(self: pycommute.loperator.HilbertSpace, f: collections.abc.Callable[[pycommute.loperator.ElementarySpace], None]) → None

Apply a given functor to all elementary spaces.

Parameters:: f – Functor to be applied.

has_algebra(self: pycommute.loperator.HilbertSpace, algebra_id: SupportsInt) → bool

Is an elementary space with a given algebra ID found in this Hilbert space?

Parameters:: algebra_id – Algebra ID.

index(self: pycommute.loperator.HilbertSpace, es: pycommute.loperator.ElementarySpace) → int: Position of a given elementary space in the product.

property dim: Dimension of this Hilbert space.

property is_sparse: Is this Hilbert space sparse (has a non-power-of-two dimension)?

property total_n_bits: The minimal number of binary digits needed to represent any state in this Hilbert space.

property vec_size: Minimal size of a state vector object compatible with this Hilbert space, \(2^\text{total_n_bits}\).

loperator.foreach(*args, **kwargs)

Overloaded function.

foreach(hs: pycommute.loperator.HilbertSpace, f: collections.abc.Callable[[typing.SupportsInt], None]) -> None

Apply a given functor to all basis state indices in a Hilbert space.

Parameters:

hs – Hilbert space in question.
f – Functor to be applied.

foreach(sp: pycommute.loperator.SpacePartition, f: collections.abc.Callable[[typing.SupportsInt, typing.SupportsInt], None]) -> None

Apply a given functor to all basis states in a given space partition. The functor must take two arguments, index of the basis state and index of the subspace this basis state belongs to.

Parameters:

sp – Space partition in question.
f – Functor to be applied.

Linear operators

LOperatorR and LOperatorC represent libcommute’s linear operator objects specialized for the real and complex scalar types respectively.

class pycommute.loperator.LOperatorR

Real-valued linear operator.

__call__(*args, **kwargs)

Overloaded function.

__call__(self: pycommute.loperator.LOperatorR, src: typing.Annotated[numpy.typing.ArrayLike, numpy.float64], dst: numpy.typing.NDArray[numpy.float64]) -> None

Act on a real state vector and write the result into another real state vector.

Parameters:

src – Source state vector.
dst – Destination state vector.

__call__(self: pycommute.loperator.LOperatorR, src: typing.Annotated[numpy.typing.ArrayLike, numpy.float64], dst: numpy.typing.NDArray[numpy.complex128]) -> None

Act on a real state vector and write the result into another complex state vector.

Parameters:

src – Source state vector.
dst – Destination state vector.

__call__(self: pycommute.loperator.LOperatorR, src: typing.Annotated[numpy.typing.ArrayLike, numpy.complex128], dst: numpy.typing.NDArray[numpy.complex128]) -> None

Act on a complex state vector and write the result into another complex state vector.

Parameters:

src – Source state vector.
dst – Destination state vector.

__call__(self: pycommute.loperator.LOperatorR, src: pycommute.loperator.MappedBasisViewR, dst: pycommute.loperator.MappedBasisViewR) -> None

Act on a mapped view of a real state vector and write the result through a view of another real state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorR, src: pycommute.loperator.MappedBasisViewR, dst: pycommute.loperator.MappedBasisViewC) -> None

Act on a mapped view of a real state vector and write the result through a view of another complex state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorR, src: pycommute.loperator.MappedBasisViewC, dst: pycommute.loperator.MappedBasisViewC) -> None

Act on a mapped view of a complex state vector and write the result through a view of another complex state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorR, src: pycommute.loperator.CompressedStateViewR, dst: pycommute.loperator.CompressedStateViewR) -> None

Act on a view of a real compressed state vector and write the result through a view of another real state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorR, src: pycommute.loperator.CompressedStateViewR, dst: pycommute.loperator.CompressedStateViewC) -> None

Act on a view of a real compressed state vector and write the result through a view of another complex state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorR, src: pycommute.loperator.CompressedStateViewC, dst: pycommute.loperator.CompressedStateViewC) -> None

Act on a view of a complex compressed state vector and write the result through a view of another complex state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorR, src: pycommute.loperator.NFermionSectorViewR, dst: pycommute.loperator.NFermionSectorViewR) -> None

Act on an N-fermion sector view of a real state vector and write the result through a view of another real state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorR, src: pycommute.loperator.NFermionSectorViewR, dst: pycommute.loperator.NFermionSectorViewC) -> None

Act on an N-fermion sector view of a real state vector and write the result through a view of another complex state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorR, src: pycommute.loperator.NFermionSectorViewC, dst: pycommute.loperator.NFermionSectorViewC) -> None

Act on an N-fermion sector view of a complex state vector and write the result through a view of another complex state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorR, src: pycommute.loperator.NFermionMultiSectorViewR, dst: pycommute.loperator.NFermionMultiSectorViewR) -> None

Act on an N-fermion multisector view of a real state vector and write the result through a view of another real state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorR, src: pycommute.loperator.NFermionMultiSectorViewR, dst: pycommute.loperator.NFermionMultiSectorViewC) -> None

Act on an N-fermion multisector view of a real state vector and write the result through a view of another complex state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorR, src: pycommute.loperator.NFermionMultiSectorViewC, dst: pycommute.loperator.NFermionMultiSectorViewC) -> None

Act on an N-fermion multisector view of a complex state vector and write the result through a view of another complex state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__init__(self: pycommute.loperator.LOperatorR, expr: pycommute.expression.ExpressionR, hs: pycommute.loperator.HilbertSpace) → None

Construct the linear operator representing action of a given polynomial expression in a Hilbert space.

Parameters:

expr – Source polynomial expression.
hs – Hilbert space the linear operator acts in.

__mul__(*args, **kwargs)

Overloaded function.

__mul__(self: pycommute.loperator.LOperatorR, sv: typing.Annotated[numpy.typing.ArrayLike, numpy.float64]) -> numpy.typing.NDArray[numpy.float64]

Act on a real state vector and return the resulting vector.

__mul__(self: pycommute.loperator.LOperatorR, sv: typing.Annotated[numpy.typing.ArrayLike, numpy.complex128]) -> numpy.typing.NDArray[numpy.complex128]

Act on a complex state vector and return the resulting vector.

class pycommute.loperator.LOperatorC

Complex-valued linear operator.

__call__(*args, **kwargs)

Overloaded function.

__call__(self: pycommute.loperator.LOperatorC, src: typing.Annotated[numpy.typing.ArrayLike, numpy.float64], dst: numpy.typing.NDArray[numpy.complex128]) -> None

Act on a real state vector and write the result into another complex state vector.

Parameters:

src – Source state vector.
dst – Destination state vector.

__call__(self: pycommute.loperator.LOperatorC, src: typing.Annotated[numpy.typing.ArrayLike, numpy.complex128], dst: numpy.typing.NDArray[numpy.complex128]) -> None

Act on a complex state vector and write the result into another complex state vector.

Parameters:

src – Source state vector.
dst – Destination state vector.

__call__(self: pycommute.loperator.LOperatorC, src: pycommute.loperator.MappedBasisViewR, dst: pycommute.loperator.MappedBasisViewC) -> None

Act on a mapped view of a real state vector and write the result through a view of another complex state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorC, src: pycommute.loperator.MappedBasisViewC, dst: pycommute.loperator.MappedBasisViewC) -> None

Act on a mapped view of a complex state vector and write the result through a view of another complex state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorC, src: pycommute.loperator.CompressedStateViewR, dst: pycommute.loperator.CompressedStateViewC) -> None

Act on a view of a real compressed state vector and write the result through a view of another complex state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorC, src: pycommute.loperator.CompressedStateViewC, dst: pycommute.loperator.CompressedStateViewC) -> None

Act on a view of a complex compressed state vector and write the result through a view of another complex state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorC, src: pycommute.loperator.NFermionSectorViewR, dst: pycommute.loperator.NFermionSectorViewC) -> None

Act on an N-fermion sector view of a real state vector and write the result through a view of another complex state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorC, src: pycommute.loperator.NFermionSectorViewC, dst: pycommute.loperator.NFermionSectorViewC) -> None

Act on an N-fermion sector view of a complex state vector and write the result through a view of another complex state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorC, src: pycommute.loperator.NFermionMultiSectorViewR, dst: pycommute.loperator.NFermionMultiSectorViewC) -> None

Act on an N-fermion multisector view of a real state vector and write the result through a view of another complex state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__call__(self: pycommute.loperator.LOperatorC, src: pycommute.loperator.NFermionMultiSectorViewC, dst: pycommute.loperator.NFermionMultiSectorViewC) -> None

Act on an N-fermion multisector view of a complex state vector and write the result through a view of another complex state vector.

Parameters:

src – View of the source state vector.
dst – View of the destination state vector.

__init__(self: pycommute.loperator.LOperatorC, expr: pycommute.expression.ExpressionC, hs: pycommute.loperator.HilbertSpace) → None

Construct the linear operator representing action of a given polynomial expression in a Hilbert space.

Parameters:

expr – Source polynomial expression.
hs – Hilbert space the linear operator acts in.

__mul__(*args, **kwargs)

Overloaded function.

__mul__(self: pycommute.loperator.LOperatorC, sv: typing.Annotated[numpy.typing.ArrayLike, numpy.float64]) -> numpy.typing.NDArray[numpy.complex128]

Act on a real state vector and return the resulting vector.

__mul__(self: pycommute.loperator.LOperatorC, sv: typing.Annotated[numpy.typing.ArrayLike, numpy.complex128]) -> numpy.typing.NDArray[numpy.complex128]

Act on a complex state vector and return the resulting vector.

Hilbert space partition

SpacePartition is a wrapper around libcommute’s utility class space_partition.

class pycommute.loperator.SpacePartition

Partition of a Hilbert space into a set of disjoint subspaces invariant under action of a given Hermitian operator (Hamiltonian).

For a detailed description of the algorithm see Computer Physics Communications 200, March 2016, 274-284 (section 4.2).

__copy__(self: pycommute.loperator.SpacePartition) → pycommute.loperator.SpacePartition

__deepcopy__(self: pycommute.loperator.SpacePartition, memo: dict) → pycommute.loperator.SpacePartition

__getitem__(self: pycommute.loperator.SpacePartition, basis_state_index: SupportsInt) → int: Find what invariant subspace a given basis state belongs to.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pycommute.loperator.SpacePartition, h: pycommute.loperator.LOperatorR, hs: pycommute.loperator.HilbertSpace) -> None

Partition a finite-dimensional Hilbert space into a direct sum of invariant subspaces of a Hermitian operator.

Parameters:

h – Hermitian operator (Hamiltonian) used to partition the space.
hs – Hilbert space to partition.

__init__(self: pycommute.loperator.SpacePartition, h: pycommute.loperator.LOperatorC, hs: pycommute.loperator.HilbertSpace) -> None

Partition a finite-dimensional Hilbert space into a direct sum of invariant subspaces of a Hermitian operator.

Parameters:

h – Hermitian operator (Hamiltonian) used to partition the space.
hs – Hilbert space to partition.

find_connections(*args, **kwargs)

Overloaded function.

find_connections(self: pycommute.loperator.SpacePartition, o: pycommute.loperator.LOperatorR) -> set[tuple[int, int]]

Analyze connections between subspaces generated by a given operator \(\hat O\). The connections are returned as a set of pairs of subspace serial numbers, (source subspace, destination subspace).

Parameters:: o – Operator \(\hat O\).
Returns:: A set of (source subspace, destination subspace) index pairs.

find_connections(self: pycommute.loperator.SpacePartition, o: pycommute.loperator.LOperatorC) -> set[tuple[int, int]]

Analyze connections between subspaces generated by a given operator \(\hat O\). The connections are returned as a set of pairs of subspace serial numbers, (source subspace, destination subspace).

Parameters:: o – Operator \(\hat O\).
Returns:: A set of (source subspace, destination subspace) index pairs.

merge_subspaces(*args, **kwargs)

Overloaded function.

merge_subspaces(self: pycommute.loperator.SpacePartition, od: pycommute.loperator.LOperatorR, o: pycommute.loperator.LOperatorR, store_matrix_elements: bool = True) -> tuple[dict[tuple[int, int], float], dict[tuple[int, int], float]]

Merge some of the invariant subspaces to ensure that a given operator \(\hat O\) and its Hermitian conjugate \(\hat O^\dagger\) generate only one-to-one connections between the subspaces.

This function can optionally collect non-vanishing matrix elements of \(\hat O\) and \(\hat O^\dagger\) and return them in the form of dictionaries {(i, j) : O_ij}.

Parameters:

od – Operator \(\hat O^\dagger\).
o – Operator \(\hat O\).
store_matrix_elements – Collect the non-vanishing matrix elements of od and o.

Returns:

A tuple containing dictionaries with the collected matrix elements of \(\hat O^\dagger\) and \(\hat O\) (empty dictionaries when store_matrix_elements = False).

merge_subspaces(self: pycommute.loperator.SpacePartition, od: pycommute.loperator.LOperatorC, o: pycommute.loperator.LOperatorC, store_matrix_elements: bool = True) -> tuple[dict[tuple[int, int], complex], dict[tuple[int, int], complex]]

Merge some of the invariant subspaces to ensure that a given operator \(\hat O\) and its Hermitian conjugate \(\hat O^\dagger\) generate only one-to-one connections between the subspaces.

This function can optionally collect non-vanishing matrix elements of \(\hat O\) and \(\hat O^\dagger\) and return them in the form of dictionaries {(i, j) : O_ij}.

Parameters:

od – Operator \(\hat O^\dagger\).
o – Operator \(\hat O\).
store_matrix_elements – Collect the non-vanishing matrix elements of od and o.

Returns:

A tuple containing dictionaries with the collected matrix elements of \(\hat O^\dagger\) and \(\hat O\) (empty dictionaries when store_matrix_elements = False).

subspace_bases(self: pycommute.loperator.SpacePartition) → list[list[int]]: Build and return lists of indices of all basis states spanning all invariant subspaces in the partition. The returned lists are disjoint and their union spans the entire Hilbert space.

subspace_basis(self: pycommute.loperator.SpacePartition, index: SupportsInt) → list[int]

Build and return a list of indices of all basis states spanning a given invariant subspace.

Parameters:: index – Index of the invariant subspace.

property dim: Dimension of the original Hilbert space used to construct this partition.

property n_subspaces: Number of invariant subspaces in this partition.

loperator.make_space_partition(*args, **kwargs)

Overloaded function.

make_space_partition(h: pycommute.loperator.LOperatorR, hs: pycommute.loperator.HilbertSpace, store_matrix_elements: bool = True) -> tuple[pycommute.loperator.SpacePartition, dict[tuple[int, int], float]]

Constructs a partition of a finite-dimensional Hilbert space into a direct sum of invariant subspaces of a given Hermitian operator.

This function can optionally collect non-vanishing matrix elements \(H_{ij}\) of the Hermitian operator and return them in a form of a dictionary {(i, j) : H_ij}.

Parameters:

h – Hermitian operator (Hamiltonian) \(\hat H\) used to partition the space.
hs – Hilbert space to partition.
store_matrix_elements – Collect the non-vanishing matrix elements of h.

Returns:

A tuple containing the constructed SpacePartition object and a dictionary with the collected matrix elements (an empty dictionary when store_matrix_elements = False).

make_space_partition(h: pycommute.loperator.LOperatorC, hs: pycommute.loperator.HilbertSpace, store_matrix_elements: bool = True) -> tuple[pycommute.loperator.SpacePartition, dict[tuple[int, int], complex]]

Constructs a partition of a finite-dimensional Hilbert space into a direct sum of invariant subspaces of a given Hermitian operator.

This function can optionally collect non-vanishing matrix elements \(H_{ij}\) of the Hermitian operator and return them in a form of a dictionary {(i, j) : H_ij}.

Parameters:

h – Hermitian operator (Hamiltonian) \(\hat H\) used to partition the space.
hs – Hilbert space to partition.
store_matrix_elements – Collect the non-vanishing matrix elements of h.

Returns:

A tuple containing the constructed SpacePartition object and a dictionary with the collected matrix elements (an empty dictionary when store_matrix_elements = False).

Mapped views of state vectors

MappedBasisViewR and MappedBasisViewC are wrappers around mapped basis views of real and complex state vectors respectively.

class pycommute.loperator.MappedBasisViewR

This object is a view of a real state vector (one-dimensional NumPy array) that performs index translation according to a predefined map. It is accepted by methods of linear operator objects LOperatorR.__call__() and LOperatorC.__call__().

MappedBasisViewR can be used in situations where a linear operator is known to act only within a subspace of a full Hilbert space, and it is desirable to store vector components only within this particular subspace. The relevant components are then stored in a NumPy array, while the view object translates indices of basis states from the full Hilbert space to the smaller subspace.

class pycommute.loperator.MappedBasisViewC

This object is a view of a complex state vector (one-dimensional NumPy array) that performs index translation according to a predefined map. It is accepted by methods of linear operator objects LOperatorR.__call__() and LOperatorC.__call__().

MappedBasisViewC can be used in situations where a linear operator is known to act only within a subspace of a full Hilbert space, and it is desirable to store vector components only within this particular subspace. The relevant components are then stored in a NumPy array, while the view object translates indices of basis states from the full Hilbert space to the smaller subspace.

class pycommute.loperator.BasisMapper

Factory class for MappedBasisViewR and MappedBasisViewC objects

__call__(*args, **kwargs)

Overloaded function.

__call__(self: pycommute.loperator.BasisMapper, sv: typing.Annotated[numpy.typing.ArrayLike, numpy.float64]) -> pycommute.loperator.MappedBasisViewR

Make a basis mapping view of a real state vector (1-dimensional NumPy array).

Parameters:: sv – The state vector to make the view of.

__call__(self: pycommute.loperator.BasisMapper, sv: typing.Annotated[numpy.typing.ArrayLike, numpy.complex128]) -> pycommute.loperator.MappedBasisViewC

Make a basis mapping view of a complex state vector (1-dimensional NumPy array).

Parameters:: sv – The state vector to make the view of.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: pycommute.loperator.BasisMapper, basis_state_indices: collections.abc.Sequence[typing.SupportsInt]) -> None

Build a mapping from a list of basis state indices to their positions within the list.

Parameters:: basis_state_indices – List of the basis state indices.

__init__(self: pycommute.loperator.BasisMapper, O: pycommute.loperator.LOperatorR, hs: pycommute.loperator.HilbertSpace) -> None

Build a mapping from a set of all basis states contributing to \(\hat O|0\rangle\), where \(|0\rangle\) is the product basis state corresponding to zero index in each elementary space.

\[|0\rangle = |0\rangle_1 |0\rangle_2 |0\rangle_3 \ldots.\]

Parameters:

O – Real-valued linear operator \(\hat O\).
hs – Hilbert space \(\hat O\) acts in.

__init__(self: pycommute.loperator.BasisMapper, O: pycommute.loperator.LOperatorC, hs: pycommute.loperator.HilbertSpace) -> None

Build a mapping from a set of all basis states contributing to \(\hat O|0\rangle\), where \(|0\rangle\) is the product basis state corresponding to zero index in each elementary space.

\[|0\rangle = |0\rangle_1 |0\rangle_2 |0\rangle_3 \ldots.\]

Parameters:

O – Complex-valued linear operator \(\hat O\).
hs – Hilbert space \(\hat O\) acts in.

__init__(self: pycommute.loperator.BasisMapper, O_list: collections.abc.Sequence[pycommute.loperator.LOperatorR], hs: pycommute.loperator.HilbertSpace, N: typing.SupportsInt) -> None

Given a list of operators \(\{\hat O_1, \hat O_2, \hat O_3, \ldots, \hat O_M\}\), build a mapping including all basis states that contribute to all states \(\hat O_1^{n_1} \hat O_2^{n_2} \ldots \hat O_M^{n_M} |0\rangle\).

\(|0\rangle\) is the product basis state corresponding to zero index in each elementary space,

\[|\hat 0\rangle = |0\rangle_1 |0\rangle_2 |0\rangle_3 \ldots,\]

and the non-negative integers \(n_m\) satisfy \(\sum_{m=1}^M n_m = N\). Mapped values are assigned continuously but without any specific order.

Parameters:

O_list – List of real-valued linear operators \(\{\hat O_m\}\).
hs – Hilbert space operators \(\hat O_m\) act in.
N – Total power \(N\).

__init__(self: pycommute.loperator.BasisMapper, O_list: collections.abc.Sequence[pycommute.loperator.LOperatorC], hs: pycommute.loperator.HilbertSpace, N: typing.SupportsInt) -> None

Given a list of operators \(\{\hat O_1, \hat O_2, \hat O_3, \ldots, \hat O_M\}\), build a mapping including all basis states that contribute to all states \(\hat O_1^{n_1} \hat O_2^{n_2} \ldots \hat O_M^{n_M} |0\rangle\).

\(|0\rangle\) is the product basis state corresponding to zero index in each elementary space,

\[|\hat 0\rangle = |0\rangle_1 |0\rangle_2 |0\rangle_3 \ldots,\]

and the non-negative integers \(n_m\) satisfy \(\sum_{m=1}^M n_m = N\). Mapped values are assigned continuously but without any specific order.

Parameters:

O_list – List of complex-valued linear operators \(\{\hat O_m\}\).
hs – Hilbert space operators \(\hat O_m\) act in.
N – Total power \(N\).

__len__(self: pycommute.loperator.BasisMapper) → int: Number of basis states in the mapping.

property inverse_map: Direct access to the inverse mapping as Dict[int, int]. (slow!)

property map: Direct access to the mapping as Dict[int, int].

Views of compressed state vectors

CompressedStateViewR and CompressedStateViewC are wrappers around views of real and complex compressed state vectors respectively.

class pycommute.loperator.CompressedStateViewR

This object is a view of a compressed real state vector (one-dimensional NumPy array) that performs basis state index translation from a (possibly) sparse Hilbert space of dimension dim to the continuous range [0; dim-1]. It is accepted by methods of linear operator objects LOperatorR.__call__() and LOperatorC.__call__().

CompressedStateViewR allows to save memory when working with sparse Hilbert spaces, as only the amplitudes corresponding to the physical basis states need be stored in the NumPy array.

__init__(self: pycommute.loperator.CompressedStateViewR, sv: Annotated[numpy.typing.ArrayLike, numpy.float64], hs: pycommute.loperator.HilbertSpace) → None

Construct a view of a compressed state vector.

Parameters:

sv – The compressed state vector to make the view of.
hs – Hilbert space.

map_index(self: pycommute.loperator.CompressedStateViewR, index: SupportsInt) → int

Translate a basis state index from the Hilbert space to the continuous range [0; hs.dim-1]. If the Hilbert space is sparse, and index does not correspond to a physical basis state, then the result is undefined.

Parameters:: index – The basis state index in the Hilbert space to be translated.

class pycommute.loperator.CompressedStateViewC

This object is a view of a compressed complex state vector (one-dimensional NumPy array) that performs basis state index translation from a (possibly) sparse Hilbert space of dimension dim to the continuous range [0; dim-1]. It is accepted by methods of linear operator objects LOperatorR.__call__() and LOperatorC.__call__().

CompressedStateViewC allows to save memory when working with sparse Hilbert spaces, as only the amplitudes corresponding to the physical basis states need be stored in the NumPy array.

__init__(self: pycommute.loperator.CompressedStateViewC, sv: Annotated[numpy.typing.ArrayLike, numpy.complex128], hs: pycommute.loperator.HilbertSpace) → None

Construct a view of a compressed state vector.

Parameters:

sv – The compressed state vector to make the view of.
hs – Hilbert space.

map_index(self: pycommute.loperator.CompressedStateViewC, index: SupportsInt) → int

Translate a basis state index from the Hilbert space to the continuous range [0; hs.dim-1]. If the Hilbert space is sparse, and index does not correspond to a physical basis state, then the result is undefined.

Parameters:: index – The basis state index in the Hilbert space to be translated.

N-fermion sector views of state vectors

The following types and functions wrap libcommute’s functionality related to the \(N\)-fermion (multi)sector views of state vectors.

loperator.n_fermion_sector_size(hs: pycommute.loperator.HilbertSpace, N: SupportsInt) → int

Compute size of a sector (subspace of a full Hilbert space) with a fixed number of fermions.

Parameters:

hs – Hilbert space.
N – Number of fermions in the sector.

loperator.n_fermion_sector_basis_states(hs: pycommute.loperator.HilbertSpace, N: SupportsInt) → list[int]

Return a list of basis states in a sector (subspace of a full Hilbert space) with a fixed number of fermions.

Parameters:

hs – Hilbert space.
N – Number of fermions in the sector.

class pycommute.loperator.NFermionSectorViewR

This object is a view of a real state vector (one-dimensional NumPy array) that performs basis state index translation from a full Hilbert space to its N-fermion subspace (sector). It is accepted by methods of linear operator objects LOperatorR.__call__() and LOperatorC.__call__().

NFermionSectorViewR can be used in situations where a linear operator is known to act only within the N-fermion sector, and it is desirable to store vector components only within this particular sector.

__init__(self: pycommute.loperator.NFermionSectorViewR, sv: Annotated[numpy.typing.ArrayLike, numpy.float64], hs: pycommute.loperator.HilbertSpace, N: SupportsInt) → None

Construct an N-fermion sector view of a state vector.

Parameters:

sv – The state vector to make the view of.
hs – Hilbert space.
N – Number of fermions in the sector.

map_index(self: pycommute.loperator.NFermionSectorViewR, index: SupportsInt) → int

Map a basis state index from the full Hilbert space to the sector.

Parameters:: index – The basis state index in the full Hilbert space.

class pycommute.loperator.NFermionSectorViewC

This object is a view of a complex state vector (one-dimensional NumPy array) that performs basis state index translation from a full Hilbert space to its N-fermion subspace (sector). It is accepted by methods of linear operator objects LOperatorR.__call__() and LOperatorC.__call__().

NFermionSectorViewC can be used in situations where a linear operator is known to act only within the N-fermion sector, and it is desirable to store vector components only within this particular sector.

__init__(self: pycommute.loperator.NFermionSectorViewC, sv: Annotated[numpy.typing.ArrayLike, numpy.complex128], hs: pycommute.loperator.HilbertSpace, N: SupportsInt) → None

Construct an N-fermion sector view of a state vector.

Parameters:

sv – The state vector to make the view of.
hs – Hilbert space.
N – Number of fermions in the sector.

map_index(self: pycommute.loperator.NFermionSectorViewC, index: SupportsInt) → int

Map a basis state index from the full Hilbert space to the sector.

Parameters:: index – The basis state index in the full Hilbert space.

loperator.n_fermion_multisector_size(hs: pycommute.loperator.HilbertSpace, sectors: collections.abc.Sequence[tuple[collections.abc.Sequence[collections.abc.Sequence[SupportsInt | str]], SupportsInt]]) → int

Compute size of a multisector (subspace of a full Hilbert space). A multisector is a set of all basis states, which have \(N_1\) particles within a subset of fermionic modes \(\{S_1\}\), \(N_2\) particles within another subset \(\{S_2\}\) and so on. There can be any number of individual pairs \((\{S_i\}, N_i)\) (sectors contributing to the multisector) as long as all subsets \(\{S_i\}\) are disjoint.

Parameters:

hs – Hilbert space.
sectors – List of sector descriptors. Each element of the list is a \((\{S_i\}, N_i)\) pair, where \(\{S_i\}\) is a set of index sequences corresponding to the relevant fermionic degrees of freedom.

loperator.n_fermion_multisector_basis_states(hs: pycommute.loperator.HilbertSpace, sectors: collections.abc.Sequence[tuple[collections.abc.Sequence[collections.abc.Sequence[SupportsInt | str]], SupportsInt]]) → list[int]

Return a list of basis states in a multisector (subspace of a full Hilbert space). A multisector is a set of all basis states, which have \(N_1\) particles within a subset of fermionic modes \(\{S_1\}\), \(N_2\) particles within another subset \(\{S_2\}\) and so on. There can be any number of individual pairs \((\{S_i\}, N_i)\) (sectors contributing to the multisector) as long as all subsets \(\{S_i\}\) are disjoint.

Parameters:

hs – Hilbert space.
sectors – List of sector descriptors. Each element of the list is a \((\{S_i\}, N_i)\) pair, where \(\{S_i\}\) is a set of index sequences corresponding to the relevant fermionic degrees of freedom.

class pycommute.loperator.NFermionMultiSectorViewR

This object is a view of a real state vector (one-dimensional NumPy array) that performs basis state index translation from a full Hilbert space to an N-fermion multisector. It is accepted by methods of linear operator objects LOperatorR.__call__() and LOperatorC.__call__().

A multisector is a set of all basis states, which have \(N_1\) particles within a subset of fermionic modes \(\{S_1\}\), \(N_2\) particles within another subset \(\{S_2\}\) and so on. There can be any number of individual pairs \((\{S_i\}, N_i)\) (sectors contributing to the multisector) as long as all subsets \(\{S_i\}\) are disjoint.

NFermionMultiSectorViewR can be used in situations where a linear operator is known to act only within the multisector, and it is desirable to store vector components only within this particular multisector.

__init__(self: pycommute.loperator.NFermionMultiSectorViewR, sv: Annotated[numpy.typing.ArrayLike, numpy.float64], hs: pycommute.loperator.HilbertSpace, sectors: collections.abc.Sequence[tuple[collections.abc.Sequence[collections.abc.Sequence[SupportsInt | str]], SupportsInt]]) → None

Construct an N-fermion multisector view of a state vector.

Parameters:

sv – The state vector to make the view of.
hs – Hilbert space.
sectors – List of sector descriptors. Each element of the list is a \((\{S_i\}, N_i)\) pair, where \(\{S_i\}\) is a set of index sequences corresponding to the relevant fermionic degrees of freedom.

map_index(self: pycommute.loperator.NFermionMultiSectorViewR, index: SupportsInt) → int

Map a basis state index from the full Hilbert space to the multisector.

Parameters:: index – The basis state index in the full Hilbert space.

class pycommute.loperator.NFermionMultiSectorViewC

This object is a view of a complex state vector (one-dimensional NumPy array) that performs basis state index translation from a full Hilbert space to an N-fermion multisector. It is accepted by methods of linear operator objects LOperatorR.__call__() and LOperatorC.__call__().

A multisector is a set of all basis states, which have \(N_1\) particles within a subset of fermionic modes \(\{S_1\}\), \(N_2\) particles within another subset \(\{S_2\}\) and so on. There can be any number of individual pairs \((\{S_i\}, N_i)\) (sectors contributing to the multisector) as long as all subsets \(\{S_i\}\) are disjoint.

NFermionMultiSectorViewC can be used in situations where a linear operator is known to act only within the multisector, and it is desirable to store vector components only within this particular multisector.

__init__(self: pycommute.loperator.NFermionMultiSectorViewC, sv: Annotated[numpy.typing.ArrayLike, numpy.complex128], hs: pycommute.loperator.HilbertSpace, sectors: collections.abc.Sequence[tuple[collections.abc.Sequence[collections.abc.Sequence[SupportsInt | str]], SupportsInt]]) → None

Construct an N-fermion multisector view of a state vector.

Parameters:

sv – The state vector to make the view of.
hs – Hilbert space.
sectors – List of sector descriptors. Each element of the list is a \((\{S_i\}, N_i)\) pair, where \(\{S_i\}\) is a set of index sequences corresponding to the relevant fermionic degrees of freedom.

map_index(self: pycommute.loperator.NFermionMultiSectorViewC, index: SupportsInt) → int

Map a basis state index from the full Hilbert space to the multisector.

Parameters:: index – The basis state index in the full Hilbert space.

Matrix representation of linear operators

loperator.make_matrix(*args, **kwargs)

Overloaded function.

make_matrix(lop: pycommute.loperator.LOperatorR, hs: pycommute.loperator.HilbertSpace) -> numpy.typing.NDArray[numpy.float64]

Make a matrix representation of a given real linear operator acting in a Hilbert space.

Parameters:

lop – Linear operator.
hs – Hilbert space.

Returns: