The Zurich Instruments LabOne Python API is distributed as the
zhinst Python package via PyPi, the
official third-party software repository for Python. The
package contains the
ziPython binary extension that is used to
communicate with Zurich Instruments data servers and devices. It allows
users to configure and stream data from their instrument directly into a
Python programming environment using Python’s own native data structures
This chapter aims to help you get started using the Zurich Instruments LabOne Python API to control your instrument.
LabOne API documentation
For a full reference of the Python API visit the LabOne API documentation.
Python is open source software, freely available for download from
Python’s official website. Python is a high-level
programming language with an extensive standard library renowned for its
"batteries included" approach. Combined with the
This chapter and the provided examples are not intended to be a Python tutorial. For help getting started with Python itself, see either the Python Tutorial or one of the many online resources, for example, the learnpython.org. The Interactive Python Course is an interesting resource for those already familiar with Python basics.
This section lists detailed requirements. In most cases, installing the
LabOne Python API should be as simple as searching for and installing
zhinst package in your Python distribution’s package manager or
running the command-line command:
pip install zhinst
The following requirements must be fulfilled in order to install and use the LabOne Python API:
One of the following supported platforms and Python versions:
32 or 64-bit Windows with a Python 2.7, 3.5, 3.6 or 3.7 installation.
64-bit Linux with a Python 2.7, 3.5, 3.6 or 3.7 installation.
64-bit macOS and the system Python 2.7 (shipped pre-installed with macOS; other Python installations are not supported). The Data Server, which is unavailable on macOS, must run remotely on either an instrument or on a separate Windows or Linux PC.
pipPython package, Python’s most popular package management system.
numpyPython package (automatically installed by
zhinstis installed over the internet).
Although the newest version of
numpyis recommended, the
zhinstpackage supports the following
Python 2.7 >= 1.6
Python 3.5 >= 1.10
Python 3.6 >= 1.12
Python 3.7 >= 1.14
The correct version of the
zhinstPython package for the target Python version and platform (automatically detected by
zhinstis installed over the internet).
Note, it’s necessary to first uninstall/remove
zhinstwhen down or upgrading to release 14.08 and it’s recommend to first uninstall
zhinstwhen down or upgrading to release 18.12. See below for more details.
Upgrading to the LabOne Python API release 14.08
Important: If you your system already has an existing
Packaging changes to the LabOne Python API in 18.12
The LabOne Python API prior to LabOne software release 18.12 was
distributed as an MSI installer (Windows) or tarball (Linux, Mac),
downloadable from the Zurich Instruments
download page. From LabOne software
release 18.12 onwards the LabOne Python API is distributed as a Python
wheel which can be either downloaded via pip (or manually) from PyPi as
Note, in releases prior to 18.12, the Python API package was called
The following Python packages can additionally be useful for programming with the LabOne Python API:
The following installs the
zhinst package from PyPi over the internet
locally for the user performing the installation and does not require
administrator rights. If the target PC for installation does not have
access to the internet, please additionally see
Determine the path to the target Python installation. If the Python executable is not in your path, you can obtain the full path to your Python executable as follows:
from __future__ import print_function import sys print(sys.executable)
On Windows this will print something similar to:
zhinstpackage. Using the full path to the Python executable,
PATH_TO_PYTHON_EXE, as determined above in Step 1, open a command prompt and run Python with the
pipmodule to install the
PATH_TO_PYTHON_EXE -m pip install --user zhinst
pipto install the
zhinstpackage locally for the user executing the command. Normally administrator rights are required in order to install the
zhinstpackage for all users of the computer, for more information see below.
Global Installation as Administrator
In order to install the
zhinst package on a computer without access to the
internet, please download the correct wheel file for your system and
Python version from https://pypi.org/project/zhinst/ from another
computer and copy it to the offline computer. If the target Python
installation is Python 2.7 on a Linux 64-bit computer, please see
Determining the correct Unicode version for Python 2.7 distributions below. If the
package is not yet installed, it can also be downloaded from either
https://pypi.org/project/numpy/ or from Christoph Gohlke’s
pythonlibs page. Then the
wheels can be installed as described above using
pip, except that the
name of the wheel file must be provided as the last argument to
instead of the name of the package,
Determining the correct Unicode version for Python 2.7 distributions
In order to determine which version of Unicode your Python 2.7 distribution uses, please type the following commands in the interactive shell of your target Python distribution:
import sys print sys.maxunicode
If the last command prints:
This section introduces the user to the LabOne Python API.
Alongside the binary extension
ziPython for interfacing with Zurich
Instruments Data Servers and devices, the LabOne Python API includes
utility functions and examples.
ziPython’s built-in documentation can be accessed using the `help
command in a python interactive shell:
On module level:
>>> import zhinst.ziPython as ziPython >>> help(ziPython)
On class level, for example, for the Sweeper Module:
>>> import zhinst.ziPython as ziPython >>> help(ziPython.SweeperModule)
On function level, for example, for the
>>> import zhinst.ziPython as ziPython >>> help(ziPython.ziDAQServer.poll)
See the LabOne API documentation for a full documentation.
Prerequisites for running the Python examples:
zhinstpackage is installed as described above in Installing the LabOne Python API .
The Data Server program is running and the instrument is discoverable, this is the case if the instrument can be seen in the User Interface.
Signal Output 1 of the instrument is connected to Signal Input 1 via a BNC cable; many of the Python examples measure on this hardware channel.
The API examples are available in the module
zhinst.examples, which is
organized into sub-modules according to the target Instrument class:
zhinst.examples.common: examples compatible with any class of instrument,
zhinst.examples.hdawg: examples only compatible with HDAWG Instruments,
zhinst.examples.hf2: examples only compatible with HF2 Series Instruments,
zhinst.examples.uhf: examples only compatible with the UHF Lock-in Amplifier.
All the examples follow the same structure and take one input argument:
The device ID of the instrument to run the example with. The recommended
way to run a
zhinst example is to import the example’s module in an
interactive shell and call the
run_example() function. For example, to
run the Data Acquisition Module FFT example:
import zhinst.examples.common.example_data_acquisition_edge_fft as example example.run_example('dev123', do_plot=True);
which will produce some output in the Python shell, such as:
Discovered device `dev196`: HF2LI with options MFK, PLL, MOD, RTK, PID, WEB. Creating an API session for device `dev196` on `127.0.0.1`, `8005` with apilevel `1`. Setting trigger/0/level to 0.221. Setting trigger/0/hysteresis 0.011. Data Acquisition Module progress (acquiring 10 triggers): 100.00%. Trigger is finished. Data Acquisition's read() returned 10 signal segments.
matplotlib is unavailable. If
is installed, most examples will also plot the retrieved data, see
Figure 1 for an example. If
you encounter an error message please ensure that the
above prerequisites are
The examples distributed with the
zhinst package can serve as a
starting point to program your own measurement needs. The example python
files, however, are generally not installed in user space. In order to
ensure that you have sufficient permission to edit the examples and that
your modifications are not overwritten by a later upgrade of the
zhinst package, please copy them to your own user space before editing
The examples are contained in a subfolder of the
If you are unsure about the location of your
path attribute of the
zhinst module can be used in order to
determine its location, for example,
from __future__ import print_function import zhinst print zhinst.__path__
will output something similar to:
In the LabOne Python API
ziCore Modules are
configured and controlled via an instance of the Module’s class. This
Module object is created using the relevant function from
ziPython.ziDAQServer. For example, an instance of the
Sweeper Module is created using
ziPython.ziDAQServer’s `sweep() function. As such, an API session
must be instantiated first using
Specifying the Data Server Hostname and Port
for more information about initializing API
session) and then a sweeper object is created from instance of the API
session as following:
>>> daq = ziPython.ziDAQServer('localhost', 8004, 6) # Create a connection to the Data Server ('localhost' means the Server is running on the same PC as the API client, use the device serial of the form 'mf-dev3000' if using an MF Instrument. >>> sweeper = daq.sweep();
Note, that since creating a Module object without an API connection to
the Data Server does not make sense, the Sweeper object is instantiated
sweep method of the
ziDAQServer class, not directly from the
The Module’s parameters are configured using the Module’s
and specifying a
value pair, for example:
>>> sweeper.set('sweep/start', 1.2e5);
The parameters can be read-back using the
get method, which supports
wildcards, for example:
>>> sweep_params = sweeper.get('sweep/*');
sweep_params now contains a dictionary of all the
Sweeper’s parameters. The other main Module commands are similarly used,
sweeper.execute(), to start the sweeper. See
for more help with Modules and a description
of their parameters.
Logging from the API is not enabled by default upon initializing a
server session with
ziPython, it must be enabled (after using
connect) with the
setDebugLevel command. For example,
sets the API’s logging level to 0, which provides the most verbose logging output. The other log levels are defined as following:
trace:0, debug:1, info:2, status:3, warning:4, error:5, fatal:6.
It is also possible for the user to write their own messages directly to
ziPythonwith ’s log using the `writeDebugLog command. For example to
write a log message of
info severity level:
>>> daq.writeDebugLog(1, 'Hello log!')
On Windows the logs are located in the directory
C:\Users\[USER]\AppData\Local\Temp\Zurich Instruments\LabOne Note that
AppData is a hidden directory. The easiest way to find it is to open a
File Explorer window and type the text
%AppData%\.. in the address
bar, and navigate from there. The directory contains folders containing
log files from various LabOne components, in particular, the
ziPythonLog folder contains logs from the LabOne Python API. On Linux,
the logs can be found at "/tmp/ziPythonLog_USERNAME", where "USERNAME"
is the same as the output of the "whoami" command.
In this section some tips and tricks for working with the LabOne Python API are provided.
Data Structures returned by
The output arguments that
data = daq.poll( poll_length, poll_timeout); x = data['dev123']['demods']['4']['sample']['x']; y = data['dev123']['demods']['4']['sample']['y'];
By default, the data returned by
daq.subscribe('/dev123/demods/0/sample') flat_dictionary_key = False data = daq.poll(0.1, 200, 1, flat_dictionary_key) if 'dev123' in data: if 'demods' in data['device']: if '0' in data['device']['demods']: # access the demodulator data: x = data['dev123']['demods']['0']['sample']['x'] y = data['dev123']['demods']['0']['sample']['y']
Could be rewritten more concisely as:
daq.subscribe('/dev123/demods/0/sample') flat_dictionary_key = True data = daq.poll(0.1, 200, 1, flat_dictionary_key) if '/dev123/demods/0/sample' in data: # access the demodulator data: x = data['/dev123/demods/0/sample']['x'] y = data['/dev123/demods/0/sample']['y']
Use the Utility Routines to load Data saved from the LabOne UI and ziControl in Python.
The utilities package