jupyter_notebooks/Tutorials/objects/ModelNoise.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Adding noise to models\n",
    "This tutorial covers how various kinds of noise (errors) can be added to a model's operations.  The procedure for specifying the noise is similar for the different types of models, though the types of noise allowed and how this noise is incorporated into the model's structure differ as we point out below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pygsti\n",
    "from pygsti.models import modelconstruction as mc\n",
    "from pygsti.models import modelnoise as mn"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Standard noise types\n",
    "There are three standard types of noise that can be added to operations in pyGSTi: depolarization, stochastic, and Lindbladian.  The first two types are common in the literature, while the third, \"Lindbladian\", needs a bit more explanation.  Many types of gate errors can be represented in terms of an *error generator*.  If $G$ is a noisy gate (a CPTP map) and $G_0$ is it's ideal counterpart, then if we write $G = e^{\\Lambda}G_0$ then $\\Lambda$ is called the gate's *error generator*.  A `LindbladErrorgen` object, exponentiated using a `ExpErrorgenOp` object represent this $e^{\\Lambda}$ in pyGSTi.  If we write $\\Lambda$ as a sum of terms, $\\Lambda = \\sum_i \\alpha_i F_i$ then, when the $F_i$ are specific generators for well-known errors (e.g. rotations or stochastic errors), the $\\alpha_i$ can roughly be interpreted as the error *rates* corresponding to the well-known error types.  PyGSTi has three specific generator types (where $P_i$ is a Pauli operator or tensor product of Pauli operators):\n",
    "\n",
    "- **Hamiltonian**: $F_i = H_i$ where $H_i : \\rho \\rightarrow -i[P_i,\\rho]$\n",
    "- **Stochastic**: $F_i = S_i$ where $S_i : \\rho \\rightarrow P_i \\rho P_i - \\rho$\n",
    "- **Affine**: $F_i = A_i$ where $A_i : \\rho \\rightarrow \\mathrm{Tr}(\\rho_{target})P_i \\otimes \\rho_{non-target}$\n",
    "\n",
    "See our recent paper on [the taxonomy of small errors](https://arxiv.org/abs/2103.01928v1) for a more theoretical foundation of error generators.\n",
    "\n",
    "Many of the model construction functions take arguments that allow users to add these standard noise types conveniently when a model is created.  Each argument expects a dictionary, where the keys are gate names and the values specify the corresponding noise. The values are different types for each argument:\n",
    "\n",
    "- `depolarization_strengths`: Values are floats, which corresponding to strengths of a `DepolarizeOp`\n",
    "- `stochastic_error_probs`: Values are lists of length $4^{N_{qubits} - 1}$, which correspond to coefficients of a stochastic Pauli channel in a `StochasticNoiseOp`. Order of the rates is lexographical, and can be checked by looking at the elements of a `\"pp\"` Basis object.\n",
    "- `lindblad_error_coeffs`: Values are a dict where the key has the form `(<type>, <basis_elements>)` and the values are the $\\alpha_i$ coefficients in the sum of Lindblad terms, which are then exponentiated to give the final noise. The type includes:\n",
    "  - `'H'` for Hamiltonian errors\n",
    "  - `'S'` for Pauli-stochastic and Pauli-correlation errors (S and C in the error generator taxonomy)\n",
    "  - `'A'` for affine errors\n",
    "  \n",
    "  and strings of `I`, `X`, `Y`, and `Z` can be used to label a Pauli basis element. \n",
    "\n",
    "### Crosstalk free (local noise) models\n",
    "We'll start with an example of placing noise on a crosstalk free model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "pspec = pygsti.processors.QubitProcessorSpec(2, ['Gxpi2', 'Gypi2', 'Gcnot'], geometry='line')\n",
    "\n",
    "mdl_locnoise = pygsti.models.create_crosstalk_free_model(\n",
    "    pspec,\n",
    "    depolarization_strengths={'Gxpi2': 0.1},  # Depolarizing noise on X\n",
    "    stochastic_error_probs={'Gypi2': [0.04, 0.05, 0.02]}, # Stochastic Pauli noise on Y\n",
    "    lindblad_error_coeffs={'Gcnot': {('H','ZZ'): 0.15} } # Hamiltonian ZZ error on CNOT\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's print out the gates to see the corresponding construction\n",
    "These should all be ComposedOps with the following format:\n",
    " - Op 1: The ideal gate, parameterized by the ideal_gate_type kwarg\n",
    " - Op 2: The noise, as parameterized by whichever noise specification was provided"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Gxpi2\n",
      "Composed operation of 2 factors:\n",
      "Factor 0:\n",
      "StaticStandardOp with name Gxpi2 and evotype densitymx\n",
      "Factor 1:\n",
      "Depolarize noise operation map with dim = 4, num params = 1\n",
      "Strength: [0.1]\n",
      "\n",
      "Gypi2\n",
      "Composed operation of 2 factors:\n",
      "Factor 0:\n",
      "StaticStandardOp with name Gypi2 and evotype densitymx\n",
      "Factor 1:\n",
      "Stochastic noise operation map with state space = QubitSpace((0,)), num params = 3\n",
      "Rates: [0.04 0.05 0.02]\n",
      "\n",
      "Gcnot\n",
      "Composed operation of 2 factors:\n",
      "Factor 0:\n",
      "StaticStandardOp with name Gcnot and evotype densitymx\n",
      "Factor 1:\n",
      "Exponentiated operation map with dim = 16, num params = 1\n",
      "\n"
     ]
    }
   ],
   "source": [
    "for gate_name, gate in mdl_locnoise.operation_blks['gates'].items():\n",
    "    print(gate_name)\n",
    "    print(gate)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can also be seen via the models' `print_modelmembers()` method (see the \"`operation_blks|gates`\" category):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Modelmember category: prep_blks|layers\n",
      "  rho0: ComputationalBasisState (0) : (contents not available)\n",
      "\n",
      "Modelmember category: povm_blks|layers\n",
      "  Mdefault: ComputationalBasisPOVM (1) : (contents not available)\n",
      "\n",
      "Modelmember category: operation_blks|gates\n",
      "  Gxpi2: ComposedOp (4) : composed of 2 factors\n",
      "    StaticStandardOp (2) : Gxpi2 gate\n",
      "    DepolarizeOp (3) : strength: [0.1]\n",
      "  Gypi2: ComposedOp (7) : composed of 2 factors\n",
      "    StaticStandardOp (5) : Gypi2 gate\n",
      "    StochasticNoiseOp (6) : rates: [0.04 0.05 0.02]\n",
      "  Gcnot: ComposedOp (11) : composed of 2 factors\n",
      "    StaticStandardOp (8) : Gcnot gate\n",
      "    ExpErrorgenOp (10) : exponentiates\n",
      "      LindbladErrorgen (9) : H(ZZ:0,1): 0.15\n",
      "\n",
      "Modelmember category: operation_blks|layers\n",
      "  Gxpi2:0: EmbeddedOp (12) : embeds (0,) into QubitSpace((0, 1))\n",
      "    ComposedOp (4) : --link--^\n",
      "      StaticStandardOp (2) : --link--^\n",
      "      DepolarizeOp (3) : --link--^\n",
      "  Gxpi2:1: EmbeddedOp (13) : embeds (1,) into QubitSpace((0, 1))\n",
      "    ComposedOp (4) : --link--^\n",
      "      StaticStandardOp (2) : --link--^\n",
      "      DepolarizeOp (3) : --link--^\n",
      "  Gypi2:0: EmbeddedOp (14) : embeds (0,) into QubitSpace((0, 1))\n",
      "    ComposedOp (7) : --link--^\n",
      "      StaticStandardOp (5) : --link--^\n",
      "      StochasticNoiseOp (6) : --link--^\n",
      "  Gypi2:1: EmbeddedOp (15) : embeds (1,) into QubitSpace((0, 1))\n",
      "    ComposedOp (7) : --link--^\n",
      "      StaticStandardOp (5) : --link--^\n",
      "      StochasticNoiseOp (6) : --link--^\n",
      "  Gcnot:0:1: ComposedOp (11) : --link--^\n",
      "    StaticStandardOp (8) : --link--^\n",
      "    ExpErrorgenOp (10) : --link--^\n",
      "      LindbladErrorgen (9) : --link--^\n",
      "  Gcnot:1:0: EmbeddedOp (16) : embeds (1, 0) into QubitSpace((0, 1))\n",
      "    ComposedOp (11) : --link--^\n",
      "      StaticStandardOp (8) : --link--^\n",
      "      ExpErrorgenOp (10) : --link--^\n",
      "        LindbladErrorgen (9) : --link--^\n",
      "\n",
      "Modelmember category: instrument_blks|layers\n",
      "\n",
      "Modelmember category: factories|gates\n",
      "\n",
      "Modelmember category: factories|layers\n",
      "\n"
     ]
    }
   ],
   "source": [
    "mdl_locnoise.print_modelmembers()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Overriding gate noise with layer noise\n",
    "By specifying a *primitive layer label* instead of a gate name as a key, we can modify the noise on a gate when it's applied to a particular qubit.  Note that this *doesn't* require that we set `independent_gates=True` in the construction function, as this argument refers to the ideal gates.  Noise can be separately given to individual primitive layer operation regardless of the values of `independent_gates`.\n",
    "\n",
    "Here's an example where we override the noise on the `Gxpi2` gate.  Notice how the `operation_blks|gates` category has both a `Gxpi2` and `Gxpi2:0` keys."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Modelmember category: prep_blks|layers\n",
      "  rho0: ComputationalBasisState (0) : (contents not available)\n",
      "\n",
      "Modelmember category: povm_blks|layers\n",
      "  Mdefault: ComputationalBasisPOVM (1) : (contents not available)\n",
      "\n",
      "Modelmember category: operation_blks|gates\n",
      "  Gxpi2: ComposedOp (4) : composed of 2 factors\n",
      "    StaticStandardOp (2) : Gxpi2 gate\n",
      "    StochasticNoiseOp (3) : rates: [0.04 0.05 0.02]\n",
      "  Gxpi2:0: ComposedOp (6) : composed of 2 factors\n",
      "    StaticStandardOp (2) : --link--^\n",
      "    StochasticNoiseOp (5) : rates: [0.08 0.1  0.06]\n",
      "  Gypi2: StaticStandardOp (7) : Gypi2 gate\n",
      "  Gcnot: StaticStandardOp (8) : Gcnot gate\n",
      "\n",
      "Modelmember category: operation_blks|layers\n",
      "  Gxpi2:0: EmbeddedOp (9) : embeds (0,) into QubitSpace((0, 1))\n",
      "    ComposedOp (6) : --link--^\n",
      "      StaticStandardOp (2) : --link--^\n",
      "      StochasticNoiseOp (5) : --link--^\n",
      "  Gxpi2:1: EmbeddedOp (10) : embeds (1,) into QubitSpace((0, 1))\n",
      "    ComposedOp (4) : --link--^\n",
      "      StaticStandardOp (2) : --link--^\n",
      "      StochasticNoiseOp (3) : --link--^\n",
      "  Gypi2:0: EmbeddedOp (11) : embeds (0,) into QubitSpace((0, 1))\n",
      "    StaticStandardOp (7) : --link--^\n",
      "  Gypi2:1: EmbeddedOp (12) : embeds (1,) into QubitSpace((0, 1))\n",
      "    StaticStandardOp (7) : --link--^\n",
      "  Gcnot:0:1: StaticStandardOp (8) : --link--^\n",
      "  Gcnot:1:0: EmbeddedOp (13) : embeds (1, 0) into QubitSpace((0, 1))\n",
      "    StaticStandardOp (8) : --link--^\n",
      "\n",
      "Modelmember category: instrument_blks|layers\n",
      "\n",
      "Modelmember category: factories|gates\n",
      "\n",
      "Modelmember category: factories|layers\n",
      "\n"
     ]
    }
   ],
   "source": [
    "mdl_locnoise = pygsti.models.create_crosstalk_free_model(pspec,\n",
    "    stochastic_error_probs={\n",
    "        'Gxpi2': [0.04, 0.05, 0.02], # Stochastic Pauli noise on X\n",
    "        ('Gxpi2', 0): [0.08, 0.1, 0.06] # Override rates for X on one of the qubits\n",
    "    }\n",
    ")\n",
    "mdl_locnoise.print_modelmembers()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Explicit models\n",
    "Specifying noise in explicit models is similar, but since explicit models only hold circuit *layer* operations, we must always specify a layer.  For example, noise cannot be attributed to just the $X(\\pi/2)$ gate, it needs to be attributed to the gate *on* a particular qubit.  Note also that primitive layer labels can be specified as either a tuple, e.g. `(\"Gxpi2\", 0)`, or by a more compact string, e.g. `\"Gxpi2:0\"`.  Similarly, Lindbladian error rates can be identified by `(type, basis_labels)` tuples or a compact string, e.g., `('H','ZZ')` or `'HZZ'`.\n",
    "\n",
    "Here is an example of adding noise to an explicit model using both tuple and compact string formats:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "pspec = pygsti.processors.QubitProcessorSpec(2, ['Gxpi2', 'Gypi2', 'Gcnot'], geometry='line')\n",
    "\n",
    "explicit_model = mc.create_explicit_model(pspec,\n",
    "                                          depolarization_strengths={'Gxpi2:0': 0.1,},\n",
    "                                          stochastic_error_probs={('Gypi2', 0): [.01]*15},\n",
    "                                          lindblad_error_coeffs={('Gcnot', 0, 1): {'HZZ': 0.07},\n",
    "                                                                 'Gcnot:1:0': {('H','IX'): 0.07} },\n",
    "                                         )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Printing the model's members reveals the simpler internal structure of an `ExplicitOpModel` - there's only a single `operations` category which holds layer operations.  These operations are `ComposedOp` operators that compose the ideal gate (`StaticUnitaryOps` in this case, since we didn't specify `ideal_gate_type`) with the specified noise operations.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "explicit_model.print_modelmembers()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Noise on SPAM operators\n",
    "State preparation and measurement (SPAM) operators always act on all $N$ qubits.  To add noise to the $N$-qubit state preparation, or measurement operations, you can specify `'prep'`, and `'povm'` as keys in the error dictionaries, just like any other layer label.   The below cell placed depolarization noise on both the state preparation and measurement of a model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mdl_locnoise = pygsti.models.create_crosstalk_free_model(pspec,\n",
    "                                                         depolarization_strengths={\n",
    "                                                             'Gxpi2': 0.1,\n",
    "                                                             'prep': 0.01,\n",
    "                                                             'povm': 0.01}\n",
    "                                                        )\n",
    "\n",
    "explicit_model = mc.create_explicit_model(pspec,\n",
    "                                          depolarization_strengths={\n",
    "                                                             'Gxpi2:0': 0.1,\n",
    "                                                             'Gxpi2:1': 0.1,\n",
    "                                                             'prep': 0.01,\n",
    "                                                             'povm': 0.01}\n",
    "                                                        )\n",
    "\n",
    "mdl_locnoise.print_modelmembers()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The printout above shows that the SPAM operators are now the ideal operators composed with depolarization noise.  It also reveals that the specified depolarization strength is applied as a parallel 1-qubit depolarization to each of the qubits."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Nonlocal noise\n",
    "So far, all the noise we've specified has been directed at the *target* qubits of the relevant operation.  For instance, when a depolarization strength is specified for a 1-qubit gates, it applies the given depolarization to gate's single target qubit.  When depolarization is applied to a 2-qubit gate, 2-qubit depolarization is applied to the target qubits.  When Lindblad error rates are given for a 1-qubit gate, they are indexed by single Pauli elements, e.g. `('H','X')`, whereas for a 2-qubit gate they are indexed by 2-qubit Paulis, e.g. `('H','XX')`.\n",
    "\n",
    "In a crosstalk free model, noise can *only* be specified on the target qubits - noise on non-target qubits is simply not allowed.  But for an explicit model, which holds solely $N$-qubit layer operations, noise for a gate (layer) can be applied to *any* of the qubits.  To specify noise that is not on the target qubits of a gate,\n",
    "\n",
    "- as the values of `depolarization_strengths` or `stochastic_error_probs`, pass a dictionary that maps qubit labels to noise values.  The qubit labels (keys) designate which qubits the noise acts upon.\n",
    "- add a colon followed by comma-separated qubit labels to the basis labels in a Lindblad error term.\n",
    "\n",
    "Here's an example of how to set non-local errors on the gates in an explicit model:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#Nonlocal explicit model\n",
    "explicit_model = mc.create_explicit_model(\n",
    "    pspec,\n",
    "    depolarization_strengths={('Gxpi2', 0): {(0,1): 0.2}},  # 2-qubit depolarization\n",
    "    lindblad_error_coeffs={('Gypi2', 0): {('H','ZZ:0,1'): 0.07,  # Hamiltonian ZZ on qubits 0 and 1\n",
    "                                          ('S', 'X:1'): 0.04}  # Stochastic X on qubit 1 (not a target qubit)\n",
    "                          },\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The errors can be verified, as usual, by printing the model's member structure:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "explicit_model.print_modelmembers()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Cloud-crosstalk (cloud noise) models\n",
    "Cloud-crosstalk models can accept the most general noise operations: they can be given local, per-gate noise as for a local noise model, and non-local noise on specific layers like for an explicit model.  Furthermore, non-local noise can be specified for *gates* (rather than layers) in a meaningful way by using **stencils**, as we demonstrate below.\n",
    "\n",
    "Let's start with an example using error specifications we've already seen:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cloudmodel = pygsti.models.create_cloud_crosstalk_model(\n",
    "    pspec,\n",
    "    stochastic_error_probs={'Gypi2': (0.03, 0.01, 0.03)},  # local noise on a gate\n",
    "    lindblad_error_coeffs={\n",
    "        ('Gxpi2',0): { ('H','X'): 0.01, ('S','XY:0,1'): 0.01},  # local and nonlocal noise on a layer \n",
    "        ('Gcnot',0,1): { ('H','ZZ'): 0.02, ('S','XX'): 0.02 },  # local noise on a layer\n",
    "    }\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The effect of these errors is entirely in the `operation_blks|cloudnoise` category.  As described in the tutorial on cloud noise models, *all* of the non-idealities in a `CloudNoiseModel` are contained in this category. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cloudmodel.print_modelmembers()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Stencils\n",
    "When there are many qubits, it can be tedious to specify non-local noise in the way shown above since you need to specify the qubits upon which the noise acts differently for each primitive layer operation.  For example, if we have a chain of 10 qubits and want an $X(\\pi/2)$ gate to depolarize the qubit to the left and right of the gate's target qubit, we would need to specify nonlocal noise on qubits 1 and 3 for $X(\\pi/2)$ on qubit 2, nonlocal noise on qubits 2 and 4 for $X(\\pi/2)$ on qubit 3, etc.\n",
    "\n",
    "*Stencils* have been developed to make this process easier.  `ProcessorSpec` objects can contain a `QubitGraph` giving the geometry of the processor (or, more accurately, of an API of the processor).  This graph can include tags that associate a *direction name* with each of its edges.  For example, the built-in (and default) linear chain (`\"line\"`) graph has two directions, \"left\" and \"right\".  When specifying non-local noise, instead of specifying absolute qubit names, you can specify *relative qubit labels*.  \n",
    "\n",
    "\n",
    "The use of relative qubit labels - or *stencil labels* as they're called in pyGSTi - causes noise to be placed on qubits relative to a gate's target qubits.  The format of a stencil label is:\n",
    "\n",
    "`\"@<target_qubit_index> + <direction> + <direction> ...\"`\n",
    "\n",
    "where `<target_qubit_index>` is an integer between 0 and the gate's number of target qubits minus 1 (e.g. 0 and 1 for a 2-qubit gate), and `<direction>` is an optional direction name to move along.  Any direction names that are used must be present in the processor specification's graph (its `geometry`).\n",
    "\n",
    "Here's a simple example that uses stencils on a processor of 4-qubits in a chain:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pspec_4Qchain = pygsti.processors.QubitProcessorSpec(4, ['Gxpi', 'Gcnot'], geometry='line')\n",
    "cloudmodel_stencils = pygsti.models.create_cloud_crosstalk_model(\n",
    "    pspec_4Qchain,\n",
    "    depolarization_strengths = {\n",
    "        'Gxpi': {('@0+left',): 0.01,   # apply depolarization noise to the qubit to the left of the target\n",
    "                 ('@0+right',): 0.01}  # apply depolarization noise to the qubit to the right of the target\n",
    "    },\n",
    "    stochastic_error_probs = {\n",
    "        'Gxpi': {('@0',) : (0.03, 0.05, 0.05)}  # local noise, so could omit use of stencil here and\n",
    "        #'Gxpi': (0.03, 0.05, 0.05)             # <-- use this line instead\n",
    "    }\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we place Pauli stochastic noise on the `Gxpi` gate and depolarizing noise on the qubits to either side.  The stencil has the effect of describing noise for each `('Gxpi',#)` layer based on the contents of the `'Gxpi'` noise specifications in a way that is dependent on the target qubit (`#`).  To be pedantic,\n",
    "\n",
    "- for `('Gxpi',0)`, `@0` evaluates to `0`, `@0+left` evaluates to NULL and `@0+right` evaluates to `1`.\n",
    "- for `('Gxpi',1)`, `@0` evaluates to `1`, `@0+left` evaluates to `0` and `@0+right` evaluates to `2`.\n",
    "- for `('Gxpi',2)`, `@0` evaluates to `2`, `@0+left` evaluates to `1` and `@0+right` evaluates to `3`.\n",
    "- for `('Gxpi',3)`, `@0` evaluates to `3`, `@0+left` evaluates to `2` and `@0+right` evaluates to NULL.\n",
    "\n",
    "When a NULL is encountered in stencil evaluation, no noise is added and evaluation continues.  This can be seen by reading through the model member structure (thought it's quite long!):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cloudmodel_stencils.print_modelmembers()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here's another examples of using stencils to construct in a 4-qubit cloud noise model:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cloudmodel_stencils2 = pygsti.models.create_cloud_crosstalk_model(pspec_4Qchain,\n",
    "    lindblad_error_coeffs={\n",
    "            'Gxpi': { ('H','X'): 0.01, ('S','X:@0+left'): 0.01, ('S','XX:@0,@0+right'): 0.02},\n",
    "            'Gcnot': { ('H','ZZ'): 0.02, ('S','XX:@1+right,@0+left'): 0.02 },\n",
    "        })"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Basis-element notation can also be abbreviated for convenience (this builds the same model a above):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cloudmodel_stencils2_abbrev = pygsti.models.create_cloud_crosstalk_model(pspec_4Qchain,\n",
    "    lindblad_error_coeffs={\n",
    "        'Gxpi': { 'HX': 0.01, 'SX:@0+left': 0.01, ('SXX:@0,@0+right'): 0.02},\n",
    "        'Gcnot': { 'HZZ': 0.02, 'SXX:@1+right,@0+left': 0.02 },\n",
    "    })"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And here's one more final example that combines several types of errors:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cloudmodel_stencils3 = pygsti.models.create_cloud_crosstalk_model(\n",
    "    pspec_4Qchain,\n",
    "    depolarization_strengths = {'Gxpi': 0.05},\n",
    "    lindblad_error_coeffs = {\n",
    "        'Gxpi': {'HX:@0': 0.1},\n",
    "        'Gxpi:2': {'HY:2': 0.2},\n",
    "        'Gcnot': {'HZZ:@0+left,@0': 0.02, 'HZZ:@1,@1+right': 0.02}\n",
    "    })"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Noise parameterizations\n",
    "Along with the amount and type of noise added to a model, you can also specify how it is represented as pyGSTi operator objects. This is significant when the model will be tweaked or optimized later on, in which case the paramterization determines how the noise operations are allowed to be tweaked (changed).  Parameterization types are especially important in cloud noise models where this constitutes the entirety of how the model is parameterized.\n",
    "\n",
    "The parameterizations for the three standard noise types are given by specifying the `depolarization_parameterization`, `stochastic_parameterization`, and `lindblad_parameterization` arguments.  The options for these are as follows:\n",
    "\n",
    "- `depolarization_parameterization`:\n",
    "    - `\"depolarize\"` (default) builds `DepolarizeOp` objects with the strength given in `depolarization_strengths`.  A `DepolarizeOp` object contains a single parameter for the depolarization rate.\n",
    "    - `\"stochastic\"` builds `StochasticNoiseOp` objects, which have separate parameters for each Pauli stochastic error rate, all of which are initially equal.  The depolarization strength is thus split evenly among the individual Pauli stochastic channels of a `StochasticNoiseOp`.\n",
    "    - `\"lindblad\"` builds exponentiated `LindbladErrorgen` object containing Pauli stochastic terms.  The error generator object is built with `parameterization=\"D\"` (an argument of `LindbladErrorgen.__init__`).  We will refer to this as the *mode* of the `LindbladErrorgen`.  `\"D\"` (depolarization) mode means it that has a single parameter is squared to give the depolarization rate.\n",
    "\n",
    "- `stochastic_parameterization`:\n",
    "    - `\"stochastic\"` (default) builds `StochasticNoiseOp` objects which have separate parameters for each Pauli stochastic error rate.  Elements of `stochastic_error_probs` are used as coefficients in a linear combination of individual Pauli stochastic channels.\n",
    "    - `\"lindblad\"` builds exponentiated `LindbladErrorgen` object containing Pauli stochastic terms.  The error generator object is built in `\"CPTP\"` mode, which means it that there is one parameter per stochastic rate (equal to the square root of the rate so it is constrained to be positive).\n",
    "    \n",
    "- `lindblad_parameterization`:  Lindblad errors are always represented by exponentiated `LindbladErrorgen` objects.  A `LindbladErrorgen` can have several different internal parameterizations, or *modes* as we refer to them here to avoid confusion with the noise or model parameterization.  The mode is by definition the value of the `parameterization` argument supplied to `LindbladErrorgen.__init__`, which influences what types of elementary error generators (e.g. 'H', 'S', 'C' and 'A') are allowed and whether the Pauli stochastic error rates are constrained to be positive. The value of `lindblad_parameterization` can be set to any valid mode value (see documentation for more details).  Usually the default values of `\"auto\"` is fine. \n",
    "\n",
    "The examples below show how the number of parameters in a cloud noise model can vary based on the way in which noise is parameterized.  For these examples, we'll go back to the 2-qubit processor specification for simplicity."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cloudmodel = pygsti.models.create_cloud_crosstalk_model(\n",
    "    pspec,\n",
    "    depolarization_strengths={'Gxpi2': 0.1},\n",
    "    depolarization_parameterization='depolarize',\n",
    "    stochastic_error_probs={'Gypi2': (0.03, 0.01, 0.03)},  # local noise on a gate\n",
    "    stochastic_parameterization='stochastic'\n",
    ")\n",
    "print(cloudmodel.num_params, \"params, 1 depolarization rate, 3 stochastic rates\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By setting the `independent_gates` argument to `True` (`False` is the default), the noise is applied to each set of target qubits independently and so have separate parameters. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cloudmodel = pygsti.models.create_cloud_crosstalk_model(\n",
    "    pspec,\n",
    "    depolarization_strengths={'Gxpi2': 0.1},\n",
    "    depolarization_parameterization='depolarize',\n",
    "    stochastic_error_probs={'Gypi2': (0.03, 0.01, 0.03)},  # local noise on a gate\n",
    "    stochastic_parameterization='stochastic',\n",
    "    independent_gates=True\n",
    ")\n",
    "print(cloudmodel.num_params, \"params, 2 depolarization rates, 6 stochastic rates (because there are 2 qubits)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Changing the depolarization parameterization to `\"stochastic\"` makes the `Gxpi2` gate take 3 parameters.  Changing the stochastic parameterization to `\"lindblad\"` doesn't change the number of parameters (still 3) but does change the type of gate object used to model the noise:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cloudmodel = pygsti.models.create_cloud_crosstalk_model(\n",
    "    pspec,\n",
    "    depolarization_strengths={'Gxpi2': 0.1},\n",
    "    depolarization_parameterization='stochastic',\n",
    "    stochastic_error_probs={'Gypi2': (0.03, 0.01, 0.03)},  # local noise on a gate\n",
    "    stochastic_parameterization='lindblad'\n",
    ")\n",
    "\n",
    "print(cloudmodel.num_params, \"params, 3 initially equal from depolarization, 3 stochastic error-generator rates\")\n",
    "\n",
    "print(\"\\nGyp2 cloud noise is:\")\n",
    "print(cloudmodel.operation_blks['cloudnoise'][('Gypi2',0)].embedded_op)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Changing the depolarization parameterization to `\"lindblad\"` makes the `Gxpi2` gate go back to taking only 1 parameter since its noise is represented by a `LindbladErrorgen` with mode `\"D\"`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cloudmodel = pygsti.models.create_cloud_crosstalk_model(\n",
    "    pspec,\n",
    "    depolarization_strengths={'Gxpi2': 0.1},\n",
    "    depolarization_parameterization='lindblad',\n",
    "    stochastic_error_probs={'Gypi2': (0.03, 0.01, 0.03)},  # local noise on a gate\n",
    "    stochastic_parameterization='lindblad'\n",
    ")\n",
    "\n",
    "print(cloudmodel.num_params, \"params, 1 from lindblad D-mode error-generator, 3 stochastic error-generator rates\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By changing the mode of Lindblad error coefficients we can:\n",
    "1. dictate what types of errors are allowed in the error generator (and could be possibly added later on)\n",
    "2. alter whether the Pauli stochastic error rates are constrained to be postive or not"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# H+S => H and S type elementary error generators are allowed; S-type coefficients must be positive\n",
    "cloudmodel = pygsti.models.create_cloud_crosstalk_model(\n",
    "    pspec,\n",
    "    lindblad_error_coeffs={\n",
    "        'Gcnot': { ('H','ZZ'): 0.02, ('S','XX'): 0.02 }\n",
    "    },\n",
    "    lindblad_parameterization='H+S'\n",
    ")\n",
    "print(cloudmodel.num_params, \"params\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# H+s => H and S type elementary error generators are allowed; S-type coefficients can be postive or negative (no constraint)\n",
    "cloudmodel = pygsti.models.create_cloud_crosstalk_model(\n",
    "    pspec,\n",
    "    lindblad_error_coeffs={\n",
    "        'Gcnot': { ('H','ZZ'): 0.02, ('S','XX'): 0.02 }\n",
    "    },\n",
    "    lindblad_parameterization='H+s'\n",
    ")\n",
    "print(cloudmodel.num_params, \"params\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# H => Only H-type elementary error generators are allowed\n",
    "cloudmodel = pygsti.models.create_cloud_crosstalk_model(\n",
    "    pspec,\n",
    "    lindblad_error_coeffs={\n",
    "        'Gcnot': { ('H','ZZ'): 0.02 }\n",
    "    },\n",
    "    lindblad_parameterization='H'\n",
    ")\n",
    "print(cloudmodel.num_params, \"params\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# CPTP => All elementary error-generator types are allowed; Pauli (diagonal) S-type coefficients must be positive.\n",
    "# Note that for CPTP types, S-type coefficients are indexed by 2 Paulis instead of 1.\n",
    "cloudmodel = pygsti.models.create_cloud_crosstalk_model(\n",
    "    pspec,\n",
    "    lindblad_error_coeffs={\n",
    "        'Gcnot': { ('H','ZZ'): 0.02, \n",
    "                   ('S', 'XX', 'XX'): 0.05, ('S', 'XY', 'XY'): 0.05, ('S', 'YX', 'YX'): 0.05,\n",
    "                   ('S', 'XX', 'XY'): 0.01 + 0.01j, ('S', 'XY', 'XX'): 0.01 - 0.01j,\n",
    "                   ('S', 'XX', 'YX'): 0.01 + 0.0j, ('S', 'YX', 'XX'): 0.01 - 0.0j,\n",
    "                   ('S', 'XY', 'YX'): 0.01 - 0.005j, ('S', 'YX', 'XY'): 0.01 + 0.005j}\n",
    "    },\n",
    "    lindblad_parameterization='CPTP'\n",
    ")\n",
    "print(cloudmodel.num_params, \"params because 1 H-type and a Hermitian 3x3 block of S-type coefficients\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}