AIDT 온디바이스 STEM 방사광 X선 스트론튬(Sr-87) 광격자 원자시계 램-디케(Lamb-Dicke) 분해능 레이저 주파수 안정화 서보 제어기

using System;
using System.Runtime.CompilerServices;

namespace ZeliDesk.Stem.OpticalClock
{
    /// <summary>
    /// PDH 복조 오차 전압 및 캐비티 환경 계측 상태
    /// </summary>
    public readonly ref struct PdhDemodulationTelemetryState
    {
        public readonly double PdhErrorVoltageMilliVolts; // PDH 믹서 출력 오차 전압 [mV]
        public readonly double PdhSensitivityMvPerHz;     // 전압-주파수 오차 감도 [mV/Hz]
        public readonly double CavityTempKelvin;          // ULE 공진기 제로 팽창 온도 [K]
        public readonly double LatticePowerWatts;         // 813nm 매직 격자 레이저 파워 [W]

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public PdhDemodulationTelemetryState(double vErr, double sens, double temp, double pLattice)
        {
            PdhErrorVoltageMilliVolts = vErr;
            PdhSensitivityMvPerHz = sens;
            CavityTempKelvin = temp;
            LatticePowerWatts = pLattice;
        }
    }

    /// <summary>
    /// AOM 고속 주파수 및 피에조 저속 보정 출력
    /// </summary>
    public readonly ref struct ClockLaserServoOutput
    {
        public readonly double AomFrequencyShiftHz;   // AOM 고속 주파수 보정치 [Hz]
        public readonly double PiezoCommandVolts;     // 공진기 피에조 미러 전압 [V]
        public readonly double ResidualFrequencyJitterHz;// 잔류 주파수 지터 [Hz]
        public readonly bool IsClockLocked;          // 시계선 잠금(<0.5Hz) 유지 플래그

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public ClockLaserServoOutput(double aomShift, double pztVolt, double jitter, bool locked)
        {
            AomFrequencyShiftHz = aomShift;
            PiezoCommandVolts = pztVolt;
            ResidualFrequencyJitterHz = jitter;
            IsClockLocked = locked;
        }
    }

    /// <summary>
    /// 10,000Hz 스트론튬 광격자 원자시계 레이저 주파수 안정화 서보 엔진
    /// </summary>
    public ref struct StrontiumClockLaserServoEngine
    {
        private readonly double _kpFast;
        private readonly double _kiFast;
        private readonly double _kdFast;
        private readonly double _kSlowPiezo;
        private readonly double _maxAomShiftHz;
        private readonly double _maxPiezoVolts;

        private double _intFast;
        private double _prevFreqErrHz;
        private double _piezoAccumVolt;

        public StrontiumClockLaserServoEngine(
            double kpFast,
            double kiFast,
            double kdFast,
            double kSlowPiezo,
            double maxAomShiftHz,
            double maxPiezoVolts)
        {
            _kpFast = kpFast;
            _kiFast = kiFast;
            _kdFast = kdFast;
            _kSlowPiezo = kSlowPiezo;
            _maxAomShiftHz = maxAomShiftHz;
            _maxPiezoVolts = maxPiezoVolts;
            _intFast = 0.0;
            _prevFreqErrHz = 0.0;
            _piezoAccumVolt = 0.0;
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public ClockLaserServoOutput ProcessCycle(
            in PdhDemodulationTelemetryState state,
            double dtSeconds)
        {
            // 1. PDH 전압으로부터 물리적 주파수 오차 Delta f [Hz] 연산
            double freqErrorHz = state.PdhErrorVoltageMilliVolts / Math.Max(1e-4, state.PdhSensitivityMvPerHz);

            // 2. 고속 루프: AOM RF 구동 주파수 PID 보정
            _intFast += freqErrorHz * dtSeconds;
            double dErr = (freqErrorHz - _prevFreqErrHz) / dtSeconds;
            _prevFreqErrHz = freqErrorHz;

            double aomShiftHz = _kpFast * freqErrorHz + _kiFast * _intFast + _kdFast * dErr;
            aomShiftHz = Math.Clamp(aomShiftHz, -_maxAomShiftHz, _maxAomShiftHz);

            // 3. 저속 루프: AOM 동작점을 중앙으로 유지하기 위한 피에조 미러 적분
            _piezoAccumVolt += _kSlowPiezo * aomShiftHz * dtSeconds;
            _piezoAccumVolt = Math.Clamp(_piezoAccumVolt, -_maxPiezoVolts, _maxPiezoVolts);

            // 4. 잔류 지터 및 잠금 판정 (0.5Hz 이하 안정화)
            double residualJitterHz = Math.Abs(freqErrorHz - aomShiftHz);
            bool isLocked = residualJitterHz <= 0.5;

            return new ClockLaserServoOutput(
                aomShiftHz,
                _piezoAccumVolt,
                residualJitterHz,
                isLocked);
        }
    }
}