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:

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:

fws-daemon 1

Run in test mode:

fws-daemon 1 --test-mode

Write daemon logs to a custom directory:

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

Open plots from an HDF5 file:

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

CLI reference

fws-daemon

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

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:

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

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.