///|
pub(all) struct TransferChannel {
  peak : Double
  outside_window_energy_fraction : Double?
  reconstruction_error_fraction : Double?
}

///|
/// A linear estimate of the sampled transfer from a known dry excitation to a
/// recorded signal. Diagnostics describe these inputs only.
pub struct TransferEstimate {
  audio : Audio
  transform_frames : Int32
  recording_frames : Int32
  probe_frames : Int32
  regularization_db : Double
  reliable_bins : Int32
  unique_bins : Int32
  channels : Array[TransferChannel]
}

///|
fn pad_spectrum(
  data : Array[Double],
  length : Int32,
) -> Result[Array[@spectrum.Complex], String] {
  let time = Array::make(length, @spectrum.Complex::zero())
  for i, value in data {
    time[i] = @spectrum.complex(re=value, im=0.0)
  }
  Ok(@spectrum.fft(time[:])) catch {
    _ => Err("transfer FFT failed")
  }
}

///|
fn bin_power(bin : @spectrum.Complex) -> Double {
  bin.re * bin.re + bin.im * bin.im
}

///|
fn transfer_reconstruction_error(
  estimate : Array[Double],
  source_fft : Array[@spectrum.Complex],
  observed_fft : Array[@spectrum.Complex],
) -> Result[Double?, String] {
  let restored = match pad_spectrum(estimate, source_fft.length()) {
    Ok(values) => values
    Err(reason) => return Err(reason)
  }
  let mut residual = 0.0
  let mut total = 0.0
  for index, measured in observed_fft {
    let predicted = restored[index].mul(source_fft[index])
    let re = predicted.re - measured.re
    let im = predicted.im - measured.im
    residual += re * re + im * im
    total += bin_power(measured)
  }
  Ok(if total > 0.0 { Some(residual / total) } else { None })
}

///|
fn transfer_channel(
  recording : Array[Double],
  source_fft : Array[@spectrum.Complex],
  regularization : Double,
  frames : Int32,
) -> Result[(Array[Double], TransferChannel), String] {
  let fft_len = source_fft.length()
  let observed_fft = match pad_spectrum(recording, fft_len) {
    Ok(values) => values
    Err(reason) => return Err(reason)
  }
  let response_fft = Array::makei(fft_len, fn(index) {
    let x = source_fft[index]
    let y = observed_fft[index]
    let divisor = bin_power(x) + regularization
    @spectrum.complex(
      re=(y.re * x.re + y.im * x.im) / divisor,
      im=(y.im * x.re - y.re * x.im) / divisor,
    )
  })
  let response = @spectrum.ifft(response_fft[:]) catch {
    _ => return Err("transfer inverse FFT failed")
  }
  let estimated = Array::make(frames, 0.0)
  let mut outside = 0.0
  let mut total = 0.0
  let mut peak = 0.0
  for i, value in response {
    let sample = value.re
    if !(sample >= -1.0e20 && sample <= 1.0e20) {
      return Err("estimated impulse response exceeds sample magnitude budget")
    }
    let energy = sample * sample
    total += energy
    if i < frames {
      estimated[i] = sample
      peak = peak.max(sample.abs())
    } else {
      outside += energy
    }
  }
  let reconstruction_error_fraction = match
    transfer_reconstruction_error(estimated, source_fft, observed_fft) {
    Ok(value) => value
    Err(reason) => return Err(reason)
  }
  Ok(
    (
      estimated,
      {
        peak,
        outside_window_energy_fraction: if total == 0.0 {
          None
        } else {
          Some(outside / total)
        },
        reconstruction_error_fraction,
      },
    ),
  )
}

///|
/// Frequency-domain Tikhonov estimate H = Y*conj(X)/(|X|²+lambda).
/// The recorded signal and probe must have a common origin and sample rate.
/// The recording must include probe_frames + response_frames - 1 samples.
/// The returned impulse starts at recording frame zero, including any delay.
pub fn estimate_transfer(
  probe : Array[Double],
  recording : Array[Array[Double]],
  sample_rate : Int32,
  response_frames : Int32,
  regularization_db~ : Double = -80.0,
) -> Result[TransferEstimate, String] {
  let recording_frames = match
    checked_audio_frames(recording, sample_rate, 262144, 2000000, 1.0e20) {
    Err(reason) => return Err(reason)
    Ok(frames) => frames
  }
  if probe.is_empty() ||
    !probe.all(v => v >= -1.0e6 && v <= 1.0e6) ||
    response_frames <= 0 ||
    response_frames > 131072 ||
    probe.length().to_int64() + response_frames.to_int64() - 1L >
    recording_frames.to_int64() ||
    !(regularization_db >= -140.0 && regularization_db <= -20.0) {
    return Err("invalid probe, regularization or insufficient recorded tail")
  }
  let fft_len = @spectrum.next_power_of_two(recording_frames) catch {
    _ => return Err("transfer FFT size selection failed")
  }
  if fft_len * recording.length() > 1048576 {
    return Err("transfer transform budget exceeded: 1048576 channel bins")
  }
  let source_fft = match pad_spectrum(probe, fft_len) {
    Ok(values) => values
    Err(reason) => return Err(reason)
  }
  let mut max_power = 0.0
  let unique_bins = fft_len / 2 + 1
  for i in 0..= regularization {
      reliable_bins += 1
    }
  }
  let samples : Array[Array[Double]] = []
  let channels : Array[TransferChannel] = []
  for input in recording {
    match transfer_channel(input, source_fft, regularization, response_frames) {
      Err(reason) => return Err(reason)
      Ok((response, diagnostic)) => {
        samples.push(response)
        channels.push(diagnostic)
      }
    }
  }
  Ok({
    audio: { samples, sample_rate, latency_samples: 0, },
    transform_frames: fft_len,
    recording_frames,
    probe_frames: probe.length(),
    regularization_db,
    reliable_bins,
    unique_bins,
    channels,
  })
}