AIDT 온디바이스 STEM 방사광 X선 극저온 초전도 키네틱 인덕턴스 검출기(KID) 주파수 다중화 서보 제어기

using System;
using System.Runtime.CompilerServices;

namespace ZeliDesk.Stem.CryoKidMultiplexing
{
    /// <summary>
    /// MKID 단일 공진 채널 IQ 텔레메트리 상태
    /// </summary>
    public readonly ref struct KidChannelTelemetryState
    {
        public readonly double InPhaseMilliVolts;         // 호모다인 I 신호 [mV]
        public readonly double QuadratureMilliVolts;     // 호모다인 Q 신호 [mV]
        public readonly double CryoStageTempMilliK;       // 헬륨-3 극저온단 온도 [mK]
        public readonly double ProbeToneFrequencyMegaHz;  // 현재 인가 프로브 톤 주파수 [MHz]

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public KidChannelTelemetryState(double iVal, double qVal, double tempMk, double fProbe)
        {
            InPhaseMilliVolts = iVal;
            QuadratureMilliVolts = qVal;
            CryoStageTempMilliK = tempMk;
            ProbeToneFrequencyMegaHz = fProbe;
        }
    }

    /// <summary>
    /// MKID DDS 주파수 합성기 서보 지령
    /// </summary>
    public readonly ref struct KidChannelServoCommand
    {
        public readonly double CommandedToneFrequencyMegaHz; // 갱신된 프로브 주파수 [MHz]
        public readonly double PhaseShiftRadians;           // 복조 위상 회전량 [rad]
        public readonly bool ResonanceLocked;                // 공진점 중심 록킹 여부

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public KidChannelServoCommand(double fCmd, double dTheta, bool locked)
        {
            CommandedToneFrequencyMegaHz = fCmd;
            PhaseShiftRadians = dTheta;
            ResonanceLocked = locked;
        }
    }

    /// <summary>
    /// 10,000Hz 0-Alloc MKID 공진 추종 서보 엔진
    /// </summary>
    public sealed class CryoKidServoEngine
    {
        private const double ResonanceQint = 85000.0;     // 내부 품질 계수 Q_int = 85,000
        private const double Ic = 0.0;                     // 공진원 중심 I 좌표 [mV]
        private const double Qc = 0.0;                     // 공진원 중심 Q 좌표 [mV]
        private const double TempSensitivity = 0.0025;     // 2.5 kHz / mK 열편이 계수
        private double _currentToneFreq;
        private double _intPhaseErr;

        public CryoKidServoEngine(double initialCenterFreqMegaHz)
        {
            _currentToneFreq = initialCenterFreqMegaHz;
            _intPhaseErr = 0.0;
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public KidChannelServoCommand UpdateServoLoop(in KidChannelTelemetryState telemetry, double dtSeconds)
        {
            // 1. 공진원 중심점 대비 위상 회전각 산출
            double dI = telemetry.InPhaseMilliVolts - Ic;
            double dQ = telemetry.QuadratureMilliVolts - Qc;
            double phaseAngle = Math.Atan2(dQ, dI);

            // 2. 적분 오차 누적 (Anti-Windup 적용)
            _intPhaseErr = Math.Clamp(_intPhaseErr + (phaseAngle * dtSeconds), -1.0, 1.0);

            // 3. 온도 변동에 따른 열적 키네틱 인덕턴스 피드포워드 역보상
            double tempOffsetMilliK = telemetry.CryoStageTempMilliK - 300.0; // 300mK 기준선
            double tempCompensationMegaHz = tempOffsetMilliK * TempSensitivity * 1e-3;

            // 4. 공진 주파수 DDS 서보 갱신 지령
            double freqCorrection = (phaseAngle / (4.0 * ResonanceQint)) * _currentToneFreq * 1.5;
            double deltaFreq = freqCorrection + (_intPhaseErr * 0.001) - tempCompensationMegaHz;

            _currentToneFreq += deltaFreq * dtSeconds;

            bool isLocked = Math.Abs(phaseAngle) < 0.08; // 0.08 rad 이내 잠금
            return new KidChannelServoCommand(_currentToneFreq, phaseAngle, isLocked);
        }
    }
}