pygsti.modelmembers

A sub-package containing the objects that are held within OpModel models.

Subpackages

Submodules

Package Contents

Classes

ModelMember

Base class for Model member objects that possess a definite state space, parameters count, and evolution type.

ModelChild

Base class for all objects contained in a Model that hold a parent reference to their parent Model.

Functions

from_memoized_dict(mm_dict, serial_memo)

Deserialize a ModelMember object and relink submembers from a memo.

class pygsti.modelmembers.ModelMember(state_space, evotype, gpindices=None, parent=None)

Bases: ModelChild, pygsti.baseobjs.nicelyserializable.NicelySerializable

Base class for Model member objects that possess a definite state space, parameters count, and evolution type.

A ModelMember can be vectorized into/onto a portion of their parent Model’s (or other ModelMember’s) parameter vector. They therefore contain a gpindices reference to the global Model indices “owned” by this member. Note that GateSetMembers may contain other GateSetMembers (may be nested).

Parameters
  • state_space (StateSpace) – The state space, which should match the parent model if/when one exists.

  • evotype (EvoType or str) – The evolution type, which should match the parent model if/when one exists.

  • gpindices (slice or numpy.ndarray, optional) – The indices of this member’s local parameters into the parent Model’s parameter vector.

  • parent (Model, optional) – The parent model.

dirty

Whether this member’s local parameters may have been updated without its parent’s knowledge. The parent model can check this flag and perform re-synchronization of it’s parameter vector when needed.

Type

bool

gpindices

The indices of this member’s local parameters into the parent Model’s parameter vector.

Type

slice or numpy.ndarray

parent

The parent model.

Type

Model, optional

property state_space(self)
property evotype(self)
property dirty(self)

Flag indicating whether this member’s local parameters may have been updated without its parent’s knowledge.

property gpindices(self)

The indices of this member’s local parameters into the parent Model’s parameter vector.

Returns

slice or numpy.ndarray

property parameter_labels(self)

An array of labels (usually strings) describing this model member’s parameters.

property parameter_bounds(self)

Upper and lower bounds on the values of each parameter, utilized by optimization routines

property parent(self)

The parent of this object.

Returns

Model

submembers(self)

Returns a sequence of any sub-ModelMember objects contained in this one.

Sub-members are processed by other ModelMember methods (e.g. unlink_parent and set_gpindices) as though the parent object is just a container for these sub-members and has no parameters of its own. Member objects that contain other members and possess their own independent parameters should implement the appropriate ModelMember functions (usually just allocate_gpindices, using the base implementation as a reference).

Returns

list or tuple

Sets the parent of this object without altering its gpindices.

This operation is appropriate to do when “re-linking” a parent with its children after the parent and child have been serialized. (the parent is not saved in serialization - see

ModelChild.__getstate__ – and so must be manually re-linked upon de-serialization).

In addition to setting the parent of this object, this method sets the parent of any objects this object contains (i.e. depends upon) - much like allocate_gpindices. To ensure a valid parent is not overwritten, the existing parent must be None prior to this call.

Parameters

parent (Model) – The model to (re-)set as the parent of this member.

Returns

None

Remove the parent-link of this member.

Called when at least one reference (via key) to this object is being disassociated with parent. If all references are to this object are now gone, set parent to None, invalidating any gpindices.

Parameters

force (bool, optional) – If True, then resets parent to None, effectively de-allocating the model member’s parameters from the parent model, even if the parent still contains references to it. If False, the parent is only set to None when its parent contains no reference to it.

Returns

None

set_gpindices(self, gpindices, parent, memo=None)

Set the parent and indices into the parent’s parameter vector that are used by this ModelMember object.

Parameters
  • gpindices (slice or integer ndarray) – The indices of this objects parameters in its parent’s array.

  • parent (Model or ModelMember) – The parent whose parameter array gpindices references.

  • memo (set, optional) – A set keeping track of the object ids that have had their indices set in a root set_gpindices call. Used to prevent duplicate calls and self-referencing loops. If memo contains an object’s id (id(self)) then this routine will exit immediately.

Returns

None

shift_gpindices(self, above, amount, parent_filter=None, memo=None)

Shifts this member’s gpindices by the given amount.

Usually called by the parent model when it shifts parameter indices around in its parameter vector.

Parameters
  • above (int) – The “insertion point” within the range of indices. All indices greater than or equal to this index are shifted.

  • amount (int) – The amount to shift indices greater than or equal to above by.

  • parent_filter (Model or None) – If a Model object, then only those members with indices allocated to this model will be shifted. It usually makes sense to specify this argument, supplying the parent model whose parameter vector is being shifted.

  • memo (set, optional) – A set keeping track of the object ids that have had their indices set in a root set_gpindices call. Used to prevent duplicate calls and self-referencing loops. If memo contains an object’s id (id(self)) then this routine will exit immediately.

Returns

None

_set_only_my_gpindices(self, gpindices, parent)
_collect_parents(self, set_to_fill=None, memo=None)

Traverse sub-member tree and record all distinct parent Models. Useful for finding the “anticipated parent” model when initializing a member with sub-members

gpindices_are_allocated(self, model, memo=None)

Whether or not this model member’s parameter indices are allocated within a potential parent model.

This is used to infer when the model member needs to have its parameter indices reallocated (by its parent model).

Parameters
  • model (Model) – Test for parameter allocation with respect to this model.

  • memo (dict, optional) – Used to prevent duplicate calls and self-referencing loops. If memo contains an object’s id (id(self)) then this routine will exit immediately with a cached value.

Returns

bool – True if this member’s .gpindices and those of its sub-members are not None and refer to parameter indices of model.

preallocate_gpindices(self, parent, memo=None)

Computes two key pieces of information for a model preparing to allocate this member.

These pieces of information are:

  1. the total number of new parameters that would need to be allocated to parent in order to have all this model member’s parameters allocated to parent.

  2. the largest parameter index from all the parameters already allocated to parent. This is useful for providing an ideal insertion point for the new parameters, once the model has made space for them.

Note that this function does not update this model member’s .gpindces or other attributes at all - it just serves as a pre-allocation probe so that the allocating model knows how much space in its parameter vector is needed/ requested by this perhaps-not-fully-allocated member.

Parameters
  • parent (Model) – The model that parameter allocation is being considered with respect to.

  • memo (set, optional) – Used to prevent duplicate calls and self-referencing loops. If memo contains an object’s id (id(self)) then this routine will exit immediately..

Returns

  • num_new_params (int) – the number of parameters that aren’t currently allocated to parent

  • max_index (int) – the maximum index of the parameters currently allocated to parent

allocate_gpindices(self, starting_index, parent, memo=None)

Sets gpindices array for this object or any objects it contains (i.e. depends upon).

Indices may be obtained from contained objects which have already been initialized (e.g. if a contained object is shared with other top-level objects), or given new indices starting with starting_index.

Parameters
  • starting_index (int) – The starting index for un-allocated parameters.

  • parent (Model or ModelMember) – The parent whose parameter array gpindices references.

  • memo (set, optional) – Used to prevent duplicate calls and self-referencing loops. If memo contains an object’s id (id(self)) then this routine will exit immediately.

Returns

num_new (int) – The number of new allocated parameters (so the parent should mark as allocated parameter indices starting_index to starting_index + new_new).

_obj_refcount(self, obj)

Number of references to obj contained within this object

init_gpindices(self)

Initializes this model member’s parameter indices by allocating them to an “anticipated” parent model.

Objects with submembers often rely on having valid .gpindices and .subm_rpindices attributes, but these aren’t set until the object is allocated to a parent model. This method initializes these attributes in the best way possible before receiving the actual parent model. Typically model members (containing sub-members) are build in two ways:

  1. The sub-members are all un-allocated, i.e. their .parent model is None

  2. The sub-members are all allocated to the same parent model.

This method computes an “anticipated parent” model as the common parent of all the submembers (if one exists) or None, and calls :method:`allocate_gpindices` using this parent model and a starting index of 0. This has the desired behavior in the two cases above. In case 1, parameter indices are set (allocated) but the parent is set to None, so that the to-be parent model will see this member as being unallocated. In case 2, the parent model, if it is the anticipated one, will see that this member’s indices are already allocated to it, and won’t need to re-allocate them.

gpindices_as_array(self)

Returns gpindices as a numpy.ndarray of integers.

The underlying .gpindices attribute itself can be None, a slice, or an integer array. If gpindices is None, an empty array is returned.

Returns

numpy.ndarray

property num_params(self)

Get the number of independent parameters which specify this object.

Returns

int

to_vector(self)

Get this object’s parameters as a 1D array of values.

Returns

numpy.ndarray

from_vector(self, v, close=False, dirty_value=True)

Initialize this object using a vector of parameters.

Parameters
  • v (numpy array) – The 1D vector of parameters. Length must == num_params()

  • close (bool, optional) – Whether v is close to the current parameter vector.

  • dirty_value (bool, optional) – The value to set this object’s “dirty flag” to before exiting this call. This is passed as an argument so it can be updated recursively. Leave this set to True unless you know what you’re doing.

Returns

None

copy(self, parent=None, memo=None)

Copy this object.

Parameters

parent (Model, optional) – The parent of the returned copy.

Returns

LinearOperator – A copy of this object.

_is_similar(self, other, rtol, atol)

Returns True if other model member (which it guaranteed to be the same type as self) has the same local structure, i.e., not considering parameter values or submembers

is_similar(self, other, rtol=1e-05, atol=1e-08)

Comparator returning whether two ModelMembers are the same type and parameterization.

ModelMembers with internal parameterization information (e.g. LindbladErrorgen) should overload this function to account for that.

Parameters
  • other (ModelMember) – ModelMember to compare to

  • rtol (float) – Relative tolerance for floating poing comparisons (passed to numpy.isclose)

  • atol (float) – Absolute tolerance for floating point comparisons (passed to numpy.isclose)

Returns

bool – True if structure (all but parameter values) matches

is_equivalent(self, other, rtol=1e-05, atol=1e-08)

Comparator returning whether two ModelMembers are equivalent.

This uses is_similar for type checking and NumPy allclose for parameter checking, so is unlikely to be needed to overload.

Note that this only checks for NUMERICAL equivalence, not whether the objects are the same.

Parameters
  • other (ModelMember) – ModelMember to compare to

  • rtol (float) – Relative tolerance for floating point comparisons (passed to numpy.isclose)

  • atol (float) – Absolute tolerance for floating point comparisons (passed to numpy.isclose)

Returns

bool – True if structure AND parameter vectors match

to_memoized_dict(self, mmg_memo)

Create a serializable dict with references to other objects in the memo.

Parameters

mmg_memo (dict) – Memo dict from a ModelMemberGraph, i.e. keys are object ids and values are ModelMemberGraphNodes (which contain the serialize_id). This is NOT the same as other memos in ModelMember (e.g. copy, allocate_gpindices, etc.).

Returns

mm_dict (dict) – A dict representation of this ModelMember ready for serialization This must have at least the following fields:

module, class, submembers, params, state_space, evotype

Additional fields may be added by derived classes.

classmethod _check_memoized_dict(cls, mm_dict, serial_memo)

Performs simple checks to ensure that mm_dict corresponds to the actual class( cls) being created, and that all submembers are present in serial_memo

abstract classmethod _from_memoized_dict(cls, mm_dict, serial_memo)

For subclasses to implement. Submember-existence checks are performed, and the gpindices of the return value is set, by the non-underscored :method:`from_memoized_dict` implemented in this class.

classmethod from_memoized_dict(cls, mm_dict, serial_memo)

Deserialize a ModelMember object and relink submembers from a memo.

Parameters
  • mm_dict (dict) –

    A dict representation of this ModelMember ready for deserialization This must have at least the following fields:

    module, class, submembers, state_space, evotype

  • serial_memo (dict) – Keys are serialize_ids and values are ModelMembers. This is NOT the same as other memos in ModelMember, (e.g. copy(), allocate_gpindices(), etc.). This is similar but not the same as mmg_memo in to_memoized_dict(), as we do not need to build a ModelMemberGraph for deserialization.

Returns

ModelMember – An initialized object

_copy_gpindices(self, op_obj, parent, memo)

Helper function for implementing copy in derived classes

_print_gpindices(self, prefix='', member_label=None, param_labels=None, max_depth=0)
_oneline_contents(self)

Summarizes the contents of this object in a single line. Does not summarize submembers.

class pygsti.modelmembers.ModelChild(parent=None)

Bases: object

Base class for all objects contained in a Model that hold a parent reference to their parent Model.

Parameters

parent (Model, optional) – The parent model.

parent

The parent of this object.

Type

Model

copy(self, parent=None, memo=None)

Copy this object. Resets parent to None or parent.

Parameters

parent (Model, optional) – The parent of the new, copied, object.

Returns

ModelChild – A copy of this object.

property parent(self)

Gets the parent of this object.

Returns

Model

__getstate__(self)

Don’t pickle parent

pygsti.modelmembers.from_memoized_dict(mm_dict, serial_memo)

Deserialize a ModelMember object and relink submembers from a memo.

Parameters
  • mm_dict (dict) –

    A dict representation of this ModelMember ready for deserialization This must have at least the following fields:

    module, class, submembers, params, state_space, evotype

  • serial_memo (dict) – Keys are serialize_ids and values are ModelMembers. This is NOT the same as other memos in ModelMember, (e.g. copy(), allocate_gpindices(), etc.). This is similar but not the same as mmg_memo in to_memoized_dict(), as we do not need to build a ModelMemberGraph for deserialization.

Returns

ModelMember – An initialized object