Metadata-Version: 2.5
Name: dac-request
Version: 0.1.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: numpy
Description-Content-Type: text/markdown

# dac-request

Small user-facing API to create DAC requests suitable for internal SafeDac usage.

`dac-request` does not talk to any hardware. It builds request objects describing what
you want the DAC to do, and serialises them to JSON. The SafeDac server receives the
JSON, validates the voltages, and only then applies them.

## Installation

Requires Python 3.10 or later.

```bash
pip install .
```

## Quick start

```python
from dac_request import DacRequestor

dac = DacRequestor(dac_index=1)

request = dac.set_single_voltage({1: 0.1, 2: -0.2})
print(request.to_json())
# {"kind": "setpoint", "voltages": {"qdac1/out1": 0.1, "qdac1/out2": -0.2}}
```

Send the JSON string to the server however your setup does it (socket, HTTP, queue, and so on).

## Concepts

- **DAC and channels.** A `DacRequestor` stands for one DAC with channels 1 to 24.
  Channels are addressed by number in the client API.
- **Ports.** In requests, channels are named `qdac<dac_index>/out<channel>`, so channel 3
  of DAC 2 is `qdac2/out3`. This is what the server sees.
- **Requests.** There are three kinds, each an immutable dataclass:

| Request           | `kind`     | Purpose                                          |
| ----------------- | ---------- | ------------------------------------------------ |
| `SetpointRequest` | `setpoint` | Set fixed voltages on one or more ports.         |
| `DcListRequest`   | `dc_list`  | Step ports through lists of voltages together.   |
| `GetRequest`      | `getpoint` | Read back the output voltages of some ports.     |

## Usage

### Fixed voltages

```python
dac = DacRequestor(dac_index=1)

# Several channels at once
dac.set_single_voltage({1: 0.1, 2: -0.2})

# A single channel
dac.channel(3).set_voltage(0.05)
```

### DC lists

All channels step through their lists together, so every list must have the same length.

```python
import numpy as np

request = dac.set_dc_list(
    {1: np.linspace(0, 0.2, 3), 2: [0.0, -0.1, -0.2]},
    dwell_s=1e-3,
    trigger_input_port=1,
)
request.per_channel_dict
# {"qdac1/out1": [0.0, 0.1, 0.2], "qdac1/out2": [0.0, -0.1, -0.2]}
```

Options:

- `dwell_s`: seconds spent on each step (default `1e-3`).
- `delay_s`: seconds to wait after a trigger before the list starts (default `0`).
- `triggered`: whether the list waits for an external trigger (default `True`).
  When `True`, `trigger_input_port` is required. Pass `triggered=False` to run untriggered.
- `stepped`: if `True` (default), each trigger advances one step; if `False`, one trigger
  plays the whole list.

### Reading voltages

```python
dac.get_voltages()          # all 24 channels
dac.channel(3).get_voltage()  # one channel
```

### Serialising and rebuilding requests

Every request has `to_dict()` and `to_json()`. On the receiving side, `request_from_json`
(or `request_from_dict`) rebuilds the right request type from its `kind`:

```python
from dac_request import request_from_json

payload = dac.set_single_voltage({1: 0.1}).to_json()
request_from_json(payload)
# SetpointRequest(voltages={'qdac1/out1': 0.1})
```

numpy scalars are converted to plain numbers. NaN and infinite voltages are rejected with
a `ValueError`, since JSON cannot represent them.

## Errors

Requests are checked for structure when built, so mistakes surface on the client:

- `KeyError` for a channel outside 1 to 24.
- `ValueError` for empty voltages, DC lists of different or zero length, a triggered
  DC list without `trigger_input_port`, or an unknown or malformed payload in
  `request_from_dict` / `request_from_json`.

Voltage limits and safety checks are done by the SafeDac server, not by this package.
