ffsim.UCJAnglesOpSpinBalanced

class ffsim.UCJAnglesOpSpinBalanced(norb, num_num_ansatz_ops, givens_ansatz_ops, final_givens_ansatz_op=None)[source]

Bases: SupportsApplyUnitary, SupportsApproximateEquality

A spin-balanced UCJ operator parameterized by gate rotation angles.

This operator has the same form as UCJOpSpinBalanced,

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

but it is parameterized by the angles of the gates that implement it rather than by orbital rotation and diagonal Coulomb matrices. Each orbital rotation \(\mathcal{U}_k\) is represented by a GivensAnsatzOp, a sequence of Givens rotations followed by a layer of single-orbital phase gates. Each diagonal Coulomb evolution \(e^{i \mathcal{J}_k}\) is represented by a NumNumAnsatzOpSpinBalanced, a sequence of number-number interactions whose angles are the entries of the diagonal Coulomb matrices \(\mathbf{J}^{(\alpha \alpha)}\) and \(\mathbf{J}^{(\alpha \beta)}\) at the specified interaction pairs. 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.

Attributes

final_givens_ansatz_op

The optional Givens rotation ansatz operator representing the final orbital rotation.

n_reps

The number of ansatz repetitions.

norb

The number of spatial orbitals.

num_num_ansatz_ops

The number-number interaction ansatz operators, one per ansatz repetition.

givens_ansatz_ops

The Givens rotation ansatz operators, one per ansatz repetition.
final_givens_ansatz_op: GivensAnsatzOp | None = None

The optional Givens rotation ansatz operator representing the final orbital rotation.

n_reps

The number of ansatz repetitions.

norb: int

The number of spatial orbitals.

num_num_ansatz_ops: list[NumNumAnsatzOpSpinBalanced]

The number-number interaction ansatz operators, one per ansatz repetition.

givens_ansatz_ops: list[GivensAnsatzOp]

The Givens rotation ansatz operators, one per ansatz repetition. The operator for repetition \(k\) represents the orbital rotation \(\mathcal{U}_k\).

Methods

from_cisd_vec(cisd_vec, *, norb, nocc[, ...])

Initialize the UCJ operator from a CISD vector.

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.

from_ucj_op(ucj_op, *[, interaction_pairs])

Initialize the angles-based UCJ operator from a matrix-based UCJ operator.

n_params(norb, n_reps, *[, ...])

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

to_parameters()

Convert the UCJ operator to a real-valued parameter vector.
static from_cisd_vec(cisd_vec, *, norb, nocc, c0_threshold=1e-12, 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 a CISD vector.

Constructs a UCJOpSpinBalanced using UCJOpSpinBalanced.from_cisd_vec() and converts it using from_ucj_op(). See UCJOpSpinBalanced.from_cisd_vec() for how the CISD amplitudes are converted to CC-style amplitudes.

Parameters:

  • cisd_vec (ndarray) – The CISD vector. This is a one-dimensional array containing the reference coefficient \(c_0\) in the first entry, followed by the singles and then doubles coefficients.

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

  • nocc (int) – The number of occupied orbitals.

  • c0_threshold (float) – Absolute value threshold for the reference coefficient. An error is raised if the absolute value of \(c_0\) is smaller than this threshold.

  • n_reps (int | None) – The number of ansatz repetitions. 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] | None) – Optional restrictions on allowed orbital interactions for the number-number interactions. If specified, interaction_pairs should be a pair of lists, for alpha-alpha and alpha-beta interactions, in that order. Either 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. 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 converted 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 converted 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:

UCJAnglesOpSpinBalanced

Returns:

The UCJ operator with parameters initialized from the CISD amplitudes.

Raises:

  • ValueError – The CISD reference coefficient is smaller than the specified threshold c0_threshold.

  • ValueError – Interaction pairs list contained duplicate interactions.

  • ValueError – Interaction pairs list contained out-of-range orbital indices.

  • ValueError – Interaction pairs list contained lower triangular pairs.

  • ValueError – The converted t2 amplitudes did not have the required symmetry.

static from_parameters(params, *, norb, n_reps, num_num_interaction_pairs=None, givens_interaction_pairs=None, with_final_givens_ansatz_op=False)[source]

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

For each ansatz repetition, the parameter vector contains the parameters of the Givens rotation ansatz operator followed by the parameters of the number-number interaction ansatz operator. These are followed by the parameters of the final Givens rotation ansatz operator, if present. See GivensAnsatzOp.to_parameters() and NumNumAnsatzOpSpinBalanced.to_parameters() for the parameter orderings of the individual operators.

Parameters:

  • params (ndarray) – The real-valued parameter vector.

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

  • n_reps (int) – The number of ansatz repetitions.

  • num_num_interaction_pairs (tuple[list[tuple[int, int]] | None, list[tuple[int, int]] | None] | None) – Optional restrictions on allowed orbital interactions for the number-number interactions. If specified, num_num_interaction_pairs should be a pair of lists, for alpha-alpha and alpha-beta interactions, in that order. Either list can be substituted with None to indicate no restrictions on interactions, in which case all upper triangular pairs are used. Each integer pair must be upper triangular, that is, of the form \((i, j)\) where \(i \leq j\).

  • givens_interaction_pairs (list[tuple[int, int]] | None) – The orbital pairs to apply the Givens rotations to in each ansatz repetition. If not specified, a full brickwork pattern of nearest-neighbor pairs with norb layers is used, which is the pattern produced by from_ucj_op() and from_t_amplitudes().

  • with_final_givens_ansatz_op (bool) – Whether to include a final Givens rotation ansatz operator. The final operator uses a full brickwork pattern of Givens rotations.

Return type:

UCJAnglesOpSpinBalanced

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 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.

Constructs a UCJOpSpinBalanced using UCJOpSpinBalanced.from_t_amplitudes() and converts it using from_ucj_op().

Parameters:

  • t2 (ndarray) – The t2 amplitudes. They must satisfy t2[i, j, a, b] == t2[j, i, b, a].

  • t1 (ndarray | None) – The t1 amplitudes.

  • n_reps (int | None) – The number of ansatz repetitions. 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] | None) – Optional restrictions on allowed orbital interactions for the number-number interactions. If specified, interaction_pairs should be a pair of lists, for alpha-alpha and alpha-beta interactions, in that order. Either 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. 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:

UCJAnglesOpSpinBalanced

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 contained lower triangular pairs.

  • ValueError – The t2 amplitudes did not have the required symmetry.

static from_ucj_op(ucj_op, *, interaction_pairs=None)[source]

Initialize the angles-based UCJ operator from a matrix-based UCJ operator.

Note

If interaction_pairs is specified, the returned operator will incorporate only the diagonal Coulomb matrix entries corresponding to the specified interactions, so it will not be equivalent to the original operator unless the other entries are zero.

Parameters:

  • ucj_op (UCJOpSpinBalanced) – The UCJ operator.

  • interaction_pairs (tuple[list[tuple[int, int]] | None, list[tuple[int, int]] | None] | None) – Optional restrictions on allowed orbital interactions for the number-number interactions. If specified, interaction_pairs should be a pair of lists, for alpha-alpha and alpha-beta interactions, in that order. Either list can be substituted with None to indicate no restrictions on interactions, in which case all upper triangular pairs are used. Each list should contain pairs of integers representing the orbitals that are allowed to interact. The order of the pairs determines the order of the corresponding parameters. Each integer pair must be upper triangular, that is, of the form \((i, j)\) where \(i \leq j\).

Return type:

UCJAnglesOpSpinBalanced

Returns:

The angles-based UCJ operator.

Raises:

  • ValueError – Interaction pairs list contained duplicate interactions.

  • ValueError – Interaction pairs list contained out-of-range orbital indices.

  • ValueError – Interaction pairs list contained lower triangular pairs.

static n_params(norb, n_reps, *, num_num_interaction_pairs=None, givens_interaction_pairs=None, with_final_givens_ansatz_op=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.

  • num_num_interaction_pairs (tuple[list[tuple[int, int]] | None, list[tuple[int, int]] | None] | None) – Optional restrictions on allowed orbital interactions for the number-number interactions. If specified, num_num_interaction_pairs should be a pair of lists, for alpha-alpha and alpha-beta interactions, in that order. Either list can be substituted with None to indicate no restrictions on interactions, in which case all upper triangular pairs are used. Each integer pair must be upper triangular, that is, of the form \((i, j)\) where \(i \leq j\).

  • givens_interaction_pairs (list[tuple[int, int]] | None) – The orbital pairs to apply the Givens rotations to in each ansatz repetition. If not specified, a full brickwork pattern of nearest-neighbor pairs with norb layers is used, which is the pattern produced by from_ucj_op() and from_t_amplitudes().

  • with_final_givens_ansatz_op (bool) – Whether to include a final Givens rotation ansatz operator. The final operator uses a full brickwork pattern of Givens rotations, so it contributes norb**2 parameters.

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 contained lower triangular pairs.

to_parameters()[source]

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

See from_parameters() for the ordering of the parameters.

Return type:

ndarray

Returns:

The real-valued parameter vector.