frinZ 4.2.0

fringe search for Yamaguchi Interferometer and Japanese VLBI Network
Documentation

frinZrs

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

frinZrs 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/frinZrs.git
cd frinZrs

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

Development Build

# Run directly
cargo run --bin frinZ --release -- [OPTIONS]
# OR
cargo run --bin frinZ-rs --release -- [OPTIONS]

Note: Both frinZ and frinZ-rs are identical programs. 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>

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

pulsar_gating --input data.cor \
  --period 0.253 --dm 26.7 \
  --bins 128 --on-duty 0.12

Outputs (CSV + PNG) are written under frinZ/pulsar_gating next to the input file:

  • *_raw_time_series.* – frequency-integrated amplitudes without DM correction
  • *_dedispersed_time_series.* – dedispersed, frequency-integrated amplitude vs time
  • *_mean_spectrum.* – time-integrated spectrum across channels
  • *_dedispersed_spectrum.* – DM 補正後の時間積分スペクトル
  • *_profile.* – folded pulse profile and gating summary
  • *_raw_heatmap.png – amplitude/phase heatmap of the raw spectra (PP × channel)
  • *_dedispersed_heatmap.png – DM 補正後のスペクトル行列（指定した場合のみ）
  • *_phase_resolved_amplitude.png – DM 補正後のパルス位相 vs 振幅プロファイル
  • *_phase_series.png – 周波数積分後の時系列を位相軸に展開した散布図

Output Files

frinZrs 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

frinZrs 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