{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# State space labelling in pyGSTi\n",
    "\n",
    "Instances of `pygsti.objects.StateSpaceLabels` describe the structure of a model's state space and associate labels with the parts of that structure.  This is particularly useful when dealing with multiple qubits or a qubit and its environment, as it can be useful to reference subspaces or subsystems of the entire quantum state space.\n",
    "\n",
    "In general, a state space is the direct sum of one or more *tensor product blocks*, each of which is the tensor product of one or more *factors*: \n",
    "\n",
    "$$ \\mbox{State space} = (\\mathcal{H}_1^A \\otimes \\mathcal{H}_2^A \\otimes \\cdots) \\oplus (\\mathcal{H}_1^B \\otimes \\mathcal{H}_2^B \\otimes \\cdots) \\oplus \\cdots$$\n",
    "\n",
    "In the above expression the tensor product blocks are in parenthesis and labelled by $A$, $B$, etc., and the $\\mathcal{H}_i^X$ are the factors.  We can initialize a `StateSpaceLabels` object using a list of tuples containing labels and dimensions which mirror this structure, i.e.\n",
    "\n",
    "~~~\n",
    "StateSpaceLabels( [(H1A_label, H2A_label, ...), ((H1B_label, H2B_label, ...), ... ],\n",
    "                  [(H1A_dim  , H2A_dim, ...),   ((H1B_dim  , H2B_dim, ...), ... ])\n",
    "~~~\n",
    "where `_label` variables are either strings or integers (it can be convenient to label qubits, for instance, by integers) and `_dim` variables are always integers.  Here are some examples:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pygsti\n",
    "from pygsti.objects import StateSpaceLabels\n",
    "\n",
    "lbls = StateSpaceLabels([('H0','H1')], [(2,3)])\n",
    "print(lbls) # label(dim) notation, '*' means 'otimes', '+' means 'oplus'\n",
    "\n",
    "lbls2 = StateSpaceLabels(('H0','H1'), (2,3)) # same as above - a *single* tensor product block\n",
    "print(lbls2)\n",
    "\n",
    "lbls3 = StateSpaceLabels([('H0',), ('H1',)], [(2,),(3,)]) # direct sum\n",
    "print(lbls3)\n",
    "\n",
    "lbls4 = StateSpaceLabels([('H1a','H2a'), ('H1b','H2b')], [(2,1),(3,4)])\n",
    "print(lbls4)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since we're often dealing with qubits (dimension = 2 factors), the labels beginning with 'Q' or that are integers default to dimension 2.  Similarly, labels beginning with 'L' default dimension 1 (an additional \"Level\").  If all the labels in the first argument passed to the `StateSpaceLabels` constructor have defaults, then the **second argument (the dimensions) may be omitted**.  For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "lbls5 = StateSpaceLabels(['Q0','Q1']) # 2 qubits\n",
    "print(lbls5)\n",
    "\n",
    "lbls6 = StateSpaceLabels(list(range(3))) # 3 qubits\n",
    "print(lbls6)\n",
    "\n",
    "lbls7 = StateSpaceLabels([('Q0','Q1'),('Leakage',)])\n",
    "print(lbls7)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The raw data within a `StateSpaceLabels` object is stored in the `.labels` and `.labeldims` members (but be careful, `labeldims` is a *dictionary*):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "lbls7.labels"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "lbls7.labeldims"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can access the total dimension of the state space using the `.dim` member ($d^2$ if the density-matrix dimension is $d$, i.e. when density matrices are $d \\times d$), and the tensor-product block dimensions $k_i^2$ (there is a kite structure of are $k_i\\times k_i$ nonzero blocks that form  the the $d \\times d$ density matrix, so $\\sum_i k_i = d$) via the `.tpb_dims` property.  You can also access the per-label dimension via the `.labeldims` dictionary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Total dim = \",lbls7.dim)\n",
    "#print(\"Separately: \",lbls7.dim, lbls7.dim.blockDims, lbls7.dim.opDim, lbls7.dim.embedDim)\n",
    "print(\"Dimensions of tensor product blocks = \", lbls7.tpb_dims)\n",
    "print(\"Dimension of the space associated with each label: \", lbls7.labeldims)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are also few convenience functions that make it easier to access the raw data: \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Number of tensor product blocks = \",lbls7.num_tensor_prod_blocks())\n",
    "print(\"The labels in the 0th tensor product block are: \",lbls7.tensor_product_block_labels(0))\n",
    "print(\"The dimensions corresponding to those labels are: \",lbls7.tensor_product_block_dims(0))\n",
    "print(\"The 'Q0' labels exists in the tensor product block w/index=\",lbls7.tpb_index['Q0'])\n",
    "print(\"The product of the dimensions associated with 'Q0' and 'Leakage' = \",lbls7.product_dim( ('Q0','Leakage') ))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**That's it!** You know all there is to know about the `StateSpaceLabels` object.  Remember you can pass a `StateSpaceLabels` object to `pygsti.construction.build_explicit_model` to create a model which operates on the given state space."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.7.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}