Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: m-labs/artiq
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: 2c15bd3e4408
Choose a base ref
...
head repository: m-labs/artiq
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: c3f3763af173
Choose a head ref
  • 4 commits
  • 7 files changed
  • 1 contributor

Commits on Aug 18, 2015

  1. Copy the full SHA
    1788162 View commit details
  2. Copy the full SHA
    c97c6e2 View commit details
  3. doc: environment

    sbourdeauducq committed Aug 18, 2015
    Copy the full SHA
    9f0ada4 View commit details
  4. doc: units

    sbourdeauducq committed Aug 18, 2015
    Copy the full SHA
    c3f3763 View commit details
4 changes: 4 additions & 0 deletions artiq/language/environment.py
Original file line number Diff line number Diff line change
@@ -285,6 +285,10 @@ def analyze(self):


class EnvExperiment(Experiment, HasEnvironment):
"""Base class for experiments that use the ``HasEnvironment`` environment
manager.
Most experiment should derive from this class."""
pass


30 changes: 23 additions & 7 deletions doc/manual/core_device.rst
Original file line number Diff line number Diff line change
@@ -26,7 +26,25 @@ FPGA board ports
KC705
-----

The main target board for the ARTIQ core device is the KC705 development board from Xilinx.
The main target board for the ARTIQ core device is the KC705 development board from Xilinx. It supports the NIST QC1 hardware via an adapter, and the NIST QC2 hardware (FMC).

With the QC1 hardware, the TTL lines are mapped as follows:

+--------------+------------+--------------+
| RTIO channel | TTL line | Capability |
+==============+============+==============+
| 0 | PMT0 | Input |
+--------------+------------+--------------+
| 1 | PMT1 | Input |
+--------------+------------+--------------+
| 2-16 | TTL0-14 | Output |
+--------------+------------+--------------+
| 17 | SMA_GPIO_N | Input+Output |
+--------------+------------+--------------+
| 18 | LED | Output |
+--------------+------------+--------------+
| 19 | TTL15 | Clock |
+--------------+------------+--------------+

Pipistrello
-----------
@@ -44,17 +62,15 @@ When plugged to an adapter, the NIST QC1 hardware can be used. The TTL lines are
+--------------+----------+------------+
| 2-16 | TTL0-14 | Output |
+--------------+----------+------------+
| 17 | TTL15 | Clock |
| 17 | EXT_LED | Output |
+--------------+----------+------------+
| 18 | EXT_LED | Output |
| 18 | USER_LED | Output |
+--------------+----------+------------+
| 19 | USER_LED | Output |
+--------------+----------+------------+
| 20 | DDS | Output |
| 19 | TTL15 | Clock |
+--------------+----------+------------+

The input only limitation on channels 0 and 1 comes from the QC-DAQ adapter. When the adapter is not used (and physically unplugged from the Pipistrello board), the corresponding pins on the Pipistrello can be used as outputs. Do not configure these channels as outputs when the adapter is plugged, as this would cause electrical contention.

The board can accept an external RTIO clock connected to PMT2. If the DDS box
does not drive the PMT2 pair, use XTRIG and patch the XTRIG transciever output
does not drive the PMT2 pair, use XTRIG and patch the XTRIG transceiver output
on the adapter board onto C:15 disconnecting PMT2.
4 changes: 2 additions & 2 deletions doc/manual/core_language_reference.rst
Original file line number Diff line number Diff line change
@@ -18,5 +18,5 @@ The most commonly used features from those modules can be imported with ``from a
:mod:`artiq.language.units` module
----------------------------------

.. automodule:: artiq.language.units
:members:
This module contains floating point constants that correspond to common physical units (ns, MHz, ...).
They are provided for convenience (e.g write ``MHz`` instead of ``1000000.0``) and code clarity purposes.
51 changes: 51 additions & 0 deletions doc/manual/environment.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
The environment
===============

Experiments interact with an environment that consists of devices, parameters, arguments and results. Access to the environment is handled by the class :class:`artiq.language.environment.EnvExperiment` that experiments should derive from.

.. _ddb:

The device database
-------------------

The device database contains information about the devices available in a ARTIQ installation, what drivers to use, what controllers to use and on what machine, and where the devices are connected.

The master (or ``artiq_run``) instantiates the device drivers (and the RPC clients in the case of controllers) for the experiments based on the contents of the device database.

The device database is stored in the memory of the master and is backed by a PYON file typically called ``ddb.pyon``.

The device database is a Python dictionary whose keys are the device names, and values can have several types.

Local devices
+++++++++++++

Local device entries are dictionaries that contain a ``type`` field set to ``local``. They correspond to device drivers that are created locally on the master (as opposed to going through the controller mechanism). The fields ``module`` and ``class`` determine the location of the Python class that the driver consists of. The ``arguments`` field is another (possibly empty) dictionary that contains arguments to pass to the device driver constructor.

Controllers
+++++++++++

Controller entries are dictionaries whose ``type`` field is set to ``controller``. When an experiment requests such a device, a RPC client (see :class:`artiq.protocols.pc_rpc`) is created and connected to the appropriate controller. Controller entries are also used by controller managers to determine what controllers to run.

The ``best_effort`` field is a boolean that determines whether to use :class:`artiq.protocols.pc_rpc.Client` or :class:`artiq.protocols.pc_rpc.BestEffortClient`. The ``host`` and ``port`` fields configure the TCP connection. The ``target`` field contains the name of the RPC target to use (you may use ``artiq_rpctool`` on a controller to list its targets). Controller managers run the ``command`` field in a shell to launch the controller, after replacing ``{port}`` and ``{bind}`` by respectively the TCP port the controller should listen to (matches the ``port`` field) and an appropriate bind address for the controller's listening socket.

Aliases
+++++++

If an entry is a string, that string is used as a key for another lookup in the device database.

The parameter database
----------------------

The parameter database is a key-value store that is global to all experiments. It is stored in the memory of the master and is backed by a PYON file typically called ``pdb.pyon``. It may be used to communicate values across experiments; for example, a periodic calibration experiment may update a parameter read by payload experiments.

Arguments
---------

Arguments are values that parameterize the behavior of an experiment and are set before the experiment is executed.

Requesting the values of arguments can only be done in the build phase of an experiment. The value requests are also used to define the GUI widgets shown in the explorer when the experiment is selected.

Results
-------

Results are the output of an experiment. They are archived after in the HDF5 format after the experiment is run. Experiments may define real-time results that are (additionally) distributed to all clients connected to the master; for example, the ARTIQ GUI may plot them while the experiment is in progress to give rapid feedback to the user. Real-time results are a global key-value store (similar to the parameter database); experiments should use distinctive real-time result names in order to avoid conflicts.
2 changes: 1 addition & 1 deletion doc/manual/getting_started.rst
Original file line number Diff line number Diff line change
@@ -23,7 +23,7 @@ As a very first step, we will turn on a LED on the core device. Create a file ``

The central part of our code is our ``LED`` class, that derives from :class:`artiq.language.environment.EnvExperiment`. Among other features, ``EnvExperiment`` calls our ``build`` method and provides the ``attr_device`` method that interfaces to the device database to create the appropriate device drivers and make those drivers accessible as ``self.core`` and ``self.led``. The ``@kernel`` decorator tells the system that the ``run`` method must be executed on the core device (instead of the host). The decorator uses ``self.core`` internally, which is why we request the core device using ``attr_device`` like any other.

Copy the files ``ddb.pyon`` and ``pdb.pyon`` (containing the device and parameter databases) from the ``examples`` folder of ARTIQ into the same directory as ``led.py`` (alternatively, you can use the ``-d`` and ``-p`` options of ``artiq_run.py``). You can open the database files using a text editor - their contents are in a human-readable format. You will probably want to set the IP address of the core device in ``ddb.pyon`` so that the computer can connect to it (it is the ``host`` parameter of the ``comm`` entry).
Copy the files ``ddb.pyon`` and ``pdb.pyon`` (containing the device and parameter databases) from the ``examples`` folder of ARTIQ into the same directory as ``led.py`` (alternatively, you can use the ``-d`` and ``-p`` options of ``artiq_run.py``). You can open the database files using a text editor - their contents are in a human-readable format. You will probably want to set the IP address of the core device in ``ddb.pyon`` so that the computer can connect to it (it is the ``host`` parameter of the ``comm`` entry). See :ref:`ddb` for more information.

Run your code using ``artiq_run``, which is part of the ARTIQ front-end tools: ::

1 change: 1 addition & 0 deletions doc/manual/index.rst
Original file line number Diff line number Diff line change
@@ -10,6 +10,7 @@ Contents:
installing
getting_started
management_system
environment
core_device
core_language_reference
core_drivers_reference
74 changes: 35 additions & 39 deletions doc/manual/ndsp_reference.rst
Original file line number Diff line number Diff line change
@@ -34,6 +34,15 @@ Client
Lab Brick Digital Attenuator (LDA)
----------------------------------

Driver
++++++

.. automodule:: artiq.devices.lda.driver
:members:

Controller
++++++++++

On Linux, you need to give your user access to the USB device.

You can do that by creating a file under ``/etc/udev/rules.d/`` named
@@ -56,15 +65,6 @@ Also, the ``SN:`` prefix is mandatory.

You can choose the LDA model with the ``-P`` parameter. The default is LDA-102.

Driver
++++++

.. automodule:: artiq.devices.lda.driver
:members:

Controller
++++++++++

.. argparse::
:ref: artiq.frontend.lda_controller.get_argparser
:prog: lda_controller
@@ -88,6 +88,25 @@ Controller
Thorlabs T-Cube
---------------

TDC001 Driver
+++++++++++++

.. autoclass:: artiq.devices.thorlabs_tcube.driver.Tdc
:members:

TPZ001 Driver
+++++++++++++

.. autoclass:: artiq.devices.thorlabs_tcube.driver.Tpz
:members:

Controller
++++++++++

.. argparse::
:ref: artiq.frontend.thorlabs_tcube_controller.get_argparser
:prog: thorlabs_controller

.. _tdc001-controller-usage-example:

TDC001 controller usage example
@@ -149,28 +168,21 @@ Then, send commands to it via the ``artiq_rpctool`` utility::
$ artiq_rpctool ::1 3255 call set_output_volts 150 # set output voltage to 150 V
$ artiq_rpctool ::1 3255 call close # close the device

TDC001 Driver
+++++++++++++

.. autoclass:: artiq.devices.thorlabs_tcube.driver.Tdc
:members:
NI PXI6733
----------

TPZ001 Driver
+++++++++++++
Driver
++++++

.. autoclass:: artiq.devices.thorlabs_tcube.driver.Tpz
.. automodule:: artiq.devices.pxi6733.driver
:members:

Controller
++++++++++

.. argparse::
:ref: artiq.frontend.thorlabs_tcube_controller.get_argparser
:prog: thorlabs_controller


NI PXI6733
----------
:ref: artiq.frontend.pxi6733_controller.get_argparser
:prog: pxi6733_controller

PXI6733 controller usage example
++++++++++++++++++++++++++++++++
@@ -201,19 +213,3 @@ Then, send a load_sample_values command to it via the ``artiq_rpctool`` utility:
This loads 4 voltage values as a numpy float array: 1.0 V, 2.0 V, 3.0 V, 4.0 V

Then the device is set up to output those samples at each rising edge of the clock.

Driver
++++++

.. automodule:: artiq.devices.pxi6733.driver
:members:

Controller
++++++++++

Usage example

.. argparse::
:ref: artiq.frontend.pxi6733_controller.get_argparser
:prog: pxi6733_controller