m-labs · Apr 9, 2016 · Apr 9, 2016 · Apr 9, 2016 · Apr 9, 2016
Showing with 100 additions and 84 deletions.

+22 −10 README.rst

+56 −61 doc/manual/installing.rst

+22 −13 doc/manual/introduction.rst
diff --git a/README.rst b/README.rst
@@ -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.
diff --git a/doc/manual/installing.rst b/doc/manual/installing.rst
@@ -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``.
diff --git a/doc/manual/introduction.rst b/doc/manual/introduction.rst
@@ -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.