Merge pull request #7 from qdev-dk/new_syntax

New syntax

objects.md

@@ -7,40 +7,40 @@ In *italics* the container just holds this object (or class) as a default for de
 Normal text the container includes and uses this object
 
 - Station
-  - BaseInstrument: IPInstrument, VisaInstrument, MockInstrument
-    - **Parameter**
+  - Instrument: IPInstrument, VisaInstrument, MockInstrument
+    - **Parameter**: InstrumentParameter
       - Validator: Anything, Strings, Numbers, Ints, Enum, MultiType
       - **SweepValues**: SweepFixedValues, AdaptiveSweep
     - Function
       - Validator
-  - *SweepStorage class*: MergedCSVStorage, ?
   - **Monitor**
-  - MeasurementSet
-    - StorageManager, Monitor
-    - *SweepStorage class*
-    - .sweep
-      - SweepValues
-      - **SweepStorage**
-  - **StorageManager**
-    - **StorageServer**
-      - SweepStorage
-      - Monitor
+  - *actions*
+- DataManager
+  - **DataServer**
+- Loop
+  - actions: Parameter, Task, Wait, (Active)Loop
+  - **ActiveLoop**
+    - **DataSet**
+      - **DataArray**
+      - **Formatter**: GNUPlotFormat
+      - **DiskIO** (may become subclass of IOManager?)
 
 ## Station
 
 A representation of the entire physical setup.
 
-Lists all the connected `Instrument`s, keeps references to the `StorageManager` and
-`Monitor` objects that are running, and holds various default settings, such as
-the default `MeasurementSet` and the default `SweepStorage` class in use right now.
+Lists all the connected `Instrument`s and the current default
+measurement (a list of actions). Contains a convenience method
+`.measure()` to measure these defaults right now, but this is separate
+from the code used by `Loop`.
 
 ## Instrument
 
 A representation of one particular piece of hardware.
 
 Lists all `Parameter`s and `Function`s this hardware is capable of, and handles the
 underlying communication with the hardware.
-`BaseInstrument` sets the common structure but real instruments will generally derive
+`Instrument` sets the common structure but real instruments will generally derive
 from its subclasses, such as `IPInstrument` and `VisaInstrument`. There is also
 `MockInstrument` for making simulated instruments, connected to a `Model` that mimics
 a serialized communication channel with an apparatus.
@@ -49,12 +49,20 @@ a serialized communication channel with an apparatus.
 
 A representation of one particular state variable.
 
-Most `Parameter`s are part of an `Instrument`, but you can also create `Parameter`s
-that execute arbitrary functions, for example to combine several gate voltages in a
-diagonal sweep. Parameters can have setters and/or getters (they must define at least
-a setter OR a getter but do not need to define both)
+Most `Parameter`s are part of an `Instrument`, using the subclass
+`InstrumentParameter` which links it to specific commands sent to a specific
+instrument. But you can also create `Parameter`s that execute arbitrary functions,
+for example to combine several gate voltages in a diagonal sweep. Parameters can
+have setters and/or getters (they must define at least a setter OR a getter but
+do not need to define both)
 
-`Parameter`s can be sliced to create a `SweepFixedValues` object.
+Gettable `Parameter`s often return one value, but can return a collection of
+values - several values with different names, or one or more arrays of values,
+ie if an instrument provides a whole data set at once, or if you want to save
+raw and calculated data side-by-side
+
+Settable `Parameter`s take a single value, and can be sliced to create a
+`SweepFixedValues` object.
 
 ## Validator
 
@@ -79,26 +87,6 @@ on the `.feedback` method by which the sweep passes measured values back into th
 A representation of some action an `Instrument` can perform, which is not connected to
 any particular state variable (eg calibrate, reset, identify)
 
-## StorageManager
-
-The gateway to the separate storage process.
-
-Sweeps and monitoring routines all pass their data through the `StorageManager` to the
-`StorageServer`, which the `StorageManager` started and is running in a separate process.
-Likewise, plotting & display routines query the `StorageServer` via the `StorageManager`
-to retrieve current data.
-
-## StorageServer
-
-Running in its own process, receives, holds, and returns current sweep and monitor data,
-and writes it to disk (or other storage)
-
-When a sweep is *not* running, the StorageServer also calls the monitor routine itself.
-But when a sweep *is* running, the sweep calls the monitor so that it can avoid conflicts.
-Also while a sweep is running, there are complementary `SweepStorage` objects in the sweep
-and `StorageServer` processes - they are nearly identical objects, but are configured
-differently.
-
 ## Monitor
 
 Measures all system parameters periodically and logs these measurements
@@ -109,27 +97,72 @@ so that during sweeps it can be given a command "measure for no longer than X se
 it will figure out which parameters it has time to measure, and which of those are most
 important (primarily, I guess, the most important were last measured the longest time ago)
 
-## MeasurementSet
+## DataManager
+
+The gateway to the separate DataServer process.
+
+Measurement `Loop`s and monitoring routines all pass their data through the
+`DataManager` to the `DataServer`, which the `DataManager` started and is
+running in a separate process.
+Likewise, plotting & display routines query the `DataServer` via the `DataManager`
+to retrieve current data.
+
+## DataServer
+
+Running in its own process, receives, holds, and returns current `Loop` and
+monitor data, and writes it to disk (or other storage)
+
+When a `Loop` is *not* running, the DataServer also calls the monitor routine.
+But when a `Loop` *is* running, *it* calls the monitor so that it can avoid conflicts.
+Also while a `Loop` is running, there are complementary `DataSet` objects in the loop
+and `DataServer` processes - they are nearly identical objects, but are configured
+differently so that the loop `DataSet` doesn't hold any data itself, it only
+passes that data on to the `DataServer`
+
+## Loop
+
+Describes a sequence of `Parameter` settings to loop over. When you attach
+`action`s to a `Loop`, it becomes an `ActiveLoop` that you can `.run()`, or
+you can run a `Loop` directly, in which case it takes the default `action`s from
+the default `Station`
+
+`actions` are a sequence of things to do at each `Loop` step: they can be
+`Parameter`s to measure, `Task`s to do (any callable that does not yield data),
+`Wait` times, other `ActiveLoop`s to nest inside this one, or `Loop`s to nest using
+the default `actions`.
+
+## ActiveLoop
+
+After a `Loop` has actions attached to it, all you can do with it is `.run()` it,
+or use it as an action inside another `Loop` which will `.run()` the whole thing.
+
+The `ActiveLoop` determines what `DataArray`s it will need to hold the data it
+collects, and it creates a `DataSet` holding these `DataArray`s
+
+## DataSet
+
+A collection of `DataArray`s that contains all the data from one measurement
+(normally one `Loop`). During measurement, it creates a twin of itself on the
+`DataServer`, and yet another copy persists in the main thread for live plotting.
+
+You also get a `DataSet` if you read back in an old data set, so it can use the
+same API for plotting and analysis during and after acquisition.
 
-A list of parameters to measure while sweeping, along with the sweep methods.
+Contains defaults for `Formatter` (`GNUPlotFormat`) and IO Manager (`DiskIO`),
+but they are kept as separate objects so that you can change them if you want
+to move or reformat an existing `DataSet`.
 
-Usually created from a `Station` and inheriting the `StorageManager`, `Monitor`,
-and default `SweepStorage` class from it.
+## DataArray
 
-The `.sweep` method starts a sweep, which creates a `SweepStorage` object and,
-if the sweep is to run in the background (the default), this method starts the
-sweep process.
+One n-dimensional data array. If it is a measured `Parameter`, it references
+other `DataArray`(s) as its setpoints.
 
-## SweepStorage
+## Formatter
 
-Object that holds sweep data and knows how to read from and write to disk or
-other long-term storage, as well as how to communicate with its clone on the
-`StorageServer` if one exists.
+Describes the file format used to read and write a `DataSet`. Uses an
+IO Manager to actually perform the storage (so that the same format can be
+used on disk, in the cloud, in a database...)
 
-A `SweepStorage` is created when a new sweep is started, and this one clones
-itself on the `StorageServer`. But you can also create a `SweepStorage` from
-a previous sweep, in which case it simply reads in the sweep and holds it
-for plotting or analysis.
+## IO Manager
 
-Subclasses (eg `MergedCSVStorage`, later perhaps `AzureStorage` etc) define
-the connection with the particular long-term storage you are using.
+Performs the actual reading and writing of files generated by a `Formatter`

qcodes/__init__.py

@@ -0,0 +1,26 @@
+# set up the qcodes namespace
+# flake8: noqa (we don't need the "<...> imported but unused" error)
+
+from qcodes.station import Station
+from qcodes.loops import get_bg, halt_bg, Loop, Task, Wait
+
+from qcodes.data.manager import get_data_manager
+from qcodes.data.data_set import DataMode, DataSet
+from qcodes.data.data_array import DataArray
+from qcodes.data.format import Formatter, GNUPlotFormat
+from qcodes.data.io import DiskIO
+
+from qcodes.instrument.base import Instrument
+from qcodes.instrument.ip import IPInstrument
+from qcodes.instrument.visa import VisaInstrument
+from qcodes.instrument.mock import MockInstrument
+
+from qcodes.instrument.function import Function
+from qcodes.instrument.parameter import Parameter, InstrumentParameter
+from qcodes.instrument.sweep_values import SweepFixedValues, AdaptiveSweep
+
+from qcodes.utils.helpers import set_mp_method, reload_code
+
+# just for convenience in debugging, so we don't have to
+# separately import multiprocessing
+from multiprocessing import active_children