pygsti.models.modelconstruction

Functions for the construction of new models.

Module Contents

Functions

create_spam_vector(vec_expr, state_space, basis)

Build a rho or E vector from an expression.

create_identity_vec(basis)

Build a the identity vector for a given space and basis.

create_operation(op_expr, state_space, basis='pp', parameterization='full', evotype='default')

Build an operation object from an expression.

_create_explicit_model_from_expressions(state_space, basis, op_labels, op_expressions, prep_labels=('rho0', ), prep_expressions=('0', ), effect_labels='standard', effect_expressions='standard', povm_labels='Mdefault', gate_type='full', prep_type='auto', povm_type='auto', instrument_type='auto', evotype='default')

Build a new Model given lists of operation labels and expressions.

create_explicit_model_from_expressions(state_space, op_labels, op_expressions, prep_labels=('rho0', ), prep_expressions=('0', ), effect_labels='standard', effect_expressions='standard', povm_labels='Mdefault', basis='auto', gate_type='full', prep_type='auto', povm_type='auto', instrument_type='auto', evotype='default')

Build a new ExplicitOpModel given lists of labels and expressions.

create_explicit_alias_model(mdl_primitives, alias_dict)

Creates a model by applying aliases to an existing model.

create_explicit_model(processor_spec, custom_gates=None, depolarization_strengths=None, stochastic_error_probs=None, lindblad_error_coeffs=None, depolarization_parameterization='depolarize', stochastic_parameterization='stochastic', lindblad_parameterization='auto', evotype='default', simulator='auto', ideal_gate_type='auto', ideal_spam_type='computational', embed_gates=False, basis='pp')

_create_explicit_model(processor_spec, modelnoise, custom_gates=None, evotype='default', simulator='auto', ideal_gate_type='auto', ideal_prep_type='auto', ideal_povm_type='auto', embed_gates=False, basis='pp')

_create_spam_layers(processor_spec, modelnoise, local_noise, ideal_prep_type, ideal_povm_type, evotype, state_space, independent_gates, independent_spam)

local_noise=True creates lindblad ops that are embedded & composed 1Q ops, and assumes

_setup_local_gates(processor_spec, evotype, modelnoise=None, custom_gates=None, ideal_gate_type=('static standard', 'static clifford', 'static unitary'))

Construct a dictionary of potentially noisy gates that act only on their target qubits.

create_crosstalk_free_model(processor_spec, custom_gates=None, depolarization_strengths=None, stochastic_error_probs=None, lindblad_error_coeffs=None, depolarization_parameterization='depolarize', stochastic_parameterization='stochastic', lindblad_parameterization='auto', evotype='default', simulator='auto', on_construction_error='raise', independent_gates=False, independent_spam=True, ensure_composed_gates=False, ideal_gate_type='auto', ideal_spam_type='computational', implicit_idle_mode='none')

Create a n-qubit "crosstalk-free" model.

_create_crosstalk_free_model(processor_spec, modelnoise, custom_gates=None, evotype='default', simulator='auto', on_construction_error='raise', independent_gates=False, independent_spam=True, ensure_composed_gates=False, ideal_gate_type='auto', ideal_prep_type='auto', ideal_povm_type='auto', implicit_idle_mode='none')

Create a n-qubit "crosstalk-free" model.

create_cloud_crosstalk_model(processor_spec, custom_gates=None, depolarization_strengths=None, stochastic_error_probs=None, lindblad_error_coeffs=None, depolarization_parameterization='depolarize', stochastic_parameterization='stochastic', lindblad_parameterization='auto', evotype='default', simulator='auto', independent_gates=False, independent_spam=True, errcomp_type='gates', implicit_idle_mode='none', verbosity=0)

Create a n-qubit "cloud-crosstalk" model.

_create_cloud_crosstalk_model(processor_spec, modelnoise, custom_gates=None, evotype='default', simulator='auto', independent_gates=False, independent_spam=True, errcomp_type='errorgens', implicit_idle_mode='none', verbosity=0)

Create a n-qubit "cloud-crosstalk" model.

create_cloud_crosstalk_model_from_hops_and_weights(processor_spec, custom_gates=None, max_idle_weight=1, max_spam_weight=1, maxhops=0, extra_weight_1_hops=0, extra_gate_weight=0, simulator='auto', evotype='default', gate_type='H+S', spam_type='H+S', implicit_idle_mode='none', errcomp_type='gates', independent_gates=True, independent_spam=True, connected_highweight_errors=True, verbosity=0)

Create a "cloud crosstalk" model based on maximum error weights and hops along the processor's qubit graph.

_iter_basis_inds(weight)

Iterate over product of weight non-identity Pauli 1Q basis indices

_pauli_product_matrix(sigma_inds)

Construct the Pauli product matrix from the given sigma_inds

_construct_restricted_weight_pauli_basis(wt, sparse=False)

_build_weight_maxhops_modelnoise(target_sslbls, weight_maxhops_tuples, lnd_parameterization, connected=True)

_build_modelnoise_from_args(depolarization_strengths, stochastic_error_probs, lindblad_error_coeffs, depolarization_parameterization, stochastic_parameterization, lindblad_parameterization, allow_nonlocal)

_nparams_xycnot_cloudnoise_model(num_qubits, geometry='line', max_idle_weight=1, maxhops=0, extra_weight_1_hops=0, extra_gate_weight=0, require_connected=False, independent_1q_gates=True, zz_only=False, bidirectional_cnots=True, verbosity=0)

Compute the number of parameters in a particular CloudNoiseModel.

pygsti.models.modelconstruction.create_spam_vector(vec_expr, state_space, basis)

Build a rho or E vector from an expression.

Parameters
  • vec_expr (string) – the expression which determines which vector to build. Currenlty, only integers are allowed, which specify a the vector for the pure state of that index. For example, “1” means return vectorize(|1><1|). The index labels the absolute index of the state within the entire state space, and is independent of the direct-sum decomposition of density matrix space.

  • state_space (StateSpace) – The state space that the created operation should act upon.

  • basis (str or Basis) – The basis of the returned vector. Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt) (or a custom basis object).

Returns

numpy array – The vector specified by vec_expr in the desired basis.

pygsti.models.modelconstruction.create_identity_vec(basis)

Build a the identity vector for a given space and basis.

Parameters

basis (Basis object) – The basis of the returned vector. Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt) (or a custom basis object).

Returns

numpy array – The identity vector in the desired basis.

pygsti.models.modelconstruction.create_operation(op_expr, state_space, basis='pp', parameterization='full', evotype='default')

Build an operation object from an expression.

Parameters
  • op_expr (string) –

    expression for the gate to build. String is first split into parts delimited by the colon (:) character, which are composed together to create the final gate. Each part takes on of the allowed forms:

    • I(ssl_0, …) = identity operation on one or more state space labels (ssl_i)

    • X(theta, ssl) = x-rotation by theta radians of qubit labeled by ssl

    • Y(theta, ssl) = y-rotation by theta radians of qubit labeled by ssl

    • Z(theta, ssl) = z-rotation by theta radians of qubit labeled by ssl

    • CX(theta, ssl0, ssl1) = controlled x-rotation by theta radians. Acts on qubit labeled by ssl1 with ssl0 being the control.

    • CY(theta, ssl0, ssl1) = controlled y-rotation by theta radians. Acts on qubit labeled by ssl1 with ssl0 being the control.

    • CZ(theta, ssl0, ssl1) = controlled z-rotation by theta radians. Acts on qubit labeled by ssl1 with ssl0 being the control.

    • CNOT(ssl0, ssl1) = standard controlled-not gate. Acts on qubit labeled by ssl1 with ssl0 being the control.

    • CPHASE(ssl0, ssl1) = standard controlled-phase gate. Acts on qubit labeled by ssl1 with ssl0 being the control.

    • LX(theta, i0, i1) = leakage between states i0 and i1. Implemented as an x-rotation between states with integer indices i0 and i1 followed by complete decoherence between the states.

  • state_space (StateSpace) – The state space that the created operation should act upon.

  • basis (str or Basis) – The basis the returned operation should be represented in.

  • parameterization ({"full","TP","static"}, optional) –

    How to parameterize the resulting gate.

    • ”full” = return a FullArbitraryOp.

    • ”TP” = return a FullTPOp.

    • ”static” = return a StaticArbitraryOp.

  • evotype (Evotype or str, optional) – The evolution type of this operation, describing how states are represented. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

Returns

LinearOperator – A gate object representing the gate given by op_expr in the desired basis.

pygsti.models.modelconstruction._create_explicit_model_from_expressions(state_space, basis, op_labels, op_expressions, prep_labels=('rho0',), prep_expressions=('0',), effect_labels='standard', effect_expressions='standard', povm_labels='Mdefault', gate_type='full', prep_type='auto', povm_type='auto', instrument_type='auto', evotype='default')

Build a new Model given lists of operation labels and expressions.

Parameters
  • state_space (StateSpace) – The state space for this model.

  • basis (Basis object) – The source and destination basis, respectively. Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt) (or a custom basis object).

  • op_labels (list of strings) –

    A list of labels for each created gate in the final model. To

    conform with text file parsing conventions these names should begin with a capital G and can be followed by any number of lowercase characters, numbers, or the underscore character.

  • op_expressions (list of strings) – A list of gate expressions, each corresponding to a operation label in op_labels, which determine what operation each gate performs (see documentation for create_operation()).

  • prep_labels (list of string, optional) – A list of labels for each created state preparation in the final model. To conform with conventions these labels should begin with “rho”.

  • prep_expressions (list of strings, optional) – A list of vector expressions for each state preparation vector (see documentation for _create_spam_vector()).

  • effect_labels (list, optional) – If povm_labels is a string, then this is just a list of the effect (outcome) labels for the single POVM. If povm_labels is a tuple, then effect_labels must be a list of lists of effect labels, each list corresponding to a POVM. If set to the special string “standard” then the length-n binary strings are used when the state space consists of n qubits (e.g. “000”, “001”, … “111” for 3 qubits) and the labels “0”, “1”, … “<dim>” are used, where <dim> is the dimension of the state space, in all non-qubit cases.

  • effect_expressions (list, optional) – A list or list-of-lists of (string) vector expressions for each POVM effect vector (see documentation for _create_spam_vector()). Expressions correspond to labels in effect_labels. If set to the special string “standard”, then the expressions “0”, “1”, … “<dim>” are used, where <dim> is the dimension of the state space.

  • povm_labels (list or string, optional) – A list of POVM labels, or a single (string) label. In the latter case, only a single POVM is created and the format of effect_labels and effect_expressions is simplified (see above).

  • parameterization ({"full","TP","static"}, optional) – How to parameterize the gates of the resulting Model (see documentation for create_operation()).

  • evotype (Evotype or str, optional) – The evolution type of this model, describing how states are represented. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

Returns

Model – The created model.

pygsti.models.modelconstruction.create_explicit_model_from_expressions(state_space, op_labels, op_expressions, prep_labels=('rho0',), prep_expressions=('0',), effect_labels='standard', effect_expressions='standard', povm_labels='Mdefault', basis='auto', gate_type='full', prep_type='auto', povm_type='auto', instrument_type='auto', evotype='default')

Build a new ExplicitOpModel given lists of labels and expressions.

Parameters
  • state_space (StateSpace) – the state space for the model.

  • op_labels (list of strings) –

    A list of labels for each created gate in the final model. To

    conform with text file parsing conventions these names should begin with a capital G and can be followed by any number of lowercase characters, numbers, or the underscore character.

  • op_expressions (list of strings) – A list of gate expressions, each corresponding to a operation label in op_labels, which determine what operation each gate performs (see documentation for create_operation()).

  • prep_labels (list of string) – A list of labels for each created state preparation in the final model. To conform with conventions these labels should begin with “rho”.

  • prep_expressions (list of strings) – A list of vector expressions for each state preparation vector (see documentation for _create_spam_vector()).

  • effect_labels (list, optional) – If povm_labels is a string, then this is just a list of the effect (outcome) labels for the single POVM. If povm_labels is a tuple, then effect_labels must be a list of lists of effect labels, each list corresponding to a POVM. If set to the special string “standard” then the length-n binary strings are used when the state space consists of n qubits (e.g. “000”, “001”, … “111” for 3 qubits) and the labels “0”, “1”, … “<dim>” are used, where <dim> is the dimension of the state space, in all non-qubit cases.

  • effect_expressions (list, optional) – A list or list-of-lists of (string) vector expressions for each POVM effect vector (see documentation for _create_spam_vector()). Expressions correspond to labels in effect_labels. If set to the special string “standard”, then the expressions “0”, “1”, … “<dim>” are used, where <dim> is the dimension of the state space.

  • povm_labels (list or string, optional) – A list of POVM labels, or a single (string) label. In the latter case, only a single POVM is created and the format of effect_labels and effect_expressions is simplified (see above).

  • basis ({'gm','pp','std','qt','auto'}, optional) –

    the basis of the matrices in the returned Model

    • ”std” = operation matrix operates on density mx expressed as sum of matrix units

    • ”gm” = operation matrix operates on dentity mx expressed as sum of normalized Gell-Mann matrices

    • ”pp” = operation matrix operates on density mx expresses as sum of tensor-product of Pauli matrices

    • ”qt” = operation matrix operates on density mx expressed as sum of Qutrit basis matrices

    • ”auto” = “pp” if possible (integer num of qubits), “qt” if density matrix dim == 3, and “gm” otherwise.

  • parameterization ({"full","TP"}, optional) – How to parameterize the gates of the resulting Model (see documentation for create_operation()).

  • evotype (Evotype or str, optional) – The evolution type of this model, describing how states are represented. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

Returns

ExplicitOpModel – The created model.

pygsti.models.modelconstruction.create_explicit_alias_model(mdl_primitives, alias_dict)

Creates a model by applying aliases to an existing model.

The new model is created by composing the gates of an existing Model, mdl_primitives, according to a dictionary of Circuit`s, `alias_dict. The keys of alias_dict are the operation labels of the returned Model. state preparations and POVMs are unaltered, and simply copied from mdl_primitives.

Parameters
  • mdl_primitives (Model) – A Model containing the “primitive” gates (those used to compose the gates of the returned model).

  • alias_dict (dictionary) – A dictionary whose keys are strings and values are Circuit objects specifying sequences of primitive gates. Each key,value pair specifies the composition rule for a creating a gate in the returned model.

Returns

Model – A model whose gates are compositions of primitive gates and whose spam operations are the same as those of mdl_primitives.

pygsti.models.modelconstruction.create_explicit_model(processor_spec, custom_gates=None, depolarization_strengths=None, stochastic_error_probs=None, lindblad_error_coeffs=None, depolarization_parameterization='depolarize', stochastic_parameterization='stochastic', lindblad_parameterization='auto', evotype='default', simulator='auto', ideal_gate_type='auto', ideal_spam_type='computational', embed_gates=False, basis='pp')
pygsti.models.modelconstruction._create_explicit_model(processor_spec, modelnoise, custom_gates=None, evotype='default', simulator='auto', ideal_gate_type='auto', ideal_prep_type='auto', ideal_povm_type='auto', embed_gates=False, basis='pp')
pygsti.models.modelconstruction._create_spam_layers(processor_spec, modelnoise, local_noise, ideal_prep_type, ideal_povm_type, evotype, state_space, independent_gates, independent_spam)

local_noise=True creates lindblad ops that are embedded & composed 1Q ops, and assumes that modelnoise specifies 1Q noise. local_noise=False assumes modelnoise specifies n-qubit noise

pygsti.models.modelconstruction._setup_local_gates(processor_spec, evotype, modelnoise=None, custom_gates=None, ideal_gate_type=('static standard', 'static clifford', 'static unitary'))

Construct a dictionary of potentially noisy gates that act only on their target qubits.

These gates are “local” because they act only on their intended target qubits. The gates consist of an ideal gate (obviously local, and crosstalk free) of the type given by ideal_gate_type composed with a noise operation given by modelnoise, if one exists. The returned dictionary contains keys for all the gate names in processor_spec. Custom gate objects can be given by custom_gates, which override the normal gate construction.

Parameters
  • processor_spec (ProcessorSpec) – The processor to create gate operations for. This object specifies the gate names and unitaries for the processor, among other things.

  • evotype (Evotype) – Create gate objects with this evolution type.

  • modelnoise (ModelNoise, optional) – Noise that should be applied after the ideal gates. This noise must be local to each gate (i.e. acting on its target qubits). See the ModelNoise object documentation for details regarding how to specify different types of noise. If None, then no noise is added .

  • custom_gates (dict, optional) – A dictionary of gate objects that should be placed in the returned dictionary in lieu of objects that would normally be constructed. Keys are gate names and values are gates.

  • ideal_gate_type (str or tuple, optional) – A gate type or tuple of gate types (listed in order of priority) which is used to construct the ideal gates. A gate type usually specifies the Python class that will be created, which determines 1) the parameterization of the gate and 2) the class/category of the gate (e.g. a StaticClifford operation has no parameters and is a Clifford operation).

Returns

gatedict (dict) – A dictionary mapping gate names to local gate operations.

pygsti.models.modelconstruction.create_crosstalk_free_model(processor_spec, custom_gates=None, depolarization_strengths=None, stochastic_error_probs=None, lindblad_error_coeffs=None, depolarization_parameterization='depolarize', stochastic_parameterization='stochastic', lindblad_parameterization='auto', evotype='default', simulator='auto', on_construction_error='raise', independent_gates=False, independent_spam=True, ensure_composed_gates=False, ideal_gate_type='auto', ideal_spam_type='computational', implicit_idle_mode='none')

Create a n-qubit “crosstalk-free” model.

By virtue of being crosstalk-free, this model’s operations only act nontrivially on their target qubits. Gates consist of an ideal gate operation possibly followed by an error operation.

Errors can be specified using any combination of the 4 error rate/coeff arguments, but each gate name must be provided exclusively to one type of specification. Each specification results in a different type of operation, depending on the parameterization:

  • depolarization_strengths -> DepolarizeOp, StochasticNoiseOp, or exp(LindbladErrorgen)

  • stochastic_error_probs -> StochasticNoiseOp or exp(LindbladErrorgen)

  • lindblad_error_coeffs -> exp(LindbladErrorgen)

In addition to the gate names, the special values “prep” and “povm” may be used as keys to specify the error on the state preparation, measurement, respectively.

Parameters
  • processor_spec (ProcessorSpec) – The processor specification to create a model for. This object specifies the gate names and unitaries for the processor, and their availability on the processor.

  • custom_gates (dict, optional) – A dictionary that associates with gate labels LinearOperator, OpFactory, or numpy.ndarray objects. These objects override any other behavior for constructing their designated operations. Keys of this dictionary may be string-type gate names or labels that include target qubits.

  • depolarization_strengths (dict, optional) – A dictionary whose keys are gate names (e.g. “Gx”) and whose values are floats that specify the strength of uniform depolarization.

  • stochastic_error_probs (dict, optional) – A dictionary whose keys are gate names (e.g. “Gx”) and whose values are tuples that specify Pauli-stochastic rates for each of the non-trivial Paulis (so a 3-tuple would be expected for a 1Q gate and a 15-tuple for a 2Q gate).

  • lindblad_error_coeffs (dict, optional) – A dictionary whose keys are gate names (e.g. “Gx”) and whose values are dictionaries corresponding to the lindblad_term_dict kwarg taken by LindbladErrorgen. Keys are (termType, basisLabel1, <basisLabel2>) tuples, where termType can be “H” (Hamiltonian), “S” (Stochastic), or “A” (Affine). Hamiltonian and Affine terms always have a single basis label (so key is a 2-tuple) whereas Stochastic tuples with 1 basis label indicate a diagonal term, and are the only types of terms allowed when nonham_mode != “all”. Otherwise, Stochastic term tuples can include 2 basis labels to specify “off-diagonal” non-Hamiltonian Lindblad terms. Basis labels can be strings or integers. Values are complex coefficients.

  • depolarization_parameterization (str of {"depolarize", "stochastic", or "lindblad"}) – Determines whether a DepolarizeOp, StochasticNoiseOp, or LindbladErrorgen is used to parameterize the depolarization noise, respectively. When “depolarize” (the default), a DepolarizeOp is created with the strength given in depolarization_strengths. When “stochastic”, the depolarization strength is split evenly among the stochastic channels of a StochasticOp. When “lindblad”, the depolarization strength is split evenly among the coefficients of the stochastic error generators (which are exponentiated to form a LindbladErrorgen with the “depol” parameterization).

  • stochastic_parameterization (str of {"stochastic", or "lindblad"}) – Determines whether a StochasticNoiseOp or LindbladErrorgen is used to parameterize the stochastic noise, respectively. When “stochastic”, elements of stochastic_error_probs are used as coefficients in a linear combination of stochastic channels (the default). When “lindblad”, the elements of stochastic_error_probs are coefficients of stochastic error generators (which are exponentiated to form a LindbladErrorgen with the “cptp” parameterization).

  • lindblad_parameterization ("auto" or a LindbladErrorgen paramtype) – Determines the parameterization of the LindbladErrorgen. When “auto” (the default), the parameterization is inferred from the types of error generators specified in the lindblad_error_coeffs dictionaries. When not “auto”, the parameterization type is passed through to the LindbladErrorgen.

  • evotype (Evotype or str, optional) – The evolution type. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

  • simulator (ForwardSimulator or {"auto", "matrix", "map"}) – The simulator used to compute predicted probabilities for the resulting Model. Using “auto” selects “matrix” when there are 2 qubits or less, and otherwise selects “map”.

  • on_construction_error ({'raise','warn',ignore'}) – What to do when the creation of a gate with the given parameterization fails. Usually you’ll want to “raise” the error. In some cases, for example when converting as many gates as you can into parameterization=”clifford” gates, “warn” or even “ignore” may be useful.

  • independent_gates (bool, optional) –

    Whether gates are allowed independent local noise or not. If False, then all gates with the same name (e.g. “Gx”) will have the same (local) noise (e.g. an overrotation by 1 degree), and the operation_bks[‘gates’] dictionary contains a single key per gate name. If True, then gates with the same name acting on different qubits may have different local noise, and so the operation_bks[‘gates’] dictionary contains a key for each gate

    available gate placement.

  • ensure_composed_gates (bool, optional) – If True then the elements of the operation_bks[‘gates’] will always be ComposedOp objects. The purpose of this is to facilitate modifying the gate operations after the model is created. If False, then the appropriately parameterized gate objects (often dense gates) are used directly.

  • ideal_gate_type (str or tuple, optional) – A gate type or tuple of gate types (listed in order of priority) which is used to construct the ideal gates. A gate type usually specifies the Python class that will be created, which determines 1) the parameterization of the gate and 2) the class/category of the gate (e.g. a StaticClifford operation has no parameters and is a Clifford operation).

  • ideal_spam_type (str or tuple, optional) – Similar to ideal_gate_type but for SPAM elements (state preparations and POVMs).

  • implicit_idle_mode ({'none', 'add_global'}) – The way idel operations are added implicitly within the created model. “none” doesn’t add any “extra” idle operations when there is a layer that contains some gates but not gates on all the qubits. “add_global” adds the global idle operation, i.e., the operation for a global idle layer (zero gates - a completely empty layer), to every layer that is simulated, using the global idle as a background idle that always occurs regardless of the operation.

Returns

LocalNoiseModel – A model with “rho0” prep, “Mdefault” POVM, and gates labeled by the gate names and qubit labels (as specified by processor_spec). For instance, the operation label for the “Gx” gate on the second qubit might be Label(“Gx”,1).

pygsti.models.modelconstruction._create_crosstalk_free_model(processor_spec, modelnoise, custom_gates=None, evotype='default', simulator='auto', on_construction_error='raise', independent_gates=False, independent_spam=True, ensure_composed_gates=False, ideal_gate_type='auto', ideal_prep_type='auto', ideal_povm_type='auto', implicit_idle_mode='none')

Create a n-qubit “crosstalk-free” model.

Similar to :method:`create_crosstalk_free_model` but the noise is input more generally, as a ModelNoise object. Arguments are the same as this function except that modelnoise is given instead of several more specific noise-describing arguments.

Returns

LocalNoiseModel

pygsti.models.modelconstruction.create_cloud_crosstalk_model(processor_spec, custom_gates=None, depolarization_strengths=None, stochastic_error_probs=None, lindblad_error_coeffs=None, depolarization_parameterization='depolarize', stochastic_parameterization='stochastic', lindblad_parameterization='auto', evotype='default', simulator='auto', independent_gates=False, independent_spam=True, errcomp_type='gates', implicit_idle_mode='none', verbosity=0)

Create a n-qubit “cloud-crosstalk” model.

In a cloud crosstalk model, gates consist of a (local) ideal gates followed by an error operation that can act nontrivially on any of the processor’s qubits (not just a gate’s target qubits). Typically a gate’s errors are specified relative to the gate’s target qubits, forming a “cloud” of errors around the target qubits using some notion of locality (that may not be spatial, e.g. local in frequency). Currently, the “ideal” portion of each gate can only be created as a static (parameterless) object – all gate parameters come from the error operation.

Errors can be specified using any combination of the 4 error rate/coeff arguments, but each gate name must be provided exclusively to one type of specification. Each specification results in a different type of operation, depending on the parameterization:

  • depolarization_strengths -> DepolarizeOp, StochasticNoiseOp, or exp(LindbladErrorgen)

  • stochastic_error_probs -> StochasticNoiseOp or exp(LindbladErrorgen)

  • lindblad_error_coeffs -> exp(LindbladErrorgen)

In addition to the gate names, the special values “prep” and “povm” may be used as keys to specify the error on the state preparation, measurement, respectively.

Parameters
  • processor_spec (ProcessorSpec) – The processor specification to create a model for. This object specifies the gate names and unitaries for the processor, and their availability on the processor.

  • custom_gates (dict, optional) – A dictionary that associates with gate labels LinearOperator, OpFactory, or numpy.ndarray objects. These objects override any other behavior for constructing their designated operations. Keys of this dictionary may be string-type gate names or labels that include target qubits.

  • depolarization_strengths (dict, optional) – A dictionary whose keys are gate names (e.g. “Gx”) and whose values are floats that specify the strength of uniform depolarization.

  • stochastic_error_probs (dict, optional) – A dictionary whose keys are gate names (e.g. “Gx”) and whose values are tuples that specify Pauli-stochastic rates for each of the non-trivial Paulis (so a 3-tuple would be expected for a 1Q gate and a 15-tuple for a 2Q gate).

  • lindblad_error_coeffs (dict, optional) – A dictionary whose keys are gate names (e.g. “Gx”) and whose values are dictionaries corresponding to the lindblad_term_dict kwarg taken by LindbladErrorgen. Keys are (termType, basisLabel1, <basisLabel2>) tuples, where termType can be “H” (Hamiltonian), “S” (Stochastic), or “A” (Affine). Hamiltonian and Affine terms always have a single basis label (so key is a 2-tuple) whereas Stochastic tuples with 1 basis label indicate a diagonal term, and are the only types of terms allowed when nonham_mode != “all”. Otherwise, Stochastic term tuples can include 2 basis labels to specify “off-diagonal” non-Hamiltonian Lindblad terms. Basis labels can be strings or integers. Values are complex coefficients.

  • depolarization_parameterization (str of {"depolarize", "stochastic", or "lindblad"}) – Determines whether a DepolarizeOp, StochasticNoiseOp, or LindbladErrorgen is used to parameterize the depolarization noise, respectively. When “depolarize” (the default), a DepolarizeOp is created with the strength given in depolarization_strengths. When “stochastic”, the depolarization strength is split evenly among the stochastic channels of a StochasticOp. When “lindblad”, the depolarization strength is split evenly among the coefficients of the stochastic error generators (which are exponentiated to form a LindbladErrorgen with the “depol” parameterization).

  • stochastic_parameterization (str of {"stochastic", or "lindblad"}) – Determines whether a StochasticNoiseOp or LindbladErrorgen is used to parameterize the stochastic noise, respectively. When “stochastic”, elements of stochastic_error_probs are used as coefficients in a linear combination of stochastic channels (the default). When “lindblad”, the elements of stochastic_error_probs are coefficients of stochastic error generators (which are exponentiated to form a LindbladErrorgen with the “cptp” parameterization).

  • lindblad_parameterization ("auto" or a LindbladErrorgen paramtype) – Determines the parameterization of the LindbladErrorgen. When “auto” (the default), the parameterization is inferred from the types of error generators specified in the lindblad_error_coeffs dictionaries. When not “auto”, the parameterization type is passed through to the LindbladErrorgen.

  • evotype (Evotype or str, optional) – The evolution type. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

  • simulator (ForwardSimulator or {"auto", "matrix", "map"}) – The simulator used to compute predicted probabilities for the resulting Model. Using “auto” selects “matrix” when there are 2 qubits or less, and otherwise selects “map”.

  • independent_gates (bool, optional) –

    Whether gates are allowed independent noise or not. If False, then all gates with the same name (e.g. “Gx”) will have the same noise (e.g. an overrotation by 1 degree), and the operation_bks[‘cloudnoise’] dictionary will contains a single key per gate name. If True, then gates with the same name acting on different qubits may have different local noise, and so the operation_bks[‘cloudnoise’] dictionary contains a key for each gate

    available gate placement.

  • independent_spam (bool, optional) – Similar to indepenent_gates but for SPAM operations.

  • errcomp_type ({'gates', 'errorgens'}) – Whether errors should be combined by composing error maps (gates) or by exponentiating the sum of error generators (composing the error generators, errorgens). The latter is only an option when the noise is given solely in terms of Lindblad error coefficients.

  • implicit_idle_mode ({'none', 'add_global'}) – The way idel operations are added implicitly within the created model. “none” doesn’t add any “extra” idle operations when there is a layer that contains some gates but not gates on all the qubits. “add_global” adds the global idle operation, i.e., the operation for a global idle layer (zero gates - a completely empty layer), to every layer that is simulated, using the global idle as a background idle that always occurs regardless of the operation.

  • verbosity (int or VerbosityPrinter, optional) – Amount of detail to print to stdout.

Returns

CloudNoiseModel

pygsti.models.modelconstruction._create_cloud_crosstalk_model(processor_spec, modelnoise, custom_gates=None, evotype='default', simulator='auto', independent_gates=False, independent_spam=True, errcomp_type='errorgens', implicit_idle_mode='none', verbosity=0)

Create a n-qubit “cloud-crosstalk” model.

Similar to :method:`create_cloud_crosstalk_model` but the noise is input more generally, as a ModelNoise object. Arguments are the same as this function except that modelnoise is given instead of several more specific noise-describing arguments.

Returns

CloudNoiseModel

pygsti.models.modelconstruction.create_cloud_crosstalk_model_from_hops_and_weights(processor_spec, custom_gates=None, max_idle_weight=1, max_spam_weight=1, maxhops=0, extra_weight_1_hops=0, extra_gate_weight=0, simulator='auto', evotype='default', gate_type='H+S', spam_type='H+S', implicit_idle_mode='none', errcomp_type='gates', independent_gates=True, independent_spam=True, connected_highweight_errors=True, verbosity=0)

Create a “cloud crosstalk” model based on maximum error weights and hops along the processor’s qubit graph.

This function provides a convenient way to construct cloud crosstalk models whose gate errors consist of Pauli elementary error generators (i.e. that correspond to Lindblad error coefficients) that are limited in weight (number of non-identity Paulis) and support (which qubits have non-trivial Paulis on them). Errors are taken to be approximately local, meaning they are concentrated near the target qubits of a gate, with the notion of locality taken from the processor specification’s qubit graph. The caller provides maximum-weight, maximum-hop (a “hop” is the movement along a single graph edge), and gate type arguments to specify the set of possible errors on a gate.

  • The global idle gate (corresponding to an empty circuit layer) has errors that are limited only by a maximum weight, max_idle_weight.

  • State preparation and POVM errors are constructed similarly, with a global-idle-like error following or preceding the preparation or measurement, respectively.

  • Gate errors are placed on all the qubits that can be reached with at most maxhops hops from (any of) the gate’s target qubits. Elementary error generators up to weight W, where W equals the number of target qubits (e.g., 2 for a CNOT gate) plus extra_gate_weight are allowed. Weight-1 terms are a special case, and the extra_weight_1_hops argument adds to the usual maxhops in this case to allow weight-1 errors on a possibly larger region of qubits around the target qubits.

Parameters
  • processor_spec (ProcessorSpec) – The processor specification to create a model for. This object specifies the gate names and unitaries for the processor, and their availability on the processor.

  • custom_gates (dict) – A dictionary that associates with gate labels LinearOperator, OpFactory, or numpy.ndarray objects. These objects describe the full action of the gate or primitive-layer they’re labeled by (so if the model represents states by density matrices these objects are superoperators, not unitaries), and override any standard construction based on builtin gate names or nonstd_gate_unitaries. Keys of this dictionary must be string-type gate names – they cannot include state space labels – and they must be static (have zero parameters) because they represent only the ideal behavior of each gate – the cloudnoise operations represent the parameterized noise. To fine-tune how this noise is parameterized, call the CloudNoiseModel constructor directly.

  • max_idle_weight (int, optional) – The maximum-weight for errors on the global idle gate.

  • max_spam_weight (int, optional) – The maximum-weight for state preparation and measurement (SPAM) errors.

  • maxhops (int) – The locality constraint: for a gate, errors (of weight up to the maximum weight for the gate) are allowed to occur on the gate’s target qubits and those reachable by hopping at most maxhops times from a target qubit along nearest-neighbor links (defined by the geometry).

  • extra_weight_1_hops (int, optional) – Additional hops (adds to maxhops) for weight-1 errors. A value > 0 can be useful for allowing just weight-1 errors (of which there are relatively few) to be dispersed farther from a gate’s target qubits. For example, a crosstalk-detecting model might use this.

  • extra_gate_weight (int, optional) – Addtional weight, beyond the number of target qubits (taken as a “base weight” - i.e. weight 2 for a 2Q gate), allowed for gate errors. If this equals 1, for instance, then 1-qubit gates can have up to weight-2 errors and 2-qubit gates can have up to weight-3 errors.

  • simulator (ForwardSimulator or {"auto", "matrix", "map"}) – The circuit simulator used to compute any requested probabilities, e.g. from :method:`probs` or :method:`bulk_probs`. Using “auto” selects “matrix” when there are 2 qubits or less, and otherwise selects “map”.

  • evotype (Evotype or str, optional) – The evolution type of this model, describing how states are represented. The special value “default” is equivalent to specifying the value of pygsti.evotypes.Evotype.default_evotype.

  • gate_type (str, optional) – The Lindblad-error parameterization type used for gate operations. This may be expanded in the future, but currently the gate errors must be of the Lindblad error-generator coefficients type, and this argument specifies what elementary error-generator coefficients are initially allowed (and linked to model parameters), before maximum-weight and locality constraints are imposed. In addition to the usual Lindblad error types, (e.g. “H”, “H+S”) the special values “none” is allowed to indicate that there should be no errors on the gates (useful if you only want errors on the SPAM, for instance).

  • spam_type (str, optional) – Similar to gate_type but for SPAM elements (state preparations and POVMs). This specifies the Lindblad-error parameterization for the state prepearation and POVM.

  • implicit_idle_mode ({'none', 'add_global'}) – The way idel operations are added implicitly within the created model. “nonw” doesn’t add any “extra” idle operations when there is a layer that contains some gates but not gates on all the qubits. “add_global” adds the global idle operation, i.e., the operation for a global idle layer (zero gates - a completely empty layer), to every layer that is simulated, using the global idle as a background idle that always occurs regardless of the operation.

  • errcomp_type ({"gates","errorgens"}) – How errors are composed when creating layer operations in the created model. “gates” means that the errors on multiple gates in a single layer are composed as separate and subsequent processes. Specifically, the layer operation has the form Composed(target,idleErr,cloudErr) where target is a composition of all the ideal gate operations in the layer, idleErr is the global idle error if implicit_idle_mode == ‘add_global’, and cloudErr is the composition (ordered as layer-label) of cloud- noise contributions, i.e. a map that acts as the product of exponentiated error-generator matrices. “errorgens” means that layer operations have the form Composed(target, error) where target is as above and error results from composing (summing) the idle and cloud-noise error generators, i.e. a map that acts as the exponentiated sum of error generators (ordering is irrelevant in this case).

  • independent_gates (bool, optional) – Whether the noise added to a gate when it acts on one set of target qubits is independent of its noise on a different set of target qubits. If False, then all gates with the same name (e.g. “Gx”) will be constrained to having the same noise on the cloud around the target qubits (even though the target qubits and cloud are different). If True, then gate noise operations for different sets of target qubits are independent.

  • independent_spam (bool, optional) – Similar to independent_gates but for state preparation and measurement operations. When False, the noise applied to each set (individual or pair or triple etc.) of qubits must be the same, e.g., if the state preparation is a perfect preparation followed by a single-qubit rotation then this rotation must be by the same angle on all of the qubits.

  • connected_highweight_errors (bool, optional) – An additional constraint regarding high-weight errors. When True, only high weight (weight 2+) elementary error generators whose non-trivial Paulis occupy a connected portion of the qubit graph are allowed. For example, if the qubit graph is a 1D chain of 4 qubits, 1-2-3-4, and weight-2 errors are allowed on a single-qubit gate with target = qubit-2, then weight-2 errors on 1-2 and 2-3 would be allowed, but errors on 1-3 would be forbidden. When False, no constraint is imposed.

  • verbosity (int or VerbosityPrinter, optional) – An integer >= 0 dictating how must output to send to stdout.

Returns

CloudNoiseModel

pygsti.models.modelconstruction._iter_basis_inds(weight)

Iterate over product of weight non-identity Pauli 1Q basis indices

pygsti.models.modelconstruction._pauli_product_matrix(sigma_inds)

Construct the Pauli product matrix from the given sigma_inds

Parameters

sigma_inds (iterable) – A sequence of integers in the range [0,3] corresponding to the I, X, Y, Z Pauli basis matrices.

Returns

numpy.ndarray or scipy.sparse.csr_matrix

pygsti.models.modelconstruction._construct_restricted_weight_pauli_basis(wt, sparse=False)
pygsti.models.modelconstruction._build_weight_maxhops_modelnoise(target_sslbls, weight_maxhops_tuples, lnd_parameterization, connected=True)
pygsti.models.modelconstruction._build_modelnoise_from_args(depolarization_strengths, stochastic_error_probs, lindblad_error_coeffs, depolarization_parameterization, stochastic_parameterization, lindblad_parameterization, allow_nonlocal)
pygsti.models.modelconstruction._nparams_xycnot_cloudnoise_model(num_qubits, geometry='line', max_idle_weight=1, maxhops=0, extra_weight_1_hops=0, extra_gate_weight=0, require_connected=False, independent_1q_gates=True, zz_only=False, bidirectional_cnots=True, verbosity=0)

Compute the number of parameters in a particular CloudNoiseModel.

Returns the number of parameters in the CloudNoiseModel containing X(pi/2), Y(pi/2) and CNOT gates using the specified arguments without actually constructing the model (useful for considering parameter-count scaling).

Parameters
  • num_qubits (int) – The total number of qubits.

  • geometry ({"line","ring","grid","torus"} or QubitGraph) – The type of connectivity among the qubits, specifying a graph used to define neighbor relationships. Alternatively, a QubitGraph object may be passed directly.

  • max_idle_weight (int, optional) – The maximum-weight for errors on the global idle gate.

  • maxhops (int) – The locality constraint: for a gate, errors (of weight up to the maximum weight for the gate) are allowed to occur on the gate’s target qubits and those reachable by hopping at most maxhops times from a target qubit along nearest-neighbor links (defined by the geometry).

  • extra_weight_1_hops (int, optional) – Additional hops (adds to maxhops) for weight-1 errors. A value > 0 can be useful for allowing just weight-1 errors (of which there are relatively few) to be dispersed farther from a gate’s target qubits. For example, a crosstalk-detecting model might use this.

  • extra_gate_weight (int, optional) – Addtional weight, beyond the number of target qubits (taken as a “base weight” - i.e. weight 2 for a 2Q gate), allowed for gate errors. If this equals 1, for instance, then 1-qubit gates can have up to weight-2 errors and 2-qubit gates can have up to weight-3 errors.

  • require_connected (bool, optional) – If True, then high-weight errors only occur on connected (via geometry) qubits. For example in a line of qubits there would not be weight-2 errors on qubits 1 and 3.

  • independent_1q_gates (bool, optional) – If True, 1Q gates on different qubits have separate (distinct) parameters. If False, the 1Q gates of each type (e.g. an pi/2 X gate) for different qubits share the same set of parameters.

  • zz_only (bool, optional) – If True, the only high-weight errors allowed are of “Z^n” type.

  • bidirectional_cnots (bool) – Whether CNOT gates can be performed in either direction (and each direction should be treated as an indepedent gate)

  • verbosity (int, optional) – An integer >= 0 dictating how much output to send to stdout.

Returns

int