pygsti.modelmembers.term

Defines classes which represent terms in gate expansions

Module Contents

Classes

RankOneTerm

An operation, like a gate, that maps a density matrix to another density matrix but in a restricted way.

_HasMagnitude

A base class that adds a magnitude property to a term class.

_NoMagnitude

A base class that adds a magnitude property to a term class.

RankOnePrepTerm

A state preparation term.

RankOneEffectTerm

A POVM effect term.

RankOneOpTerm

An operation term.

RankOnePrepTermWithMagnitude

A state preparation term with magnitude tracking.

RankOneEffectTermWithMagnitude

A POVM effect term with magnitude tracking.

RankOneOpTermWithMagnitude

An operation term with magnitude tracking.

_HasNumericalCoefficient

A base class for terms that have numerical coefficients.

_HasPolynomialCoefficient

A base class for terms that have polynomial coefficients..

RankOnePolynomialPrepTerm

A state preparation term with polynomial coefficient.

RankOnePolynomialEffectTerm

A POVM effect term with polynomial coefficient.

RankOnePolynomialOpTerm

An operation term with polynomial coefficient.

RankOnePolynomialPrepTermWithMagnitude

A state preparation term with polynomial coefficient and magnitude tracking.

RankOnePolynomialEffectTermWithMagnitude

A POVM effect term with polynomial coefficient and magnitude tracking.

RankOnePolynomialOpTermWithMagnitude

An operation term with polynomial coefficient and magnitude tracking.

RankOneDirectPrepTerm

A state preparation term with numerical coefficient (and no magnitude tracking).

RankOneDirectEffectTerm

A POVM effect term with numerical coefficient (and no magnitude tracking).

RankOneDirectOpTerm

An operation term with numerical coefficient (and no magnitude tracking).

Functions

compose_terms_with_mag(terms, magnitude)

Compose multiple terms and set the resulting term's magnitude.

compose_terms(terms)

Compose a sequence of terms.

exponentiate_terms(terms, order, postterm, cache=None, order_base=None)

Exponentiate a list of terms.

exponentiate_terms_above_mag(terms, order, postterm, cache=None, min_term_mag=None)

Exponentiate a list of terms with magnitude above min_term_mag.

pygsti.modelmembers.term.compose_terms_with_mag(terms, magnitude)

Compose multiple terms and set the resulting term’s magnitude.

Usually, for performance reasons, the magnitude of a composed term is not set. This function explicitly does so.

Parameters
  • terms (sequence) – A sequence of :class:`RankOneTerm`s.

  • magnitude (float) – The magnitude of the compsed term.

Returns

RankOneTerm

pygsti.modelmembers.term.compose_terms(terms)

Compose a sequence of terms.

Composition is done with time ordered left-to-right. Thus composition order is NOT the same as usual matrix order. E.g. if there are three terms: terms[0] = T0: rho -> A*rho*A terms[1] = T1: rho -> B*rho*B terms[2] = T2: rho -> C*rho*C Then the resulting term T = T0*T1*T2 : rho -> CBA*rho*ABC, so that term[0] is applied first not last to a state.

Parameters

terms (list) – A list of :class:`RankOneTerm`s to compose.

Returns

RankOneTerm

pygsti.modelmembers.term.exponentiate_terms(terms, order, postterm, cache=None, order_base=None)

Exponentiate a list of terms.

This function collects those terms of the orders given in orders. Optionally post-multiplies the single term postterm (so this term actually acts before the exponential-derived terms).

Parameters
  • terms (list) – The list of terms to exponentiate. All these terms are considered “first order” terms.

  • order (int) – An integers specifying the order of the terms to collect.

  • postterm (RankOneTerm) – A term that is composed first (so “post” in the sense of matrix multiplication, not composition). May be the identity (no-op) term.

  • cache (dict, optional) – A dictionary used to cache results for speeding up repeated calls to this function. Usually an empty dictionary is supplied to the first call.

  • order_base (float, optional) – What constitutes 1 order of magnitude. If None, then polynomial coefficients are used.

Returns

list – A list of RankOneTerm objects giving the terms at order.

pygsti.modelmembers.term.exponentiate_terms_above_mag(terms, order, postterm, cache=None, min_term_mag=None)

Exponentiate a list of terms with magnitude above min_term_mag.

This function collects those terms of the orders given in orders. Optionally post-multiplies the single term postterm (so this term actually acts before the exponential-derived terms).

Parameters
  • terms (list) – The list of terms to exponentiate. All these terms are considered “first order” terms.

  • order (int) – Integer specifying the order to compute.

  • postterm (RankOneTerm) – A term that is composed first (so “post” in the sense of matrix multiplication, not composition).

  • cache (dict, optional) – A cache to speedup repeated calls. Currently unused because min_term_mag is likely to be different on every call.

  • min_term_mag (float, optional) – The minimum term magnitude.

Returns

list

class pygsti.modelmembers.term.RankOneTerm(rep, evotype)

Bases: object

An operation, like a gate, that maps a density matrix to another density matrix but in a restricted way.

While a RankOneTerm doesn’t have to map pure states to pure states, its action can be written:

rho -> A*rho*B

Where A and B are unitary state operations. This means that if rho can be written rho = |psi1><psi2| then the action of a RankOneTerm preserves the separable nature or rho (which need not always be a valid density matrix since it can be just a portion of one).

A RankOneTerm anticipates its application to “separable” (as defined above) states, and can even be used to represent such a separable state or an analagous POVM effect. This occurs when the first element of pre_ops and post_ops is a preparation or POVM effect vector instead of a gate operation.

Note that operations are stored in composition (time) order rather than matrix order, and that adjoint operations are stored in post_ops so that they can be applied directly to the adjoint of the “bra” part of the state (which is a “ket” - a usual state).

Finally, a coefficient (usually a number or a Polynomial) is held, representing the prefactor for this term as a part of a larger density matrix evolution.

Parameters

rep (SVTermRep or SBTermRep) – The term representation object the acts as the core of this term.

torep(self)

Access to the underlying representation object.

copy(self)

Copies this term.

Returns

RankOneTerm

__mul__(self, x)

Multiply by scalar

__rmul__(self, x)
class pygsti.modelmembers.term._HasMagnitude

Bases: object

A base class that adds a magnitude property to a term class.

Magnitudes are used in pruned-path or direct term-based (path integral) forward simulation.

magnitude

This term’s magnitude.

Type

float

logmagnitude

The logarithm of this term’s magnitude (held separately for performance).

Type

float

property magnitude(self)

This term’s magnitude.

property logmagnitude(self)

The logarithm of this term’s magnitude (held separately for performance).

compose(self, all_terms, magnitude)

Compose all_terms and set the composed term’s magnitude to magnitude.

Parameters
  • all_terms (list) – List of the terms to compose.

  • magnitude (float) – The magnitude of the composed term.

Returns

RankOneTerm

class pygsti.modelmembers.term._NoMagnitude

Bases: object

A base class that adds a magnitude property to a term class.

compose(self, all_terms)

Compose all_terms and set the composed term’s magnitude to magnitude.

Parameters

all_terms (list) – List of the terms to compose.

Returns

RankOneTerm

class pygsti.modelmembers.term.RankOnePrepTerm(rep, evotype)

Bases: RankOneTerm, _NoMagnitude

A state preparation term.

classmethod create_from(cls, coeff, pre_state, post_state, evotype, state_space)

Creates a :class:`RankOnePrepTerm`s using natural arguments.

Parameters
  • coeff (Polynomial or complex) – The term’s coefficient.

  • pre_state (State or StateRep or numpy.ndarray) – The ‘ket’ (left-side) state of the operator.

  • post_state (State or StateRep or numpy.ndarray) – The ‘bra’ (right-side) state of the operator

  • evotype (Evotype or str) – The evolution type

  • state_space (StateSpace or str) – The state space of this term.

Returns

RankOnePrepTerm

embed(self, state_space, target_labels)

Embeds this term’s action as a part of a larger state space.

Parameters
  • state_space (StateSpace) – The full state space this term’s action will be embedded into.

  • target_labels (tuple) – A tuple of the target labels.

Returns

RankOnePrepTerm

class pygsti.modelmembers.term.RankOneEffectTerm(rep, evotype)

Bases: RankOneTerm, _NoMagnitude

A POVM effect term.

classmethod create_from(cls, coeff, pre_effect, post_effect, evotype, state_space)

Creates a :class:`RankOneEffectTerm`s using natural arguments.

Parameters
  • coeff (Polynomial or complex) – The term’s coefficient.

  • pre_effect (POVMEffect or EffectRep or numpy.ndarray) – The ‘bra’ (left-side) effect of the operator.

  • post_effect (POVMEffect or EffectRep or numpy.ndarray) – The ‘ket’ (right-side) effect of the operator

  • evotype (Evotype or str) – The evolution type

  • state_space (StateSpace or str) – The state space of this term.

Returns

RankOneEffectTerm

embed(self, state_space, target_labels)

Embeds this term’s action as a part of a larger state space.

Parameters
  • state_space (StateSpace) – The full state space this term’s action will be embedded into.

  • target_labels (tuple) – A tuple of the target labels.

Returns

RankOneEffectTerm

class pygsti.modelmembers.term.RankOneOpTerm(rep, evotype)

Bases: RankOneTerm, _NoMagnitude

An operation term.

classmethod create_from(cls, coeff, pre_op, post_op, evotype, state_space)

Creates a :class:`RankOneOpTerm`s using natural arguments.

Parameters
  • coeff (Polynomial or complex) – The term’s coefficient.

  • pre_op (LinearOperator or OpRep or numpy.ndarray) – The left-side operator, i.e. A in rho => A rho B^dag.

  • post_op (LinearOperator or OpRep or numpy.ndarray) – The right-side operator, i.e. B in rho => A rho B^dag.

  • evotype (Evotype or str) – The evolution type

  • state_space (StateSpace or str) – The state space of this term.

Returns

RankOneOpTerm

embed(self, state_space, target_labels)

Embeds this term’s action as a part of a larger state space.

Parameters
  • state_space (StateSpace) – The full state space this term’s action will be embedded into.

  • target_labels (tuple) – A tuple of the target labels.

Returns

RankOneOpTerm

class pygsti.modelmembers.term.RankOnePrepTermWithMagnitude(rep, evotype)

Bases: RankOneTerm, _HasMagnitude

A state preparation term with magnitude tracking.

embed(self, state_space, target_labels)

Embeds this term’s action as a part of a larger state space.

Parameters
  • state_space (StateSpace) – The full state space this term’s action will be embedded into.

  • target_labels (tuple) – A tuple of the target labels.

Returns

RankOnePrepTermWithMagnitude

class pygsti.modelmembers.term.RankOneEffectTermWithMagnitude(rep, evotype)

Bases: RankOneTerm, _HasMagnitude

A POVM effect term with magnitude tracking.

embed(self, state_space, target_labels)

Embeds this term’s action as a part of a larger state space.

Parameters
  • state_space (StateSpace) – The full state space this term’s action will be embedded into.

  • target_labels (tuple) – A tuple of the target labels.

Returns

RankOneEffectTermWithMagnitude

class pygsti.modelmembers.term.RankOneOpTermWithMagnitude(rep, evotype)

Bases: RankOneTerm, _HasMagnitude

An operation term with magnitude tracking.

embed(self, state_space, target_labels)

Embeds this term’s action as a part of a larger state space.

Parameters
  • state_space (StateSpace) – The full state space this term’s action will be embedded into.

  • target_labels (tuple) – A tuple of the target labels.

Returns

RankOneOpTermWithMagnitude

class pygsti.modelmembers.term._HasNumericalCoefficient

Bases: object

A base class for terms that have numerical coefficients.

coeff

The term’s coefficient.

Type

complex or float

classmethod _coeff_rep(cls, coeff)
property coeff(self)

The term’s coefficient (float or complex).

class pygsti.modelmembers.term._HasPolynomialCoefficient

Bases: object

A base class for terms that have polynomial coefficients..

coeff

The term’s coefficient.

Type

Polynomial

classmethod _coeff_rep(cls, coeff)
property coeff(self)

The term’s coefficient (a Polynomial).

map_indices_inplace(self, mapfn)

Performs a bulk find & replace on the coefficient polynomial’s variable indices.

This function should only be called when this term’s coefficient is a Polynomial.

Parameters

mapfn (function) – A function that takes as input an “old” variable-index-tuple (a key of this Polynomial) and returns the updated “new” variable-index-tuple.

Returns

None

mapvec_indices_inplace(self, mapvec)

Performs a bulk find & replace on this polynomial’s variable indices.

This function is similar to :method:`map_indices` but uses a vector to describe individual index updates instead of a function for increased performance.

This function should only be called when this term’s coefficient is a Polynomial.

Parameters

mapvec (numpy.ndarray) – An array whose i-th element gives the updated “new” index for the i-th variable. Note that this vector maps individual variable indices old->new, whereas mapfn in :method:`map_indices` maps between tuples of indices.

Returns

None

class pygsti.modelmembers.term.RankOnePolynomialPrepTerm(rep, evotype)

Bases: RankOnePrepTerm, _HasPolynomialCoefficient

A state preparation term with polynomial coefficient.

copy_with_magnitude(self, mag)

Copy and set the magnitude of the copy to mag

Parameters

mag (float) – Magnitude to set.

Returns

RankOnePolynomialPrepTermWithMagnitude

class pygsti.modelmembers.term.RankOnePolynomialEffectTerm(rep, evotype)

Bases: RankOneEffectTerm, _HasPolynomialCoefficient

A POVM effect term with polynomial coefficient.

copy_with_magnitude(self, mag)

Copy and set the magnitude of the copy to mag

Parameters

mag (float) – Magnitude to set.

Returns

RankOnePolynomialEffectTermWithMagnitude

class pygsti.modelmembers.term.RankOnePolynomialOpTerm(rep, evotype)

Bases: RankOneOpTerm, _HasPolynomialCoefficient

An operation term with polynomial coefficient.

copy_with_magnitude(self, mag)

Copy and set the magnitude of the copy to mag

Parameters

mag (float) – Magnitude to set.

Returns

RankOnePolynomialOpTermWithMagnitude

class pygsti.modelmembers.term.RankOnePolynomialPrepTermWithMagnitude(rep, evotype)

Bases: RankOnePrepTermWithMagnitude, _HasPolynomialCoefficient

A state preparation term with polynomial coefficient and magnitude tracking.

class pygsti.modelmembers.term.RankOnePolynomialEffectTermWithMagnitude(rep, evotype)

Bases: RankOneEffectTermWithMagnitude, _HasPolynomialCoefficient

A POVM effect term with polynomial coefficient and magnitude tracking.

class pygsti.modelmembers.term.RankOnePolynomialOpTermWithMagnitude(rep, evotype)

Bases: RankOneOpTermWithMagnitude, _HasPolynomialCoefficient

An operation term with polynomial coefficient and magnitude tracking.

class pygsti.modelmembers.term.RankOneDirectPrepTerm(rep, evotype)

Bases: RankOnePrepTerm, _HasNumericalCoefficient

A state preparation term with numerical coefficient (and no magnitude tracking).

class pygsti.modelmembers.term.RankOneDirectEffectTerm(rep, evotype)

Bases: RankOneEffectTerm, _HasNumericalCoefficient

A POVM effect term with numerical coefficient (and no magnitude tracking).

class pygsti.modelmembers.term.RankOneDirectOpTerm(rep, evotype)

Bases: RankOneOpTerm, _HasNumericalCoefficient

An operation term with numerical coefficient (and no magnitude tracking).