<img src="./src/frinZmain/frinZlogo1.png" width=45%>  <img src="./src/frinZmain/frinZlogo2.png" width=45%>

# 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

```bash
# 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

```bash
# 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

```bash
frinZ [OPTIONS]
```

### Input Options

#### Single File Analysis
```bash
# 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
```bash
# 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
```bash
# Cross-power spectrum instead of fringe
frinZ --input data.cor --frequency
```

#### Precise Search Mode
```bash
# 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
```bash
# Apply delay and rate corrections
frinZ --input data.cor --delay-correct 5.2 --rate-correct -0.03
```

### RFI Mitigation

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

### Bandpass Calibration

```bash
# 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
```bash
# Save analysis results to text files
frinZ --input data.cor --output

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

#### Plotting
```bash
# 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
```bash
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
```bash
frinZ --phase-reference cal.cor target.cor 1 30 60 5 \
  --search --plot --output
```

### Pulsar Gating Analysis

```bash
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](https://github.com/M-AKIMOTOO/frinZ.py) - Original Python implementation
