pygsti.modelmembers.operations.opfactory

Defines the OpFactory class

Module Contents

Classes

OpFactory

An object that can generate "on-demand" operators (can be SPAM vecs, etc., as well) for a Model.

EmbeddedOpFactory

A factory that embeds a given factory's action into a single, pre-defined set of target sectors.

EmbeddingOpFactory

A factory that "on-demand" embeds a given factory or operation into any requested set of target sectors.

ComposedOpFactory

A factory that composes a number of other factories and/or operations.

UnitaryOpFactory

An operation factory based on a unitary-matrix-producing function.

Functions

op_from_factories(factory_dict, lbl)

Create an operator for lbl from the factories in factory_dict.

pygsti.modelmembers.operations.opfactory.op_from_factories(factory_dict, lbl)

Create an operator for lbl from the factories in factory_dict.

If the label has arguments, then this function looks for an operator factory associated with the label without its arguments. If one exists, the operator is created by calling :method:`OpFactory.create_simplified_op`. with the label’s arguments. Otherwise, it looks for a factory associated with the label’s name (lbl.name) and passes both the labe’s state-space-labels and arguments (if any) to :method:`OpFactory.create_simplified_op`.

Raises a KeyError if a matching factory cannot be found.

Parameters
  • factory_dict (dict) – A dictionary whose keys are labels and values are OpFactory objects.

  • lbl (Label) – The label to build an operation for.

Returns

LinearOperator

class pygsti.modelmembers.operations.opfactory.OpFactory(state_space, evotype)

Bases: pygsti.modelmembers.modelmember.ModelMember

An object that can generate “on-demand” operators (can be SPAM vecs, etc., as well) for a Model.

It is assigned certain parameter indices (it’s a ModelMember), which definie the block of indices it may assign to its created operations.

The central method of an OpFactory object is the create_op method, which creates an operation that is associated with a given label. This is very similar to a LayerLizard’s function, though a LayerLizard has detailed knowledge and access to a Model’s internals whereas an OpFactory is meant to create a self-contained class of operators (e.g. continuously parameterized gates or on-demand embedding).

This class just provides a skeleton for an operation factory - derived classes add the actual code for creating custom objects.

Parameters
  • state_space (StateSpace) – The state-space of the operation(s) this factory builds.

  • evotype (Evotype) – The evolution type of the operation(s) this factory builds.

abstract create_object(self, args=None, sslbls=None)

Create the object that implements the operation associated with the given args and sslbls.

Note to developers The difference beween this method and :method:`create_op` is that this method just creates the foundational object without needing to setup its parameter indices (a technical detail which connects the created object with the originating factory’s parameters). The base-class create_op method calls create_object and then performs some additional setup on the returned object before returning it itself. Thus, unless you have a reason for implementing create_op it’s often more convenient and robust to implement this function.

Parameters
  • args (list or tuple) – The arguments for the operation to be created. None means no arguments were supplied.

  • sslbls (list or tuple) – The list of state space labels the created operator should act on. If None, then these labels are unspecified and should be irrelevant to the construction of the operator (which typically, in this case, has some fixed dimension and no noition of state space labels).

Returns

ModelMember – Can be any type of operation, e.g. a LinearOperator, SPAMVec, Instrument, or POVM, depending on the label requested.

create_op(self, args=None, sslbls=None)

Create the operation associated with the given args and sslbls.

Parameters
  • args (list or tuple) – The arguments for the operation to be created. None means no arguments were supplied.

  • sslbls (list or tuple) – The list of state space labels the created operator should act on. If None, then these labels are unspecified and should be irrelevant to the construction of the operator (which typically, in this case, has some fixed dimension and no noition of state space labels).

Returns

ModelMember – Can be any type of operation, e.g. a LinearOperator, SPAMVec, Instrument, or POVM, depending on the label requested.

create_simplified_op(self, args=None, sslbls=None, item_lbl=None)

Create the simplified operation associated with the given args, sslbls, and item_lbl.

Similar to as :method:`create_op`, but returns a simplified operation (i.e. not a POVM or Instrument). In addition, the item_lbl argument must be used for POVMs and Instruments, as these need to know which (simple) member of themselves to return (this machinery still needs work).

That is, if create_op returns something like a POVM or an Instrument, this method returns a single effect or instrument-member operation (a single linear-operator or SPAM vector).

Parameters
  • args (list or tuple) – The arguments for the operation to be created. None means no arguments were supplied.

  • sslbls (list or tuple) – The list of state space labels the created operator should act on. If None, then these labels are unspecified and should be irrelevant to the construction of the operator (which typically, in this case, has some fixed dimension and no noition of state space labels).

  • item_lbl (str, optional) – Effect or instrument-member label (index) for factories that create POVMs or instruments, respectively.

Returns

ModelMember – Can be any type of siple operation, e.g. a LinearOperator or SPAMVec, depending on the label requested.

abstract transform_inplace(self, s)

Update OpFactory so that created ops O are additionally transformed as inv(s) * O * s.

Parameters

s (GaugeGroupElement) – A gauge group element which specifies the “s” matrix (and it’s inverse) used in the above similarity transform.

Returns

None

__str__(self)

Return str(self).

class pygsti.modelmembers.operations.opfactory.EmbeddedOpFactory(state_space, target_labels, factory_to_embed)

Bases: OpFactory

A factory that embeds a given factory’s action into a single, pre-defined set of target sectors.

Parameters
  • state_space (StateSpace) – The state space of this factory, describing the space of these that the operations produced by this factory act upon.

  • target_labels (list of strs) – The labels contained in state_space_labels which demarcate the portions of the state space acted on by the operations produced by factory_to_embed (the “contained” factory).

  • factory_to_embed (OpFactory) – The factory object that is to be contained within this factory, and that specifies the only non-trivial action of the operations this factory produces.

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 _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.

create_op(self, args=None, sslbls=None)

Create the operation associated with the given args and sslbls.

Parameters
  • args (list or tuple) – The arguments for the operation to be created. None means no arguments were supplied.

  • sslbls (list or tuple) – The list of state space labels the created operator should act on. If None, then these labels are unspecified and should be irrelevant to the construction of the operator (which typically, in this case, has some fixed dimension and no noition of state space labels).

Returns

ModelMember – Can be any type of operation, e.g. a LinearOperator, State, Instrument, or POVM, depending on the label requested.

submembers(self)

Get the ModelMember-derived objects contained in this one.

Returns

list

property num_params(self)

Get the number of independent parameters which specify this OpFactory.

Returns

int – the number of independent parameters.

to_vector(self)

Extract a vector of the underlying gate parameters from this OpFactory.

Returns

numpy array – a 1D numpy array with length == num_params().

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

Initialize this OpFactory using a vector of its parameters.

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

  • close (bool, optional) – Whether v is close to this factory’s current set of parameters. Under some circumstances, when this is true this call can be completed more quickly.

  • 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

class pygsti.modelmembers.operations.opfactory.EmbeddingOpFactory(state_space, factory_or_op_to_embed, num_target_labels=None, allowed_sslbls_fn=None)

Bases: OpFactory

A factory that “on-demand” embeds a given factory or operation into any requested set of target sectors.

This is similar to an EmbeddedOpFactory except in this case how the “contained” operation/factory is embedded is not determined at creation time: the sslbls argument of :method:`create_op` is used instead.

Parameters
  • state_space (StateSpace) – The state space of this factory, describing the space of these that the operations produced by this factory act upon.

  • factory_or_op_to_embed (LinearOperator or OpFactory) – The factory or operation object that is to be contained within this factory. If a linear operator, this same operator (not a copy) is embedded however is requested. If a factory, then this object’s create_op method is called with any args that are passed to the embedding-factory’s create_op method, but the sslbls are always set to None (as they are processed by the embedding

  • num_target_labels (int, optional) – If not None, the number of target labels that should be expected (usually equal to the number of qubits the contained gate acts upon). If None, then the length of the sslbls passed to this factory’s create_op method is not checked at all.

  • allowed_sslbls_fn (callable, optional) – A boolean function that takes a single sslbls argument specifying the state-space labels for which the factory has been asked to embed factory_or_op_to_embed. If the function returns True then the embedding is allowed, if False then an error is raised.

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 _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.

create_op(self, args=None, sslbls=None)

Create the operation associated with the given args and sslbls.

Parameters
  • args (list or tuple) – The arguments for the operation to be created. None means no arguments were supplied.

  • sslbls (list or tuple) – The list of state space labels the created operator should act on. If None, then these labels are unspecified and should be irrelevant to the construction of the operator (which typically, in this case, has some fixed dimension and no noition of state space labels).

Returns

ModelMember – Can be any type of operation, e.g. a LinearOperator, State, Instrument, or POVM, depending on the label requested.

submembers(self)

Get the ModelMember-derived objects contained in this one.

Returns

list

property num_params(self)

Get the number of independent parameters which specify this OpFactory.

Returns

int – the number of independent parameters.

to_vector(self)

Extract a vector of the underlying gate parameters from this OpFactory.

Returns

numpy array – a 1D numpy array with length == num_params().

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

Initialize this OpFactory using a vector of its parameters.

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

  • close (bool, optional) – Whether v is close to this factory’s current set of parameters. Under some circumstances, when this is true this call can be completed more quickly.

  • 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

class pygsti.modelmembers.operations.opfactory.ComposedOpFactory(factories_or_ops_to_compose, state_space='auto', evotype='auto', dense=False)

Bases: OpFactory

A factory that composes a number of other factories and/or operations.

Label arguments are passed unaltered through this factory to any component factories.

Parameters
  • factories_or_ops_to_compose (list) – List of LinearOperator or OpFactory-derived objects that are composed to form this factory. There should be at least one factory among this list, otherwise there’s no need for a factory. Elements are composed with vectors in left-to-right ordering, maintaining the same convention as operation sequences in pyGSTi. Note that this is opposite from standard matrix multiplication order.

  • state_space (StateSpace or "auto") – States space of the operations produced by this factory. Can be set to “auto” to take the state space from factories_or_ops_to_compose[0] if there’s at least one factory or operator being composed.

  • evotype ({"densitymx","statevec","stabilizer","svterm","cterm","auto"}) – The evolution type of this factory. Can be set to “auto” to take the evolution type of factories_or_ops_to_compose[0] if there’s at least one factory or operator being composed.

  • dense (bool, optional) – Whether dense composed operations (ops which hold their entire

create_op(self, args=None, sslbls=None)

Create the operation associated with the given args and sslbls.

Parameters
  • args (list or tuple) – The arguments for the operation to be created. None means no arguments were supplied.

  • sslbls (list or tuple) – The list of state space labels the created operator should act on. If None, then these labels are unspecified and should be irrelevant to the construction of the operator (which typically, in this case, has some fixed dimension and no noition of state space labels).

Returns

ModelMember – Can be any type of operation, e.g. a LinearOperator, State, Instrument, or POVM, depending on the label requested.

submembers(self)

Get the ModelMember-derived objects contained in this one.

Returns

list

property num_params(self)

Get the number of independent parameters which specify this factory.

Returns

int – the number of independent parameters.

to_vector(self)

Get the parameters as an array of values.

Returns

numpy array – The parameters as a 1D array with length num_params().

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

Initialize this factory using a vector of parameters.

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

  • close (bool, optional) – Whether v is close to this factory’s current set of parameters. Under some circumstances, when this is true this call can be completed more quickly.

  • 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

class pygsti.modelmembers.operations.opfactory.UnitaryOpFactory(fn, state_space, superop_basis='pp', evotype='densitymx')

Bases: OpFactory

An operation factory based on a unitary-matrix-producing function.

Converts a function, f(arg_tuple), that outputs a unitary matrix (operation) into a factory that produces a StaticArbitraryOp superoperator.

Parameters
  • fn (function) – A function that takes as it’s only argument a tuple of label-arguments (arguments included in circuit labels, e.g. ‘Gxrot;0.347’) and returns a unitary matrix – a complex numpy array that has dimension 2^nQubits, e.g. a 2x2 matrix in the 1-qubit case.

  • state_space (StateSpace) – The state space of this factory, describing the space of these that the operations produced by this factory act upon. The function fn should return a unitary matrix with dimension state_space.udim, e.g. a 2x2 matrix when state_space describes a single qubit.

  • superop_basis (Basis or {"std","pp","gm","qt"}) – The basis used to represent super-operators. If the operations produced by this factor need to be given a dense superoperator representation, this basis is used. Usually the default of “pp” is what you want.

  • evotype ({"densitymx","statevec","stabilizer","svterm","cterm"}) – The evolution type of the operation(s) this factory builds.

create_object(self, args=None, sslbls=None)

Create the object which implements the operation associated with the given args and sslbls.

Parameters
  • args (list or tuple) – The arguments for the operation to be created. None means no arguments were supplied.

  • sslbls (list or tuple) – The list of state space labels the created operator should act on. If None, then these labels are unspecified and should be irrelevant to the construction of the operator (which typically, in this case, has some fixed dimension and no noition of state space labels).

Returns

ModelMember – Can be any type of operation, e.g. a LinearOperator, State, Instrument, or POVM, depending on the label requested.