Skip to content

v0.1.41 - Parallel and Serial Threshold Scanning (2025-12-14)

What Changed?

This release introduces two new sophisticated threshold scanning scripts for OSECHI detector characterization. parallel_scan.sh performs lock-step scanning where all three channels vary simultaneously for multi-channel sensitivity analysis. serial_scan.sh scans each channel individually with others masked for per-channel characterization. Both scripts implement real-time event streaming for efficient data collection.

What's New

Feature 1: Parallel Threshold Scanning with parallel_scan.sh

What it does: Performs lock-step (simultaneous) threshold scanning across all three detector channels. All channels vary together with the same step increment, enabling efficient multi-channel sensitivity analysis in a single scan. Reduces measurement points from (2nsteps+1)³ to (2nsteps+1).

How to use it:

# Basic scan: all channels from 0-600 ADC in 100-count steps
./parallel_scan.sh

# Custom scan: ch1=250, ch2=300, ch3=280, ±4 steps, 50 ADC/step, 15 events/step
./parallel_scan.sh 250 300 280 4 50 15

Output:

  • parallel_scan_<timestamp>.jsonl: Real-time streamed detection events
  • parallel_scan_<timestamp>_summary.json: Scan metadata and per-measurement statistics

Feature 2: Serial Threshold Scanning with serial_scan.sh

What it does: Performs sequential per-channel threshold scanning with automatic masking of non-active channels (threshold=1000). Enables accurate per-channel sensitivity characterization without crosstalk. Total measurement points: 3 × (2*nsteps+1).

How to use it:

# Basic scan: each channel 0-600 ADC
./serial_scan.sh

# Custom scan: different centers for each channel
./serial_scan.sh 250 300 280 4 50 15

Output:

  • serial_scan_<timestamp>.jsonl: Real-time streamed detection events
  • serial_scan_<timestamp>_summary.json: Scan metadata with per-channel results

Enhancement: Real-Time Event Streaming

Both scripts now implement real-time file flushing using tee -a to enable:

  • Immediate data visibility during measurement
  • Efficient file handling without buffering entire runs in memory
  • Progress monitoring during long scans

Installation

Quick Start

# Get the release
git checkout vX.Y.Z

# Setup
task env:setup

# Run CLI
uv run kazunoko --help

What's Different from the Last Version?

✅ Added

  • New examples/parallel_scan.sh: Lock-step threshold scanning for simultaneous multi-channel analysis
  • New examples/serial_scan.sh: Per-channel sequential scanning with masking for individual channel characterization
  • Real-time event streaming with tee -a in both scan scripts for immediate data visibility
  • Enhanced documentation in scan scripts with detailed function comments and section headers

🔧 Changed

  • examples/parallel_scan.sh: Refactored from 3D grid scanning to lock-step single-loop design
  • Measurement points reduced from (2nsteps+1)³ to (2nsteps+1)
  • All three channels now vary simultaneously with the same step increment
  • Improved code organization with clear helper functions and section markers
  • Simplified examples/basic_daq.sh and examples/advanced_daq.sh for clarity
  • Updated docs/getting-started/first-measurement.md to remove status check step

🐛 Fixed

  • Fixed seq command syntax in loop iterations to properly handle negative ranges

Is It Safe to Upgrade?

Backward Compatible: Yes

  • All existing features remain unchanged
  • parallel_scan.sh replaces the old threshold_scan.sh with improved architecture
  • New scanning scripts are additions and do not affect existing CLI or library functionality
  • Example scripts are optional utilities and safe to upgrade

Tests Passed

  • ✅ Builds without errors (uv sync, uvx ruff check, uvx mypy)
  • ✅ Both parallel_scan.sh and serial_scan.sh verified with manual testing
  • ✅ Real-time streaming with tee -a confirmed working correctly
  • ✅ Lock-step loop iteration verified with test runs
  • ✅ Pre-commit hooks pass successfully

Release Details

  • Date: 2025-12-14
  • Version: v0.1.41
  • Files Changed: 6
  • New: examples/parallel_scan.sh
  • New: examples/serial_scan.sh
  • Modified: examples/basic_daq.sh
  • Modified: examples/advanced_daq.sh
  • Modified: docs/getting-started/first-measurement.md
  • New: docs/releases/v0.1.41.md
  • Commits:
  • 1e7ecca refactor: convert parallel_scan to lock-step threshold progression
  • 9d0a4f9 feat: add serial_scan.sh for per-channel threshold characterization
  • ce6dd4b feat: enable real-time file flushing in threshold scan scripts
  • 90dba43 refactor: implement lock-step measurement loop in parallel_scan.sh
  • 21d5e43 docs: improve readability and documentation in scan scripts

Next Steps

  • Consider adding Python analysis utilities for threshold scan data visualization
  • Potential GUI tool for interactive threshold optimization
  • Integration of scan results into detector calibration workflow