frinZ

Rust version of frinZ.py - A high-performance fringe-fitting tool for VLBI data analysis.
Original Python version: https://github.com/M-AKIMOTOO/frinZ.py

Overview

frinZ is a Rust implementation of the frinZ fringe-fitting tool for processing Very Long Baseline Interferometry (VLBI) correlation data. It provides accurate delay and rate measurements with enhanced performance compared to the original Python version.

Features

• Fringe fitting analysis for VLBI correlation data (.cor files)
• Phase reference calibration with polynomial fitting
• Precise search mode with iterative refinement
• RFI mitigation with frequency range exclusion
• Bandpass calibration with binary file support
• Visualization with delay/rate plots and cumulative SNR plots
• Multiple output formats (text, binary, plots)
• Cross-power spectrum analysis
• Pulsar gating analysis with dedispersion, folding, and gating reports

Installation

From Source

# Clone the repository
git clone https://github.com/M-AKIMOTOO/frinZ.git
cd frinZ

# Install to ~/.cargo/bin
cargo install --path . --bin frinZ

Development Build

# Check only the publishable frinZ crate
cargo check -p frinZ --all-targets

# Build the frinZ binary
cargo build -p frinZ --bin frinZ --release

# Build everything in this repository
cargo build --workspace --release

Local Tools In This Workspace

This repository is split into:

• frinZ: publishable crate and main binary
• frinZ-tools: local-only package for gfrinZ, pulsar_gating, cormerge, corshow, and bandscythe

# Check all local tools
cargo check -p frinZ-tools --all-targets

# Build all local tools
cargo build -p frinZ-tools

# Build each tool separately
cargo build -p frinZ-tools --bin gfrinZ --release
cargo build -p frinZ-tools --bin pulsar_gating --release
cargo build -p frinZ-tools --bin cormerge --release
cargo build -p frinZ-tools --bin corshow --release
cargo build -p frinZ-tools --bin bandscythe --release

Run examples:

cargo run -p frinZ-tools --bin gfrinZ --release -- --help
cargo run -p frinZ-tools --bin pulsar_gating --release -- --help
cargo run -p frinZ-tools --bin cormerge --release -- --help
cargo run -p frinZ-tools --bin corshow --release -- --help
cargo run -p frinZ-tools --bin bandscythe --release -- --help

Note: crates.io publish target is frinZ only. On Windows, antivirus software may flag the compiled binary.

Usage

Basic Syntax

frinZ [OPTIONS]

Input Options

Single File Analysis

# Basic fringe fitting
frinZ --input data.cor

# With integration time and loop count
frinZ --input data.cor --length 30 --loop 5

# Skip first 10 seconds
frinZ --input data.cor --skip 10

Phase Reference Analysis

# Basic phase referencing (calibrator, target)
frinZ --phase-reference cal.cor target.cor

# With fit_spec and custom integration times
frinZ --phase-reference cal.cor target.cor 2 60 120 3
# Arguments: calibrator target fit_spec cal_length target_length loop
# fit_spec: <deg>, sin, <deg>+sin, <deg>+sin:<period_sec>
# With polynomial degree and custom integration times
frinZ --phase-reference cal.cor target.cor 2 60 120 3
# Arguments: calibrator target fit_degree cal_length target_length loop

Analysis Options

Frequency Domain Analysis

# Cross-power spectrum instead of fringe
frinZ --input data.cor --frequency

Precise Search Mode

# Enable iterative search with custom iterations
frinZ --input data.cor --search --iter 5

# With search windows
frinZ --input data.cor --search --delay-window -10 10 --rate-window -0.1 0.1

Manual Corrections

# Apply delay and rate corrections
frinZ --input data.cor --delay-correct 5.2 --rate-correct -0.03

RFI Mitigation

# Exclude frequency ranges (MHz)
frinZ --input data.cor --rfi "100,120" "400,500"

Bandpass Calibration

# Generate bandpass table
frinZ --input cal.cor --bandpass-table

# Apply existing bandpass calibration
frinZ --input data.cor --bandpass /path/to/bandpass_table.bin

Output Options

Text Output

# Save analysis results to text files
frinZ --input data.cor --output

# Show header information
frinZ --input data.cor --header

Plotting

# Generate fringe plots
frinZ --input data.cor --plot

# Time series plots
frinZ --input data.cor --add-plot

# Cumulative SNR plots
frinZ --input data.cor --cumulate 10

Advanced Examples

Complete Analysis with All Options

frinZ --input data.cor \
  --length 60 --loop 10 --skip 5 \
  --search --iter 3 \
  --delay-window -20 20 --rate-window -0.05 0.05 \
  --rfi "150,200" \
  --plot --add-plot --output \
  --bandpass cal_bandpass.bin

Phase Reference with Custom Parameters

frinZ --phase-reference cal.cor target.cor 1 30 60 5 \
  --search --plot --output

Pulsar Gating Analysis

# Known pulsar mode (period is given)
pulsar_gating --input data.cor \
  --period 0.253 --dm 26.7 \
  --bins 128 --on-duty 0.12

# Unknown pulsar mode (period/DM estimated from data)
pulsar_gating --input data.cor --bins 128 --amp-threshold 0.015

Build or run pulsar_gating from the local-only tools package:

cargo build -p frinZ-tools --bin pulsar_gating --release
# or
cargo run -p frinZ-tools --bin pulsar_gating --release -- --help

pulsar_gating creates outputs under frinZ/pulsar_gating/ next to the input .cor.

Modes

• Known mode (--period required, --dm optional): Performs dedispersion (if DM is given), fold, on/off pulse bin selection, and gated spectrum/profile products.
• Unknown mode (--period omitted): Estimates period from fringe-derived products, estimates DM from sub-band delay fit, writes handoff parameters, then automatically runs known mode with estimated values.

Core algorithm flow

1. Read .cor sectors and build channel-wise time series.
2. Build fringe products (rate spectrum, delay-rate plane).
3. Estimate period from spacing of periodic peaks in the rate spectrum (rate-diff).
4. Refine period by fold-SNR scan.
5. Estimate DM by fitting delay vs 1/f^2 from phase-shifted sub-band folded profiles.
6. Run known-mode gating with selected/refined parameters.

Estimated/refined period and estimated DM are printed to stdout.

Noise evaluation before/after gating

pulsar_gating evaluates noise in two stages.

1. Before gating (folded profile)

   • On-pulse bins are chosen by --on-duty (largest folded amplitudes).
   • Off-pulse bins are the remaining bins.
   • off_mean and off_sigma are computed from off-pulse folded amplitudes.
   • Estimated S/N is:
     • (peak_amp - off_mean) / off_sigma

2. After gating (on/off weighted aggregation)

   • Time-domain means are computed from dedispersed sector amplitudes:
     • on_mean: weighted mean over on-pulse sectors
     • off_mean: weighted mean over off-pulse sectors
     • off_sigma: standard deviation of off-pulse sector amplitudes
   • Gated time S/N is:
     • (on_mean - off_mean) / off_sigma
   • Gated profile S/N is computed from channel-subtracted time series (on-off) as:
     • peak(on-off) / sigma(off on-off)

In stdout and *_summary.txt, these appear as:

• Estimated S/N (pre-gating folded profile)
• Gated on-mean, Gated off-mean, Gated off σ
• Gated time S/N
• Gated profile S/N, Gated profile σ

ゲーティング前後のノイズ評価（日本語）

pulsar_gating では、ノイズ評価を次の2段階で行います。

1. ゲーティング前（folded profile）

   • --on-duty で指定した割合だけ、振幅の大きい位相ビンを on-pulse として選択します。
   • 残りの位相ビンを off-pulse とします。
   • off-pulse の振幅から off_mean と off_sigma を計算します。
   • Estimated S/N は次式です。
     • (peak_amp - off_mean) / off_sigma

2. ゲーティング後（on/off 重み付き集約）

   • dedispersed したセクター振幅から次を計算します。
     • on_mean: on-pulse セクターの重み付き平均
     • off_mean: off-pulse セクターの重み付き平均
     • off_sigma: off-pulse セクター振幅の標準偏差
   • Gated time S/N は次式です。
     • (on_mean - off_mean) / off_sigma
   • Gated profile S/N は、チャネルごとの off 平均を引いた on-off 時系列から計算し、次式で定義します。
     • peak(on-off) / sigma(off on-off)

stdout と *_summary.txt では、主に以下の項目として表示されます。

• Estimated S/N（ゲーティング前 folded profile）
• Gated on-mean, Gated off-mean, Gated off σ
• Gated time S/N
• Gated profile S/N, Gated profile σ

Main outputs (current default)

• *_rate_spectrum.png – rate profile with threshold/periodic markers.
• *_rate_spectrum_above_amp.csv – points above --amp-threshold.
• *_rate_spectrum_periodic_peaks.csv – periodic peak candidates used for period spacing.
• *_delay_rate_peakscan.png – delay-window peak scan map.
• *_rate_diff_folded_profile.png – folded profile from rate-diff period (when available).
• *_dm_fit_points.csv – DM fit points and residuals (when DM estimation succeeds).
• *_unknown_handoff.txt – estimated period, dm, and reproducible command.
• *_profile.csv, *_folded_profile.png – fold result from known-mode stage.
• *_gated_spectrum_difference.csv, *_gated_spectrum.png
• *_gated_profile.csv, *_gated_profile.png
• *_onoff_pulse_bins.txt, *_summary.txt
• *_dedispersed_time_series.csv, *_dedispersed_time_series.png
• *_raw_phase_heatmap.png, *_phase_aligned_heatmap.png, *_phase_aligned_onminusoff_heatmap.png
• *_gated_spectrum_on.csv, *_gated_spectrum_off.csv
• *_gated_time_series.csv, *_gated_time_series.png
• *_gated_time_series_diff.csv, *_gated_time_series_diff.png

Notes

• Recent versions intentionally reduce redundant CSV/PNG generation to shorten runtime and reduce disk usage.
• Legacy files from older naming/output schemes are cleaned up automatically when running pulsar_gating.

Output Files

frinZ creates organized output directories:

frinZ/
├── fringe_graph/          # Delay/rate plots
│   ├── time_domain/
│   └── freq_domain/
├── fringe_output/         # Text analysis results
├── add_plot/             # Time series plots
├── cumulate/             # Cumulative SNR plots
├── bandpass_table/       # Bandpass calibration files
├── phase_reference/      # Phase reference outputs
└── cor_header/           # Header information

Output File Formats

• Text files (.txt): Analysis results with delay, rate, SNR, and statistics
• Binary files (.bin, .cor): Complex spectra and calibrated data
• Plot files (.png): Visualization of fringe patterns and time series

File Naming Convention

Output files follow the pattern:

{station1}_{station2}_{timestamp}_{source}_{band}_len{length}s[_rfi][_bp]

Example: YAMAGU32_YAMAGU34_2025001120000_3C84_x_len60s_rfi

Command Reference

Required Arguments (one of)

• --input <FILE>: Single .cor file for analysis
• --phase-reference <CAL> <TARGET> [OPTIONS]: Phase referencing mode

Time Parameters

• --length <SECONDS>: Integration time (default: entire file)
• --skip <SECONDS>: Skip time from start (default: 0)
• --loop <COUNT>: Number of processing loops (default: 1)
• --cumulate <SECONDS>: Cumulative integration length

Search Parameters

• --search: Enable precise search mode
• --iter <COUNT>: Search iterations (default: 3)
• --delay-window <MIN MAX>: Delay search range (samples)
• --rate-window <MIN MAX>: Rate search range (Hz)
• --delay-correct <VALUE>: Manual delay correction (samples)
• --rate-correct <VALUE>: Manual rate correction (Hz)

Analysis Options

• --frequency: Frequency domain analysis
• --rfi <"MIN,MAX">: RFI frequency ranges to exclude (MHz)
• --bandpass <FILE>: Apply bandpass calibration
• --bandpass-table: Generate bandpass table

Output Options

• --output: Save text results
• --header: Show header information
• --plot: Generate fringe plots
• --add-plot: Generate time series plots
• --cross-output: Output complex visibility data
• --dynamic-spectrum: Generate dynamic spectrum plots

Performance Notes

frinZ provides significant performance improvements over the Python version:

• Faster FFT processing using rustfft
• Optimized memory usage for large datasets
• Parallel processing capabilities
• Accuracy comparable to original (within 0.1%)

The minor numerical differences (≤0.1%) compared to frinZ.py arise from:

• Different FFT library implementations (rustfft vs scipy.fft)
• Precision differences in binary decoding (Rust: 7-8 digits, Python: 6 digits)
• DC component handling in FFT processing

License

This program is licensed under the MIT License.

Author

(c) M.AKIMOTO with Gemini in 2025/08/04

Related Projects

• frinZ.py - Original Python implementation