초전도 마이크로파 키네틱 인덕턴스 검출기(MKID) & 1,000Hz 0-Alloc C# 테라헤르츠 광자 계수 서보 엔진

using System;
using System.Runtime.CompilerServices;

namespace ZeliDesk.Stem.Superconductivity
{
    /// <summary>
    /// MKID 단일 광자 검출 텔레메트리 구조체 (16-byte 스택 전용)
    /// </summary>
    public readonly ref struct MkidPhotonState
    {
        public readonly float PhaseShiftRad;      // 마이크로파 공진 위상 편이 Δθ (rad)
        public readonly float EstimatedEnergyEv;  // 추정 단일 광자 에너지 (eV)
        public readonly float ResonatorFreqShiftKhz; // 공진 주파수 이동량 (kHz)
        public readonly bool PhotonTriggered;     // 광자 도달 이벤트 판정

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public MkidPhotonState(float phase, float energy, float freqShift, bool triggered)
        {
            PhaseShiftRad = phase;
            EstimatedEnergyEv = energy;
            ResonatorFreqShiftKhz = freqShift;
            PhotonTriggered = triggered;
        }
    }

    /// <summary>
    /// 1,000Hz Zero-Allocation 초전도 MKID 신호 복조 및 에너지 분해 서보 엔진
    /// </summary>
    public ref struct MkidDemodulationServoEngine
    {
        private readonly float _centerI;             // 공진기 루프 중심 I 좌표
        private readonly float _centerQ;             // 공진기 루프 중심 Q 좌표
        private readonly float _phaseToEvRatio;      // 위상 편이 대비 에너지 변환 계수 (eV/rad)
        private readonly float _qualityFactorQ;      // 공진기 부하 품질계수
        private float _baselinePhaseRad;             // 무광자 상태 기준 위상

        private const float TriggerThresholdRad = 0.15f; // 광자 감지 임계 위상

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public MkidDemodulationServoEngine(float centerI, float centerQ, float phaseToEv, float qFactor)
        {
            _centerI = centerI;
            _centerQ = centerQ;
            _phaseToEvRatio = phaseToEv;
            _qualityFactorQ = qFactor;
            _baselinePhaseRad = 0.0f;
        }

        /// <summary>
        /// 1ms 주기(1,000Hz) 마이크로파 ADC I/Q 신호로부터 위상 편이 산출 및 광자 에너지 결정 (0-Alloc)
        /// </summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public MkidPhotonState Update1Khz(float sampledI, float sampledQ)
        {
            // 1) 공진 루프 중심점 기준 극좌표 위상 각도 계산
            float di = sampledI - _centerI;
            float dq = sampledQ - _centerQ;
            float currentPhase = MathF.Atan2(dq, di);

            // 2) 기준 위상 대비 순수 광자 유도 위상 편이 DeltaTheta 산출
            float phaseShift = currentPhase - _baselinePhaseRad;

            // 3) 주파수 편이 Delta_f = -(DeltaTheta / 4Q) * f_0 역산 (kHz 단위)
            float freqShiftKhz = -(phaseShift / (4.0f * _qualityFactorQ)) * 5.0e6f;

            // 4) 광자 흡수 이벤트 판정 및 에너지 계산
            bool isPhoton = MathF.Abs(phaseShift) > TriggerThresholdRad;
            float photonEnergyEv = isPhoton ? MathF.Abs(phaseShift) * _phaseToEvRatio : 0.0f;

            // 무광자 상태일 때 기준 위상 서서히 드리프트 추적 (저주파 열적 변동 보상)
            if (!isPhoton)
            {
                _baselinePhaseRad += (currentPhase - _baselinePhaseRad) * 0.05f;
            }

            return new MkidPhotonState(phaseShift, photonEnergyEv, freqShiftKhz, isPhoton);
        }
    }
}