artiq/RELEASE_NOTES.rst

.. Add new releases at the top to keep important stuff directly visible.

Release notes
=============

3.0 (unreleased)
----------------

* The --embed option of applets is replaced with the environment variable
  ARTIQ_APPLET_EMBED. The GUI sets this enviroment variable itself and the
  user simply needs to remove the --embed argument.
* EnvExperiment's prepare calls prepare for all its children.
* Dynamic __getattr__'s returning RPC target methods are not supported anymore.
  Controller driver classes must define all their methods intended for RPC as
  members.
* Datasets requested by experiments are by default archived into their HDF5
  output. If this behavior is undesirable, turn it off by passing
  ``archive=False`` to ``get_dataset``.
* ``seconds_to_mu`` and ``mu_to_seconds`` have become methods of the core
  device driver (use e.g. ``self.core.seconds_to_mu()``).
* AD9858 DDSes and NIST QC1 hardware are no longer supported.
* The DDS class names and setup options have changed, this requires an update of
  the device database.
* ``int(a, width=b)`` has been removed. Use ``int32(a)`` and ``int64(a)``.
* The kc705 gateware target has been renamed kc705_dds.
* ``artiq.coredevice.comm_tcp`` has been renamed ``artiq.coredevice.comm_kernel``,
  and ``Comm`` has been renamed ``CommKernel``.
* The "collision" and "busy" RTIO errors are reported through the log instead of
  raising exceptions.
* Results are still saved when ``analyze`` raises an exception.
* ``LinearScan`` and ``RandomScan`` have been consolidated into RangeScan.
* The Pipistrello is no longer supported. For a low-cost ARTIQ setup, use either
  ARTIQ 2.x with Pipistrello, or the future ARTIQ 4.x with Kasli.
* The device database is now generated by an executable Python script. To migrate
  an existing database, add ``device_db = `` at the beginning, and replace any PYON
  identifiers (``true``, ``null``, ...) with their Python equivalents
  (``True``, ``None` ...).
* Controllers are now named ``aqctl_XXX`` instead of ``XXX_controller``.
* In the device database, the "comm" device has been folded into the "core" device.
  Move the "host" argument into the "core" device, and remove the "comm" device.
* The core device log now contains important information about events such as
  RTIO collisions. A new controller ``aqctl_corelog`` must be running to forward
  those logs to the master. See the example device databases to see how to
  instantiate this controller. Using ``artiq_session`` ensures that a controller
  manager is running simultaneously with the master.
* Experiments scheduled with the "flush pipeline" option now proceed when there
  are lower-priority experiments in the pipeline. Only experiments at the current
  (or higher) priority level are flushed.


2.3
---

* When using conda, add the conda-forge channel before installing ARTIQ.


2.2
---

No further notes.


2.1
---

No further notes.


2.0
---

No further notes.


2.0rc2
------

No further notes.


2.0rc1
------

* The format of the influxdb pattern file is simplified. The procedure to
  edit patterns is also changed to modifying the pattern file and calling:
  ``artiq_rpctool.py ::1 3248 call scan_patterns`` (or restarting the bridge)
  The patterns can be converted to the new format using this code snippet::

    from artiq.protocols import pyon
    patterns = pyon.load_file("influxdb_patterns.pyon")
    for p in patterns:
        print(p)

* The "GUI" has been renamed the "dashboard".
* When flashing NIST boards, use "-m nist_qcX" or "-m nist_clock" instead of
  just "-m qcX" or "-m clock" (#290).
* Applet command lines now use templates (e.g. $python) instead of formats
  (e.g. {python}).
* On Windows, GUI applications no longer open a console. For debugging
  purposes, the console messages can still be displayed by running the GUI
  applications this way::

    python3.5 -m artiq.frontend.artiq_browser
    python3.5 -m artiq.frontend.artiq_dashboard

  (you may need to replace python3.5 with python)
  Please always include the console output when reporting a GUI crash.
* The result folders are formatted "%Y-%m-%d/%H instead of "%Y-%m-%d/%H-%M".
  (i.e. grouping by day and then by hour, instead of by day and then by minute)
* The ``parent`` keyword argument of ``HasEnvironment`` (and ``EnvExperiment``)
  has been replaced. Pass the parent as first argument instead.
* During experiment examination (and a fortiori repository scan), the values of
  all arguments are set to ``None`` regardless of any default values supplied.
* In the dashboard's experiment windows, partial or full argument recomputation
  takes into account the repository revision field.
* By default, ``NumberValue`` and ``Scannable`` infer the scale from the unit
  for common units.
* By default, artiq_client keeps the current persist flag on the master.
* GUI state files for the browser and the dashboard are stores in "standard"
  locations for each operating system. Those are
  ``~/.config/artiq/2/artiq_*.pyon`` on Linux and
  ``C:\Users\<username>\AppData\Local\m-labs\artiq\2\artiq_*.pyon`` on
  Windows 7.
* The position of the time cursor is kept across experiments and RTIO resets
  are manual and explicit (inter-experiment seamless handover).
* All integers manipulated by kernels are numpy integers (numpy.int32,
  numpy.int64). If you pass an integer as a RPC argument, the target function
  receives a numpy type.


1.3
---

No further notes.


1.2
---

No further notes.


1.1
---

* TCA6424A.set converts the "outputs" value to little-endian before programming
  it into the registers.


1.0
---

No further notes.


1.0rc4
------

* setattr_argument and setattr_device add their key to kernel_invariants.


1.0rc3
------

* The HDF5 format has changed.

  * The datasets are located in the HDF5 subgroup ``datasets``.
  * Datasets are now stored without additional type conversions and annotations
    from ARTIQ, trusting that h5py maps and converts types between HDF5 and
    python/numpy "as expected".

* NumberValue now returns an integer if ``ndecimals`` = 0, ``scale`` = 1 and
  ``step`` is integer.


1.0rc2
------

* The CPU speed in the pipistrello gateware has been reduced from 83 1/3 MHz to
  75 MHz. This will reduce the achievable sustained pulse rate and latency
  accordingly. ISE was intermittently failing to meet timing (#341).
* set_dataset in broadcast mode no longer returns a Notifier. Mutating datasets
  should be done with mutate_dataset instead (#345).


1.0rc1
------

* Experiments (your code) should use ``from artiq.experiment import *``
  (and not ``from artiq import *`` as previously)
* Core device flash storage has moved due to increased runtime size.
  This requires reflashing the runtime and the flash storage filesystem image
  or erase and rewrite its entries.
* ``RTIOCollisionError`` has been renamed to ``RTIOCollision``
* the new API for DDS batches is::

    with self.core_dds.batch:
       ...

  with ``core_dds`` a device of type ``artiq.coredevice.dds.CoreDDS``.
  The dds_bus device should not be used anymore.
* LinearScan now supports scanning from high to low. Accordingly,
  its arguments ``min/max`` have been renamed to ``start/stop`` respectively.
  Same for RandomScan (even though there direction matters little).