ffsim.contract

Functions for contracting tensors and constructing linear operators.

ffsim.contract.contract_diag_coulomb(vec, mat, norb, nelec, *, z_representation=False)

Contract a diagonal Coulomb operator with a vector.

A diagonal Coulomb operator has the form

$$\sum _{i,j,\sigma ,\tau }{Z}_{ij}^{(\sigma \tau )}{n}_{\sigma ,i}{n}_{\tau ,j}/2$$

where $n_{\sigma ,i}$ denotes the number operator on orbital $i$ with spin $\sigma$ and $Z^{(\sigma \tau )}$ is a real-valued matrix

Parameters:

• vec (ndarray) – The state vector to be transformed.

• mat (ndarray | tuple[ndarray | None, ndarray | None, ndarray | None]) – The diagonal Coulomb matrix $Z$. You can pass either a single Numpy array specifying the coefficients to use for all spin interactions, or you can pass a tuple of three Numpy arrays specifying independent coefficients for alpha-alpha, alpha-beta, and beta-beta interactions (in that order). If passing a tuple, you can set a tuple element to None to indicate the absence of interactions of that type.

• norb (int) – The number of spatial orbitals.

• nelec (tuple[int, int]) – The number of alpha and beta electrons.

• z_representation (bool) – Whether the input matrices are in the “Z” representation.

Return type:

ndarray

Returns:

The result of applying the diagonal Coulomb operator on the input state vector.

ffsim.contract.contract_num_op_sum(vec, coeffs, norb, nelec)

Contract a linear combination of number operators with a vector.

A linear combination of number operators has the form

$$\sum _{\sigma ,i}{\lambda }_i{n}_{\sigma ,i}$$

where $n_{\sigma ,i}$ denotes the number operator on orbital $i$ with spin $\sigma$ and the ${\lambda }_i$ are real numbers.

Parameters:

• vec (ndarray) – The state vector to be transformed.

• coeffs (ndarray) – The coefficients of the linear combination.

• norb (int) – The number of spatial orbitals.

• nelec (tuple[int, int]) – The number of alpha and beta electrons.

Returns:

The result of applying the linear combination of number operators on the input state vector.

ffsim.contract.contract_one_body(vec, mat, norb, nelec)

Contract a one-body tensor with a vector.

A one-body tensor has the form

$$\sum _{ij}{M}_{ij}{a}_i^{†}{a}_j$$

where $M$ is a complex-valued matrix.

Parameters:

• mat (ndarray) – The one-body tensor.

• norb (int) – The number of spatial orbitals.

• nelec (tuple[int, int]) – The number of alpha and beta electrons.

Return type:

ndarray

Returns:

A LinearOperator that implements the action of the one-body tensor.

ffsim.contract.diag_coulomb_linop(mat, norb, nelec, *, orbital_rotation=None, z_representation=False)

Convert a (rotated) diagonal Coulomb matrix to a linear operator.

A rotated diagonal Coulomb operator has the form

$$\mathcal{U}(\sum _{i,j,\sigma ,\tau }{Z}_{ij}^{(\sigma \tau )}{n}_{\sigma ,i}{n}_{\tau ,j}/2){\mathcal{U}}^{†}$$

where $n_{\sigma ,i}$ denotes the number operator on orbital $i$ with spin $\sigma$, $Z^{(\sigma \tau )}$ is a real-valued matrix, and $\mathcal{U}$ is an optional orbital rotation.

Parameters:

• mat (ndarray | tuple[ndarray | None, ndarray | None, ndarray | None]) – The diagonal Coulomb matrix $Z$. You can pass either a single Numpy array specifying the coefficients to use for all spin interactions, or you can pass a tuple of three Numpy arrays specifying independent coefficients for alpha-alpha, alpha-beta, and beta-beta interactions (in that order). If passing a tuple, you can set a tuple element to None to indicate the absence of interactions of that type.

• norb (int) – The number of spatial orbitals.

• nelec (tuple[int, int]) – The number of alpha and beta electrons.

• orbital_rotation (ndarray | tuple[ndarray | None, ndarray | None] | None) – The optional orbital rotation. You can pass either a single Numpy array specifying the orbital rotation to apply to both spin sectors, or you can pass a pair of Numpy arrays specifying independent orbital rotations for spin alpha and spin beta. If passing a pair, you can use None for one of the values in the pair to indicate that no operation should be applied to that spin sector.

• z_representation (bool) – Whether the input matrices are in the “Z” representation.

Return type:

LinearOperator

Returns:

A LinearOperator that implements the action of the diagonal Coulomb operator.

ffsim.contract.num_op_sum_linop(coeffs, norb, nelec, *, orbital_rotation=None)

Convert a (rotated) linear combination of number operators to a linear operator.

A rotated linear combination of number operators has the form

$$\mathcal{U}(\sum _{\sigma ,i}{\lambda }_i{n}_{\sigma ,i}){\mathcal{U}}^{†}$$

where $n_{\sigma ,i}$ denotes the number operator on orbital $i$ with spin $\sigma$, the ${\lambda }_i$ are real numbers, and $\mathcal{U}$ is an optional orbital rotation.

Parameters:

• coeffs (ndarray) – The coefficients of the linear combination.

• norb (int) – The number of spatial orbitals.

• nelec (tuple[int, int]) – The number of alpha and beta electrons.

• orbital_rotation (ndarray | None) – A unitary matrix describing the optional orbital rotation.

Return type:

LinearOperator

Returns:

A LinearOperator that implements the action of the linear combination of number operators.

ffsim.contract.one_body_linop(mat, norb, nelec)

Convert a one-body tensor to a linear operator.

A one-body tensor has the form

$$\sum _{ij}{M}_{ij}{a}_i^{†}{a}_j$$

where $M$ is a complex-valued matrix.

Parameters:

• mat (ndarray) – The one-body tensor.

• norb (int) – The number of spatial orbitals.

• nelec (tuple[int, int]) – The number of alpha and beta electrons.

Return type:

LinearOperator

Returns:

A LinearOperator that implements the action of the one-body tensor.