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

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

Return a random state vector sampled from the uniform distribution.

Warning

This function is deprecated. Use ffsim.random.random_state_vector() instead.

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.

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_ucj_op_spin_balanced(norb, *, n_reps=1, with_final_orbital_rotation=False, 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.

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

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

  • 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_ucj_operator(norb, *, n_reps=1, with_final_orbital_rotation=False, seed=None)[source]

Sample a random 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.

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

Return type:

UCJOperator

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