rough sketch of abaco autotune api

api.jl

# written in Julia just because its easier and more compact to annotate the code with types (mainly vector vs scalar)
# and group the data into structs.... we will write everything in python
# the goal is just to get a sense of what functions we need from the abaco hardware side (abaco_*)
# and what functions we want to expose from some analysis package, and what data all of those will want

const Vec = Vector{Float64}
struct S21
    frequency::Vec
    transmission::Vec
    phase::Vec  # future
end

struct FluxRampParams
    frequency # we could run at lower frequency to make sure we get nice arcs to find cenering info
    wave_shape  # we could do a square wave for eg transient location
    delay # change transient location
end

struct Centering # to shift ArcData to center the circle and rotate it to avoid the channel arctan crossing
    I0     
    Q0
    θrot
end

struct ArcData
    f::Float64
    power::Float64
    centering_when_aquired::Centering
    I::Vec
    Q::Vec
end

struct ArcSummary
    f::Float64
    power::Float64
    centering_when_aquired::Centering
    I0::Float64
    Q0::Float64
    radius::Float64
    θmin::Float64
    θspan::Float64
    enclosed_area::Float64
    other_quality_metric::Float64
end

struct VPhiData
    f::Float64
    power::Float64
    x::Vec # sample number? time?
    ϕ::Vec # arctan phase
end

struct HardwareSetup
    fs::Vec # absolute frequencies in channel order
    powers::Vec # powers in channel order
    phase_IQ::Vec # phase between I and Q in channel order
    phase::Vec # overall phase in channel order
    lo_frequency::Float64 # lo_frequency
    frp::FluxRampParams
    # we work in absolute frequencies, somewhere else in the code translates to frequency offsets
end

# we may find say 33 resonances, but only have 24 TESs and/or 24 firmware channel
# so at some point we need to use that information to choose a subset of resonsances to 
# proceed with
struct DownselectInfo
    n_channels::Int
    where_we_think_TESs_are_attached # type?, Vector{Bool} per resonance, Vector{Float64} of expected frequencies?
end

# data aquisition
abaco_get_s21(power::Float64) = S21()
abaco_get_arcs(powers::Vec, frequencies::Vec, frp::FluxRampParams) = Vector{ArcData}
abaco_get_vphis(powers::Vec, frequencies::Vec, frp::FluxRampParams) = Vector{VPhiData}
abaco_finalize_tune(hs::HardwareSetup) = nothing

# analysis
find_resonant_frequencies(s21::S21) = Vector{Float64}
analyze_arc(arc::ArcData) = ArcSummary()
# a vector over resonances, then a vector of arcs just on that resonance
choose_independently(arcs::Vector{Vector{ArcSummary}}) = f_choices::Vec, p_choices::Vec
locate_transient(data::VPhiData) = xt # starting position of transient
eliminate_delay(xt::Float64, frp::FluxRampParams) = new_frp::FluxRampParams
downselect(arcs::Vector{Vector{ArcSummary}}, dsi::DownselectInfo) = arcs::Vector{Vector{ArcSummary}}

# future analysis:
choose_jointly(arc::Vector{Vector{ArcSummary}}) =  f_choices::Vec, p_choices::Vec, lo_freq::Float64

# baby's first tune script
power0 = REASONABLE_POWER_LEVEL
frp0 = FLUX_RAMP_PARAMS_GUESS
s21 = abaco_get_s21(power0)
fs = find_resonant_frequencies(s21)
powers = ones(length(fs)) * power0
arcs0 = abaco_get_arcs(powers, fs, frp0)
arcs = downselect(arcs0, DOWNSELECT_INFO)
arcs_analyzed = [[analyze_arc(arc) for arc in arcs_single_resonance] for arcs_single_resonance in arcs]
f_choices, p_choices = choose_independently(arcs_analyzed)
vphis = abaco_get_vphi([power0], f_choices[1:1], frp0)
frp = eliminate_delay(locate_transient(vphi[0]))
abaco_finalize_tune(f_choices, p_choices, frp)