This module provides functionality for labelling endpoints in wires. The goal is to achieve two things:

• Label qubits individually. For example, we would like to label three qubits (a, b, c) as "a", "b", and "c", respectively.
• Label data structures all at once. For example, if a=[x,y,z] is a piece of quantum data, and we label this data structure "a", then the individual qubits will be labelled: x = a[0], y = a[1], z = a[2].

We can also combine both methods to arbitrary nesting levels. For example, we can label (([x,y,z], t), [u,v,w]) as ("a", ["u", "v", "w"]), to get the labelling x = a[0,0], y = a[0,1], z = a[0,2], t = a[1], u = u, v = v, w = w.

A Labelable instance should be defined for each new instance of QCData. The general idea is that the structure of the label should exactly follow the structure of the data being labeled, except that at any level the label can be a string (which will then be decorated with appropriate subscripts for each leaf in the data structure).

In practice, there are two cases to consider: adding a new QCData constructor, and adding a new atomic QCData.

New QCshape constructors

Consider the case of a new QCData constructor:

 instance (QCData a) => QCData (Constructor a).

There are two required Labelable instances. The first instance deals with a label that is a string, and takes the following form:

 instance (Labelable a String) => Labelable (Constructor a) String where
   label_rec as s = do
     label_rec <<<a1>>> s `indexed` <<<index1>>>
     ...
     label_rec <<<an>>> s `indexed` <<<indexn>>>

Here, a₁...a_n are the components of the data structure, and index₁...indexn/ are the corresponding subscripts. The function indexed appends a subscript of the form "[i]". There is a similar function dotted_indexed, which appends a subscript of the form ".i".

The second required instance deals with a label that is a data structure of the same shape as the data being labeled. It takes the form:

 instance (Labelable a s) => Labelable (Constructor a) (Constructor s) where
   label_rec as ss idx = do
     label_rec <<<a1>>> <<<s1>>>
     ...
     label_rec <<<an>>> <<<sn>>>

Here, a₁...a_n are the components of the data structure, and s₁...s_n are the corresponding components of the label.

Example

As a concrete example, consider a constructor

 data MaybeTwo a = One a | Two a a
 instance (QCData a) => QCData (MaybeTwo a)

The following instance declarations would be appropriate:

 instance (Labelable a String) => Labelable (MaybeTwo a) String where
    label_rec (One x) s =
      with_dotted_index "one" $ do
        label_rec x s
    label_rec (Two x y) s =
      with_dotted_index "two" $ do
        label_rec x s `indexed` "0"
        label_rec y s `indexed` "1"

 instance (Labelable a s) => Labelable (MaybeTwo a) (MaybeTwo s) where
    label_rec (One x) (One s) = label_rec x s
    label_rec (Two x y) (Two s t) = do
      label_rec x s
      label_rec y t
    label_rec _ _ = return ()  -- fail silently

With this example, the commands

 mklabel (One x) "s"
 mklabel (Two y z) "s"

produce the respective labelings

 x -> s.one
 y -> s.two[0]
 z -> s.two[1]

New atomic QCShape

Consider the case of a new atomic QCData instance:

 instance QCData (Atomic x).

We usually need a Labelable instance for the cases x=Qubit and x=Bit. This should be done uniformly, by using the QCLeaf type class. The instance takes the following form:

 instance QCLeaf x => Labelable (Atomic x) String where
   label_rec a s = do
     label_rec <<<a1>>> s `indexed` <<<index1>>>
     ...
     label_rec <<<an>>> s `indexed` <<<indexn>>>

Here, a₁...a_n are the components of the data structure, and index₁...indexn/ are the corresponding subscripts. It is up to the designer of the data structure to decide what are "components" and how they should be labelled. On or more layers of string or numeric indices can be added as appropriate.

Example

Consider the following sample atomic quantum data. A real number consists of an exponent, a sign, and a list of digits.

 data MyReal x = MyReal Int x [x]
 instance QCLeaf x => QCData (MyReal x)

The following instance declaration would be appropriate:

 instance QCLeaf x => Labelable (MyReal x) String where
    label_rec (MyReal exp sign digits) s = do
      label_rec sign s `dotted_indexed` "sign"
      with_dotted_index "digit" $ do
        sequence_ [ label_rec d s `indexed` show i | (d,i) <- zip digits [-exp..] ]

With this example, the command

 mklabel (MyReal 2 x [y0, y1, y2, y3]) "s"

produces the labeling

 x  -> "s.sign"
 y0 -> "s.digit[-2]"
 y1 -> "s.digit[-1]"
 y2 -> "s.digit[0]"
 y3 -> "s.digit[1]"

Note that we could have also used the default labeling for the members of a list, but in this case, it was convenient to use a custom labeling.