Metadata-Version: 2.4
Name: sqdtoolz
Version: 0.9.2.dev1
Summary: toolbox to control and run experiments
Author-email: Prasanna Pakkiam <p.pakkiam@uq.edu.au>, Rohit Beriwal <r.beriwal@uq.edu.au>
Project-URL: Homepage, https://github.com/sqdlab/sqdtoolz
Keywords: control toolbox,timing
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: scipy
Requires-Dist: bokeh
Requires-Dist: openqasm3
Requires-Dist: openpulse
Requires-Dist: pandas==2.3.3
Requires-Dist: h5py
Provides-Extra: full
Requires-Dist: qcodes>=0.21.0; extra == "full"
Requires-Dist: pyvisa-py; extra == "full"
Requires-Dist: resonator-tools; extra == "full"
Requires-Dist: ply; extra == "full"
Requires-Dist: laboneq; extra == "full"
Requires-Dist: laboneq-applications; extra == "full"
Dynamic: license-file

# SQDToolz

[![UnitTests](https://github.com/sqdlab/SQDToolz/actions/workflows/UnitTests.yaml/badge.svg)](https://github.com/sqdlab/SQDToolz/actions/workflows/UnitTests.yaml)

This is a toolbox to control instruments to run a general lab experiments. This was designed to supersede *UQTools*, keeping simplicity, scalability and efficiency in check. It currently uses QCoDeS to communicate with the instruments, while providing higher level functionality such as timing control, pulse generation, automatic parameter updates and data/configuration storage.

There are two classes of documentation provided for this stack:

- [User documentation](docs/User/Readme.md)
    - [Driver-specific documentation](docs/User/InstrumentSpecific/Readme.md)
    - [Custom device documentation](docs/User/CustomDevices/Readme.md)
    - [Measurement methods](docs/User/MeasurementMethods/Readme.md)
- [Developer documentation](docs/Developer/Readme.md)


## Installation instructions:

Although SQDToolz is on PyPI to satisfy other dependency chains, it is typically installed by cloning the repository and running the setup file via pip as an editable installation. Note that it is done in the editable mode so that one may modify the stack and push changes to GIT without upsetting the pip package manager. If the goal is to simply install the latest standalone release, then just run `pip install sqdtoolz[full]` after activating the venv (i.e. no need to clone the repository etc.). Omit `[full]` if the instrumentation/control stack need not be installed.

Run Anaconda prompt and run the following command to create an environment (in this example, the name is sqdtoolz_env):

```
conda create -n sqdtoolz_env python=3.10
```

Now activate the environment:

```
activate sqdtoolz_env
```

Now choose a folder to house the SQDToolz stack (idea is to create an editable folder such that the code can be modified and pushed without upsetting the pip package manager). Once navigating to this folder, run the usual GIT clone:

```
cd C:/Users/....../myFolder/
git clone https://github.com/sqdlab/sqdtoolz.git
```

Now there is a sqdtoolz folder in the current directory. Do not enter this new folder. Simply run:

```
pip install -e sqdtoolz[full]
```

This should install all required dependencies.

## Updating new required packages

Just log into the virtual environment, navigate to the sqdtoolz folder and then run:

```
python -m pip install -e sqdtoolz[full]
```

## Basic design overview:

The stack is structured as follows:

1. Laboratory - highest level object that holds experiment parameters, runs experiments and handles saving of data and experiment+instrument configurations

2. Experiment - an object when run will generate a set of input gates (e.g. to a qubit) while receiving output signals (e.g. qubit readout). The language here is generic and agnostic to the underlying implementation.

3. Experiment-Configuration - sets up the trigger relations between the HAL instruments and handles the translations of generic pulse sequences into the actual AWG channels (e.g. mapping a qubit gate-sequence onto two AWG channels when using IQ modulation).

4. HAL - the Hardware-Abstraction-Layer is used to package raw instruments (e.g. DDG, AWG and ACQ instruments) for use in describing trigger relationships and to send commands (e.g. programming waveforms) in an instrument-agnostic manner (i.e. the interface to command different AWGs is done so via the same object properties and interface functions). The HAL abstracts the specific device into a particular type; this standardisation enables easy browsing of parameters. For example, given two microwave sources from Tektronix and Keysight, both sources will use the associated HAL object `GENmwSource` to ensure a uniform API when handling said objects (e.g. to set the output frequency, one just sets the universal `Frequency` property of the `GENmwSource` object).

5. QCoDeS-Drivers: This has all the vendor level drivers for the instruments. Most instruments have pyVISA implementation, while others use local APIs (e.g. HiSLIP or some DLL).

## Overview

Basic workflow involves:

- A `Laboratory` object is created for a given experimental run. This specifies the output directory.
- Devices that may be used are specified in the YAML (as per QCoDeS).
- Devices desired for a given experimental run are loaded from the YAML and then housed inside HAL objects
- Devices desired for a particular experiment are loaded into an `ExperimentConfiguration` object to store all HAL parameters and device settings (e.g. waveforms, frequencies, powers etc.) and trigger relationships for the timing diagram.
- When running an experiment (whether it is a default one or a custom one), the given `ExperimentConfiguration` object is used to instantiate the `Experiment` object.

When the experiment finishes, it creates a folder with the date and time-stamp. Said folder includes:

- At least, one HDF5 file with the output data (usually updated in real-time to enable live-plotting)
- `timing_diagram.png` - the timing diagram of instruments used in the current experiment highlighting the trigger relationships and the time-frames win which instruments output or acquire signals.
- `laboratory_parameters.txt` - names and values of currently defined `Variable` objects in the current experimental run
- `laboratory_configuration.txt` - a full dump of all HAL-level instrument parameters. This is used to easily browse the instrument parameters (e.g. frequency, power, sample-rates etc.). In fact, the `ExperimentViewer` UI uses this file to easily compare instrument parameters between two different experiments.
- `instrument_configuration.txt` - a QCoDeS instrument parameter dump. Used as a last resort for it is heavily obfuscated with the device-specific parameters.

Note that the folder may also include other files such as fitted plots if the derived `Experiment` object outputs said files. Other noteworthy features include:

- Flexible waveform generation engine that includes auto-compression that utilises the sequencing functionality (in supported AWGs) to lower the waveform memory usage.
- Live `ExperimentViewer` module that shows the current state of all HAL-level parameters in the experiment. It is useful to help ensure that the desired instruments are in the correct states during the experiment. It can be run via `lab.open_browser()`.
- Live plotting engine when using SQDViz.
- Structural types supported via `ExperimentSpecification`. For example, a qubit type can hold parameters such as its drive frequency, optimal drive amplitude/time for Pauli-X Gates, T1 time etc.

It should be noted that experiments can automatically interface with parameters (either inside `ExperimentSpecification` or normal `Variable` objects). For example, a Rabi experiment will automatically fit the resulting oscillations to update the currently optimal drive amplitude and time for Pauli-X gates on a given qubit. Thus, one may run cascades of experiments in an automated sequence. A usual sequence might be to run a Rabi experiment (update the currently optimal tipping $\pi/2$ amplitude), run a more optimal Ramsey experiment (update the detuning frequency) and finally run a T1 experiment with the optimal qubit drive parameters. This three-experiment combination could be run in a loop with all **parameters being updated and saved automatically in real-time**. Using the experiment grouping functionality, one may group all said experiments into a single time-stamped folder with the data IO retrieval functionality present to automatically amalgamate all results across multiple experiments (e.g. this is useful when trying to collate all T1 values when generating T1-statistics).

