Feat/channelization with small cleanup

docs/examples/driver_examples/Qcodes example with QDac_channels.ipynb

@@ -0,0 +1,296 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Qcodes example with QDac_channels"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import qcodes as qc\n",
+    "import numpy as np\n",
+    "\n",
+    "from time import sleep\n",
+    "\n",
+    "from qcodes.instrument_drivers.QDev.QDac_channels import QDac"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "# Connect to the instrument\n",
+    "qdac = QDac('qdac', 'ASRL6::INSTR', update_currents=False)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Basic QDac Usage\n",
+    "\n",
+    "The QCoDeS QDac driver currently supports using\n",
+    "  * 48 Output Channels\n",
+    "  * 3 $\\times$ 6 temperature sensors\n",
+    "\n",
+    "Each output channel has six parameters:\n",
+    "  * DC voltage\n",
+    "  * DC voltage range\n",
+    "  * Current out (read-only)\n",
+    "  * Current out range\n",
+    "  * slope\n",
+    "  * sync\n",
+    "\n",
+    "The slope is the (maximal) slope in V/s that the channel can allow its voltage to change by. By default, all channels have a slope of \"Inf\". The slope can be changed dynamically, but no more than 8 channels can have a finite slope at any given time (this is due to hardware limitations)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Current out is the current flowing through the channel this is read-only\n",
+    "print(qdac.ch01.i.get(), qdac.ch01.i.unit)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# The current range can be either 0 to 1 μA or 0 to 100 μA\n",
+    "print(qdac.ch01.irange.get())\n",
+    "# This is set with either 0 (0 to 1 μA) or 1 (0 to 100 μA) \n",
+    "qdac.ch01.irange.set(1)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# The DC voltage may directly be set and gotten\n",
+    "qdac.ch01.v.set(-1)\n",
+    "print('Channel 1 voltage: {} {}'.format(qdac.ch01.v.get(), qdac.ch01.v.unit))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Multiple channels can be addressed simultaneously via the 'channels' list\n",
+    "qdac.channels[0:20].v.get()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Similarly, we may set them\n",
+    "qdac.channels[0:2].v.set(-1)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# The maximal voltage change (in V/s) may be set for each channel\n",
+    "qdac.ch01.slope.set(1)\n",
+    "qdac.ch02.slope.set(2)\n",
+    "# An overview may be printed (all other channels have 'Inf' slope)\n",
+    "qdac.printslopes()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "# now setting channel 1 and 2 voltages will cause slow ramps to happen\n",
+    "qdac.ch01.v.set(0)\n",
+    "qdac.ch02.v.set(0)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Note that only 8 (or fewer) channels can have finite slopes at one time\n",
+    "# To make space for other channels, set the slope to inifite\n",
+    "qdac.ch01.slope('Inf')\n",
+    "qdac.printslopes()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "# To each channel one may assign a sync channel:\n",
+    "qdac.ch02.sync(2)  # sync output 2 will fire a 10 ms 5 V pulse when ch02 ramps\n",
+    "# note that even if no visible ramp is performed (i.e. ramping from 1 V to 1 V), a pulse is still fired.\n",
+    "\n",
+    "# The sync pulse settings can be modified\n",
+    "qdac.ch02.sync_delay(0)  # The sync pulse delay (s)\n",
+    "qdac.ch02.sync_duration(25e-3)  # The sync pulse duration (s). Default is 10 ms."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "qdac.ch02.v.set(0)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "# syncs are unassigned by assigning sync 0\n",
+    "qdac.ch02.sync(0)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Attention!\n",
+    "\n",
+    "The v_range parameter is really controlling a 20 dB (amplitude factor 10) attenuator. Upon changing the vrange, the attenuator is **immediately** applied (or revoked). This will --irrespective of any slope set-- cause an instantaneous voltage change unless the channel voltage is zero. By default, all attenuators are off, and the voltage range is from -10 V to 10 V for all channels."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Here is a small example showing what to look out for\n",
+    "#\n",
+    "qdac.ch01.vrange.set(0)  # Attenuation OFF (the default)\n",
+    "qdac.ch01.v.set(1.5)\n",
+    "qdac.ch01.vrange.set(1)  # Attenuation ON\n",
+    "print(qdac.ch01.v.get())  # Returns 0.15 V\n",
+    "qdac.ch01.v.set(0.1)\n",
+    "qdac.ch01.vrange.set(0)  # Attenuation OFF\n",
+    "print(qdac.ch01.v.get())  # returns 1 V"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Overview of channel settings\n",
+    "\n",
+    "The driver provides a method for pretty-printing the state of all channels. On startup, all channels are queried for voltage and current across them, but the current query is very slow (blame the hardware).\n",
+    "\n",
+    "The pretty-print method may or may not **update** the values for the currents, depending on the value of the `update_currents` flag. Each current reading takes some 200 ms, so updating all current values takes about 10 s."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "scrolled": false
+   },
+   "outputs": [],
+   "source": [
+    "qdac.print_overview(update_currents=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Temperature sensors\n",
+    "\n",
+    "Physically, the QDac consists of six boards each hosting eight channels. On three locations on each board, a temperature sensors is placed. These provide read-only parameters, named `tempX_Y` where `X` is the board number and `Y` the sensor number."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(qdac.temp0_0.get(), qdac.temp0_0.unit)\n",
+    "print(qdac.temp2_1.get(), qdac.temp0_0.unit)\n",
+    "print(qdac.temp5_2.get(), qdac.temp0_0.unit)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "qdac.close()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "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.5.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 1
+}

qcodes/__init__.py

@@ -45,6 +45,7 @@
 from qcodes.instrument.base import Instrument
 from qcodes.instrument.ip import IPInstrument
 from qcodes.instrument.visa import VisaInstrument
+from qcodes.instrument.channel import InstrumentChannel, ChannelList
 
 from qcodes.instrument.function import Function
 from qcodes.instrument.parameter import (

qcodes/instrument/base.py

@@ -34,6 +34,10 @@ class Instrument(Metadatable, DelegateAttributes):
 
         functions (Dict[Function]): All the functions supported by this
             instrument. Usually populated via ``add_function``
+
+        submodules (Dict[Metadatable]): All the submodules of this instrument
+            such as channel lists or logical groupings of parameters.
+            Usually populated via ``add_submodule``
     """
 
     shared_kwargs = ()
@@ -48,6 +52,7 @@ def __init__(self, name, **kwargs):
         super().__init__(**kwargs)
         self.parameters = {}
         self.functions = {}
+        self.submodules = {}
 
         self.name = str(name)
 
@@ -306,6 +311,36 @@ def add_function(self, name, **kwargs):
         func = Function(name=name, instrument=self, **kwargs)
         self.functions[name] = func
 
+    def add_submodule(self, name, submodule):
+        """
+        Bind one submodule to this instrument.
+
+        Instrument subclasses can call this repeatedly in their ``__init__``
+        method for every submodule of the instrument.
+
+        Submodules can effectively be considered as instruments within the main
+        instrument, and should at minimum be snapshottable. For example, they can
+        be used to either store logical groupings of parameters, which may or may
+        not be repeated, or channel lists.
+
+        Args:
+            name (str): how the submodule will be stored within ``instrument.submodules``
+            and also how it can be addressed.
+
+            submodule (Metadatable): The submodule to be stored.
+
+        Raises:
+            KeyError: if this instrument already contains a submodule with this
+                name.
+            TypeError: if the submodule that we are trying to add is not an instance
+                of an Metadatable object.
+        """
+        if name in self.submodules:
+            raise KeyError('Duplicate submodule name {}'.format(name))
+        if not isinstance(submodule, Metadatable):
+            raise TypeError('Submodules must be metadatable.')
+        self.submodules[name] = submodule
+
     def snapshot_base(self, update=False):
         """
         State of the instrument as a JSON-compatible dict.
@@ -321,6 +356,8 @@ def snapshot_base(self, update=False):
                                    for name, param in self.parameters.items()),
                 'functions': dict((name, func.snapshot(update=update))
                                   for name, func in self.functions.items()),
+                'submodules': dict((name, subm.snapshot(update=update))
+                                  for name, subm in self.submodules.items()),
                 '__class__': full_class(self),
                 }
         for attr in set(self._meta_attrs):
@@ -459,7 +496,7 @@ def ask_raw(self, cmd):
     # etc...                                                                #
     #
 
-    delegate_attr_dicts = ['parameters', 'functions']
+    delegate_attr_dicts = ['parameters', 'functions', 'submodules']
 
     def __getitem__(self, key):
         """Delegate instrument['name'] to parameter or function 'name'."""