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
zhinst.core 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.
LabOne API Examples
To see the Python API in action take a look at some of the examples that we published on our public GitHub repository.
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 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:
x86_64, with a Python 3.5-3.9 installation.
GNU/Linux with glibc 2.17 or newer (CentOS/RHEL 7+, all recent versions of Debian and Ubuntu).
x86_64wheels are available for Python 3.5-3.9.
aarch64wheels are available for Python 3.7-3.9.
x86_64and Python 3.5-3.9. macOS 11+
arm64(Apple Silicon) wheels are provided for Python 3.9+.
Installation on Linux requires
pip19.3+ for support of the
manylinux2014platform tag. In case of problems, please try to install the package in a virtual environment with latest
$ python3 -m venv venv $ . venv/bin/activate $ pip install --upgrade pip $ pip install zhinst
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:
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
package is not yet installed, it can be downloaded from
https://pypi.org/project/numpy/. 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,
This section introduces the user to the LabOne Python API.
Alongside the binary extension
zhinst.core for interfacing with Zurich
Instruments Data Servers and devices, the LabOne Python API includes
See the LabOne API documentation for all available utility functions, in
zhinst.core's built-in documentation can be accessed using the
command in a python interactive shell:
On module level:
>>> import zhinst.core >>> help(zhinst.core)
On class level, for example, for the Sweeper Module:
>>> import zhinst.core >>> help(zhinst.core.SweeperModule)
On function level, for example, for the
>>> import zhinst.core >>> help(zhinst.core.ziDAQServer.poll)
See the LabOne API documentation for a full documentation.
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
zhinst.core.ziDAQServer. For example, an instance of the
Sweeper Module is created using
zhinst.core.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 = zhinst.core.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('start', 1.2e5);
The parameters can be read-back using the
get method, which supports
wildcards, for example:
>>> sweep_params = sweeper.get('*');
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. 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
the LabOne Python API 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 LabOne Python API.
The output arguments that the LabOne Python API returns are designed to use the
native data structures that Python users are familiar with and that
reflect the data’s location in the instruments node hierarchy. For
example, when the
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