# Quickstart

## Prerequisites

- Rust toolchain (1.80+): <https://rustup.rs>
- Optional: `libcfitsio-dev` for FITS ingest (see {doc}`overview`)

## Building

```bash
# Show all available targets
make help

# Pure Zarr mode (no C dependencies)
make release

# Full build with FITS ingest (needs libcfitsio-dev)
make release-full

# Install to ~/.cargo/bin (installs both calibrate and zarr-fits binaries)
make install          # pure Zarr
make install-full     # with FITS ingest + zarr-fits binary
```

## Running Calibration

From a pre-converted Zarr store:

```bash
calibrate -i /data/l0/session.zarr \
          --output /data/l1/ \
          --atm-table atm.catm
```

From a FITS folder (requires `fits-ingest` feature):

```bash
calibrate -f /data/raw/session_001 \
          --output /data/l1/ \
          --atm-table atm.catm
```

This creates `session_001.zarr` alongside the FITS folder, then calibrates.
On subsequent runs the conversion is skipped automatically.

## Common Options

```bash
# Fixed PWV instead of fitting
calibrate -i session.zarr --output l1/ --atm-table atm.catm --pwv 1.2

# Custom instrument parameters (new flag names with backward-compat aliases)
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --forward-eff 0.95 --sideband-gain 0.45
# Equivalent using old aliases:
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --foeff 0.95 --gain-image 0.45

# Gain interpolation level 2
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --gain-interpolate 2

# Per-pixel PWV fitting
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --pwv-per-pixel

# SKYDIFF diagnostic
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --skydiff 3

# SKYCHOPDIFF diagnostic (chopped scans; add --dbs-coupling for
# kalibrate-style blended skies)
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --skydiff 3 --skychopdiff

# List scans without calibrating
calibrate -i session.zarr --list-scans

# Calibrate only a scan range
calibrate -i session.zarr --output l1/ --atm-table atm.catm \
  --scan-range 25650 25660
```

## Standalone FITS Conversion

```bash
zarr-fits convert \
  --fits-folder /data/raw/session_001 \
  --zarr-path /data/l0/session.zarr
```

## Checking Output

Read the L1 Zarr store with Python:

```python
import zarr

store = zarr.open("/data/l1/scan_025650", mode="r")
spectra = store["spectra"][:]    # [C, D, R, A, S] antenna temperature
t_sys = store["t_sys"][:]       # [C, R, A, S] system temperature
flags = store["flags"][:]       # [C, D, R, A, S] u16 bitmask
```

## Python Bindings

```bash
cd crates/cal-py && maturin develop
```

```python
import _cal_rs

scans = _cal_rs.list_scans("/data/l0/session.zarr")
result = _cal_rs.calibrate_store(
    input_path="/data/l0/session.zarr",
    output_path="/data/l1/",
    atm_table_path="atm.catm",
)
print(f"OK: {result['successes']}, Failed: {len(result['failures'])}")
```

## Running Tests

```bash
make test          # all tests (needs libcfitsio-dev)
make test-cal      # calibration tests only (no cfitsio)
make test-zarr     # FITS conversion tests only
```