Excitation generator utilities (qiskit_nature.second_q.circuit.library.ansatzes.utils)#

Utility methods to build fermionic and vibrational excitations.

generate_fermionic_excitations(num_excitations, num_spatial_orbitals, num_particles, *, alpha_spin=True, beta_spin=True, max_spin_excitation=None, generalized=False, preserve_spin=True)[source]#

Generates all possible excitations with the given number of excitations for the specified number of particles distributed among the given number of spatial orbitals.

The method must be called for each type of excitation (singles, doubles, etc.) that is to be considered in the Ansatz. Excitations will be produced based on an initial Hartree-Fock occupation by default unless generalized is set to True, in which case the excitations are only determined based on the number of spatial orbitals and are independent from the number of particles.

This method assumes block-ordered spin-orbitals.

Parameters:

  • num_excitations (int) – number of excitations per operator (1 means single excitations, etc.).

  • num_spatial_orbitals (int) – number of spatial-orbitals.

  • num_particles (tuple[int, int]) – number of alpha and beta particles.

  • alpha_spin (bool) – boolean flag whether to include alpha-spin excitations.

  • beta_spin (bool) – boolean flag whether to include beta-spin excitations.

  • max_spin_excitation (int | None) – the largest number of excitations within a spin. E.g. you can set this to 1 and num_excitations to 2 in order to obtain only mixed-spin double excitations (alpha,beta) but no pure-spin double excitations (alpha,alpha or beta,beta).

  • generalized (bool) – boolean flag whether or not to use generalized excitations, which ignore the occupation of the spin orbitals. As such, the set of generalized excitations is only determined from the number of spin orbitals and independent from the number of particles.

  • preserve_spin (bool) – boolean flag whether or not to preserve the particle spins.

Returns:

The list of excitations encoded as tuples of tuples. Each tuple in the list is a pair. The first tuple contains the occupied spin orbital indices whereas the second one contains the indices of the unoccupied spin orbitals.

Return type:

list[tuple[tuple[int, …], tuple[int, …]]]

Examples

Generate excitations with basic inputs.

>>> from qiskit_nature.second_q.circuit.library.ansatzes.utils.fermionic_excitation_generator import generate_fermionic_excitations
>>> generate_fermionic_excitations(num_excitations=1, num_spatial_orbitals=3, num_particles=(1,1))
[((0,), (1,)), ((0,), (2,)), ((3,), (4,)), ((3,), (5,))]

Generate generalized excitations.

>>> generate_fermionic_excitations(1, 3, (1, 1), generalized=True)
[((0,), (1,)), ((0,), (2,)), ((1,), (2,)), ((3,), (4,)), ((3,), (5,)), ((4,), (5,))]
generate_vibration_excitations(num_excitations, num_modals)[source]#

Generates all possible excitations with the given number of excitations for the specified number of particles distributed among the given number of spin orbitals.

This method assumes block-ordered spin-orbitals.

Parameters:

  • num_excitations (int) – number of excitations per operator (1 means single excitations, etc.).

  • num_modals (list[int]) – the number of modals per mode.

Returns:

The list of excitations encoded as tuples of tuples. Each tuple in the list is a pair of tuples. The first tuple contains the occupied spin orbital indices whereas the second one contains the indices of the unoccupied spin orbitals.

Return type:

list[tuple[tuple[Any, …], …]]