AIDT 온디바이스 STEM 방사광 X선 초전도 양자 큐비트(Transmon Qubit) 3차원 공진기 미세 마이크로포닉스 및 주파수 지터 서보 제어기

using System;
using System.Runtime.CompilerServices;

namespace ZeliDesk.Stem.Synchrotron.SuperconductingQubit
{
    /// <summary>
    /// 3D 초전도 공진기 마이크로파 I/Q 수신 계측 상태
    /// </summary>
    public readonly ref struct QubitResonatorTelemetryState
    {
        public readonly double InPhaseVoltI;          // 수신 마이크로파 동상 성분 I [V]
        public readonly double QuadratureVoltQ;       // 수신 마이크로파 직교 성분 Q [V]
        public readonly double NominalResonatorGhz;   // 공진기 기준 주파수 [GHz]
        public readonly double LoadedQualityFactor;   // 부하 Q-인자 QL
        public readonly double MixingChamberTempMilliK;// 믹싱 챔버 온도 [mK]

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public QubitResonatorTelemetryState(double i, double q, double freqGhz, double ql, double tempMk)
        {
            InPhaseVoltI = i;
            InPhaseVoltQ = q;
            NominalResonatorGhz = freqGhz;
            LoadedQualityFactor = ql;
            MixingChamberTempMilliK = tempMk;
        }
    }

    /// <summary>
    /// 공진기 마이크로포닉스 보정 출력
    /// </summary>
    public readonly ref struct QubitResonatorControlOutput
    {
        public readonly double FrequencyDetuningKhz;  // 마이크로포닉스 주파수 편위 [kHz]
        public readonly double PiezoCommandVolt;       // 고속 피에조 튜너 구동 전압 [V]
        public readonly double DigitalLoShiftKhz;      // 디지털 LO 주파수 보정치 [kHz]
        public readonly bool IsQubitReadoutReady;      // 주파수 지터 < 0.5kHz 판독 준비 플래그

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public QubitResonatorControlOutput(double detuning, double pztVolt, double loShift, bool ready)
        {
            FrequencyDetuningKhz = detuning;
            PiezoCommandVolt = pztVolt;
            DigitalLoShiftKhz = loShift;
            IsQubitReadoutReady = ready;
        }
    }

    /// <summary>
    /// 10,000Hz 초전도 큐비트 캐비티 마이크로포닉스 주파수 서보 엔진
    /// </summary>
    public ref struct TransmonResonatorFrequencyServoEngine
    {
        private readonly double _kp;
        private readonly double _ki;
        private readonly double _kd;
        private readonly double _piezoVoltPerKhz;
        private readonly double _maxPiezoVolt;

        private double _intDetuning;
        private double _prevDetuning;

        public TransmonResonatorFrequencyServoEngine(
            double kp,
            double ki,
            double kd,
            double piezoVoltPerKhz,
            double maxPiezoVolt)
        {
            _kp = kp;
            _ki = ki;
            _kd = kd;
            _piezoVoltPerKhz = piezoVoltPerKhz;
            _maxPiezoVolt = maxPiezoVolt;
            _intDetuning = 0.0;
            _prevDetuning = 0.0;
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public QubitResonatorControlOutput ProcessCycle(
            in QubitResonatorTelemetryState state,
            double dtSeconds)
        {
            // 1. I/Q 신호로부터 공진기 반사 위상각 theta 산출
            double phaseRad = Math.Atan2(state.QuadratureVoltQ, state.InPhaseVoltI);

            // 2. 부하 Q-인자 기반 순간 주파수 편위 Delta f [kHz] 계산
            // phase = -2 * QL * (Delta_f / f0)
            double f0Khz = state.NominalResonatorGhz * 1e6;
            double detuningKhz = -(phaseRad * f0Khz) / (2.0 * state.LoadedQualityFactor);

            // 3. PID 서보 연산 (피에조 기계 튜닝)
            _intDetuning += detuningKhz * dtSeconds;
            double dDetuning = (detuningKhz - _prevDetuning) / dtSeconds;
            _prevDetuning = detuningKhz;

            double compKhz = _kp * detuningKhz + _ki * _intDetuning + _kd * dDetuning;
            double pztVolt = Math.Clamp(compKhz * _piezoVoltPerKhz, -_maxPiezoVolt, _maxPiezoVolt);

            // 4. 고속 잔류 주파수 지터의 디지털 LO 주파수 피드포워드 상쇄
            double loShiftKhz = detuningKhz;

            // 5. 판독 준비 상태 (주파수 지터 0.5kHz 이내)
            bool isReady = Math.Abs(detuningKhz) <= 0.5;

            return new QubitResonatorControlOutput(
                detuningKhz,
                pztVolt,
                loShiftKhz,
                isReady);
        }
    }
}