Metadata-Version: 2.2
Name: rfmux
Version: 1.7.0
Summary: Python library for t0.technology CRS board running rfmux firmware
Author-Email: Graeme Smecher <gsmecher@t0.technology>, Joshua Montgomery <joshua@t0.technology>
Project-URL: homepage, https://github.com/t0/rfmux
Project-URL: repository, https://github.com/t0/rfmux
Requires-Python: >=3.10
Requires-Dist: PyQt6
Requires-Dist: aiohttp
Requires-Dist: awaitless
Requires-Dist: click>=8.0
Requires-Dist: fru
Requires-Dist: h5py
Requires-Dist: ipykernel<7
Requires-Dist: ipython
Requires-Dist: jupyterlab
Requires-Dist: jupytext
Requires-Dist: matplotlib
Requires-Dist: numba
Requires-Dist: numpy
Requires-Dist: pexpect
Requires-Dist: psutil
Requires-Dist: pygetdata; platform_machine != "aarch64"
Requires-Dist: pyqtgraph
Requires-Dist: pytest
Requires-Dist: pytest-asyncio
Requires-Dist: pyyaml
Requires-Dist: qtconsole
Requires-Dist: requests_futures
Requires-Dist: scipy
Requires-Dist: simplejson
Requires-Dist: sqlalchemy
Requires-Dist: tqdm
Requires-Dist: tuber-client[async]>=0.18
Requires-Dist: xmodem
Requires-Dist: tbb; sys_platform != "darwin"
Provides-Extra: qc
Requires-Dist: beautifulsoup4; extra == "qc"
Requires-Dist: htpy; extra == "qc"
Requires-Dist: markdown; extra == "qc"
Requires-Dist: markupsafe; extra == "qc"
Requires-Dist: pytest_check; extra == "qc"
Requires-Dist: requests; extra == "qc"
Requires-Dist: scikit-learn; extra == "qc"
Requires-Dist: weasyprint; extra == "qc"
Description-Content-Type: text/markdown

# rfmux

[rfmux](https://github.com/t0/rfmux) is the Python API for
[t0.technology](https://t0.technology)'s Control and Readout System (CRS), a
hardware platform designed for operating large arrays of Kinetic Inductance
Detectors (KIDs) used in radio astronomy and quantum sensing applications.

The CRS + MKIDs firmware is described in
[this conference proceedings](https://arxiv.org/abs/2406.16266).

## Quick Start

### Installation

We recommend using [uv](https://github.com/astral-sh/uv) for installation:

```bash
# Install uv (if not already installed)
$ curl -LsSf https://astral.sh/uv/install.sh | sh  # Linux/macOS or WSL
# Or: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

# Create virtual environment 
uv venv ### or uv venv my-env-name
source .venv/bin/activate # On Windows: .venv/Scripts/activate
# or source my-env-name/bin/activate

```

rfmux is available on PyPI or from the git repo. For installing directly from PyPI:

```bash
# Install rfmux
$ uv pip install rfmux
```

Or to install directly from the cloned git repo:

```bash
# in the rfmux directory
$ uv pip install -e .
```

**Note:** rfmux now uses a C++ extension for packet processing.  PyPI hosts
pre-built binaries (wheels) for common platforms (Linux x86_64, macOS,
Windows). If wheels aren't available for your platform, you'll need a C++
compiler. See [Installation Guide](docs/installation.md) for details.

### Interactive GUI

To launch the Periscope GUI, run:

```bash
$ uv run periscope # or periscope
```

To open a pulse capture or time-ordered data file in review mode, offline:

```bash
$ periscope --review pulse_module2_171224.h5
```

To add Periscope to your application menu, with its icon, and to the
right-click **Open With** menu of `.h5` and `.hdf5` files (Linux and
Windows, for your user only, no administrator rights):

```bash
$ rfmux periscope --install-desktop
```

`--default-for-hdf5` also makes double-clicking an HDF5 file open it in
Periscope, and `--desktop-icon` puts a shortcut on the desktop. The entries
start Periscope from the environment you ran this in, so run it again after
moving to another one. `rfmux periscope --uninstall-desktop` removes them.

https://github.com/user-attachments/assets/581d4ff8-5ea2-493a-9c9c-c93d6ca847e2

### Scripting with Mock Mode

If you do not have a CRS board (or cryogenic detectors) handy, you can use
"mock" mode for a software emulation:

```python
# Emulate CRS hardware for offline development
s = rfmux.load_session("""
!HardwareMap
- !flavour "rfmux.mock"
- !CRS { serial: "MOCK0001" }
""")
```

### Scripting with CRS Hardware

To control a single network-attached CRS from your PC's Python prompt, use:

```python
import rfmux

# Connect to a CRS board
s = rfmux.load_session('!HardwareMap [ !CRS { serial: "0033" } ]')
crs = s.query(rfmux.CRS).one()
await crs.resolve()

# Acquire samples
samples = await crs.get_samples(1000, channel=1, module=1)
```

## Documentation

- **[Installation Guide](docs/installation.md)** - Detailed installation for all platforms, building from source
- **[Getting Started](docs/guides/getting-started.md)** - Usage patterns, hardware hierarchy, common operations
- **[Networking Guide](docs/guides/networking.md)** - UDP tuning, multicast configuration, troubleshooting
- **[Firmware Guide](docs/guides/firmware.md)** - Fetching, managing, and flashing firmware
- **[Pulse Capture Guide](docs/guides/pulse-capture.md)** - Detecting and recording detector pulses, in Periscope and from a script
- **[100G Captures](docs/guides/100g-captures.md)** - Recording the channel stream, a pulse capture and a parser dirfile together with `rfmux record`, reviewing them in Periscope and drawing them over each other
- **[Release Notes](docs/release-notes/)** - What changed in each release

## Executable Jupytex Notebooks

- **[Detailed KID Tuning](rfmux/reference-notebooks/Demos/simplified_tuning_flow.md)** - Sweeping, fitting, biasing, measuring noise
- **[Detailed Pulse Capture](rfmux/reference-notebooks/Demos/pulse_capture.md)** - Detecting and recording detector pulses

The last two are runnable notebooks that ship with the package. See
[reference-notebooks/README.md](rfmux/reference-notebooks/README.md) for how to
open them.

## Repository Structure

```
rfmux/
├── docs/                    # Documentation
├── firmware/                # Firmware binaries (Git LFS)
├── rfmux/                   # Main Python package
│   ├── algorithms/          # Network analysis, fitting, biasing
│   ├── core/                # Hardware schema, sessions, transfer functions
│   ├── mock/                # Physics-based CRS simulator
│   ├── pulse_capture/       # Pulse detection, HDF5 capture, histograms
│   ├── reference-notebooks/ # Runnable demos, shipped with the package
│   ├── streamer/            # C++ packet receiver library
│   └── tools/               # Periscope GUI, CLI, firmware, QC suite
└── test/                    # Test suite
```

RPC to the board is provided by the separate
[tuber](https://pypi.org/project/tuber-client/) package.

## Contributing & Feedback

rfmux is permissively licensed; see LICENSE for details.

We actively encourage contributions and feedback. Understanding operator needs
is how we determine what to add to rfmux.

- **Pull Requests:** Your contributions are welcome
- **Issues:** Please submit tickets for bugs or enhancement suggestions
- **Collaborator Slack:** Join #crs-collaboration - email Joshua@t0.technology with your name, affiliation, and project

## Citation

When citing rfmux or CRS, please reference:
> CRS + MKIDs Conference Proceedings: https://arxiv.org/abs/2406.16266
