ffsim.UCJOpSpinUnbalanced¶

class ffsim.UCJOpSpinUnbalanced(diag_coulomb_mats, orbital_rotations, final_orbital_rotation=None, validate=True, rtol=1e-05, atol=1e-08)[source]¶

Bases: SupportsApplyUnitary, SupportsApproximateEquality

A spin-unbalanced unitary cluster Jastrow operator.

A unitary cluster Jastrow (UCJ) operator has the form

\[\prod_{k = 1}^L \mathcal{U}_k e^{i \mathcal{J}_k} \mathcal{U}_k^\dagger\]

where each \(\mathcal{U_k}\) is an orbital rotation and each \(\mathcal{J}\) is a diagonal Coulomb operator of the form

\[\begin{split}\mathcal{J} = \frac12\sum_{\substack{ij \\ \sigma \tau}} \mathbf{J}^{(\sigma \tau)}_{ij} n_{i\sigma} n_{j\tau}.\end{split}\]

Since \(\mathbf{J}^{(\sigma \tau)}_{ij} = \mathbf{J}^{(\tau \sigma)}_{ji}\), each diagonal Coulomb operator requires 3 matrices for its description: \(\mathbf{J}^{(\alpha \alpha)}\), \(\mathbf{J}^{(\alpha \beta)}\), and \(\mathbf{J}^{(\beta \beta)}\). The number of terms \(L\) is referred to as the number of ansatz repetitions and is accessible via the n_reps attribute.

To support variational optimization of the orbital basis, an optional final orbital rotation can be included in the operator, to be performed at the end.

Parameters:

validate (InitVar[bool]) – Whether to validate the operator attributes. Setting this to False skips validation, which is useful if you need to create many instances of this class and are confident that the attributes are valid.
rtol (InitVar[float]) – Relative numerical tolerance for validation checks.
atol (InitVar[float]) – Absolute numerical tolerance for validation checks.

Attributes

`atol`
`final_orbital_rotation`	The optional final orbital rotation, as a Numpy array of shape `(2, norb, norb)`.
`n_reps`	The number of ansatz repetitions.
`norb`	The number of spatial orbitals.
`rtol`
`validate`
`diag_coulomb_mats`	The diagonal Coulomb matrices, as a Numpy array of shape `(n_reps, 3, norb, norb)`.
`orbital_rotations`	The orbital rotations, as a Numpy array of shape `(n_reps, 2, norb, norb)`.

atol: InitVar[float] = 1e-08¶

final_orbital_rotation: ndarray | None = None¶: The optional final orbital rotation, as a Numpy array of shape (2, norb, norb). This can be viewed as a list of two orbital rotations, the first one for spin alpha and the second one for spin beta.

n_reps¶: The number of ansatz repetitions.

norb¶: The number of spatial orbitals.

rtol: InitVar[float] = 1e-05¶

validate: InitVar[bool] = True¶

diag_coulomb_mats: ndarray¶: The diagonal Coulomb matrices, as a Numpy array of shape (n_reps, 3, norb, norb). The last two axes index the rows and columns of the matrices, and the third from last axis, which has 3 dimensions, indexes the spin interaction type of the matrix: alpha-alpha, alpha-beta, and beta-beta (in that order). The first axis indexes the ansatz repetitions.

orbital_rotations: ndarray¶: The orbital rotations, as a Numpy array of shape (n_reps, 2, norb, norb). The last two axes index the rows and columns of the orbital rotations, and the third from last axis, which has 2 dimensions, indexes the spin sector of the orbital rotation: first alpha, then beta. The first axis indexes the ansatz repetitions.

Methods

`from_parameters`(params, *, norb, n_reps[, ...])	Initialize the UCJ operator from a real-valued parameter vector.
`from_t_amplitudes`(t2, *[, t1, n_reps, ...])	Initialize the UCJ operator from t2 (and optionally t1) amplitudes.
`n_params`(norb, n_reps, *[, ...])	Return the number of parameters of an ansatz with given settings.
`to_parameters`([interaction_pairs])	Convert the UCJ operator to a real-valued parameter vector.

static from_parameters(params, *, norb, n_reps, interaction_pairs=None, with_final_orbital_rotation=False)[source]¶

Initialize the UCJ operator from a real-valued parameter vector.

Parameters:

params (ndarray) – The real-valued parameter vector.
norb (int) – The number of spatial orbitals.
n_reps (int) – The number of ansatz repetitions.
interaction_pairs (tuple[list[tuple[int, int]] | None, list[tuple[int, int]] | None, list[tuple[int, int]] | None] | None) – Optional restrictions on allowed orbital interactions for the diagonal Coulomb operators. If specified, interaction_pairs should be a tuple of 3 lists, for alpha-alpha, alpha-beta, and beta-beta interactions, in that order. Any list can be substituted with None to indicate no restrictions on interactions. Each list should contain pairs of integers representing the orbitals that are allowed to interact. These pairs can also be interpreted as indices of diagonal Coulomb matrix entries that are allowed to be nonzero. For the alpha-alpha and beta-beta interactions, each integer pair must be upper triangular, that is, of the form \((i, j)\) where \(i \leq j\).
with_final_orbital_rotation (bool) – Whether to include a final orbital rotation in the operator.

Return type:

UCJOpSpinUnbalanced

Returns:

The UCJ operator constructed from the given parameters.

Raises:

ValueError – The number of parameters passed did not match the number expected based on the function inputs.
ValueError – Interaction pairs list contained duplicate interactions.
ValueError – Interaction pairs list contained out-of-range orbital indices.
ValueError – Interaction pairs list for alpha-alpha or beta-beta interactions contained lower triangular pairs.

static from_t_amplitudes(t2, *, t1=None, n_reps=None, interaction_pairs=None, tol=1e-08, optimize=False, regularization=0, multi_stage_start=None, multi_stage_step=None, validate=True, rtol=1e-05, atol=1e-08, **optimize_kwargs)[source]¶

Initialize the UCJ operator from t2 (and optionally t1) amplitudes.

Performs a double factorization of the t2 amplitudes and constructs the ansatz repetitions from the terms of the decomposition, up to an optionally specified number of repetitions. Within the alpha-beta and same-spin terms, repetitions are included in decreasing order of the magnitude of the corresponding singular value or eigenvalue in the factorization. See the description of n_reps for how repetitions are divided between the two.

Parameters:

t2 (tuple[ndarray, ndarray, ndarray]) – The t2 amplitudes. This should be a tuple of 3 Numpy arrays, (t2aa, t2ab, t2bb), containing the alpha-alpha, alpha-beta, and beta-beta t2 amplitudes. The same-spin amplitudes t2aa and t2bb must be antisymmetric in the occupied indices and in the virtual indices.
t1 (tuple[ndarray, ndarray] | None) – The t1 amplitudes. This should be a pair of Numpy arrays, (t1a, t1b), containing the alpha and beta t1 amplitudes.
n_reps (int | tuple[int, int] | None) – The number of ansatz repetitions. You can pass a single integer or a pair of integers. If a single integer, the repetitions are divided between terms from the alpha-beta t2 amplitudes and terms from the alpha-alpha and beta-beta t2 amplitudes by selecting the repetitions with the largest magnitudes. The magnitude of an alpha-beta repetition is the corresponding singular value of the alpha-beta t2 amplitudes, and the magnitude of a same-spin repetition is the root sum of squares of the corresponding eigenvalues of the alpha-alpha and beta-beta t2 amplitudes, each scaled by \(1/\sqrt{2}\). With this scaling, the squared magnitudes of all repetitions sum to the squared norm of the t2 amplitudes in the spin-orbital basis, so every distinct excitation counts equally. If a pair of integers, then the first integer specifies the number of terms to use from the alpha-beta t2 amplitudes, and the second integer specifies the number of terms to use from the alpha-alpha and beta-beta t2 amplitudes. If not specified, then it is set to the number of terms resulting from the double factorization of the t2 amplitudes. If the specified number of repetitions is larger than the number of terms resulting from the double factorization, then the ansatz is padded with additional identity operators up to the specified number of repetitions.
interaction_pairs (tuple[list[tuple[int, int]] | None, list[tuple[int, int]] | None, list[tuple[int, int]] | None] | None) – Optional restrictions on allowed orbital interactions for the diagonal Coulomb operators. If specified, interaction_pairs should be a tuple of 3 lists, for alpha-alpha, alpha-beta, and beta-beta interactions, in that order. Any list can be substituted with None to indicate no restrictions on interactions. Each list should contain pairs of integers representing the orbitals that are allowed to interact. These pairs can also be interpreted as indices of diagonal Coulomb matrix entries that are allowed to be nonzero. For the alpha-alpha and beta-beta interactions, each integer pair must be upper triangular, that is, of the form \((i, j)\) where \(i \leq j\).
tol (float) – Tolerance for error in the double-factorized decomposition of the t2 amplitudes. The error is defined as the maximum absolute difference between an element of the original tensor and the corresponding element of the reconstructed tensor.
optimize (bool) – Whether to optimize the tensors returned by the decomposition to minimize the error in the factorization.
regularization (float) – See ffsim.linalg.double_factorized_t2_compressed() for a description of this argument. This argument is ignored if optimize is set to False.
multi_stage_start (int | None) – See ffsim.linalg.double_factorized_t2_compressed() for a description of this argument. This argument is ignored if optimize is set to False.
multi_stage_step (int | None) – See ffsim.linalg.double_factorized_t2_compressed() for a description of this argument. This argument is ignored if optimize is set to False.
validate (bool) – Whether to validate the symmetry of the t2 amplitudes.
rtol (float) – Relative numerical tolerance for validation checks.
atol (float) – Absolute numerical tolerance for validation checks.
optimize_kwargs – Keyword arguments to pass to scipy.optimize.minimize(). The default method is "L-BFGS-B". These arguments are ignored if optimize is set to False.

Return type:

UCJOpSpinUnbalanced

Returns:

The UCJ operator with parameters initialized from the t2 amplitudes.

Raises:

ValueError – Interaction pairs list contained duplicate interactions.
ValueError – Interaction pairs list contained out-of-range orbital indices.
ValueError – Interaction pairs list for alpha-alpha or beta-beta interactions contained lower triangular pairs.
ValueError – The same-spin t2 amplitudes were not antisymmetric.

static n_params(norb, n_reps, *, interaction_pairs=None, with_final_orbital_rotation=False)[source]¶

Return the number of parameters of an ansatz with given settings.

Parameters:

norb (int) – The number of spatial orbitals.
n_reps (int) – The number of ansatz repetitions.
interaction_pairs (tuple[list[tuple[int, int]] | None, list[tuple[int, int]] | None, list[tuple[int, int]] | None] | None) – Optional restrictions on allowed orbital interactions for the diagonal Coulomb operators. If specified, interaction_pairs should be a tuple of 3 lists, for alpha-alpha, alpha-beta, and beta-beta interactions, in that order. Any list can be substituted with None to indicate no restrictions on interactions. Each list should contain pairs of integers representing the orbitals that are allowed to interact. These pairs can also be interpreted as indices of diagonal Coulomb matrix entries that are allowed to be nonzero. For the alpha-alpha and beta-beta interactions, each integer pair must be upper triangular, that is, of the form \((i, j)\) where \(i \leq j\).
with_final_orbital_rotation (bool) – Whether to include a final orbital rotation in the operator.

Return type:

int

Returns:

The number of parameters of the ansatz.

Raises:

ValueError – Interaction pairs list contained duplicate interactions.
ValueError – Interaction pairs list contained out-of-range orbital indices.
ValueError – Interaction pairs list for alpha-alpha or beta-beta interactions contained lower triangular pairs.

to_parameters(interaction_pairs=None)[source]¶

Convert the UCJ operator to a real-valued parameter vector.

Note

If interaction_pairs is specified, the returned parameter vector will incorporate only the diagonal Coulomb matrix entries corresponding to the specified interactions, so the original operator will not be recoverable from the parameter vector.

Parameters:

interaction_pairs (tuple[list[tuple[int, int]] | None, list[tuple[int, int]] | None, list[tuple[int, int]] | None] | None) – Optional restrictions on allowed orbital interactions for the diagonal Coulomb operators. If specified, interaction_pairs should be a tuple of 3 lists, for alpha-alpha, alpha-beta, and beta-beta interactions, in that order. Any list can be substituted with None to indicate no restrictions on interactions. Each list should contain pairs of integers representing the orbitals that are allowed to interact. These pairs can also be interpreted as indices of diagonal Coulomb matrix entries that are allowed to be nonzero. For the alpha-alpha and beta-beta interactions, each integer pair must be upper triangular, that is, of the form \((i, j)\) where \(i \leq j\).

Return type:

ndarray

Returns:

The real-valued parameter vector.

Raises:

ValueError – Interaction pairs list contained duplicate interactions.
ValueError – Interaction pairs list contained out-of-range orbital indices.
ValueError – Interaction pairs list for alpha-alpha or beta-beta interactions contained lower triangular pairs.