# soltool — gain solution management

`soltool` manages DP3 gain solution files (H5Parm format).  It covers the
full post-calibration workflow: combining per-spectral-window bandpass
solutions, smoothing in time and frequency, and producing diagnostic plots.

## combine — merge per-spectral-window bandpass solutions

`combine` assembles multiple H5Parm gain files into a single broadband
solution.  It handles two cases automatically:

- **Same frequency axis** — files are averaged in time using complex-space
  sigma-clipping.  Outlier time slots (by per-antenna standard deviation and
  flag count) are rejected before averaging.  This is the typical use case
  when each spectral window was calibrated independently on the same
  calibrator observation.

- **Different frequency axes** — files are sorted by frequency and
  concatenated.  All groups must share the same antenna set.

Both cases can occur in the same call: files are first grouped by frequency
axis, each group is averaged, and the averaged groups are then concatenated.

### Usage

```
soltool combine SW*/instrument_di_bp.h5 -o bp_cal.h5
```

Collects one H5Parm per spectral window (each a different frequency range),
averages time slots within each window, and concatenates across windows into
`bp_cal.h5`.  Add `--plot-dir plots/` to also write `spectra.pdf` and
`delay.pdf` alongside the output.

If instead all inputs share the same frequency axis — e.g. several calibrator
passes of the same field — `combine` reduces them to a single time-averaged
solution, giving a more stable bandpass:

```
soltool combine obs1/instrument_di_bp.h5 obs2/instrument_di_bp.h5 -o bp_cal_mean.h5
```

### Reference

```{eval-rst}
.. click:: nenucal.tools.soltool:combine
   :prog: soltool combine
   :nested: full
```

---

## smooth — Gaussian smoothing in time and frequency

`smooth` applies a 2-D Gaussian kernel to the amplitude and phase of one or
more gain solution files.  It operates in-place: the smoothed values are
written back into the same H5Parm file.

The kernel size is expressed as a full-width at half-maximum (FWHM) in
minutes (time axis) and MHz (frequency axis).  A separate, typically larger,
kernel is used for the direction named `Main` (the target field) to reflect
the expectation that the main-field solutions vary more slowly than bright
off-axis sources.

Phase smoothing is done in the complex plane (`exp(i·phase)`) to avoid
wrapping artefacts near ±π.  Flagged samples (stored as NaN) are excluded
from the convolution via a masked-array boundary extension.

Amplitude outliers are sigma-clipped at `--clip_nsigma` before smoothing so
that a single bad solution does not spread into its neighbours.

### Usage

```
soltool smooth instrument_di.h5
```

Applies a 16 min × 2 MHz kernel to all directions except `Main`, and a
20 min × 4 MHz kernel to `Main`.  Tighten the kernels for a
direction-dependent solution:

```
soltool smooth instrument_dde.h5 --fwhm_time 8 --fwhm_freq 1 --main_fwhm_time 12 --main_fwhm_freq 2
```

Several files can be passed at once (each smoothed independently), and
`--clip_nsigma` (default 4) controls how aggressively amplitude outliers are
clipped before the Gaussian convolution.

### Reference

```{eval-rst}
.. click:: nenucal.tools.soltool:smooth
   :prog: soltool smooth
   :nested: full
```

---

## plot — waterfall plots per antenna

`plot` produces amplitude and phase waterfall images (time on the x-axis,
frequency on the y-axis) for every antenna in the solution file.  One PNG is
written per combination of data type (amplitude or phase), calibration
direction, and polarisation.

All PNGs for a given solution file are written to a subdirectory named
`sol_plots/` next to the file (configurable with `--plot_dir`).

### Usage

```
soltool plot instrument_di.h5
```

Writes PNGs to `instrument_di/sol_plots/`, one per direction and polarisation
for both amplitude and phase.  Use `--plot_dir` to change the output location;
multiple files can be passed in one call.

### Reference

```{eval-rst}
.. click:: nenucal.tools.soltool:plot
   :prog: soltool plot
   :nested: full
```

---

## plot-spectra — bandpass amplitude spectra

`plot-spectra` writes a multi-page PDF showing the bandpass amplitude as a
function of frequency for each antenna.  Both polarisations are overlaid on
the same axes.  The first time slot (index 0) is used, so this command is
most informative on a solution file that already has a single representative
time step — for example the output of `combine`.

Five antennas are shown per page by default (`--nrows`).

### Usage

```
soltool plot-spectra bp_cal.h5
```

Writes `bp_cal_spectra.pdf` next to the input file.  `-o` sets a custom output
path and `--nrows` changes how many antennas are shown per page (default 5).

### Reference

```{eval-rst}
.. click:: nenucal.tools.soltool:plot_spectra_cmd
   :prog: soltool plot-spectra
   :nested: full
```

---

## plot-delay — delay spectrum per antenna

`plot-delay` computes the Fourier transform of each antenna's bandpass
amplitude along the frequency axis and plots the resulting delay power
spectrum.  Peaks at non-zero delay reveal spectrally structured gain
errors caused by RFI, cable reflections, or calibration artefacts.

All antennas are shown in a grid on a single page.  Frequencies above
`--fmax` (default 71 MHz, just below the FM band) are excluded before
the transform.  The y-axis is logarithmic and the x-axis runs from 0 to
`--delay-max` microseconds.

The command requires `ps_eor` to be installed.  If it is not available,
a warning is printed and the command exits gracefully without writing a file.

### Usage

```
soltool plot-delay bp_cal.h5
```

Writes `bp_cal_delay.pdf` next to the input file.  `-o` sets the output path,
`--delay-max` the x-axis range (µs), and `--fmax` the upper frequency cutoff —
useful when the top of the band is heavily flagged.

### Reference

```{eval-rst}
.. click:: nenucal.tools.soltool:plot_delay_cmd
   :prog: soltool plot-delay
   :nested: full
```