UCC

class UCC(num_spatial_orbitals=None, num_particles=None, excitations=None, qubit_mapper=None, *, alpha_spin=True, beta_spin=True, max_spin_excitation=None, generalized=False, preserve_spin=True, include_imaginary=False, reps=1, initial_state=None)

Bases: EvolvedOperatorAnsatz

The Unitary Coupled-Cluster Ansatz. For more information, see [1].

This ansatz is an EvolvedOperatorAnsatz given by \(e^{T - T^{\dagger}}\) where \(T\) is the cluster operator. This cluster operator generally consists of excitation operators which are generated by generate_fermionic_excitations().

This method constructs the requested excitations based on a HartreeFock reference state by default. When setting up a VQE algorithm using this ansatz and initial state, it is likely you will also want to use a HFInitialPoint that has been configured using the corresponding ansatz parameters. This can be done as follows:

qubit_mapper = JordanWignerMapper()
ucc = UCC(4, (2, 2), 'sd', qubit_mapper)
hf_initial_point = HFInitialPoint()
hf_initial_point.ansatz = ucc
initial_point = hf_initial_point.to_numpy_array()
vqe = VQE(Estimator(), ucc, SLSQP(), initial_point=initial_point)

You can also use a custom excitation generator method by passing a callable to excitations.

A utility class UCCSD exists, which is equivalent to:

uccsd = UCC(excitations='sd', alpha_spin=True, beta_spin=True, max_spin_excitation=None)

If you want to use a tailored ansatz, you have multiple options to do so. Below, we provide some examples:

# pure single excitations (equivalent options):
uccs = UCC(excitations='s')
uccs = UCC(excitations=1)
uccs = UCC(excitations=[1])

# pure double excitations (equivalent options):
uccd = UCC(excitations='d')
uccd = UCC(excitations=2)
uccd = UCC(excitations=[2])

# combinations of excitations:
custom_ucc_sd = UCC(excitations='sd')  # see also the convenience sub-class UCCSD
custom_ucc_sd = UCC(excitations=[1, 2])  # see also the convenience sub-class UCCSD
custom_ucc_sdt = UCC(excitations='sdt')
custom_ucc_sdt = UCC(excitations=[1, 2, 3])
custom_ucc_st = UCC(excitations='st')
custom_ucc_st = UCC(excitations=[1, 3])

# you can even define a fully custom list of excitations:

def custom_excitation_list(num_spatial_orbitals: int,
                           num_particles: tuple[int, int]
                           ) -> list[tuple[tuple[Any, ...], ...]]:
    # generate your list of excitations...
    my_excitation_list = [...]
    # For more information about the required format of the return statement, please take a
    # look at the documentation of
    # `qiskit_nature.second_q.circuit.library.ansatzes.utils.fermionic_excitation_generator`
    return my_excitation_list

my_custom_ucc = UCC(excitations=custom_excitation_list)

Keep in mind, that in all of the examples above we have not set any of the following keyword arguments, which must be specified before the ansatz becomes usable:

• qubit_mapper

• num_particles

• num_spatial_orbitals

If you are using this ansatz with a Qiskit Nature algorithm, these arguments will be set for you, depending on the rest of the stack.

References

[1] arXiv:1805.04340

Parameters:

• num_spatial_orbitals (int | None) – The number of spatial orbitals.

• num_particles (tuple[int, int] | None) – The tuple of the number of alpha- and beta-spin particles.

• excitations (str | int | list[int] | Callable[[int, tuple[int, int]], list[tuple[tuple[int, ...], tuple[int, ...]]]] | None) –

  This can be any of the following types:

  str:

  Contains the types of excitations. Allowed characters are: 's' for singles, 'd' for doubles, 't' for triples, and 'q' for quadruples.

  int:

  A single, positive integer which denotes the number of excitations (1 == 's', 2 == 'd', etc.)

  list[int]:

  A list of positive integers generalizing the above to multiple numbers of excitations ([1, 2] == 'sd', etc.)

  Callable:

  A function which is used to generate the excitations. The callable must take the keyword arguments num_spatial_orbitals and num_particles (with identical types to those explained above) and must return a list[tuple[tuple[int, ...], tuple[int, ...]]]. For more information on how to write such a callable refer to the default method                     generate_fermionic_excitations().

• qubit_mapper (QubitMapper | None) – The QubitMapper which takes care of mapping to a qubit operator.

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

• include_imaginary (bool) – Boolean flag which when set to True expands the ansatz to include imaginary parts using twice the number of free parameters.

• reps (int) – The number of times to repeat the evolved operators.

• initial_state (QuantumCircuit | None) – A QuantumCircuit object to prepend to the circuit. Note that this setting does not influence the excitations. When relying on the default generation method (i.e. not providing a Callable to excitations), these will always be constructed with respect to a HartreeFock reference state. When setting up a VQE algorithm using this ansatz and initial state, it is likely you will also want to use a HFInitialPoint that has been configured using the corresponding ansatz parameters.

Attributes

excitation_list

The excitation list that UCC is using.

Raises:

QiskitNatureError – If private the excitation list is None.

excitations

The excitations.

num_particles

The number of particles.

num_spatial_orbitals

The number of spatial orbitals.

operators

The operators that are evolved in this circuit.

Returns:

The operators to be evolved contained in this ansatz or

None if the configuration is not complete

Return type:

list

qubit_mapper

The qubit operator mapper.

Methods

excitation_ops()

Parses the excitations and generates the list of operators.

Raises:

QiskitNatureError – if invalid excitations are specified.

Returns:

The list of generated excitation operators.

Return type:

list[SparseLabelOp]