Metadata-Version: 2.4
Name: dt4800
Version: 1.0.0
Summary: Python binding of the DT4800 SDK: control of the CAEN DT4800 Micro Digital Detector Emulator
Author-email: Nuclear Instruments <support@nuclearinstruments.eu>
License: MIT
Project-URL: Homepage, https://gitlab.nuclearinstruments.eu/public-repo/dt4800
Project-URL: Documentation, https://public-repo.pages.nuclearinstruments.eu/dt4800/
Project-URL: Source, https://gitlab.nuclearinstruments.eu/public-repo/dt4800
Project-URL: Issues, https://gitlab.nuclearinstruments.eu/public-repo/dt4800/-/issues
Keywords: DT4800,CAEN,Nuclear Instruments,detector emulator,pulser,nuclear physics,spectroscopy
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: numpy
Requires-Dist: numpy; extra == "numpy"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# dt4800 — Python binding of the DT4800 SDK

Control the **CAEN DT4800 Micro Digital Detector Emulator** (Nuclear Instruments) from
Python: time base (constant, Poisson, external), amplitude (fixed or from a spectrum),
pulse shape, noise, output stage, trigger output, monitoring (In / Out / LIVE % / Counts,
realtime signal and spectrum), `.nis` settings files, the Spectrum Importer and Editor,
the isotope library and Radionuclide Composer, activation and the FPGA firmware update.
The package calls the native DT4800 library (`dt4800.dll` / `libdt4800.so` /
`libdt4800.dylib`) through `ctypes`; a built-in simulator (`sim://`) lets you develop and
test without hardware.

## Installation

```
pip install dt4800
```

The wheels for Windows (x64, x86) and Linux (x86_64 and aarch64, glibc 2.34+)
include the native library. Python 3.8 or later; no mandatory dependency
(`pip install dt4800[numpy]` to get numpy arrays from the read functions with
`as_numpy=True`).

With the source distribution, or to use another build of the library, point
`DT4800_LIBRARY` at it (full path of `dt4800.dll` / `libdt4800.so` / `libdt4800.dylib`);
otherwise the library is looked up in the package, then by the system loader.

### USB drivers

The DT4800 is an FTDI USB device, driven through FTDI's D2XX library:

- **Windows**: install the CAEN FTDI driver from the DT4800 SDK installer (or the DT4800
  Control Software); it provides `ftd2xx.dll`.
- **Linux**: the wheels carry FTDI's `libftd2xx.so` inside the package; the instrument must
  be accessible to your user: install the udev rule (the `.deb` / `.rpm` packages of the SDK
  install it), then unplug and plug the instrument again.

`dt4800.usb_driver()` tells which D2XX library is used (or why none can be loaded). The
simulator needs no driver.

## Quick start

```python
import dt4800

print(dt4800.version())

with dt4800.open("sim://") as dev:            # the simulator, no hardware
    print(dev.info.model_name, dev.info.serial)
    ch = dev.channel(0)
    ch.set_shape(rise_us=0.05, tau_us=50)      # Control Software units
    ch.set_timebase(dt4800.TimebaseMode.POISSON, rate_hz=10000)
    ch.set_fixed_energy(20000)                 # register value (2 x panel LSB)
    ch.set_output(gain=1.0, offset=0)
    ch.enable()                                # OUTPUT on
    st = ch.stats()
    print(st.count_rate, st.live, "%.1f %%" % st.live_percent, st.event_counter)
```

On USB:

```python
for d in dt4800.enumerate(dt4800.Bus.USB):
    print(d.serial, d.address, "busy" if d.busy else "")

with dt4800.open("usb://") as dev:             # or "usb://<serial>"
    ch = dev.channel(0)
    ch.apply(dt4800.load_settings("panel.nis"))   # a Control Software settings file
```

A spectrum and the Radionuclide Composer:

```python
lines = [l.source() for n in ("Co-60", "Cs-137")
         for l in dt4800.nuclide_lines(n, dt4800.LineType.GAMMA) if l.intensity > 1]
lo, hi = dt4800.compose_range(lines)
spectrum = dt4800.peaks_to_spectrum(dt4800.compose_peaks(lines, lo, hi))
ch.set_spectrum(spectrum)
```

Errors raise `dt4800.Dt4800Error` subclasses (`OutOfRangeError`, `InvalidParameterError`,
`NotFoundError`, `FileError`, `DeviceTimeoutError`, ...) carrying `.status`, `.message`
(the description of the library) and `.function`. The `examples/` folder has runnable
scripts for every feature (`python examples/01_info.py sim://`).

## GUI example

`examples/gui/dt4800_panel.py` is a PyQt6 control panel reproducing the main window of the
DT4800 Control Software (with the plot window: input spectrum, realtime spectrum, realtime
signal); it runs on the simulator too:

```
pip install -r examples/requirements.txt
python examples/gui/dt4800_panel.py sim://
```

## Documentation

User guide and API reference: <https://public-repo.pages.nuclearinstruments.eu/dt4800/>

Source: <https://gitlab.nuclearinstruments.eu/public-repo/dt4800> — MIT License.
