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: e2def34ede40
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: 64d1bca6c10f
Choose a head ref
  • 4 commits
  • 3 files changed
  • 1 contributor

Commits on Apr 9, 2016

  1. README: note about doc/manual/introduction.rst

    @jordens
    jordens committed Apr 9, 2016
    Copy the full SHA
    dee5740 View commit details

  2. introduction.rst: update license

    @jordens
    jordens committed Apr 9, 2016
    Copy the full SHA
    a48f44e View commit details

  3. README: rewrite, summarizing more aspects of ARTIQ

    @jordens
    jordens committed Apr 9, 2016
    Copy the full SHA
    c858d44 View commit details

  4. installing.rst: update, clarify

    @jordens
    jordens committed Apr 9, 2016
    Copy the full SHA
    64d1bca View commit details
Showing with 100 additions and 84 deletions.
  1. +22 −10 README.rst
  2. +56 −61 doc/manual/installing.rst
  3. +22 −13 doc/manual/introduction.rst
32 changes: 22 additions & 10 deletions README.rst
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,29 @@
.. Always keep doc/manual/introduction.rst synchronized with this file, with the exception of the logo.
.. image:: doc/logo/artiq.png

ARTIQ (Advanced Real-Time Infrastructure for Quantum physics) is a
next-generation control system for quantum information experiments. It is
developed in partnership with the Ion Storage Group at NIST, and its
applicability reaches beyond ion trapping.
ARTIQ (Advanced Real-Time Infrastructure for Quantum physics) is the next-generation control system for quantum information experiments.
It is developed by `M-Labs <https://m-labs.hk>`_ for and in partnership with the `Ion Storage Group at NIST <http://www.nist.gov/pml/div688/grp10/index.cfm>`_ as free software.
It is offered to the entire research community as a solution equally applicable to other challenging control tasks outside the field of ion trapping.

The system features a high-level programming language that helps describing complex experiments, which is compiled and executed on dedicated hardware with nanosecond timing resolution and sub-microsecond latency. It includes graphical user interfaces to parametrize and schedule experiments and to visualize and explore the results.

ARTIQ uses FPGA hardware to perform its time-critical tasks.
It is designed to be portable to hardware platforms from different vendors and FPGA manufacturers.
Currently, one configuration of a `low-cost open hardware FPGA board <http://pipistrello.saanlima.com/>`_ and several different configurations of a `high-end FPGA evaluation kit <http://www.xilinx.com/products/boards-and-kits/ek-k7-kc705-g.html>`_ are used and supported.
Any of these FPGA platforms can be combined with any number of additional peripherals, either already accessible from ARTIQ or made accessible with little effort.

Custom hardware components with widely extended capabilities and advanced support for scalable and fully distributed real-time control of experiments `are being designed <https://github.com/m-labs/artiq-hardware>`_.

ARTIQ and its dependencies are available in the form of `conda packages <https://conda.anaconda.org/m-labs/label/main>`_ for both Linux and Windows.
Packages containing pre-compiled binary images to be loaded onto the hardware platforms are supplied for each configuration.
Like any open source software ARTIQ can equally be built and installed directly from `source <https://github.com/m-labs/artiq>`_.

The system features a high-level programming language that helps describing
complex experiments, which is compiled and executed on dedicated hardware with
nanosecond timing resolution and sub-microsecond latency.
ARTIQ is supported by M-Labs and developed openly.
Components, features, fixes, improvements, and extensions are funded by and developed for the partnering research groups.

Technologies employed include Python, Migen, MiSoC/mor1kx, LLVM and llvmlite.
Technologies employed include `Python <https://www.python.org/>`_, `Migen <https://github.com/m-labs/migen>`_, `MiSoC <https://github.com/m-labs/misoc>`_/`mor1kx <https://github.com/openrisc/mor1kx>`_, `LLVM <http://llvm.org/>`_/`llvmlite <https://github.com/numba/llvmlite>`_, and `Qt5 <http://www.qt.io/>`_.

Website:
https://m-labs.hk/artiq
Website: https://m-labs.hk/artiq

Copyright (C) 2014-2016 M-Labs Limited. Licensed under GNU GPL version 3.
117 changes: 56 additions & 61 deletions doc/manual/installing.rst
View file
Original file line number Diff line number Diff line change
@@ -6,118 +6,109 @@ The conda package contains pre-built binaries that you can directly flash to you
But you can also :ref:`install from sources <install-from-sources>`.

.. warning::
NIST users need to pay close attention to their ``umask``. The sledgehammer
called ``secureconfig`` leaves you (and root) with umask 027 and files
created by root (e.g. ``sudo make install``) inaccessible to you.
NIST users on Linux need to pay close attention to their ``umask``.
The sledgehammer called ``secureconfig`` leaves you (and root) with umask 027 and files created by root (for example through ``sudo make install``) inaccessible to you.
The usual umask is 022.


Installing using conda
----------------------

.. warning::
Conda packages are supported for Linux (64-bit) and Windows (32- and 64-bit). Users of other
operating systems (32-bit Linux, BSD, ...) should install from source.
Conda packages are supported for Linux (64-bit) and Windows (32- and 64-bit).
Users of other operating systems (32-bit Linux, BSD, OSX ...) should and can :ref:`install from source <install-from-sources>`.


Installing Anaconda or Miniconda
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* You can either install Anaconda (choose Python 3.5) from https://store.continuum.io/cshop/anaconda/

* Or install the more minimalistic Miniconda (choose Python 3.5) from http://conda.pydata.org/miniconda.html
You can either install Anaconda (choose Python 3.5) from https://store.continuum.io/cshop/anaconda/ or install the more minimalistic Miniconda (choose Python 3.5) from http://conda.pydata.org/miniconda.html

After installing either Anaconda or Miniconda, open a new terminal and make sure the following command works::
After installing either Anaconda or Miniconda, open a new terminal (also known as command line, console, or shell and denoted here as lines starting with ``$``) and verify the following command works::

$ conda

If it prints the help of the ``conda`` command, your install is OK.
If not, then make sure your ``$PATH`` environment variable contains the path to anaconda3/bin (or miniconda3/bin)::

$ echo $PATH
/home/.../miniconda3/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin

If your ``$PATH`` misses reference the ``miniconda3/bin`` or ``anaconda3/bin`` you can fix this by typing::

$ export PATH=$HOME/miniconda3/bin:$PATH
Executing just ``conda`` should print the help of the ``conda`` command [1]_.

Installing the ARTIQ packages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For this, you need to add our Anaconda repository to your conda configuration::
Add the M-Labs ``main`` Anaconda package repository containing stable releases and release candidates to your conda configuration::

$ conda config --add channels http://conda.anaconda.org/m-labs/label/main

.. note::
To use the development versions of ARTIQ, also add the ``dev`` label (http://conda.anaconda.org/m-labs/label/dev).
Development versions contain more features, but are not as well-tested and are more likely to contain bugs or inconsistencies.
Development versions are built for every change and contain more features, but are not as well-tested and are more likely to contain more bugs or inconsistencies than the releases in the ``main`` label.

Then you can install the ARTIQ package, it will pull all the necessary dependencies.
Then prepare to create a new conda environment with the ARTIQ package and the matching binaries for your hardware:
choose a suitable name for the environment, for example ``artiq-main`` if you intend to track the main label or ``artiq-2016-04-01`` if you consider the environment a snapshot of ARTIQ on 2016-04-01.
Choose the package containing the binaries for your hardware:

* For the Pipistrello board::
* ``artiq-pipistrello-nist_qc1`` for the `Pipistrello <http://pipistrello.saanlima.com/>`_ board with the NIST adapter to SCSI cables and AD9858 DDS chips.
* ``artiq-kc705-nist_qc1`` for the `KC705 <http://www.xilinx.com/products/boards-and-kits/ek-k7-kc705-g.html>`_ board with the NIST adapter to SCSI cables and AD9858 DDS chips.
* ``artiq-kc705-nist_clock`` for the KC705 board with the NIST "clock" FMC backplane and AD9914 DDS chips.
* ``artiq-kc7005-nist_qc2`` for the KC705 board with the NIST QC2 FMC backplane and AD9914 DDS chips.

Conda will create the environment, automatically resolve, download, and install the necessary dependencies and install the packages you select:::

$ ENV=$(date +artiq-%Y-%m-%d); conda create -n $ENV artiq-pipistrello-nist_qc1; \
echo "Created environment $ENV for ARTIQ"
$ conda create -n artiq-main artiq-pipistrello-nist_qc1

* For the KC705 board with SCSI cables and AD9858 DDS chips::
After the installation, activate the newly created environment by name.
On Unix::

$ ENV=$(date +artiq-%Y-%m-%d); conda create -n $ENV artiq-kc705-nist_qc1; \
echo "Created environment $ENV for ARTIQ"
$ source activate artiq-main

* For the KC705 board with the "clock" FMC backplane and AD9914 DDS chips::
On Windows::

$ ENV=$(date +artiq-%Y-%m-%d); conda create -n $ENV artiq-kc705-nist_clock; \
echo "Created environment $ENV for ARTIQ"
$ activate artiq-main

* For the KC705 board with the QC2 FMC backplane and AD9914 DDS chips::
This activation has to be performed in every new shell you open to make the ARTIQ tools from that environment available.

$ ENV=$(date +artiq-%Y-%m-%d); conda create -n $ENV artiq-kc705-nist_qc2; \
echo "Created environment $ENV for ARTIQ"
.. note::
[Linux] The ``qt5`` package requires libraries not packaged under the ``m-labs`` conda labels.
Those need to be installed through the Linux distribution's mechanism.
If GUI programs do not start because they ``could not find or load the Qt platform plugin "xcb"``, install the various ``libxcb-*`` packages through your distribution's preferred mechanism.
The names of the libraries missing can be obtained from the output of a command like ``ldd [path-to-conda-installation]/envs/artiq-main/lib/qt5/plugins/platform/libqxcb.so``.

This creates a new Conda "environment" (i.e. an isolated installation) and prints its name.
If you ever need to upgrade ARTIQ, it is advised to install it again
in a new environment so that you can roll back to a version that is known to
work correctly.
Upgrading ARTIQ
^^^^^^^^^^^^^^^

After this, add the newly created environment to your ``$PATH``. This can be easily
done using the following command::
When upgrading ARTIQ or when testing different versions it is recommended that new environments are created instead of upgrading the packages in existing environments.
Keep previous environments around until you are certain that they are not needed anymore and a new environment is known to work correctly.
You can create a new conda environment specifically to test a certain version of ARTIQ:::

$ source activate artiq-[date]
$ conda create -n artiq-test-1.0rc2 artiq-pipistrello-nist_qc1=1.0rc2

You will need to invoke this command in every new shell. When in doubt, you can list
the existing environments using::
Switching between conda environments using ``$ source deactivate artiq-1.0rc2`` and ``$ source activate artiq-1.0rc1`` is the recommended way to roll back to previous versions of ARTIQ.
You can list the environments you have created using::

$ conda env list

.. note::
The ``qt5`` package requires (on Linux only) libraries not packaged under the ``m-labs`` conda labels.
Those need to be installed through the Linux distribution's mechanism.
If ``artiq_gui`` does not start because ``it could not find or load the Qt platform plugin "xcb"``, install the various ``libxcb-*`` packages through your distribution's mechanism.
The names of the libraries missing can be obtained from the output of a command like ``ldd [path-to-conda-installation]/envs/artiq-[date]/lib/qt5/plugins/platform/libqxcb.so``.
See also the `conda documentation <http://conda.pydata.org/docs/using/envs.html>`_ for managing environments.

Preparing the core device FPGA board
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You now need to flash 3 things on the FPGA board:
You now need to write three binary images onto the FPGA board:

1. The FPGA gateware bitstream
2. The BIOS
3. The ARTIQ runtime

They are all shipped in our Conda packages, along with the required flash proxy gateware bitstreams.
They are all shipped in the conda packages, along with the required flash proxy gateware bitstreams.

.. _install-openocd:

Installing OpenOCD
..................

There are several tools that can be used to write the thee binaries into
the core device FPGA board's flash memory. Xilinx ISE (impact) or Vivado work, as does xc3sprog
sometimes. OpenOCD is the recommended and most reliable method. But
it is not currently packaged as a conda package.
There are several tools that can be used to write the thee binaries into the core device FPGA board's flash memory.
Xilinx ISE (impact) or Vivado work, as does xc3sprog sometimes.
OpenOCD is the recommended and most reliable method.
It is however not currently packaged as a conda package nor has it been tested on Windows.

The following instructions are for Ubuntu.

::
Use these commands to download, build, and install ``openocd`` from source on Debian or Ubuntu systems::

$ cd ~/artiq-dev
$ git clone https://github.com/ntfreak/openocd.git
@@ -130,17 +121,15 @@ The following instructions are for Ubuntu.
$ sudo cp contrib/99-openocd.rules /etc/udev/rules.d
$ sudo adduser $USER plugdev



Then, you can flash the board:

* For the Pipistrello board::

$ artiq_flash -t pipistrello -m qc1

* For the KC705 board::
* For the KC705 board (selecting the appropriate hardware peripheral)::

$ artiq_flash -m [qc1/clock/qc2]
$ artiq_flash -t kc705 -m [qc1/clock/qc2]

For the KC705, the next step is to flash the MAC and IP addresses to the board. See :ref:`those instructions <flash-mac-ip-addr>`.

@@ -204,7 +193,7 @@ Preparing the core device FPGA board

These steps are required to generate gateware bitstream (``.bit``) files, build the MiSoC BIOS and ARTIQ runtime, and flash FPGA boards. If the board is already flashed, you may skip those steps and go directly to `Installing the host-side software`.

* Install the FPGA vendor tools (e.g. Xilinx ISE and/or Vivado):
* Install the FPGA vendor tools (i.e. Xilinx ISE and/or Vivado):

* Get Xilinx tools from http://www.xilinx.com/support/download/index.htm. ISE can build gateware bitstreams both for boards using the Spartan-6 (Pipistrello) and 7-series devices (KC705), while Vivado supports only boards using 7-series devices.

@@ -429,3 +418,9 @@ The core device may use either an external clock signal or its internal clock. T

$ artiq_coreconfig write -s startup_clock i # internal clock (default)
$ artiq_coreconfig write -s startup_clock e # external clock


.. rubric:: Footnotes

.. [1] [Linux] If your shell does not find the ``conda`` command, make sure that the conda binaries are in your ``$PATH``:
If ``$ echo $PATH`` does not show the conda directories, add them: execute ``$ export PATH=$HOME/miniconda3/bin:$PATH`` if you installed conda into ``~/miniconda3``.
35 changes: 22 additions & 13 deletions doc/manual/introduction.rst
View file
Original file line number Diff line number Diff line change
@@ -3,21 +3,30 @@ Introduction

.. this does not work because of relative paths for the logo:
.. include:: ../../README.rst
and including in README.rst does not work on github
therefore just keep this content synchronized with README.rst
and including in README.rst does not work on github therefore just keep this content synchronized with README.rst
ARTIQ (Advanced Real-Time Infrastructure for Quantum physics) is a
next-generation control system for quantum information experiments. It is
developed in partnership with the Ion Storage Group at NIST, and its
applicability reaches beyond ion trapping.
ARTIQ (Advanced Real-Time Infrastructure for Quantum physics) is the next-generation control system for quantum information experiments.
It is developed by `M-Labs <https://m-labs.hk>`_ for and in partnership with the `Ion Storage Group at NIST <http://www.nist.gov/pml/div688/grp10/index.cfm>`_ as free software.
It is offered to the entire research community as a solution equally applicable to other challenging control tasks outside the field of ion trapping.

The system features a high-level programming language that helps describing
complex experiments, which is compiled and executed on dedicated hardware with
nanosecond timing resolution and sub-microsecond latency.
The system features a high-level programming language that helps describing complex experiments, which is compiled and executed on dedicated hardware with nanosecond timing resolution and sub-microsecond latency. It includes graphical user interfaces to parametrize and schedule experiments and to visualize and explore the results.

Technologies employed include Python, Migen, MiSoC/mor1kx, LLVM and llvmlite.
ARTIQ uses FPGA hardware to perform its time-critical tasks.
It is designed to be portable to hardware platforms from different vendors and FPGA manufacturers.
Currently, one configuration of a `low-cost open hardware FPGA board <http://pipistrello.saanlima.com/>`_ and several different configurations of a `high-end FPGA evaluation kit <http://www.xilinx.com/products/boards-and-kits/ek-k7-kc705-g.html>`_ are used and supported.
Any of these FPGA platforms can be combined with any number of additional peripherals, either already accessible from ARTIQ or made accessible with little effort.

ARTIQ is licensed under 3-clause BSD.
Custom hardware components with widely extended capabilities and advanced support for scalable and fully distributed real-time control of experiments `are being designed <https://github.com/m-labs/artiq-hardware>`_.

Website:
https://m-labs.hk/artiq
ARTIQ and its dependencies are available in the form of `conda packages <https://conda.anaconda.org/m-labs/label/main>`_ for both Linux and Windows.
Packages containing pre-compiled binary images to be loaded onto the hardware platforms are supplied for each configuration.
Like any open source software ARTIQ can equally be built and installed directly from `source <https://github.com/m-labs/artiq>`_.

ARTIQ is supported by M-Labs and developed openly.
Components, features, fixes, improvements, and extensions are funded by and developed for the partnering research groups.

Technologies employed include `Python <https://www.python.org/>`_, `Migen <https://github.com/m-labs/migen>`_, `MiSoC <https://github.com/m-labs/misoc>`_/`mor1kx <https://github.com/openrisc/mor1kx>`_, `LLVM <http://llvm.org/>`_/`llvmlite <https://github.com/numba/llvmlite>`_, and `Qt5 <http://www.qt.io/>`_.

Website: https://m-labs.hk/artiq

Copyright (C) 2014-2016 M-Labs Limited. Licensed under GNU GPL version 3.