Metadata-Version: 2.4
Name: fws-daemon
Version: 3.3.1
Summary: FWS scan daemon and analysis tools
Author-email: Hugo Valim <hugo.valim@ess.se>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: epics-bridge<5,>=4.4.1
Requires-Dist: pyyaml
Requires-Dist: h5py
Requires-Dist: numpy
Requires-Dist: p4p
Requires-Dist: matplotlib
Requires-Dist: scipy
Provides-Extra: dev
Requires-Dist: build==1.4.0; extra == "dev"
Requires-Dist: pre-commit==4.2.0; extra == "dev"
Requires-Dist: pytest==8.4.1; extra == "dev"
Requires-Dist: pytest-cov==6.2.1; extra == "dev"
Requires-Dist: pytest-mock==3.15.1; extra == "dev"
Requires-Dist: twine==6.2.0; extra == "dev"

# fws-daemon

`fws-daemon` is a Python-EPICS daemon that provides scan and analysis toolkit functionalities for the FWS system.
It orchestrates scan execution through `fws_daemon/scan`, collects
and post-processes scan data, and writes structured HDF5 output for
offline analysis.

## What this project includes

- `fws-daemon` CLI: runs the scan daemon
- `fws-plot` CLI: opens interactive plotting tools for produced HDF5 files
- Typed scan configuration and orchestration modules
- Callback pipeline for scan status, Gaussian fitting, and HDF5 writing
- Tests for orchestration, callbacks, interface mapping, and packaging

## Installation

Install from the repository root:

```sh
pip install .
```

This installs the console scripts:

- `fws-daemon`
- `fws-plot`

For development environment setup and editable installs, see
`docs/development.md`.

## Quick start

Run daemon for scanner index 1:

```sh
fws-daemon 1
```

Run in test mode:

```sh
fws-daemon 1 --test-mode
```

Write daemon logs to a custom directory:

```sh
fws-daemon 1 --log-dir /tmp/fws-daemon
```

Open plots from an HDF5 file:

```sh
fws-plot /path/to/scan.h5 PDB --iops-channel ch1 --scanner-index 1
```

## CLI reference

### `fws-daemon`

```text
fws-daemon <scanner_index> [--test-mode] [--custom-callback PATH]
                      [--log-dir PATH]
```

Arguments:

- `scanner_index` (int): FWS scanner number
- `--test-mode`: use `Test:*` PV prefixes
- `--custom-callback`: Python file exposing `get_pre_callback` and/or
  `get_post_callback`. **This executes arbitrary Python from the provided
  file path**; only use trusted scripts.
- `--log-dir`: daemon log directory (default: `var/log/fws-daemon/fws-<NN>` for
  the selected scanner index). Use a writable path if the default location is
  not permitted on your host.

### `fws-plot`

```text
fws-plot <file_path> <struck_channel>
         [--iops-channel CH1|CH2] [--scanner-index N]
```

Arguments:

- `file_path`: path to an HDF5 scan file
- `struck_channel`: DAQ channel (for example `PDB`, `PDT`)
- `--iops-channel`: optional IOPS channel, defaults to `ch1`
- `--scanner-index`: optional scanner index (auto-detected from filename
  when omitted)

## Architecture overview

The runtime flow for `fws-daemon`:

1. Parse daemon CLI args and resolve IOC prefixes.
2. Build `FWSScanInterface` and start `FWSScanBridgeDaemon`.
3. Read scan inputs from EPICS PVs and validate into `ScanConfig`.
4. Plan scan positions with `ScanPlanner`.
5. Execute each step with `FWSScanRunner`.
6. Collect PV data with `ScanDataCollector`.
7. Run callbacks:
   - `ScanStatusCallback`
   - `GaussFitCallback`
   - `HDF5WriterCallback`
8. Persist data and metadata to HDF5.

For deeper details see:

- `docs/architecture.md`
- `docs/development.md`
- `docs/operations.md`
- `CONTRIBUTING.md`

## HDF5 output model (high level)

- Root-level metadata attributes (scan args, user, start time, source)
- Per-scan groups (`scan_001`, `scan_002`, ...)
- Nested data groups (`scan`, `struck`, `idc`, `beam`, etc.) with datasets
  and engineering units where available

## Development and testing

Run tests:

```sh
pytest -v
```

Coverage thresholds and test options are configured in `pytest.ini`.
Before running tests locally, make sure dependencies are installed in your
active environment.

## Repository layout

```text
fws_daemon/
  daemon/      # bridge daemon, interface mapping, callbacks, entrypoint
  scan/        # scan config, planner, runner, orchestration
  plots/       # interactive plot tools and CLI
  utils/       # fitting and path/filename helpers
tests/         # unit and integration tests
```

## License

No license file is currently present in this repository. If you intend to
distribute this package externally, add an explicit `LICENSE` file and ensure
`pyproject.toml` metadata matches the chosen license.
