How to write a config file
=============================

In order to use qFabric to control AWGs, a config file is needed to specify the AWGs.
The config file uses `TOML`_, a configuration format that is easy to read.
This page contains information about how to write a config file.

Create a TOML file
-----------------------
First, create a config file in any path you want with any name.
In this tutorial, We name it ``example_config.toml``.
We recommend to place your config file in a location that is backed up regularly or version tracked.

Specify the config verison
----------------------------
In ``example_config.toml``, add the following lines.

.. code-block:: toml

   [config]
   version = 1

This specify the version of the config. The latest config version is 1.

Config version history
^^^^^^^^^^^^^^^^^^^^^^^^^
v1: The first config version.

Add start and stop step information
---------------------------------------
Then we want to add information about the start step and the stop step.
The start and stop steps are optional. They are inserted to the start and end of each sequence.
They are useful for cases where a digital channel is needed to synchronize other AWG devices.
Certain AWG devices may not run the last step in a sequence. In this case, the stop step
is an empty step that do not change the output if not run.

.. code-block:: toml

   [start_step]
   use = true
   duration = 10e-6
   digital_channel_synchronize = 0  # comment out if no digital channel is used for synchronization

   [stop_step]
   use = true
   duration = 10e-6

Set ``use`` to ``true`` or ``false`` to turn the start or stop steps on or off.
Set ``duration`` to the desired duration of the step.
The ``digital_channel_synchronize`` setting defines the digital channel used set to high
during the start step to synchronize other AWG devices.
If this line is deleted or commented, no digital channel is automatically turned on during the start step.

Add an AWG device
----------------------------
After that, We want to define an AWG device controlled by qFabric.
We assume that the first device is a Spectrum Instruments m4i.6622 AWG device.
qFabric has built-in support of this device.

To define this device, add the following lines.

.. code-block:: toml

   [[awgs]]
   name = "m4i6622_1"

   segmenter_module = "qfabric.planner.segmenter.m4i6622"
   segmenter_class = "M4i6622Segmenter"
   device_module = "qfabric.programmer.device.m4i6622"
   device_class = "M4i6622Device"

Here ``[[awgs]]`` specifies an entry added to the ``awg`` array of this config.
We define the ``name`` of the AWG, which can be customized to any text.

We also define the dotted python module paths and class names that
support this AWG model (See :doc:`../developers/add_awg_support` for adding new AWG support),
which are subclasses of :class:`~qfabric.planner.segmenter.Segmenter`
and :class:`~qfabric.programmer.device.Device`.
These classes can be in any module that can be imported by python.

After this, we define the arguments for the segmenter (:class:`~qfabric.planner.segmenter.m4i6622.M4i6622Segmenter`):

.. code-block:: toml

   # the following lines needs to be indented.
     [awgs.segmenter_config]
     analog_channels = [0, 1, 2, 3]
     digital_channels = [0, 1, 2]
     analog_channels_to_store_digital_data = [1, 2, 3]

All required parameters of the segmenter class must be defined here,
under the same names as the argument names defined in the segmenter class ``__init__``

The following arguments are required by any segmenter class:

* ``analog_channels``: List of analog channels defined on this device.
* ``digital_channels``: List of digital channels defined on this device.

Then we define the arguments for the device (:class:`~qfabric.programmer.device.m4i6622.M4i6622Device`):

.. code-block:: toml

   # the following lines needs to be indented.
     [awgs.device_config]
     resource = "/dev/spcm0"
     external_clock_frequency = 10000000

Again, all required parameters of the device class must be defined here
(except the ``segmenter`` parameter, which is the segmenter object generated by the config above),
under the same names as the argument name defined in the device class ``__init__``.

The following arguments are required by any device class:

* ``resource``: Path to the AWG device.

Add another AWG device
----------------------------
To control more than one AWG devices, we can add another entry in the ``awg`` array:

.. code-block:: toml

   [[awgs]]
   name = "m4i6622_2"

   segmenter_module = "qfabric.planner.segmenter.m4i6622"
   segmenter_class = "M4i6622Segmenter"
   device_module = "qfabric.programmer.device.m4i6622"
   device_class = "M4i6622Device"

     [awgs.segmenter_config]
     analog_channels = [4, 5, 6, 7]
     digital_channels = [3, 4, 5]
     analog_channels_to_store_digital_data = [5, 6, 7]

     [awgs.device_config]
     resource = "/dev/spcm1"
     external_clock_frequency = 10000000

Note that the ``analog_channels`` or ``digital_channels`` defined by multple AWG devices
cannot contain the same indices.

Use the config file
----------------------------
To use the config file, run the following code in python:

.. code-block:: python

   from qfabric import ExperimentManager

   config_file_path = "example_config.toml"
   manager = ExperimentManager(config_file_path)

.. _TOML: https://toml.io/en/