atsbindings

Python bindings for the AlazarTech C API built using ctypes. This library provides a relatively thin layer over the C API, offering direct function mapping. In prinicple, all AlazarTech boards are supported; however, please see the Board Notes section below for tested models and specific quirks.

Developers familiar with the AlazarTech API can get started quickly. For those with limited experience, it is recommended to read the official API Programmer's Guide and review the acquisition.py example to understand how the bindings translate into Python.

Design

• Pythonic Naming Convention:
  C API functions are renamed to follow Python conventions with the leading "Alazar" namespace removed. For example:
  • AlazarSetCaptureClock() → set_capture_clock()
• Board Class:
  Functions requiring a board handle as the first argument are grouped into a Board class. This class automatically manages the board handle.
• Buffer Class:
  Simplifies configuration for AutoDMA transfer by automatically setting up a ctypes array of the correct type and size. Includes:
  • Methods for converting acquired data to a NumPy array.
  • Support for interleaved channels.
  • Support for 12-bit unpacking (currently slow).
• Enumerations:
  Enumerations (under the Ats namespace) include helper methods to:
  • Convert to and from string representations.
  • Create values from integer and floating-point inputs.
    Example:

    >>> from atsbindings import Ats
    >>> sample_rate = 250e6
    >>> Ats.SampleRates.from_hertz(2 * sample_rate)
    <SampleRates.SAMPLE_RATE_500MSPS: 48>
    

• BoardSpecificInfo:
  Provides board-specific parameters and feature details, as described in the API documentation.
  See the get_board_specific_info.py example for usage.
• System Class:
  Offers system-level information such as:
  • Number of boards detected.
  • DLL versions.
  • Other global properties.

Features Not Included

• High-Level API:
  A more pythonic interface is beyond the scope of this wrapper package. See the Dirigo plugin for a higher level API.
• Single-Port Acquisitions:
  Deprecated, lower-performance data transfer method.
• Linux Support:
  Currently, this library supports Windows only.
• Miscellaneous Functions:
  Some less commonly used functions have been omitted for clarity. Contact TDW if you need something not currently available.

Limitations

While this library closely wraps the C API, the Python interpreter introduces some overhead that may affect performance in certain scenarios. To minimize this impact:

• Limit the frequency of wrapper calls.
• Use relatively large buffer sizes for data transfer. (Alazar documentation suggest setting the buffer size between 1 MB and 16 MB.)

Installation

1. Install the Digitizer Driver:
   Download and install the appropriate driver from the AlazarTech downloads page.
2. Install Alazar DSO:
   Download and install the Alazar DSO software to verify hardware functionality.
3. Install the Digitizer:
   Power down the computer, install the digitizer in an appropriate extension slot, and power up.
4. Test with Alazar DSO:
   Run Alazar DSO to confirm the card is functioning correctly. If the card does not work in DSO, it will not work with atsbindings!
5. Install atsbindings:
   Install atsbindings from PyPI (or clone this repository and install it with pip). Using a virtual environment manager such as Conda is recommended.
6. Run Examples:
   Try the example scripts in the examples folder to validate your installation.

Board Notes

This library has been tested with the following boards:

• ATS9373:
  • For 2-channel acquisiton, samples must be interleaved.
  • No Traditional AutoDMA mode on this board.
• ATS9870:
• ATS9351
• ATS9350
• ATS9440
• ATS460

Not supported:

• ATS9370
  • No longer listed on Alazar website. Incomplete information in BSI table.

Contributing

Suggestions are welcome! Please message the developer directly. Pull requests will not be accepted.

Legal Disclaimer

This library is provided "as is" without any warranties, express or implied, including but not limited to the implied warranties of merchantability, fitness for a particular purpose, or non-infringement. The authors are not responsible for any damage to hardware, data loss, or other issues arising from the use or misuse of this library. Users are advised to thoroughly test this library with their specific hardware and configurations before deployment.

This library depends on the AlazarTech C API and its associated drivers, which must be installed and configured separately. Compatibility and performance depend on the proper installation and operation of these third-party components.

This library is an independent implementation based on publicly available documentation from AlazarTech. It is not affiliated with, endorsed by, or officially supported by AlazarTech.

Use this library at your own risk. Proper operation of hardware and compliance with applicable laws and regulations is the sole responsibility of the user.

This project is licensed under the MIT License. See the LICENSE file for details.

Funding

Development has been supported in part by the National Cancer Institute of the National Institutes of Health under award number R01CA249151.

The content of this repository is solely the responsibility of the authors and does not necessarily represent the official views of the National Institutes of Health.