ffsim.random

Random sampling utilities.

ffsim.random.random_antihermitian(dim, *, seed=None, dtype=<class 'complex'>)[source]

Return a random anti-Hermitian matrix.

Parameters:

  • dim (int) – The width and height of the matrix.

  • rank – The rank of the matrix. If None, the maximum rank is used.

  • seed – A seed to initialize the pseudorandom number generator. Should be a valid input to np.random.default_rng.

  • dtype – The data type to use for the result.

Return type:

ndarray

Returns:

The sampled anti-Hermitian matrix.

ffsim.random.random_density_matrix(dim, *, seed=None, dtype=<class 'complex'>)[source]

Returns a random density matrix distributed with Hilbert-Schmidt measure.

A density matrix is positive semi-definite and has trace equal to one.

Parameters:

  • dim (int) – The width and height of the matrix.

  • seed – A seed to initialize the pseudorandom number generator. Should be a valid input to np.random.default_rng.

Return type:

ndarray

Returns:

The sampled density matrix.

Raises:

ValueError – Dimension must be at least one.

References

ffsim.random.random_diagonal_coulomb_hamiltonian(norb, *, seed=None)[source]

Sample a random diagonal Coulomb Hamiltonian.

Parameters:

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

  • rank – The desired number of terms in the two-body part of the Hamiltonian. If not specified, it will be set to norb * (norb + 1) // 2.

  • seed – A seed to initialize the pseudorandom number generator. Should be a valid input to np.random.default_rng.

Return type:

DiagonalCoulombHamiltonian

Returns:

The sampled diagonal Coulomb Hamiltonian.

ffsim.random.random_double_factorized_hamiltonian(norb, *, rank=None, z_representation=False, real=False, seed=None)[source]

Sample a random double-factorized Hamiltonian.

Parameters:

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

  • rank (int | None) – The desired number of terms in the two-body part of the Hamiltonian. If not specified, it will be set to norb * (norb + 1) // 2.

  • z_representation (bool) – Whether to return a Hamiltonian in the “Z” representation.

  • real (bool) – Whether to sample a real-valued object rather than a complex-valued one.

  • seed – A seed to initialize the pseudorandom number generator. Should be a valid input to np.random.default_rng.

Return type:

DoubleFactorizedHamiltonian

Returns:

The sampled double-factorized Hamiltonian.

ffsim.random.random_fermion_hamiltonian(norb, n_terms=None, seed=None)[source]

Sample a random fermion Hamiltonian.

A fermion Hamiltonian is hermitian and conserves particle number and spin Z.

Parameters:

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

  • n_terms (int | None) – The number of terms to include in the operator. If not specified, norb is used.

  • seed – A seed to initialize the pseudorandom number generator. Should be a valid input to np.random.default_rng.

Return type:

FermionOperator

Returns:

The sampled fermion Hamiltonian.

ffsim.random.random_fermion_operator(norb, n_terms=None, max_term_length=None, seed=None)[source]

Sample a random fermion operator.

Parameters:

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

  • n_terms (int | None) – The number of terms to include in the operator. If not specified, norb is used.

  • max_term_length (int | None) – The maximum length of a term. If not specified, norb is used.

  • seed – A seed to initialize the pseudorandom number generator. Should be a valid input to np.random.default_rng.

Return type:

FermionOperator

Returns:

The sampled fermion operator.

ffsim.random.random_hermitian(dim, *, seed=None, dtype=<class 'complex'>)[source]

Return a random Hermitian matrix.

Parameters:

  • dim (int) – The width and height of the matrix.

  • rank – The rank of the matrix. If None, the maximum rank is used.

  • seed – A seed to initialize the pseudorandom number generator. Should be a valid input to np.random.default_rng.

  • dtype – The data type to use for the result.

Return type:

ndarray

Returns:

The sampled Hermitian matrix.

ffsim.random.random_molecular_hamiltonian(norb, seed=None, dtype=<class 'complex'>)[source]

Sample a random molecular Hamiltonian.

Parameters:

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

  • seed – A seed to initialize the pseudorandom number generator. Should be a valid input to np.random.default_rng.

  • dtype – The data type to use for the one- and two-body tensors. The constant term will always be of type float.

Return type:

MolecularHamiltonian

Returns:

The sampled molecular Hamiltonian.

ffsim.random.random_orthogonal(dim, seed=None, dtype=<class 'float'>)[source]

Return a random orthogonal matrix distributed with Haar measure.

Parameters:

  • dim (int) – The width and height of the matrix.

  • seed – The pseudorandom number generator or seed. Should be an instance of np.random.Generator or else a valid input to np.random.default_rng.

Return type:

ndarray

Returns:

The sampled orthogonal matrix.

References

ffsim.random.random_real_symmetric_matrix(dim, *, rank=None, seed=None, dtype=<class 'float'>)[source]

Return a random real symmetric matrix.

Parameters:

  • dim (int) – The width and height of the matrix.

  • rank (int | None) – The rank of the matrix. If None, the maximum rank is used.

  • seed – The pseudorandom number generator or seed. Should be an instance of np.random.Generator or else a valid input to np.random.default_rng.

Return type:

ndarray

Returns:

The sampled real symmetric matrix.

ffsim.random.random_special_orthogonal(dim, seed=None, dtype=<class 'float'>)[source]

Return a random special orthogonal matrix distributed with Haar measure.

Parameters:

  • dim (int) – The width and height of the matrix.

  • seed – The pseudorandom number generator or seed. Should be an instance of np.random.Generator or else a valid input to np.random.default_rng.

Return type:

ndarray

Returns:

The sampled special orthogonal matrix.

ffsim.random.random_state_vector(dim, *, seed=None, dtype=<class 'complex'>)[source]

Return a random state vector sampled from the uniform distribution.

Parameters:

  • dim (int) – The dimension of the state vector.

  • seed – A seed to initialize the pseudorandom number generator. Should be a valid input to np.random.default_rng.

  • dtype – The data type to use for the result.

Return type:

ndarray

Returns:

The sampled state vector.

Raises:

ValueError – Dimension must be at least one.

ffsim.random.random_t2_amplitudes(norb, nocc, *, seed=None, dtype=<class 'complex'>)[source]

Sample a random t2 amplitudes tensor.

Parameters:

  • norb (int) – The number of orbitals.

  • nocc (int) – The number of orbitals that are occupied by an electron.

  • seed – A seed to initialize the pseudorandom number generator. Should be a valid input to np.random.default_rng.

  • dtype – The data type to use for the result.

Return type:

ndarray

Returns:

The sampled t2 amplitudes tensor.

ffsim.random.random_two_body_tensor(dim, *, rank=None, seed=None, dtype=<class 'complex'>)[source]

Sample a random two-body tensor.

Parameters:

  • dim (int) – The dimension of the tensor. The shape of the returned tensor will be (dim, dim, dim, dim).

  • rank (int | None) – Rank of the sampled tensor. The default behavior is to use the maximum rank, which is norb * (norb + 1) // 2.

  • seed – A seed to initialize the pseudorandom number generator. Should be a valid input to np.random.default_rng.

  • dtype – The data type to use for the result.

Return type:

ndarray

Returns:

The sampled two-body tensor.

ffsim.random.random_uccsd_restricted(norb, nocc, *, with_final_orbital_rotation=False, real=False, seed=None)[source]

Sample a random UCCSD operator.

Parameters:

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

  • nocc (int) – The number of spatial orbitals that are occupied by electrons.

  • with_final_orbital_rotation (bool) – Whether to include a final orbital rotation in the operator.

  • real (bool) – Whether to sample a real-valued object rather than a complex-valued one.

  • seed – A seed to initialize the pseudorandom number generator. Should be a valid input to np.random.default_rng.

Return type:

UCCSDOpRestrictedReal

Returns:

The sampled UCCSD operator.

ffsim.random.random_ucj_op_spin_balanced(norb, *, n_reps=1, with_final_orbital_rotation=False, interaction_pairs=None, seed=None)[source]

Sample a random spin-balanced unitary cluster Jastrow (UCJ) operator.

Parameters:

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

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

  • with_final_orbital_rotation (bool) – Whether to include a final orbital rotation in the operator.

  • interaction_pairs (tuple[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 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. These pairs can also be interpreted as indices of diagonal Coulomb matrix entries that are allowed to be nonzero. Each integer pair must be upper triangular, that is, of the form \((i, j)\) where \(i \leq j\).

  • seed – A seed to initialize the pseudorandom number generator. Should be a valid input to np.random.default_rng.

Return type:

UCJOpSpinBalanced

Returns:

The sampled UCJ operator.

ffsim.random.random_ucj_op_spin_unbalanced(norb, *, n_reps=1, interaction_pairs=None, with_final_orbital_rotation=False, seed=None)[source]

Sample a random spin-unbalanced unitary cluster Jastrow (UCJ) operator.

Parameters:

  • norb (int) – The number of 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.

  • seed – A seed to initialize the pseudorandom number generator. Should be a valid input to np.random.default_rng.

Return type:

UCJOpSpinUnbalanced

Returns:

The sampled UCJ operator.

ffsim.random.random_ucj_op_spinless(norb, *, n_reps=1, interaction_pairs=None, with_final_orbital_rotation=False, seed=None)[source]

Sample a random spinless unitary cluster Jastrow (UCJ) operator.

Parameters:

  • norb (int) – The number of orbitals.

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

  • with_final_orbital_rotation (bool) – Whether to include a final orbital rotation in the operator.

  • interaction_pairs (list[tuple[int, int]] | None) – Optional restrictions on allowed orbital interactions for the diagonal Coulomb operators. If specified, interaction_pairs should be a list of integer pairs 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. Each integer pair must be upper triangular, that is, of the form \((i, j)\) where \(i \leq j\).

  • seed – A seed to initialize the pseudorandom number generator. Should be a valid input to np.random.default_rng.

Return type:

UCJOpSpinless

Returns:

The sampled UCJ operator.

ffsim.random.random_unitary(dim, *, seed=None, dtype=<class 'complex'>)[source]

Return a random unitary matrix distributed with Haar measure.

Parameters:

  • dim (int) – The width and height of the matrix.

  • seed – A seed to initialize the pseudorandom number generator. Should be a valid input to np.random.default_rng.

  • dtype – The data type to use for the result.

Return type:

ndarray

Returns:

The sampled unitary matrix.

References