Zurich Instruments Toolkit

https://docs.zhinst.com/zhinst-toolkit/en/latest/
Admin
Zurich Instruments Toolkit (zhinst-toolkit) is a high-level Python driver package for communicating...
Tokens:996,930
Snippets:6,947
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Documentation Dependencies

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/contributing/index

Installs the required Python packages for building the documentation, as specified in 'docs/requirements.txt', ensuring all tools for Sphinx are available.

```bash
pip install -r docs/requirements.txt
```

--------------------------------

### Example Usage of zhinst-toolkit Device Settings Access

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.modules.device_settings_module.DeviceSettingsModule.read

This Python example demonstrates the recommended way to access device settings using the `zhinst-toolkit` library, by directly calling the device object or its sub-modules, rather than using the `read()` method.

```Python
device = session.connect_device()
...
device()
<all device settings>
device.demods()
<all demodulator settings>
```

--------------------------------

### Build Jupyter Notebooks from Markdown Examples

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/contributing/index

Converts local Markdown example files into Jupyter Notebooks using a Python script. This is useful for turning documentation into executable and interactive notebooks.

```bash
python scripts/generate_notebooks.py local
```

--------------------------------

### Python Example: Initializing and Using Sequence Class

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_modules/zhinst/toolkit/sequence

Illustrates how to create a `Sequence` object, assign waveforms and constants, and set the sequencer code. The example also shows the resulting sequencer code generated by converting the `Sequence` object to a string, which includes automatically added constants and waveform declarations.

```python
waveforms = Waveforms()
waveforms[0] = (0.5*np.ones(1008), -0.2*np.ones(1008), np.ones(1008))
sequencer = Sequence()
sequencer.constants["PULSE_WIDTH"] = 10e-9 #ns
sequencer.waveforms = waveforms
sequencer.code = """\
    // Hello World
    repeat(5)
    ...
    """
# To generate the final sequencer code:
# print(str(sequencer))
```

```sequencer
// Constants
const PULSE_WIDTH = 10e-9;
// Waveforms declaration
assignWaveIndex(placeholder(1008, true, false), placeholder(1008, false, false), 0);
assignWaveIndex(placeholder(1008, false, false), placeholder(1008, false, false), 2);
// Hello World
repeat(5)
...
```

--------------------------------

### Install zhinst-toolkit Python Package

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/first_steps/installation

This command uses pip, the Python package installer, to download and install the zhinst-toolkit library along with its required dependencies from PyPI. It's the standard method for setting up the toolkit in a Python environment.

```bash
pip install zhinst-toolkit
```

--------------------------------

### Start Method API Reference

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/genindex

API reference for methods that initiate processes, including a Transaction method and a SHFQA method for continuous software triggering.

```APIDOC
zhinst.toolkit.nodetree.nodetree.Transaction.start()
```

```APIDOC
zhinst.toolkit.driver.devices.shfqa.SHFQA.start_continuous_sw_trigger()
```

--------------------------------

### Python Example: Creating and Using a Sequence Object

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.sequence.Sequence

This example demonstrates how to initialize a `Sequence` object, define waveforms using `Waveforms`, set constants, and assign sequencer code. It illustrates how the `Sequence` class automatically generates the full sequencer code, including constant declarations and waveform assignments, when converted to a string.

```Python
waveforms = Waveforms()
waveforms[0] = (0.5*np.ones(1008), -0.2*np.ones(1008), np.ones(1008))
sequencer = Sequence()
sequencer.constants["PULSE_WIDTH"] = 10e-9 #ns
sequencer.waveforms = waveforms
sequencer.code = """
// Hello World
repeat(5)
...
"""
str(sequencer)
# Expected Output:
# // Constants
# const PULSE_WIDTH = 10e-9;
# // Waveforms declaration
# assignWaveIndex(placeholder(1008, true, false), placeholder(1008, \
#     false, false), 0);
# assignWaveIndex(placeholder(1008, false, false), placeholder(1008, \
#     false, false), 2);
# // Hello World
# repeat(5)
# ...
```

--------------------------------

### Build HTML Documentation with Sphinx

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/contributing/index

Builds the HTML documentation and examples using Sphinx. The 'local' or 'remote' argument can be passed to control the build process, generating the final documentation files.

```bash
make html [local | remote]
```

--------------------------------

### Documenting QuantumSystemHub.run Method

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_sources/_autosummary/zhinst.toolkit.driver.devices.quantum_system_hub.QuantumSystemHub.run.rst

API documentation for the `run` method of the `QuantumSystemHub` class, detailing its module and class context as automatically generated by Sphinx/reStructuredText.

```APIDOC
Module: zhinst.toolkit.driver.devices.quantum_system_hub
Class: QuantumSystemHub
  Method: run
    Description: Automatically documented method. Specific parameters and return types are not detailed in the provided source directive.
```

--------------------------------

### Deep Get Operation Example

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.nodetree.node.Node

Example of using the 'deep' flag for a get operation, which returns both the value and a timestamp from the device, indicating a blocking read.

```python
nodetree.demods[0].freq(deep=True)
(343283971893, 2000)
```

--------------------------------

### Retrieve Node Value from Data Server

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/first_steps/quickstart

This example shows how to access and retrieve the current value of a node in the LabOne Data Server's hierarchical node tree using the session object. It demonstrates accessing the `debug.level` node to get its current status.

```Python
session.debug.level()
```

--------------------------------

### API Overview for zhinst.toolkit Package

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.devices.qhub

Provides a hierarchical overview of the `zhinst.toolkit` package, detailing its submodules and the classes contained within them. This includes the `command_table` submodule with its `CommandTable`, `HeaderEntry`, and `ListEntry` classes, outlining their respective members.

```APIDOC
Module: zhinst.toolkit
  Submodule: command_table
    Class: CommandTable
      - as_dict
      - clear
      - is_valid
      - update
      - active_validation
      - header
      - table
    Class: HeaderEntry
      - version
    Class: ListEntry
      - as_list
```

--------------------------------

### NodeTree Device Node Access Examples (Python)

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_modules/zhinst/toolkit/nodetree/nodetree

Illustrates common usage patterns for accessing device-specific nodes with the NodeTree, including hiding device prefixes for cleaner access.

```Python
>>> nodetree = NodeTree(daq)
>>> nodetree.dev123.demods[0].freq
/dev123/demods/0/freq
>>> nodetree = NodeTree(daq, prefix_hide = "dev123", list_nodes = ["/dev123/*"])
>>> nodetree.demods[0].freq
/dev123/demods/0/freq
```

--------------------------------

### Get Single Node Value

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/first_steps/nodetree

Shows how to retrieve the value of a specific node using the overloaded call operator. This example gets the 'order' property of the first demodulator.

```Python
device.demods[0].order()
```

--------------------------------

### API Documentation for zhinst.toolkit.command_table.ListEntry

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.devices.quantum_system_hub.QuantumSystemHub.arm_and_run

API reference for the zhinst.toolkit.command_table.ListEntry class, including methods to convert list entries.

```APIDOC
Class: zhinst.toolkit.command_table.ListEntry
Methods:
  as_list()
```

--------------------------------

### Get Auxiliary Input Node Value

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/first_steps/nodetree

Shows how to retrieve the value of an auxiliary input node using the call operator. This example gets the value of the first auxiliary input.

```Python
device.auxins[0]()
```

--------------------------------

### API Documentation for zhinst.toolkit.nodetree

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.session.Session.connect_device

Outlines the structure of the `zhinst.toolkit.nodetree` module, covering `connection_dict`, `helper` utilities, `node` definitions, and core `nodetree` components.

```APIDOC
connection_dict:
  ConnectionDict
helper:
  create_or_append_set_transaction()
  not_callable_in_transactions()
  resolve_wildcards_labone()
  NodeDict
  lazy_property()
node:
  Node
  NodeEnum
  NodeEnumMeta
  NodeInfo
  NodeList
nodetree:
  Connection
  NodeTree
  Transaction
```

--------------------------------

### API Reference: zhinst.toolkit.driver.devices.qhub module

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.session.Session.from_existing_connection

Documents the qhub module within the zhinst.toolkit.driver.devices package, providing API details for QHub devices.

```APIDOC
Module: zhinst.toolkit.driver.devices.qhub
```

--------------------------------

### Access Device-Specific Nodes and Functionalities

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/first_steps/quickstart

This example shows how to access device-specific nodes and functionalities once a device object is obtained from the session. It retrieves the frequency of a demodulator and lists available attributes for a demodulator object, highlighting the `demods` attribute.

```Python
device = session.devices['dev1234']
device.demods[0].freq()
dir(device.demods[0])
```

--------------------------------

### Generate Sequencer Code Snippet with Python

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.waveform.Waveforms.get_sequence_snippet

Demonstrates how to use the `Waveform` class and its `assign_waveform` method to define waveforms, then generate a sequencer code snippet using `get_sequence_snippet()`. The example shows the Python setup code and the resulting sequencer output.

```Python
waveform = Waveform()
waveform.assign_waveform(
        0,
        wave1=Wave(
            np.ones(1008),
            name="w1",
            output=OutputType.OUT1 | OutputType.OUT2
        ),
        wave2=Wave(
            -np.ones(1008),
            name="w2",
            output=OutputType.OUT2),
        markers=15 * np.ones(1008),
    )
waveform.get_sequence_snippet()
```

```Sequencer
wave w1 = placeholder(1008, true, true);
wave w2 = placeholder(1008, true, true);
assignWaveIndex(1, 2, w1, 2, w2, 0);
```

--------------------------------

### API Reference: zhinst.toolkit.driver.devices.quantum_system_hub module

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.session.Session.from_existing_connection

Documents the quantum_system_hub module within the zhinst.toolkit.driver.devices package, providing API details for Quantum System Hub devices.

```APIDOC
Module: zhinst.toolkit.driver.devices.quantum_system_hub
```

--------------------------------

### API Documentation for zhinst.toolkit.driver

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.session.Session.connect_device

Provides an overview of the `zhinst.toolkit.driver` module, listing its sub-modules for devices, general modules, nodes, and parsers.

```APIDOC
devices:
  base
  hdawg
  pqsc
  qhub
  quantum_system_hub
  shfqa
  shfqc
  shfsg
  uhfli
  uhfqa
modules:
  base_module
  daq_module
  device_settings_module
  impedance_module
  pid_advisor_module
  precompensation_advisor_module
  scope_module
  shfqa_sweeper
  sweeper_module
nodes:
  awg
  command_table_node
  multistate
  readout
  shfqa_scope
  spectroscopy
parsers:
  Parse
```

--------------------------------

### Python NodeTree Magic Method Usage Examples

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_modules/zhinst/toolkit/nodetree/node

Illustrates common usage patterns for various Python magic methods when interacting with `Node` objects within a `NodeTree` structure, demonstrating how to check for node presence, iterate, compare, and get length.

```python
"freq" in nodetree.demods[0]
```

```python
for node, info in nodetree.demods["*"]
```

```python
nodetree.demods[0].freq == nodetree.demods["*/freq"]
```

```python
len(nodetree.demods)
```

```python
if nodetree.demods[0].freq:
```

--------------------------------

### Execute Data Acquisition Measurement Loop

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/examples/daq_module

Initializes plotting environment and variables for the measurement. It starts the DAQ module execution and enters a loop to continuously read and plot data until the module finishes or a timeout occurs, ensuring all data is processed.

```python
import time

ts0 = np.nan
timeout = 1.5 * TOTAL_DURATION
start_time = time.time()
results = {x: [] for x in sample_nodes}

fig = plt.figure()
ax1 = fig.add_subplot(111)
ax1.set_xlabel("Time ($s$)")
ax1.set_ylabel("Subscribed signals")
ax1.set_xlim([0, TOTAL_DURATION])
ax1.grid()

# Start recording data
daq_module.execute()

while time.time() - start_time < timeout:
    results, ts0 = read_and_plot_data(daq_module, results, ts0)
    if daq_module.raw_module.finished():
        # Once finished, call once more to get the potential remaining data.
        results, ts0 = read_and_plot_data(daq_module, results, ts0)
        break

    time.sleep(BURST_DURATION)
```

--------------------------------

### AWG.enable_sequencer API Documentation

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.nodes.awg.AWG.enable_sequencer

Documents the `enable_sequencer` method of the `AWG` class, which starts the sequencer of a specific channel. It highlights its synchronous behavior, advising asynchronous alternatives for multi-instrument setups, and provides details on parameters, return types, and potential runtime errors.

```APIDOC
AWG.enable_sequencer(*, single: bool) -> None

Description: Starts the sequencer of a specific channel.

Warning: This function is synchronous and blocks until the sequencer is enabled. When working with multiple instruments this function is the wrong approach and the sequencer should be enabled asynchronously.

Parameters:
  single (bool): Flag if the sequencer should be disabled after finishing execution.

Raises:
  RuntimeError: If the sequencer could not be enabled.

Return type: None

Changed in version 0.5.0: Check the acknowledged value instead of using wait_for_state_change.
```

--------------------------------

### QHub Class API Documentation

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.devices.qhub.QHub

API documentation for the QHub class, detailing its constructor, inherited base class, parameters, and available methods for interacting with the Zurich Instruments QHub.

```APIDOC
class QHub(serial: str, device_type: str, session: Session)
  Bases: QuantumSystemHub
  Description: High-level driver for the Zurich Instruments QHub.

  Methods:
    arm(*[, deep, repetitions, holdoff])
      Description: Prepare QHub for triggering the instruments.

  Parameters:
    serial (str)
    device_type (str)
    session (Session)
```

--------------------------------

### API Reference for zhinst.toolkit.session Module

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.devices.quantum_system_hub.QuantumSystemHub.wait_done

Documents the classes and methods within the `zhinst.toolkit.session` module, including device management, module creation, and session control functionalities.

```APIDOC
zhinst.toolkit.session:
  Devices:
    connected: method
    created_devices: method
    visible: method
  HF2Devices:
    add_hf2_device: method
    connected: method
    visible: method
  ModuleHandler:
    create_awg_module: method
    create_daq_module: method
    create_device_settings_module: method
    create_impedance_module: method
    create_mds_module: method
    create_pid_advisor_module: method
    create_precompensation_advisor_module: method
    create_qa_module: method
    create_scope_module: method
    create_shfqa_sweeper: method
    create_sweeper_module: method
    awg: property
    daq: property
    device_settings: property
    impedance: property
    mds: property
    pid_advisor: property
    precompensation_advisor: property
    qa: property
    scope: property
    shfqa_sweeper: property
    sweeper: property
  PollFlags:
    DETECT_AND_THROW: constant
    DETECT: constant
    FILL: constant
    DEFAULT: constant
  Session:
    clone_underlying_session: method
    connect_device: method
    disconnect_device: method
    from_existing_connection: method
    poll: method
    raw_path_to_node: method
    set_transaction: method
    sync: method
    daq_server: property
    devices: property
    is_hf2_server: property
    modules: property
    multi_transaction: property
    server_host: property
    server_port: property
```

--------------------------------

### Read Node Value from LabOne Node Tree (Python)

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_sources/first_steps/quickstart.rst

Demonstrates how to read a value from the LabOne node tree, which organizes all settings and data hierarchically. The node tree can be accessed like a nested dictionary or more readably by attribute. This example retrieves the current debug level.

```python
session.debug.level()
'status'
```

--------------------------------

### Establish Session to LabOne Data Server (Python)

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_sources/first_steps/quickstart.rst

Connects to the LabOne Data Server using `zhinst.toolkit.Session`. This session object serves as the primary entry point for all interactions with Zurich Instruments devices and the LabOne API. The example uses 'localhost', but it can be replaced with a remote server's address.

```python
from zhinst.toolkit import Session
session = Session("localhost")
```

--------------------------------

### Install zhinst-toolkit using pip

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_sources/first_steps/installation.rst

This command installs the zhinst-toolkit Python package and its automatically managed dependencies using pip, the standard Python package installer. Ensure you have Python 3.7 or newer installed.

```Shell
$ pip install zhinst-toolkit
```

--------------------------------

### zhinst.toolkit.command_table API Documentation

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.devices.quantum_system_hub.QuantumSystemHub.wait_done

API documentation for the zhinst.toolkit.command_table module, including classes like ListEntry, ParentEntry, and ParentNode, and their associated methods.

```APIDOC
zhinst.toolkit.command_table:
  ListEntry:
    range()
  ParentEntry:
    as_dict()
    clear()
    info()
  ParentNode:
    is_empty()
```

--------------------------------

### Change Node Value in LabOne Node Tree (Python)

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_sources/first_steps/quickstart.rst

Illustrates how to modify a node's value within the LabOne node tree. Values are updated by passing the desired new value as an argument to the node's call operation. This example changes the debug level to 'warning' and then verifies the change.

```python
session.debug.level('warning')
session.debug.level()
'warning'
```

--------------------------------

### Define and Apply Custom Node Parsers in zhinst.toolkit

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/first_steps/nodetree

This snippet illustrates how to define and apply custom `GetParser` and `SetParser` functions to a node in `zhinst.toolkit`. These functions are executed before getting or setting a value, allowing for custom processing. The example also shows how to temporarily disable these parsers using `parse=False`.

```Python
def get_print(value):
    print(f"Received <{value}> from LabOne")
    return value

def set_print(value):
    print(f"Will send <{value}> to LabOne")
    return value

device.root.update_node(
    device.demods[0].enable,
    {
        "GetParser": get_print,
        "SetParser": set_print,
    }
)

device.demods[0].enable("on")
device.demods[0].enable(parse= False)
```

--------------------------------

### API Documentation for zhinst.toolkit.session.Session

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.devices.quantum_system_hub.QuantumSystemHub.arm_and_run

API reference for the zhinst.toolkit.session.Session class, detailing its methods for session management and properties for accessing server and device information.

```APIDOC
Class: zhinst.toolkit.session.Session
Methods:
  clone_underlying_session()
  connect_device()
  disconnect_device()
  from_existing_connection()
  poll()
  raw_path_to_node()
  set_transaction()
  sync()
Properties:
  daq_server
  devices
  is_hf2_server
  modules
  multi_transaction
  server_host
  server_port
```

--------------------------------

### API Reference: zhinst.toolkit.sequence Module

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.devices.shfqa.SHFQA.start_continuous_sw_trigger

Documentation for the `sequence` module within `zhinst.toolkit`, focusing on the `Sequence` class and its methods for managing instrument sequences.

```APIDOC
zhinst.toolkit.sequence:
  Sequence:
    - to_string()
    - code()
    - command_table()
    - constants()
    - waveforms()
```

--------------------------------

### Configure Instrument Demodulators and Signal Outputs

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/examples/sweeper_module

Configures the input and output channels, demodulator settings (enable, rate, ADC select, order, time constant, oscillator select, harmonic), and signal output settings (on, enables, range, amplitudes) for the connected Zurich Instruments device. This setup prepares the device for signal acquisition and generation within a transaction block for atomic updates.

```Python
OUT_CHANNEL = 0
OUT_MIXER_CHANNEL = 1 # UHFLI: 3, HF2LI: 6, MFLI: 1
IN_CHANNEL = 0
DEMOD_INDEX = 0
OSC_INDEX = 0

with device.set_transaction():
    device.sigins[IN_CHANNEL].ac(0)
    device.sigins[IN_CHANNEL].range(0.2)

    device.demods[DEMOD_INDEX].enable(True)
    device.demods[DEMOD_INDEX].rate(10e3)
    device.demods[DEMOD_INDEX].adcselect(IN_CHANNEL)
    device.demods[DEMOD_INDEX].order(4)
    device.demods[DEMOD_INDEX].timeconstant(0.01)
    device.demods[DEMOD_INDEX].oscselect(OSC_INDEX)
    device.demods[DEMOD_INDEX].harmonic(1)

    device.sigouts[OUT_CHANNEL].on(True)
    device.sigouts[OUT_CHANNEL].enables[OUT_MIXER_CHANNEL](1)
    device.sigouts[OUT_CHANNEL].range(1)
    device.sigouts[OUT_CHANNEL].amplitudes(OUT_MIXER_CHANNEL)
```

--------------------------------

### Configure zhinst-toolkit Sweeper Module Parameters

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/examples/sweeper_module

Initializes and configures the Sweeper module for a frequency sweep. It sets the target device, defines the sweep range (start, stop, sample count), specifies the grid node for sweeping (oscillator frequency), and configures various sweep parameters like loop count, bandwidth control, bandwidth overlap, scan type, settling time, inaccuracy, and averaging settings.

```Python
# Specify the number of sweeps to perform back-to-back.
LOOPCOUNT = 2

sweeper = session.modules.sweeper
sweeper.device(device)

sweeper.gridnode(device.oscs[OSC_INDEX].freq)
sweeper.start(4e3)
sweeper.stop(500e3) # 500e3 for MF devices, 50e6 for others
sweeper.samplecount(100)
sweeper.xmapping(1)
sweeper.bandwidthcontrol(2)
sweeper.bandwidthoverlap(0)
sweeper.scan(0)
sweeper.loopcount(LOOPCOUNT)
sweeper.settling.time(0)
sweeper.settling.inaccuracy(0.001)
sweeper.averaging.tc(10)
sweeper.averaging.sample(10)
```

--------------------------------

### API Documentation for zhinst.toolkit.sequence.Sequence

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.devices.quantum_system_hub.QuantumSystemHub.arm_and_run

API reference for the zhinst.toolkit.sequence.Sequence class, including methods to convert sequences to strings and properties for accessing sequence components like code, command tables, constants, and waveforms.

```APIDOC
Class: zhinst.toolkit.sequence.Sequence
Methods:
  to_string()
Properties:
  code
  command_table
  constants
  waveforms
```

--------------------------------

### API Reference for zhinst.toolkit.driver.devices.qhub

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.nodes.awg

API reference for the `zhinst.toolkit.driver.devices.qhub` module.

```APIDOC
module zhinst.toolkit.driver.devices.qhub
```

--------------------------------

### Compile Sequencer Program Example

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_modules/zhinst/toolkit/driver/nodes/awg

Example usage of the `compile_sequencer_program` method to compile a sequencer program for a specific device.

```Python
elf, compile_info = device.awgs[0].compile_sequencer_program(seqc)
```

--------------------------------

### zhinst.toolkit.session Module API Reference

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.devices.qhub.QHub.arm

Detailed API documentation for the `zhinst.toolkit.session` module, which provides core functionalities for managing devices, handling modules, and controlling the session with Zurich Instruments devices. It includes classes for device discovery, module creation, and session-wide operations.

```APIDOC
Module: zhinst.toolkit.session
  Class: Devices
    Properties:
      connected
      created_devices
      visible
  Class: HF2Devices
    Methods:
      add_hf2_device()
    Properties:
      connected
      visible
  Class: ModuleHandler
    Methods:
      create_awg_module()
      create_daq_module()
      create_device_settings_module()
      create_impedance_module()
      create_mds_module()
      create_pid_advisor_module()
      create_precompensation_advisor_module()
      create_qa_module()
      create_scope_module()
      create_shfqa_sweeper()
      create_sweeper_module()
    Properties:
      awg
      daq
      device_settings
      impedance
      mds
      pid_advisor
      precompensation_advisor
      qa
      scope
      shfqa_sweeper
      sweeper
  Class: PollFlags
    Members:
      DETECT_AND_THROW
      DETECT
      FILL
      DEFAULT
  Class: Session
    Methods:
      clone_underlying_session()
      connect_device()
      disconnect_device()
      from_existing_connection()
      poll()
      raw_path_to_node()
      set_transaction()
      sync()
    Properties:
      daq_server
      devices
      is_hf2_server
      modules
      multi_transaction
      server_host
      server_port
```

--------------------------------

### Install Python Dependencies

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/contributing/index

Installs the required Python packages listed in the 'requirements.txt' file using pip, ensuring all necessary libraries for the project are available.

```bash
pip install -r requirements.txt
```

--------------------------------

### DeviceSettingsModule.read() API Reference

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.modules.device_settings_module.DeviceSettingsModule.read

API documentation for the `read` method of `DeviceSettingsModule`, detailing its signature, purpose, return type, and a crucial note regarding its recommended usage.

```APIDOC
DeviceSettingsModule.read() -> NodeDict
  Description: Read device settings.
  Note: It is not recommend to use this function to read the device settings. Instead one can use the zhinst-toolkit functionality to read all settings from a device/subtree from the device directly by calling it.
  Returns: Device settings.
  Return Type: NodeDict
```

--------------------------------

### Install zhinst-toolkit in Editable Mode

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/contributing/index

Installs the 'zhinst-toolkit' package in editable mode, allowing changes to the source code to be reflected without reinstallation, which is ideal for development.

```bash
pip install -e .
```

--------------------------------

### Sequence Generation

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.devices.quantum_system_hub.QuantumSystemHub.arm_and_run

Documentation for the Sequence class, including methods for converting sequences to strings and accessing their components like code, command table, constants, and waveforms.

```APIDOC
zhinst.toolkit.sequence.Sequence.to_string
zhinst.toolkit.sequence.Sequence.code
zhinst.toolkit.sequence.Sequence.command_table
zhinst.toolkit.sequence.Sequence.constants
zhinst.toolkit.sequence.Sequence.waveforms
```

--------------------------------

### Method: get() (ConnectionDict)

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/genindex

Retrieves a value using the get() method of the ConnectionDict class, providing dictionary-like access to connection values.

```APIDOC
zhinst.toolkit.nodetree.connection_dict.ConnectionDict.get()
```

--------------------------------

### Create DeviceSettingsModule in Python

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_modules/zhinst/toolkit/session

Creates an instance of `DeviceSettingsModule`. The resulting module provides access to the nodetree and its underlying `zhinst.core` module via `raw_module`. New instances consume resources as they establish a new DataServer session and are not managed by the toolkit directly; a managed instance is available via `device_settings_module`.

```Python
def create_device_settings_module(self) -> tk_modules.DeviceSettingsModule:
    """Create an instance of the DeviceSettingsModule.

    The resulting Module will have the nodetree accessible. The underlying
    zhinst.core Module can be accessed through the `raw_module`
    property.

    The new instance establishes a new session to the DataServer.
    New instances should therefor be created carefully since they consume
    resources.

    The new module is not managed by toolkit. A managed instance is provided
    by the property `device_settings_module`.

    Returns:
        Created module
    """
    return tk_modules.DeviceSettingsModule(
        self._session.daq_server.deviceSettings(), self._session
    )
```

```APIDOC
create_device_settings_module(self) -> tk_modules.DeviceSettingsModule
  Description: Create an instance of the DeviceSettingsModule.
  Details:
    - The resulting Module will have the nodetree accessible.
    - The underlying zhinst.core Module can be accessed through the `raw_module` property.
    - The new instance establishes a new session to the DataServer. New instances should therefor be created carefully since they consume resources.
    - The new module is not managed by toolkit. A managed instance is provided by the property `device_settings_module`.
  Returns: Created module
```

--------------------------------

### NodeTree Attribute Access Example (Python)

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_modules/zhinst/toolkit/nodetree/nodetree

Demonstrates accessing nodes using attribute notation with the NodeTree instance. This example shows how to navigate nested nodes.

```Python
>>> nodetree = NodeTree(connection)
>>> nodetree.example.nodes[8].test
    /example/nodes/8/test
```

--------------------------------

### Method: get() (Connection)

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/genindex

Retrieves a value using the get() method of the Connection class, typically used to fetch node values from the device.

```APIDOC
zhinst.toolkit.nodetree.nodetree.Connection.get()
```

--------------------------------

### zhinst-toolkit Session and Waveform API Reference

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.modules.shfqa_sweeper.SHFQASweeper.run

Comprehensive API documentation for the `zhinst.toolkit.session` and `zhinst.toolkit.waveform` modules. It outlines the available classes, their methods, and properties for interacting with Zurich Instruments devices, including device discovery, module creation, data polling, and waveform generation/assignment.

```APIDOC
zhinst.toolkit.session:
  Devices:
    connected: property
    created_devices: property
    visible: property
  HF2Devices:
    add_hf2_device(): method
    connected: property
    visible: property
  ModuleHandler:
    create_awg_module(): method
    create_daq_module(): method
    create_device_settings_module(): method
    create_impedance_module(): method
    create_mds_module(): method
    create_pid_advisor_module(): method
    create_precompensation_advisor_module(): method
    create_qa_module(): method
    create_scope_module(): method
    create_shfqa_sweeper(): method
    create_sweeper_module(): method
    awg: property
    daq: property
    device_settings: property
    impedance: property
    mds: property
    pid_advisor: property
    precompensation_advisor: property
    qa: property
    scope: property
    shfqa_sweeper: property
    sweeper: property
  PollFlags: Enum
    DETECT_AND_THROW: constant
    DETECT: constant
    FILL: constant
    DEFAULT: constant
  Session:
    clone_underlying_session(): method
    connect_device(): method
    disconnect_device(): method
    from_existing_connection(): method
    poll(): method
    raw_path_to_node(): method
    set_transaction(): method
    sync(): method
    daq_server: property
    devices: property
    is_hf2_server: property
    modules: property
    multi_transaction: property
    server_host: property
    server_port: property

zhinst.toolkit.waveform:
  OutputType: Enum
    OUT1: constant
    OUT2: constant
  Wave: class
  Waveforms:
    assign_native_awg_waveform(): method
    assign_waveform(): method
    get_raw_vector(): method
    get_sequence_snippet(): method
    validate(): method
```

--------------------------------

### Deep Set Operation Example

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.nodetree.node.Node

Example of using the 'deep' flag for a set operation, which returns the value acknowledged by the device, useful for verifying precise floating-point settings.

```python
nodetree.demods[0].freq(29999,99999, deep=True)
3000
```

--------------------------------

### API Reference: zhinst.toolkit.driver.devices.shfqc module

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.session.Session.from_existing_connection

Documents the shfqc module within the zhinst.toolkit.driver.devices package, providing API details for SHFQc devices.

```APIDOC
Module: zhinst.toolkit.driver.devices.shfqc
```

--------------------------------

### API Reference for zhinst.toolkit.driver.devices.quantum_system_hub

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.nodes.awg

API reference for the `zhinst.toolkit.driver.devices.quantum_system_hub` module.

```APIDOC
module zhinst.toolkit.driver.devices.quantum_system_hub
```

--------------------------------

### Get Transaction Result List (Python)

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_modules/zhinst/toolkit/nodetree/nodetree

Retrieves the list of all added node value pairs from the internal queue of a transaction. This method is typically called to get the outcome of a series of node operations.

```Python
def result(self) -> t.Optional[t.List[t.Tuple[str, t.Any]]]:
    """Resulting transaction list.

    Result:
        List of all added node value pairs.
    """
    return self._queue
```

--------------------------------

### API Documentation for Connection.get Method

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.nodetree.nodetree.Connection.get

Detailed API documentation for the 'get' method of the 'Connection' class. This method mirrors the functionality of the 'zhinst.core get' command, accepting a path and returning an object.

```APIDOC
Class: Connection
  Method: get(*path: str*, *args, **kwargs)
    Description: Mirrors the behavior of zhinst.core `get` command.
    Parameters:
      path (str): The path to get.
    Return Type:
      object
```

--------------------------------

### API Reference: zhinst.toolkit.driver Module

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.devices.shfqa.SHFQA.start_continuous_sw_trigger

Documentation for the `driver` module within `zhinst.toolkit`, covering device drivers, modules, nodes, and parsers for instrument control.

```APIDOC
zhinst.toolkit.driver:
  devices:
    - base
    - hdawg
    - pqsc
    - qhub
    - quantum_system_hub
    - shfqa
    - shfqc
    - shfsg
    - uhfli
    - uhfqa
  modules:
    - base_module
    - daq_module
    - device_settings_module
    - impedance_module
    - pid_advisor_module
    - precompensation_advisor_module
    - scope_module
    - shfqa_sweeper
    - sweeper_module
  nodes:
    - awg
    - command_table_node
    - multistate
    - readout
    - shfqa_scope
    - spectroscopy
  parsers:
    - Parse
```

--------------------------------

### zhinst.toolkit Python Library API Reference

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.modules.precompensation_advisor_module

Comprehensive API documentation for the zhinst.toolkit library, detailing classes, their methods, and attributes for device interaction, module handling, and waveform generation.

```APIDOC
Devices:
  connected()
  created_devices()
  visible()

HF2Devices:
  add_hf2_device()
  connected()
  visible()

ModuleHandler:
  create_awg_module()
  create_daq_module()
  create_device_settings_module()
  create_impedance_module()
  create_mds_module()
  create_pid_advisor_module()
  create_precompensation_advisor_module()
  create_qa_module()
  create_scope_module()
  create_shfqa_sweeper()
  create_sweeper_module()
  awg()
  daq()
  device_settings()
  impedance()
  mds()
  pid_advisor()
  precompensation_advisor()
  qa()
  scope()
  shfqa_sweeper()
  sweeper()

PollFlags:
  DETECT_AND_THROW
  DETECT
  FILL
  DEFAULT

Session:
  clone_underlying_session()
  connect_device()
  disconnect_device()
  from_existing_connection()
  poll()
  raw_path_to_node()
  set_transaction()
  sync()
  daq_server()
  devices()
  is_hf2_server()
  modules()
  multi_transaction()
  server_host()
  server_port()

waveform:
  OutputType:
    OUT1
    OUT2
  Wave:
  Waveforms:
    assign_native_awg_waveform()
    assign_waveform()
    get_raw_vector()
    get_sequence_snippet()
    validate()
```

--------------------------------

### Example Usage of Node.child_nodes in Python

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.nodetree.node.Node.child_nodes

This example demonstrates how to use the `Node.child_nodes()` method to retrieve child nodes from a nodetree. It shows how to initialize the generator and then fetch the first child node using `next()`.

```python
child_nodes = nodetree.demods[0].child_nodes()
next(child_nodes)
# Expected output: /dev1234/demods/0/freq
```

--------------------------------

### DeviceSettingsModule Class API Reference

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_modules/zhinst/toolkit/driver/modules/device_settings_module

API documentation for the `DeviceSettingsModule` class, which handles saving and loading device settings. It details the constructor and key methods for managing settings files.

```APIDOC
class DeviceSettingsModule(BaseModule):
  Description: Implements the device settings module for storing and loading settings. The Device Settings Module provides functionality for saving and loading device settings to and from file. The file is saved in XML format.

  Methods:
    __init__(self, device_settings_module: ZIDeviceSettingsModule, session: "Session")
      Description: Initializes the DeviceSettingsModule.
      Parameters:
        device_settings_module: Instance of the core Impedance Module.
        session: Session to the Data Server.

    _simple_execution(self, command: str, filename: t.Union[str, Path], device: t.Union[str, "DeviceType"], timeout: float = 30) -> None
      Description: Executes a command on a clean module. This function creates an new module instance to avoid misconfiguration. It is also synchronous, meaning it will block until command has finished.
      Parameters:
        command: The command to execute. (`save`, `load`, `read`)
        filename: The path to the settings file.
        device: The device to load the settings to.
        timeout: Max time to wait for the loading to finish.
      Raises:
        TimeoutError: If the loading of the settings timed out.

    load_from_file(self, filename: t.Union[str, Path], device: t.Union["DeviceType", str], timeout: float = 30) -> None
      Description: Load a LabOne settings file to a device. This function creates an new module instance to avoid misconfiguration. It is also synchronous, meaning it will block until loading the settings has finished.
      Parameters:
        filename: The path to the settings file.
        device: The device to load the settings to.
        timeout: Max time to wait for the loading to finish.
      Raises:
        TimeoutError: If the loading of the settings timed out.

    save_to_file(self, filename: t.Union[str, Path], device: t.Union["DeviceType", str], timeout: int = 30) -> None
      Description: Save the device settings to a LabOne settings file. This function creates an new module instance to avoid misconfiguration. It is also synchronous, meaning it will block until save operation has finished.
      Parameters:
        filename: The path to the settings file.
        device: The device which settings should be saved.
        timeout: Max time to wait for the loading to finish.
      Raises:
        TimeoutError: If the loading of the settings timed out.

    read(self) -> NodeDict
      Description: Read device settings. Note: It is not recommend to use this function to read the device settings. Instead one can use the zhinst-toolkit functionality
```

--------------------------------

### Execute Wildcard Get Operation for Nodes

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_modules/zhinst/toolkit/nodetree/node

This method performs a wildcard 'get' operation to retrieve values for multiple subnodes. It is designed to always perform a deep get, but the timestamp is only returned if the 'deep' flag is explicitly set. The method forwards keyword arguments to the underlying 'zhinst.core' function and handles type errors for 'settingsonly' arguments. It processes raw results, parses individual node values, and returns them as a NodeDict or a standard dictionary.

```python
    def _get_wildcard(
        self, deep=True, enum=True, parse=True, **kwargs
    ) -> t.Union[NodeDict, t.Dict[str, t.Any]]:
        """Execute a wildcard get.

        The get is performed as a deep get (for all devices except HF2)
        regardless of the ``deep`` flag. If the ``deep`` flag is not set the
        timestamp is removed to ensure concistency.

        The kwargs will be forwarded to the maped zhinst.core function call.

        Args:
            deep: Flag if the get operation should return the cached value
                from the Data Server or get the value from the device, which is
                significantly slower. The wildcard get is always performed as
                deep get but the timestamp is only returned if the ``deep```
                flag is set.
            enum: Flag if enumerated values should return the enum value as
                string or return the raw number.
            parse: Flag if the GetParser, if present, should be applied or not.

        Returns:
            ``NodeDict`` if deep is `True`. Else a dictionary.
            Dictionary or a Mapping with the values of all subnodes.

        Raises:
            KeyError: If the node does not resolve to at least one valid leaf
                node.
        """
        # modules don`t have settingsonly argument ... this will be caught in
        # a try catch block to avoid unnecessary comparisons
        kwargs.setdefault("settingsonly", False)
        kwargs.setdefault("flat", True)
        try:
            result_raw = self._root.connection.get(self.node_info.path, **kwargs)
        except TypeError:
            del kwargs["settingsonly"]
            result_raw = self._root.connection.get(self.node_info.path, **kwargs)
        if not result_raw:
            raise KeyError(self.node_info.path)
        if not kwargs["flat"]:
            return result_raw
        result = {}
        for sub_node_raw, node_value in result_raw.items():
            sub_node = self._root.raw_path_to_node(sub_node_raw)
            timestamp, value = self._parse_get_entry(node_value)
            value = sub_node._parse_get_value(value, enum=enum, parse=parse)
            # although the operation is a deep get we hide the timestamp
            # to ensure consistency
            result[sub_node_raw] = (timestamp, value) if deep else value
        return NodeDict(result)
```

```APIDOC
_get_wildcard(deep: bool = True, enum: bool = True, parse: bool = True, **kwargs) -> t.Union[NodeDict, t.Dict[str, t.Any]]
  deep: Flag if the get operation should return the cached value from the Data Server or get the value from the device, which is significantly slower. The wildcard get is always performed as deep get but the timestamp is only returned if the `deep` flag is set.
  enum: Flag if enumerated values should return the enum value as string or return the raw number.
  parse: Flag if the GetParser, if present, should be applied or not.
  Returns: `NodeDict` if deep is `True`. Else a dictionary. Dictionary or a Mapping with the values of all subnodes.
  Raises: KeyError: If the node does not resolve to at least one valid leaf node.
```

--------------------------------

### NodeTree Initialization and Prefix Hiding

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.nodetree.nodetree.NodeTree

This example illustrates initializing the `NodeTree` with a connection and demonstrates how the `prefix_hide` parameter can simplify node access by automatically prepending a specified device ID to node paths. It shows both standard access and access with a hidden prefix.

```Python
nodetree = NodeTree(daq)
nodetree.dev123.demods[0].freq
# Expected output: /dev123/demods/0/freq
nodetree = NodeTree(daq, prefix_hide = "dev123", list_nodes = ["/dev123/*"])
nodetree.demods[0].freq
# Expected output: /dev123/demods/0/freq
```

--------------------------------

### Get and Set Node Value

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.nodetree.node.Node

Demonstrates how to retrieve and set the value of a specific node (e.g., frequency of a demodulator) using the call operator. First, it gets the current frequency, then sets it, and finally verifies the new value.

```python
nodetree.demods[0].freq()
1000
nodetree.demods[0].freq(2000)
nodetree.demods[0].freq()
2000
```

--------------------------------

### API Reference: zhinst.toolkit.driver.devices.pqsc module

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.session.Session.from_existing_connection

Documents the pqsc module within the zhinst.toolkit.driver.devices package, providing API details for PQSC devices.

```APIDOC
Module: zhinst.toolkit.driver.devices.pqsc
```

--------------------------------

### Python Example: Compile and Upload Sequencer Program

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.nodes.awg.AWG.compile_sequencer_program

This example demonstrates the typical workflow for compiling a sequencer program using `AWG.compile_sequencer_program`, uploading the generated ELF data to the device, waiting for the device to be ready, and then enabling the AWG.

```python
>>> elf, compile_info = device.awgs[0].compile_sequencer_program(seqc)
>>> device.awgs[0].elf.data(elf)
>>> device.awgs[0].ready.wait_for_state_change(1)
>>> device.awgs[0].enable(True)
```

--------------------------------

### API Reference: zhinst.toolkit.session.Devices

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_autosummary/zhinst.toolkit.driver.devices.quantum_system_hub.QuantumSystemHub.check_ref_clock

Documentation for the `Devices` class within the `zhinst.toolkit.session` module, which manages connected and visible Zurich Instruments devices.

```APIDOC
Class: zhinst.toolkit.session.Devices
  Properties:
    connected: list
    created_devices: list
    visible: list
```

--------------------------------

### API Documentation for ConnectionDict.get Method

Source: https://docs.zhinst.com/zhinst-toolkit/en/latest/_sources/_autosummary/zhinst.toolkit.nodetree.connection_dict.ConnectionDict.get.rst

Documents the 'get' method of the 'ConnectionDict' class. This method is part of the 'zhinst.toolkit.nodetree.connection_dict' module and its full signature, parameters, and return types are typically generated by Sphinx's automethod directive from the source code.

```APIDOC
Module: zhinst.toolkit.nodetree.connection_dict
Class: ConnectionDict
Method: get
  Description: (Details generated by automethod directive)
  Parameters: (Details generated by automethod directive)
  Returns: (Details generated by automethod directive)
```
Tokens:
Raw