AIDT 온디바이스 STEM 방사광 X선 옵토메카닉스(Cavity Optomechanics) 방사압 및 나노기계 공진 주파수 레이저 냉각 서보 제어기

using System;
using System.Runtime.CompilerServices;

namespace ZeliDesk.Stem.Synchrotron.Optomechanics
{
    /// <summary>
    /// 호모다인 간섭계 I/Q 위상 및 기계적 진동 계측 상태
    /// </summary>
    public readonly ref struct OptomechanicalTelemetryState
    {
        public readonly double HomodyneInPhaseVolt;     // 동상 성분 I [V]
        public readonly double HomodyneQuadratureVolt;  // 직교 성분 Q [V]
        public readonly double MechanicalFrequencyMhz;  // 나노멤브레인 진동 주파수 [MHz]
        public readonly double CavityLinewidthKhz;      // 공진기 선폭 kappa [kHz]

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public OptomechanicalTelemetryState(double iVolt, double qVolt, double fMhz, double kappaKhz)
        {
            HomodyneInPhaseVolt = iVolt;
            HomodyneQuadratureVolt = qVolt;
            MechanicalFrequencyMhz = fMhz;
            CavityLinewidthKhz = kappaKhz;
        }
    }

    /// <summary>
    /// 광역학 냉각 서보 제어 출력
    /// </summary>
    public readonly ref struct OptomechanicsCoolingOutput
    {
        public readonly double DetuningErrorKhz;     // 적색 측파대 목표 디튜닝 오차 [kHz]
        public readonly double PiezoCavityVolt;      // 공진기 길이 조정 피에조 전압 [V]
        public readonly double EstimatedPhononNumber;// 추정 나노멤브레인 평균 포논 수
        public readonly bool IsInQuantumGroundState; // 양자 바닥상태(n < 1) 도달 여부

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public OptomechanicsCoolingOutput(double errKhz, double volt, double phonon, bool groundState)
        {
            DetuningErrorKhz = errKhz;
            PiezoCavityVolt = volt;
            EstimatedPhononNumber = phonon;
            IsInQuantumGroundState = groundState;
        }
    }

    /// <summary>
    /// 10,000Hz 광역학 방사압 레이저 냉각 서보 제어 엔진
    /// </summary>
    public ref struct CavityOptomechanicsCoolingServoEngine
    {
        private readonly double _targetDetuningRatio; // 목표 디튜닝 비 (보통 -1.0, 즉 Delta = -omega_m)
        private readonly double _kp;
        private readonly double _ki;
        private readonly double _kd;
        private readonly double _piezoVoltPerKhz;
        private readonly double _maxPiezoVolt;

        private double _integral;
        private double _prevErrorKhz;

        public CavityOptomechanicsCoolingServoEngine(
            double targetDetuningRatio,
            double kp,
            double ki,
            double kd,
            double piezoVoltPerKhz,
            double maxPiezoVolt)
        {
            _targetDetuningRatio = targetDetuningRatio;
            _kp = kp;
            _ki = ki;
            _kd = kd;
            _piezoVoltPerKhz = piezoVoltPerKhz;
            _maxPiezoVolt = maxPiezoVolt;
            _integral = 0.0;
            _prevErrorKhz = 0.0;
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public OptomechanicsCoolingOutput Update(
            in OptomechanicalTelemetryState state,
            double dtSeconds)
        {
            // 1. 호모다인 I/Q 신호로부터 현재 레이저-공진기 디튜닝 추정
            double phase = Math.Atan2(state.HomodyneQuadratureVolt, state.HomodyneInPhaseVolt);
            // 선형 영역 디튜닝 환산 [kHz]: Delta = (kappa / 2) * tan(phase)
            double currentDetuningKhz = (state.CavityLinewidthKhz / 2.0) * Math.Tan(phase);

            // 2. 적색 측파대 목표 디튜닝: Delta_target = -omega_m
            double targetDetuningKhz = _targetDetuningRatio * (state.MechanicalFrequencyMhz * 1000.0);
            double errorKhz = currentDetuningKhz - targetDetuningKhz;

            // 3. PID 서보 연산
            _integral += errorKhz * dtSeconds;
            double derivative = (errorKhz - _prevErrorKhz) / dtSeconds;
            _prevErrorKhz = errorKhz;

            double correctionKhz = _kp * errorKhz + _ki * _integral + _kd * derivative;

            // 4. 피에조 전압 출력 및 리미터
            double cmdVolt = Math.Clamp(correctionKhz * _piezoVoltPerKhz, -_maxPiezoVolt, _maxPiezoVolt);

            // 5. 냉각 상태 및 포논 점유수 추정
            // 오차가 50kHz 이내일 때 냉각 효율 극대화
            double absErr = Math.Abs(errorKhz);
            double phonon = Math.Max(0.2, 0.4 + (absErr / 100.0));
            bool isGroundState = phonon < 1.0;

            return new OptomechanicsCoolingOutput(errorKhz, cmdVolt, phonon, isGroundState);
        }
    }
}