SpinOp#
- class SpinOp(data, spin=Fraction(1, 2), num_spins=None, *, copy=True, validate=True)[source]#
Bases:
SparseLabelOp
XYZ Spin operator.
A
SpinOp
represents a weighted sum of spin operator terms with a certain spin value associated to them. This value can be an integer for bosonic particles or a half-integer (fraction) for fermions.These operator terms are encoded as sparse labels, strings consisting of a space-separated list of expressions. Each expression must look like
[XYZ]_<index>
or[XYZ]_<index>^<power>
, where the<index>
is a non-negative integer representing the index of the spin mode where theX
,Y
orZ
component of the spin operator is to be applied.The value of
index
is bound by the number of spins(num_spins
) of the operator (Note: since Python indices are 0-based, the maximum value an index can take is given bynum_spins-1
). The<power>
is a positive integer indicating the number of times the given operator is applied to the mode at<index>
. You can omit<power>
, implying a single application of the operator (power = 1
).Initialization
A
SpinOp
is initialized with a dictionary, mapping terms to their respective coefficients. For example:from qiskit_nature.second_q.operators import SpinOp x = SpinOp({"X_0": 1}, spin=3/2) y = SpinOp({"Y_0": 1}, spin=3/2) z = SpinOp({"Z_0": 1}, spin=3/2)
are \(S^x, S^y, S^z\) for spin 3/2 system. The two qutrit Heisenberg model with transverse magnetic field is
SpinOp({ "X_0 X_1": -1, "Y_0 Y_1": -1, "Z_0 Z_1": -1, "Z_0": -0.3, "Z_1": -0.3, }, spin=1 )
This means \(- S^x_0 S^x_1 - S^y_0 S^y_1 - S^z_0 S^z_1 - 0.3 S^z_0 - 0.3 S^z_1\).
An example using labels with powers would be:
from qiskit_nature.second_q.operators import SpinOp op = SpinOp({"X_0^2 Y_1^3 Z_0": 1})
By default, this way of initializing will create a full copy of the dictionary of coefficients. If you have very restricted memory resources available, or would like to avoid the additional copy, the dictionary will be stored by reference if you disable
copy
like so:some_big_data = { "X_0 Y_0": 1.0, "X_1 Y_1": -1.0, # ... } op = SpinOp( some_big_data, num_spins=2, copy=False, )
Note
It is the users’ responsibility, that in the above scenario,
some_big_data
is not changed after initialization of theSpinOp
, since the operator contents are not guaranteed to remain unaffected by such changes.Algebra
SpinOp
supports the following basic arithmetic operations: addition, subtraction, scalar multiplication, adjoint, composition and tensoring.As of now, operations that involve two different instances of
SpinOp
(i.e. addition, subtraction, composition, and tensoring) are only supported for identical spins (op_1.num_spins == op_2.num_spins
).For example,
Addition
SpinOp({"X_1": 1}, num_spins=2) + SpinOp({"X_0": 1}, num_spins=2)
Sum
sum(SpinOp({label: 1}, num_spins=3) for label in ["X_0", "Z_1", "X_2 Z_2"])
Scalar multiplication
0.5 * SpinOp({"X_1": 1}, num_spins=2)
Operator multiplication
op1 = SpinOp({"X_0 Z_1": 1}, num_spins=2) op2 = SpinOp({"Z_0 X_0 X_1": 1}, num_spins=2) print(op1 @ op2)
Tensor multiplication
op = SpinOp({"X_0 Z_1": 1}, num_spins=2) print(op ^ op)
Adjoint
SpinOp({"X_0 Z_1": 1j}, num_spins=2).adjoint()
Iteration
Instances of
SpinOp
are iterable. Iterating a SpinOp yields (term, coefficient) pairs describing the terms contained in the operator. Labels containing powers/exponents will be expanded into multiple (term, coefficient) pairs.The following attributes can be set via the initializer but can also be read and updated once the
SpinOp
object has been constructed.- num_spins#
the number of spins on which this operator acts. This is considered a lower bound, which means that mathematical operations acting on two or more operators will result in a new operator with the maximum number of spins of any of the involved operators.
- Type:
int | None
- spin#
positive half-integer (integer or half-odd-integer) that represents spin.
- Type:
float | Fraction
- Parameters:
data (Mapping[str, _TCoeff]) – label string, list of labels and coefficients. See the label section in the documentation of
SpinOp
for more details.spin (float | Fraction) – positive half-integer (integer or half-odd-integer) that represents spin.
num_spins (int | None) – the number spins on which this operator acts.
copy (bool) – when set to False the
data
will not be copied and the dictionary will be stored by reference rather than by value (which is the default;copy=True
). Note, that this requires you to not change the contents of the dictionary after constructing the operator. This also impliesvalidate=False
. Use with care!validate (bool) – when set to False the
data
keys will not be validated. Note, that the SparseLabelOp base class, makes no assumption about the data keys, so will not perform any validation by itself. Only concrete subclasses are encouraged to implement a key validation method. Disable this setting with care!
- Raises:
QiskitNatureError – when an invalid key is encountered during validation.
QiskitNatureError – when spin is not a positive half-integer.
Attributes
- atol = 1e-08#
- register_length#
- rtol = 1e-05#
Methods
- adjoint()#
Return the adjoint of the Operator.
- Return type:
Self
- argsort(*, weight=False)#
Returns the keys which sort this operator.
- Parameters:
weight (bool) – when True, the returned keys will sort this operator according to the coefficient weights of the stored terms; when False, the keys will sort the operator by its keys (i.e. lexicographically).
- Returns:
The sequence of keys which sort this operator.
- Return type:
- assign_parameters(parameters)#
Assign parameters to new parameters or values.
- Parameters:
parameters (Mapping[ParameterExpression, _TCoeff]) – The mapping from parameters to new parameters or values.
- Returns:
A new operator with the parameters assigned.
- Return type:
- chop(atol=None)#
Chops the real and imaginary parts of the operator coefficients.
This function separately chops the real and imaginary parts of all coefficients to the provided tolerance. Parameters are chopped only if they are exactly zero.
- compose(other, qargs=None, front=False)[source]#
Returns the operator composition with another operator.
- Parameters:
- Returns:
The operator resulting from the composition.
- Return type:
Note
Composition (
&
) by default is defined as left matrix multiplication for matrix operators, while@
(equivalent todot()
) is defined as right matrix multiplication. This means thatA & B == A.compose(B)
is equivalent toB @ A == B.dot(A)
whenA
andB
are of the same type.Setting the
front=True
keyword argument changes this to right matrix multiplication which is equivalent to thedot()
methodA.dot(B) == A.compose(B, front=True)
.
- conjugate()[source]#
Returns the conjugate of the
SpinOp
.- Returns:
The complex conjugate of this
SpinOp
.- Return type:
- dot(other, qargs=None)#
Return the right multiplied operator self * other.
- Parameters:
other (Operator) – an operator object.
qargs (list or None) – Optional, a list of subsystem positions to apply other on. If None apply on all subsystems (default: None).
- Returns:
The right matrix multiplied Operator.
- Return type:
Operator
Note
The dot product can be obtained using the
@
binary operator. Hencea.dot(b)
is equivalent toa @ b
.
- equiv(other, *, atol=None, rtol=None)#
Check equivalence of two
SparseLabelOp
instances up to an accepted tolerance.- Parameters:
other (SparseLabelOp) – the second
SparseLabelOp
to compare with this instance.atol (float | None) – Absolute numerical tolerance. The default behavior is to use
self.atol
.rtol (float | None) – Relative numerical tolerance. The default behavior is to use
self.rtol
.
- Returns:
True if operators are equivalent, False if not.
- Raises:
ValueError – Raised if either operator contains parameters
- Return type:
- classmethod from_polynomial_tensor(tensor)[source]#
Constructs the operator from a
PolynomialTensor
.- Parameters:
tensor (PolynomialTensor) – the
PolynomialTensor
to be expanded.- Returns:
The constructed operator.
- Return type:
- classmethod from_terms(terms)[source]#
Constructs a new
SparseLabelOp
from a sequence returned byterms()
.
- get(k[, d]) D[k] if k in D, else d. d defaults to None. #
- index_order()[source]#
Convert to the equivalent operator with the terms of each label ordered by index.
Returns a new operator (the original operator is not modified).
- Returns:
The index ordered operator.
- Return type:
- induced_norm(order=1)#
Returns the p-norm induced by the operator coefficients.
If the operator is represented as a sum of terms
\[\sum_i w_i H_i\]then the induced \(p\)-norm is
\[\left(\sum_i |w_i|^p \right)^{1/p}\]This is the standard \(p\)-norm of the operator coefficients considered as a vector (see https://en.wikipedia.org/wiki/Norm_(mathematics)#p-norm). Note that this method does not normal-order or simplify the operator before computing the norm; performing either of those operations can affect the result.
- Parameters:
order (int) – Order \(p\) of the norm. The default value is 1.
- Returns:
The induced norm.
- Return type:
- Raises:
ValueError – Operator contains parameters.
- Return type:
- is_zero(tol=None)#
Returns true if operator length is zero or all coefficients have value zero.
- items() a set-like object providing a view on D's items #
- keys() a set-like object providing a view on D's keys #
- classmethod one(spin=Fraction(1, 2))[source]#
Constructs the “one” spin operator for a given spin.
- Returns:
The “one” spin operator for
spin
.- Return type:
- parameters()#
Returns a list of the parameters in the operator.
- Returns:
A list of the parameters in the operator.
- Return type:
list[ParameterExpression]
- permute_indices(permutation)#
Permutes the indices of the operator.
This method applies the provided index permutation to all labels of this operator. The provided permutation must be a sequence of integers whose length is equal to the
register_length
of the operator. The integer at any given index of the sequence indicates the new index which that location will be permuted to. For example:op = SparseLabelOp({"+_0 -_1 +_2 -_3": 1.0}) permuted_op = op.permute_indices([3, 1, 0, 2]) assert permuted_op == SparseLabelOp({"+_3 -_1 +_0 -_2": 1.0})
Warning
This permutation utility is very powerful. Be mindful of the implications such a permutation might have on other components of the stack. To name an example, the builtin two-qubit reduction of the
ParityMapper
might not yield the expected results when used on permuted operator.- Parameters:
permutation (Sequence[int]) – a sequence of integers indicating the permutation to be applied. See above for an example.
- Returns:
A new operator instance with the permuted indices.
- Raises:
ValueError – if the length of the
permutation
argument does not equalregister_length
.- Return type:
- power(n)#
Return the compose of a operator with itself n times.
- Parameters:
n (int) – the number of times to compose with self (n>0).
- Returns:
the n-times composed operator.
- Return type:
Clifford
- Raises:
QiskitError – if the input and output dimensions of the operator are not equal, or the power is not a positive integer.
- round(decimals=0)#
Rounds the operator coefficients to a specified number of decimal places.
- Parameters:
decimals (int) – the number of decimal places to round coefficients to. By default this will round to the nearest integer value.
- Returns:
The rounded operator.
- Return type:
- simplify(atol=None)[source]#
Simplify the operator.
The simplifications implemented by this method should be: - to eliminate terms whose coefficients are close (w.r.t.
atol
) to 0. - to combine the coefficients which correspond to equivalent terms (see also the note below)Note
simplify()
should be used to simplify terms whose coefficients are close to zero, up to the specified numerical tolerance. It still differs slightly fromchop()
because that will chop real and imaginary part components individually.Note
The meaning of “equivalence” between multiple terms depends on the specific operator subclass. As a restriction this method is required to preserve the order of appearance of the different components within a term. This avoids some possibly unexpected edge cases. However, this also means that some equivalencies cannot be detected. Check for other methods of a specific subclass which may affect the order of terms and can allow for further simplifications to be implemented.
This method returns a new operator (the original operator is not modified).
- sort(*, weight=False)#
Returns a new sorted operator.
- Parameters:
weight (bool) – when True, the returned keys will sort this operator according to the coefficient weights of the stored terms; when False, the keys will sort the operator by its keys (i.e. lexicographically).
- Returns:
A new operator instance with its contents sorted.
- Return type:
- tensor(other)[source]#
Returns the tensor product with another SparseLabelOp.
- Parameters:
other (SpinOp) – the other SparseLabelOp.
- Returns:
The operator resulting from the tensor product, \(self \otimes other\).
- Return type:
Note
The tensor product can be obtained using the
^
binary operator. Hencea.tensor(b)
is equivalent toa ^ b
.
- terms()[source]#
Provides an iterator analogous to
items()
but with the labels already split into pairs of operation characters and indices. If the labels contain an exponent, they will be expanded into as many elements as indicated by the exponent. For example, label"X_0^3"
will yield([("X", 0), ("X", 0), ("X", 0)], coeff)
.- Yields:
A tuple with two items; the first one being a list of pairs of the form (char, int) where char is either
X
,Y
orZ
and the integer corresponds to the index on which the operator gets applied; the second item of the returned tuple is the coefficient of this term.- Return type:
- to_matrix()[source]#
Convert to dense matrix.
- Returns:
The matrix (numpy.ndarray with dtype=numpy.complex128)
- Return type:
- transpose()[source]#
Returns the transpose of the
SpinOp
.- Returns:
The transpose of the
SpinOp
.- Return type:
- values() an object providing a view on D's values #
- classmethod x(spin=Fraction(1, 2))[source]#
Constructs the X spin operator for a given spin.
- Returns:
The X spin operator for
spin
.- Return type:
- classmethod y(spin=Fraction(1, 2))[source]#
Constructs the Y spin operator for a given spin.
- Returns:
The Y spin operator for
spin
.- Return type: