syncsim

type AR1Config struct {
	// Tau is the correlation time constant in seconds.
	Tau Seconds `toml:"tau" check:">=0,<=1000000" comment:"Correlation time constant (s)"`

	// Sigma is the steady-state RMS in nanoseconds.
	Sigma clocksim.Nanoseconds `toml:"sigma" check:">=0,<=10000" comment:"Steady-state RMS (ns)"`
}

type AR1FMConfig struct {
	// Tau is the correlation time constant in seconds.
	Tau Seconds `toml:"tau" check:">=0,<=1000000" comment:"Correlation time constant (s)"`

	// Sigma is the steady-state RMS of frequency bias in ppb.
	Sigma clocksim.PPB `toml:"sigma" check:">=0,<=10000" comment:"Steady-state RMS of frequency bias (ppb)"`
}

type Config struct {
	Sim   SimConfig      `toml:"sim" comment:"Simulation parameters"`
	PHC   PHCConfig      `toml:"phc" comment:"PHC oscillator error model"`
	GPS   GPSConfig      `toml:"gps" comment:"GPS time pulse error model"`
	Sync  phcsync.Config `toml:"sync" comment:"PHC sync controller parameters"`
	Pulse PulseConfig    `toml:"pulse" comment:"Pulse delivery timing"`
	Msg   MsgConfig      `toml:"msg" comment:"GPS message delivery timing"`
	Fault FaultConfig    `toml:"fault" comment:"Fault injection parameters"`
}

type DriftConfig struct {
	// Tau is the characteristic timescale in seconds.
	Tau Seconds `toml:"tau" check:">=0,<=1000000" comment:"Characteristic timescale (s)"`

	// Sigma is the RMS phase deviation in nanoseconds.
	Sigma clocksim.Nanoseconds `toml:"sigma" check:">=0,<=10000" comment:"RMS phase deviation (ns)"`

	// Zeta is the damping ratio.
	Zeta float64 `toml:"zeta" check:">=0,<=10" comment:"Damping ratio"`
}

type Event struct {
	Time float64
	Type EventType
	Data any
}

type EventType int

type ExcursionConfig struct {
	// StartTime is when the excursion begins in seconds.
	StartTime Seconds `toml:"startTime" check:">=0" comment:"When excursion begins (s)"`

	// Duration is the total excursion duration including ramps in seconds.
	Duration Seconds `toml:"duration" check:">=0" comment:"Total duration including ramps (s)"`

	// Amplitude is the peak phase shift in nanoseconds.
	Amplitude clocksim.Nanoseconds `toml:"amplitude" comment:"Peak phase shift (ns)"`

	// Rise configures the rising edge ramp.
	Rise RampConfig `toml:"rise" comment:"Rising edge ramp"`

	// Fall configures the falling edge ramp.
	Fall RampConfig `toml:"fall" comment:"Falling edge ramp"`
}

type FaultConfig struct {
	Outage    []OutageConfig    `toml:"outage" comment:"Signal outage periods"`
	Outlier   []OutlierConfig   `toml:"outlier" comment:"Discrete phase outlier injection"`
	Excursion []ExcursionConfig `toml:"excursion" comment:"Temporary phase excursions"`
}

type FreqSinusoid struct {
	// Period is the oscillation period in seconds.
	Period Seconds `toml:"period" check:">0,<=1000000" comment:"Oscillation period (s)"`

	// Amp is the frequency amplitude in parts-per-billion.
	Amp clocksim.PPB `toml:"amp" check:">=0,<=10000" comment:"Frequency amplitude (ppb)"`

	// PhaseInit is the initial phase as a fraction of cycle [0,1).
	PhaseInit float64 `toml:"phaseInit" check:">=0,<1" comment:"Initial phase [0,1)"`
}

type GPSConfig struct {
	// Jitter is white phase noise stddev in nanoseconds.
	// Typical: 0.1-5 ns survey-grade, 5-50 ns consumer-grade.
	Jitter clocksim.Nanoseconds `toml:"jitter" check:">=0,<=1000" comment:"White phase noise stddev (ns)"`

	// Sawtooth configures GPS receiver quantization sawtooth error.
	Sawtooth SawtoothConfig `toml:"sawtooth" comment:"GPS receiver quantization sawtooth error"`

	// AR1 is a list of AR(1) colored phase noise processes.
	AR1 []AR1Config `toml:"ar1" comment:"AR(1) colored phase noise processes"`

	// AR1FM is an AR(1) frequency modulation process (sigma in ppb).
	AR1FM AR1FMConfig `toml:"ar1FM" comment:"AR(1) frequency modulation process"`

	// RandomWalk is the random walk FM coefficient in ppb/√s.
	RandomWalk float64 `toml:"randomWalk" check:">=0,<=1000" comment:"Random walk FM coefficient (ppb/√s)"`

	// Drift configures bounded drift (2nd-order Gauss-Markov).
	Drift DriftConfig `toml:"drift" comment:"Bounded drift (2nd-order Gauss-Markov)"`

	// Resonator configures a damped oscillator on phase.
	Resonator ResonatorConfig `toml:"resonator" comment:"Damped oscillator on phase"`

	// Sinusoid is a list of sinusoidal phase modulation components.
	Sinusoid []PhaseSinusoid `toml:"sinusoid" comment:"Sinusoidal phase modulation components"`
}

type MsgConfig struct {
	// Delay is the mean delay from the PPS pulse to when the GPS time message
	// is received. Real GPS receivers take 50-250ms to transmit after the pulse.
	Delay Seconds `toml:"delay" check:">=0,<1" comment:"Mean message delay after pulse (s)"`

	// Jitter is the standard deviation of the message arrival time.
	Jitter Seconds `toml:"jitter" check:">=0,<1" comment:"Message delay stddev (s)"`

	// SawtoothType specifies how sawtooth correction messages are delivered:
	//   - SawtoothPrePulse ("prepulse"): Correction arrives before the pulse (UBX-TIM-TP)
	//   - SawtoothPostPulse ("postpulse"): Correction arrives after the pulse (UBX-TIM-TOS)
	//   - SawtoothNone ("none"): No correction messages
	SawtoothType SawtoothType `toml:"sawtoothType" comment:"How sawtooth correction is delivered (prepulse/postpulse/none)"`

	// PrePulseTime is the time before the PPS edge when a PrePulse correction
	// message is delivered. Only used when SawtoothType is SawtoothPrePulse.
	PrePulseTime Seconds `toml:"prePulseTime" check:">=0,<1" comment:"Time before pulse for prepulse message (s)"`

	// PostPulseDelay is the delay after the PPS edge when a PostPulse correction
	// message is delivered. Only used when SawtoothType is SawtoothPostPulse.
	PostPulseDelay Seconds `toml:"postPulseDelay" check:">=0,<1" comment:"Delay after pulse for postpulse message (s)"`
}

type NavSolutionMsgEventData struct {
	PPS float64
}

type OutageConfig struct {
	// StartTime is when the outage begins in seconds.
	StartTime Seconds `toml:"startTime" check:">=0" comment:"When outage begins (s)"`

	// Duration is the outage duration in seconds.
	Duration Seconds `toml:"duration" check:">=0" comment:"Outage duration (s)"`
}

type OutlierConfig struct {
	// Time is the simulation time at which to inject an outlier.
	Time Seconds `toml:"time" check:">=0" comment:"When to inject outlier (s)"`

	// Offset is the magnitude of the phase offset to inject in nanoseconds.
	// Typical multipath outliers are 1000-10000 ns (1-10 µs).
	Offset clocksim.Nanoseconds `toml:"offset" comment:"Outlier offset magnitude (ns)"`
}

type PHCConfig struct {
	// FreqOffset is the constant frequency offset in ppb.
	// Typical values: ±1000-10000 ppb for factory-trimmed oscillators.
	FreqOffset clocksim.PPB `toml:"freqOffset" check:">=-1_000_000,<=1_000_000" comment:"Constant frequency offset (ppb)"`

	// Drift is the linear frequency drift rate in ppb per day.
	Drift float64 `toml:"drift" check:">=-1_000_000,<=1_000_000" comment:"Linear frequency drift (ppb/day)"`

	// WhiteNoise is the standard deviation of white frequency noise in ppb.
	// Typical values are 1-20 ppb for good crystals.
	WhiteNoise clocksim.PPB `toml:"whiteNoise" check:">=0,<=10000" comment:"White frequency noise stddev (ppb)"`

	// FlickerNoise is the standard deviation of flicker (1/f) frequency noise in ppb.
	// Typical values are 0.1-5 ppb for crystals.
	FlickerNoise clocksim.PPB `toml:"flickerNoise" check:">=0,<=10000" comment:"Flicker (1/f) frequency noise stddev (ppb)"`

	// RandomWalk is the random walk FM coefficient in ppb/√s.
	// Typical values are 0.01-1 ppb/√s.
	RandomWalk clocksim.PPB `toml:"randomWalk" check:">=0,<=10000" comment:"Random walk FM coefficient (ppb/√s)"`

	// Sinusoid is a list of sinusoidal frequency modulation components.
	Sinusoid []FreqSinusoid `toml:"sinusoid" comment:"Sinusoidal frequency modulation components"`
}

type PhaseSinusoid struct {
	// Period is the oscillation period in seconds.
	Period Seconds `toml:"period" check:">0,<=1000000" comment:"Oscillation period (s)"`

	// Amp is the phase amplitude in nanoseconds.
	Amp clocksim.Nanoseconds `toml:"amp" check:">=0,<=10000" comment:"Phase amplitude (ns)"`

	// PeakAt is the time of day when the sinusoid peaks.
	// Used with SimConfig.StartTime to calculate initial phase.
	// Defaults to 06:00:00, which gives phase 0 when StartTime is 00:00:00.
	PeakAt toml.LocalTime `toml:"peakAt" comment:"Time of day when sinusoid peaks (HH:MM:SS)"`
}

type PostPulseMsgEventData struct {
	PPS float64
}

type PrePulseMsgEventData struct {
	PPS      float64
	Sawtooth float64
}

type PulseConfig struct {
	// MinDelay is the minimum delay from the true GPS second to when the
	// PPS pulse edge is delivered to the PHC timestamper. Real GPS receivers
	// have internal processing delays that prevent the pulse from arriving
	// exactly at the second boundary. The actual delay for each pulse is
	// uniformly distributed between MinDelay and MaxDelay.
	// Typical values are 5-50 microseconds (0.000005 to 0.00005).
	MinDelay Seconds `toml:"minDelay" check:">=0,<1" comment:"Min pulse delay from GPS second (s)"`

	// MaxDelay is the maximum delay from the true GPS second to when the
	// PPS pulse edge is delivered to the PHC timestamper. Must be >= MinDelay.
	MaxDelay Seconds `toml:"maxDelay" check:">=0,<1" comment:"Max pulse delay from GPS second (s)"`

	// Width is the pulse width for dual-edge timestamping mode.
	// When Width > 0, the simulator generates both rising and falling edges.
	// When Width = 0, only rising edges are generated (single-edge mode).
	// Typical GPS receivers use 100ms (0.1) pulse width.
	Width Seconds `toml:"width" check:">=0,<1" comment:"Pulse width (0=single-edge mode)"`
}

type PulseEventData struct {
	EdgeIdx int
	PPS     float64
}

type RampConfig struct {
	// Duration is the ramp duration in seconds. 0 means instant transition.
	Duration Seconds `toml:"duration" check:">=0" comment:"Ramp duration (s)"`

	// Power controls the ramp shape. nil defaults to 2.0 (smooth S-curve).
	// power > 1 gives smooth acceleration/deceleration at endpoints.
	// power = 1 is linear.
	Power *float64 `toml:"power" check:">0,<=10" comment:"Shape power (>1 for smooth S-curve)"`
}

type ResonatorConfig struct {
	// Period is the natural oscillation period in seconds.
	Period Seconds `toml:"period" check:">=0,<=1000000" comment:"Natural oscillation period (s)"`

	// Sigma is the RMS phase deviation in nanoseconds.
	Sigma clocksim.Nanoseconds `toml:"sigma" check:">=0,<=10000" comment:"RMS phase deviation (ns)"`

	// Zeta is the damping ratio.
	Zeta float64 `toml:"zeta" check:">=0,<=10" comment:"Damping ratio"`
}

type SawtoothConfig struct {
	// Amp is the sawtooth amplitude in nanoseconds (≈ 0.5e9/f_osc).
	Amp float64 `toml:"amp" check:">=0,<=1000" comment:"Sawtooth amplitude (ns, ≈ 0.5e9/f_osc)"`

	// PhaseInit is the initial phase [0,1), default 0.5.
	PhaseInit float64 `toml:"phaseInit" check:">=0,<1" comment:"Initial phase [0,1)"`

	// InternalClock models the GPS receiver's internal oscillator error.
	InternalClock FreqSinusoid `toml:"internalClock" comment:"GPS internal oscillator error model"`
}

type SawtoothType int

type Seconds = float64

type SimConfig struct {
	// Duration is the simulation duration in seconds.
	Duration Seconds `toml:"duration" check:">0" comment:"Simulation duration (s)"`

	// StartTime is the wall-clock time of day for simulation t=0.
	// Used with PhaseSinusoid.PeakAt to calculate initial phase.
	// Defaults to 00:00:00 (midnight).
	StartTime toml.LocalTime `toml:"startTime" comment:"Wall-clock time for t=0 (HH:MM:SS)"`
}

type Stats struct {
	statsobs.Stats                       // embedded - detailed tracking statistics from observer
	SampleCount     int                  // total samples fed to controller
	TrackingStdDev  float64              // stddev from true time in nanoseconds (simulation-only)
	TrackingMean    float64              // mean offset from true time in nanoseconds (simulation-only)
	TrackingAbsMax  time.Duration        // max absolute offset from true time (simulation-only)
	TrackingADev    float64              // Allan deviation of tracking offsets (simulation-only)
	ModeSamples     map[phcsync.Mode]int // samples per mode (non-zero only)
	ModeTransitions map[phcsync.Mode]int // transitions into each mode (non-zero only)
}

type TickEventData struct {
}