ElectronicDensity

class ElectronicDensity(alpha=None, beta=None, beta_alpha=None, *, validate=True)

Bases: ElectronicIntegrals

The ElectronicDensity property.

This property adds operators to evaluate the 1- and 2-reduced density matrices (RDMs). It is implemented as a subclass of the ElectronicIntegrals which means that it supports mathematical operations and generally stores unrestricted spin data. However, you can trace out the spin using trace_spin().

Any None-valued argument will internally be replaced by an empty PolynomialTensor (see also qiskit_nature.second_q.operators.PolynomialTensor.empty()).

প্যারামিটার:

• alpha (PolynomialTensor | None) -- the up-spin electronic integrals

• beta (PolynomialTensor | None) -- the down-spin electronic integrals

• beta_alpha (PolynomialTensor | None) -- the beta-alpha-spin two-body electronic integrals. This may only contain the ++-- key.

• validate (bool) -- when set to False, no validation will be performed. Disable this setting with care!

রেইজেস:

• KeyError -- if the alpha tensor contains keys other than "", "+-", and "++--".

• KeyError -- if the beta tensor contains keys other than "", "+-", and "++--".

• KeyError -- if the beta_alpha tensor contains keys other than "++--".

• ValueError -- if the reported register_length attributes of the alpha-, beta-, and beta-alpha-spin tensors do not all match.

Attributes

alpha

The up-spin electronic integrals.

alpha_beta

The alpha-beta-spin two-body electronic integrals.

These get reconstructed from beta_alpha by transposing in the physicist' ordering convention.

beta

The down-spin electronic integrals.

beta_alpha

The beta-alpha-spin two-body electronic integrals.

one_body

Returns only the one-body integrals.

register_length

The size of the operator that can be generated from these ElectronicIntegrals.

two_body

Returns only the two-body integrals.

Methods

classmethod apply(function, *operands, multi=False, validate=True)

Exposes the qiskit_nature.second_q.operators.PolynomialTensor.apply() method.

This behaves identical to the apply implementation of the PolynomialTensor, applied to the alpha, beta, and beta_alpha attributes of the provided ElectronicIntegrals operands.

This method is special, because it handles the scenario in which any operand has a non-empty beta attribute, in which case the empty-beta attributes of any other operands will be filled with alpha attributes of those operands. The beta_alpha attributes will only be handled if they are non-empty in all supplied operands.

প্যারামিটার:

• function (Callable[[...], ndarray | SparseArray | complex]) -- the function to apply to the internal arrays of the provided operands. This function must take numpy (or sparse) arrays as its positional arguments. The number of arguments must match the number of provided operands.

• operands (ElectronicIntegrals) -- a sequence of ElectronicIntegrals instances on which to operate.

• multi (bool) -- when set to True this indicates that the provided numpy function will return multiple new numpy arrays which will each be wrapped into an ElectronicIntegrals instance separately.

• validate (bool) -- when set to False, no validation will be performed. Disable this setting with care!

রিটার্নস:

A new ElectronicIntegrals.

রিটার্ন টাইপ:

ElectronicIntegrals | list[qiskit_nature.second_q.operators.electronic_integrals.ElectronicIntegrals]

classmethod einsum(einsum_map, *operands, validate=True)

Exposes the qiskit_nature.second_q.operators.PolynomialTensor.einsum() method.

This behaves identical to the einsum implementation of the PolynomialTensor, applied to the alpha, beta, and beta_alpha attributes of the provided ElectronicIntegrals operands.

This method is special, because it handles the scenario in which any operand has a non-empty beta attribute, in which case the empty-beta attributes of any other operands will be filled with alpha attributes of those operands. The beta_alpha attributes will only be handled if they are non-empty in all supplied operands.

প্যারামিটার:

• einsum_map (dict[str, tuple[str, ...]]) -- a dictionary, mapping from numpy.einsum() subscripts to a tuple of strings. These strings correspond to the keys of matrices to be extracted from the provided ElectronicIntegrals operands. The last string in this tuple indicates the key under which to store the result in the returned ElectronicIntegrals.

• operands (ElectronicIntegrals) -- a sequence of ElectronicIntegrals instances on which to operate.

• validate (bool) -- when set to False, no validation will be performed. Disable this setting with care!

রিটার্নস:

A new ElectronicIntegrals.

রিটার্ন টাইপ:

ElectronicIntegrals

classmethod empty(num_spatial_orbitals, *, include_rdm2=True)

Initializes an empty (all-zero) ElectronicDensity.

প্যারামিটার:

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

• include_rdm2 (bool) -- whether to include the 2-body RDMs.

রিটার্নস:

The resulting ElectronicDensity.

রিটার্ন টাইপ:

ElectronicDensity

equiv(other)

Check equivalence of first ElectronicIntegrals with other

প্যারামিটার:

other (object) -- second ElectronicIntegrals object to be compared with the first.

রিটার্নস:

True when ElectronicIntegrals objects are equivalent, False when not.

রিটার্ন টাইপ:

bool

classmethod from_orbital_occupation(alpha_occupation, beta_occupation, *, include_rdm2=True)

Initializes an ElectronicDensity from the provided orbital occupations.

This method assumes an orthonormal basis, and will initialize the 1-RDMs simply as diagonal matrices of the provided orbital occupations. The 2-RDMs are computed based on these 1-RDMs.

প্যারামিটার:

• alpha_occupation (Sequence[float]) -- the alpha-spin orbital occupations.

• beta_occupation (Sequence[float]) -- the beta-spin orbital occupations.

• include_rdm2 (bool) -- whether to include the 2-body RDMs.

রিটার্নস:

The resulting ElectronicDensity.

রিটার্ন টাইপ:

ElectronicDensity

classmethod from_particle_number(num_spatial_orbitals, num_particles, *, include_rdm2=True)

Initializes an ElectronicDensity from the provided number of particles.

প্যারামিটার:

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

• num_particles (int | tuple[int, int]) -- the number of particles. If this is an integer it is interpreted as the total number of particles. If it is a tuple of two integers, these are treated as the number of alpha- and beta-spin particles, respectively.

• include_rdm2 (bool) -- whether to include the 2-body RDMs.

রিটার্নস:

The resulting ElectronicDensity.

রিটার্ন টাইপ:

ElectronicDensity

classmethod from_raw_integrals(h1_a, h2_aa=None, h1_b=None, h2_bb=None, h2_ba=None, *, validate=True, auto_index_order=True)

Loads the provided integral matrices into an ElectronicIntegrals instance.

When auto_index_order is enabled, qiskit_nature.second_q.operators.tensor_ordering.find_index_order() will be used to determine the index ordering of the h2_aa matrix, based on which the two-body matrices will automatically be transformed to the physicist' order, which is required by the qiskit_nature.second_q.operators.PolynomialTensor.

প্যারামিটার:

• h1_a (ndarray | SparseArray) -- the alpha-spin one-body integrals.

• h2_aa (ndarray | SparseArray | None) -- the alpha-alpha-spin two-body integrals.

• h1_b (ndarray | SparseArray | None) -- the beta-spin one-body integrals.

• h2_bb (ndarray | SparseArray | None) -- the beta-beta-spin two-body integrals.

• h2_ba (ndarray | SparseArray | None) -- the beta-alpha-spin two-body integrals.

• validate (bool) -- whether or not to validate the integral matrices. Disable this setting with care!

• auto_index_order (bool) -- whether or not to automatically convert the matrices to physicists' order.

রেইজেস:

QiskitNatureError -- if auto_index_order=True, upon encountering an invalid qiskit_nature.second_q.operators.tensor_ordering.IndexType.

রিটার্নস:

The resulting ElectronicIntegrals.

রিটার্ন টাইপ:

ElectronicIntegrals

classmethod identity(num_spatial_orbitals, *, include_rdm2=True)

Initializes an identity ElectronicDensity.

প্যারামিটার:

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

• include_rdm2 (bool) -- whether to include the 2-body RDMs.

রিটার্নস:

The resulting ElectronicDensity.

রিটার্ন টাইপ:

ElectronicDensity

interpret(result)

Interprets an qiskit_nature.second_q.problems.EigenstateResult.

In particular, this method gathers the evaluated auxiliary operator values and constructs the resulting ElectronicDensity and stores it in the result object.

প্যারামিটার:

result (EigenstateResult) -- the result to add meaning to.

second_q_coeffs()

Constructs the total PolynomialTensor contained the second-quantized coefficients.

This function constructs the spin-orbital basis tensor as a qiskit_nature.second_q.operators.PolynomialTensor, by arranging the alpha and beta attributes in a block-ordered fashion (up-spin integrals cover the first part, down-spin integrals the second part of the resulting register space).

If the beta and/or beta_alpha attributes are empty, the alpha data will be used in their place.

রিটার্নস:

The PolynomialTensor representing the entire system.

রিটার্ন টাইপ:

PolynomialTensor

second_q_ops()

Returns the density evaluation operators.

রিটার্নস:

A mapping of strings to FermionicOp objects.

রিটার্ন টাইপ:

Mapping[str, FermionicOp]

split(function, indices_or_sections, *, validate=True)

Exposes the qiskit_nature.second_q.operators.PolynomialTensor.split() method.

This behaves identical to the split implementation of the PolynomialTensor, applied to the alpha, beta, and beta_alpha attributes of the provided ElectronicIntegrals operands.

নোট

When splitting arrays this will likely lead to array shapes which would fail the shape validation check. This is considered an advanced use case which is why the user is left to disable this check themselves, to ensure they know what they are doing.

প্যারামিটার:

• function (Callable[[...], ndarray | SparseArray | Number]) -- the splitting function to use. This function must take a single numpy (or sparse) array as its first input followed by a sequence of indices to split on. You should use functools.partial if you need to provide keyword arguments (e.g. partial(np.split, axis=-1)). Common methods to use here are numpy.hsplit() and numpy.vsplit().

• indices_or_sections (int | Sequence[int]) -- a single index or sequence of indices to split on.

• validate (bool) -- when set to False, no validation will be performed. Disable this setting with care!

রিটার্নস:

The new ElectronicIntegrals instances.

রিটার্ন টাইপ:

list[qiskit_nature.second_q.operators.electronic_integrals.ElectronicIntegrals]

classmethod stack(function, operands, *, validate=True)

Exposes the qiskit_nature.second_q.operators.PolynomialTensor.stack() method.

This behaves identical to the stack implementation of the PolynomialTensor, applied to the alpha, beta, and beta_alpha attributes of the provided ElectronicIntegrals operands.

This method is special, because it handles the scenario in which any operand has a non-empty beta attribute, in which case the empty-beta attributes of any other operands will be filled with alpha attributes of those operands. The beta_alpha attributes will only be handled if they are non-empty in all supplied operands.

নোট

When stacking arrays this will likely lead to array shapes which would fail the shape validation check. This is considered an advanced use case which is why the user is left to disable this check themselves, to ensure they know what they are doing.

প্যারামিটার:

• function (Callable[[...], ndarray | SparseArray | Number]) -- the stacking function to apply to the internal arrays of the provided operands. This function must take a sequence of numpy (or sparse) arrays as its first argument. You should use functools.partial if you need to provide keyword arguments (e.g. partial(np.stack, axis=-1)). Common methods to use here are numpy.hstack() and numpy.vstack().

• operands (Sequence[ElectronicIntegrals]) -- a sequence of ElectronicIntegrals instances on which to operate.

• validate (bool) -- when set to False, no validation will be performed. Disable this setting with care!

রিটার্নস:

A new ElectronicIntegrals.

রিটার্ন টাইপ:

ElectronicIntegrals

trace_spin()

Returns a PolynomialTensor where the spin components have been traced out.

This will sum the alpha and beta components, tracing out the spin.

রিটার্নস:

A PolynomialTensor with the spin traced out.

রিটার্ন টাইপ:

PolynomialTensor