ElectronicIntegrals#
- class ElectronicIntegrals(alpha=None, beta=None, beta_alpha=None, *, validate=True)[source]#
Bases:
LinearMixin
A container class for electronic operator coefficients (a.k.a. electronic integrals).
This class contains multiple
qiskit_nature.second_q.operators.PolynomialTensor
instances, dealing with the specific case of storing electronic integrals, where the up- and down-spin electronic interactions need to be handled separately. These two spins are also commonly referred to by \(\alpha\) and \(\beta\), respectively.Specifically, this class stores three
PolynomialTensor
instances:alpha
: which stores the up-spin integralsbeta
: which stores the down-spin integralsbeta_alpha
: which stores beta-alpha-spin two-body integrals
These tensors are subject to some expectations, namely:
for
alpha
andbeta
only the following keys are allowed:""
,"+-"
,"++--"
for
beta_alpha
the only allowed key is"++--"
the reported
register_length
attributes of all non-empty tensors must match
There are two ways of constructing the
ElectronicIntegrals
:# assuming you already have your one- and two-body integrals from somewhere h1_a, h2_aa, h1_b, h2_bb, h2_ba = ... from qiskit_nature.second_q.operators import ElectronicIntegrals, PolynomialTensor alpha = PolynomialTensor({"+-": h1_a, "++--": h2_aa}) beta = PolynomialTensor({"+-": h1_b, "++--": h2_bb}) beta_alpha = PolynomialTensor({"++--": h2_ba}) integrals = ElectronicIntegrals(alpha, beta, beta_alpha) # alternatively, the following achieves the same effect: integrals = ElectronicIntegrals.from_raw_integrals(h1_a, h2_aa, h1_b, h2_bb, h2_ba)
This class then exposes common mathematical operations performed on these tensors allowing simple manipulation of the underlying data structures.
# addition integrals + integrals # scalar multiplication 2.0 * integrals
This class will substitute empty
beta
andbeta_alpha
tensors with thealpha
tensor when necessary. For example, this means the following will happen:integrals_pure = ElectronicIntegrals(alpha) integrals_mixed = ElectronicIntegrals(alpha, beta, beta_alpha) sum = integrals_pure + integrals_mixed print(sum.beta.is_empty()) # False print(sum.beta_alpha.is_empty()) # False print(sum.beta.equiv(alpha + beta)) # True print(sum.beta_alpha.equiv(alpha + beta_alpha)) # True
The same logic holds for other mathematical operations involving multiple
ElectronicIntegrals
.You can add a custom offset to be included in the operator generated from these coefficients like so:
from qiskit_nature.second_q.operators import PolynomialTensor integrals: ElectronicIntegrals offset = 2.5 integrals.alpha += PolynomialTensor({"": offset})
Any
None
-valued argument will internally be replaced by an emptyPolynomialTensor
(see alsoqiskit_nature.second_q.operators.PolynomialTensor.empty()
).- Parameters:
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!
- Raises:
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)[source]#
Exposes the
qiskit_nature.second_q.operators.PolynomialTensor.apply()
method.This behaves identical to the
apply
implementation of thePolynomialTensor
, applied to thealpha
,beta
, andbeta_alpha
attributes of the providedElectronicIntegrals
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 withalpha
attributes of those operands. Thebeta_alpha
attributes will only be handled if they are non-empty in all supplied operands.- Parameters:
function (Callable[..., np.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!
- Returns:
A new
ElectronicIntegrals
.- Return type:
- classmethod einsum(einsum_map, *operands, validate=True)[source]#
Exposes the
qiskit_nature.second_q.operators.PolynomialTensor.einsum()
method.This behaves identical to the
einsum
implementation of thePolynomialTensor
, applied to thealpha
,beta
, andbeta_alpha
attributes of the providedElectronicIntegrals
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 withalpha
attributes of those operands. Thebeta_alpha
attributes will only be handled if they are non-empty in all supplied operands.- Parameters:
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 providedElectronicIntegrals
operands. The last string in this tuple indicates the key under which to store the result in the returnedElectronicIntegrals
.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!
- Returns:
A new
ElectronicIntegrals
.- Return type:
- classmethod from_raw_integrals(h1_a, h2_aa=None, h1_b=None, h2_bb=None, h2_ba=None, *, validate=True, auto_index_order=True)[source]#
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 theh2_aa
matrix, based on which the two-body matrices will automatically be transformed to the physicist’ order, which is required by theqiskit_nature.second_q.operators.PolynomialTensor
.- Parameters:
h1_a (np.ndarray | SparseArray) – the alpha-spin one-body integrals.
h2_aa (np.ndarray | SparseArray | None) – the alpha-alpha-spin two-body integrals.
h1_b (np.ndarray | SparseArray | None) – the beta-spin one-body integrals.
h2_bb (np.ndarray | SparseArray | None) – the beta-beta-spin two-body integrals.
h2_ba (np.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.
- Raises:
QiskitNatureError – if auto_index_order=True, upon encountering an invalid
qiskit_nature.second_q.operators.tensor_ordering.IndexType
.- Returns:
The resulting
ElectronicIntegrals
.- Return type:
- second_q_coeffs()[source]#
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 thealpha
andbeta
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/orbeta_alpha
attributes are empty, thealpha
data will be used in their place.- Returns:
The
PolynomialTensor
representing the entire system.- Return type:
- split(function, indices_or_sections, *, validate=True)[source]#
Exposes the
qiskit_nature.second_q.operators.PolynomialTensor.split()
method.This behaves identical to the
split
implementation of thePolynomialTensor
, applied to thealpha
,beta
, andbeta_alpha
attributes of the providedElectronicIntegrals
operands.Note
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.
- Parameters:
function (Callable[..., np.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 arenumpy.hsplit()
andnumpy.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!
- Returns:
The new
ElectronicIntegrals
instances.- Return type:
- classmethod stack(function, operands, *, validate=True)[source]#
Exposes the
qiskit_nature.second_q.operators.PolynomialTensor.stack()
method.This behaves identical to the
stack
implementation of thePolynomialTensor
, applied to thealpha
,beta
, andbeta_alpha
attributes of the providedElectronicIntegrals
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 withalpha
attributes of those operands. Thebeta_alpha
attributes will only be handled if they are non-empty in all supplied operands.Note
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.
- Parameters:
function (Callable[..., np.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 arenumpy.hstack()
andnumpy.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!
- Returns:
A new
ElectronicIntegrals
.- Return type:
- trace_spin()[source]#
Returns a
PolynomialTensor
where the spin components have been traced out.This will sum the
alpha
andbeta
components, tracing out the spin.- Returns:
A
PolynomialTensor
with the spin traced out.- Return type: