AIDT 온디바이스 STEM 방사광 X선 자속 양자 큐비트(Flux Qubit) 마이크로그라디오미터 나노-SQUID 자속 잠금 서보 제어기

using System;
using System.Runtime.CompilerServices;

namespace ZeliDesk.Stem.Synchrotron.FluxQubit
{
    /// <summary>
    /// 나노-SQUID 프리앰프 전압 및 극저온 챔버 상태
    /// </summary>
    public readonly ref struct SquidGradiometerTelemetryState
    {
        public readonly double PreampVoltageMilliVolts; // SQUID 증폭 출력 전압 [mV]
        public readonly double SetpointVoltageMilliVolts;// 동작점 기준 전압 [mV]
        public readonly double FluxToVoltSensitivityMvPerPhi0; // V_Phi 감도 [mV/Phi0]
        public readonly double CryoTempMilliK;          // 시료 온도 [mK]

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public SquidGradiometerTelemetryState(double vPreamp, double vSet, double sens, double temp)
        {
            PreampVoltageMilliVolts = vPreamp;
            SetpointVoltageMilliVolts = vSet;
            FluxToVoltSensitivityMvPerPhi0 = sens;
            CryoTempMilliK = temp;
        }
    }

    /// <summary>
    /// 자속 잠금 루프(FLL) 보상 전류 및 제어 상태
    /// </summary>
    public readonly ref struct FluxLockControlOutput
    {
        public readonly double FeedbackCurrentMicroAmps;// 보상 코일 구동 전류 [uA]
        public readonly double ResidualFluxMicroPhi0;   // 잔류 자속 오차 [uPhi0]
        public readonly bool IsFluxLocked;             // 자속 잠금(<2.0 uPhi0) 유지 여부

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public FluxLockControlOutput(double currentUa, double resFlux, bool locked)
        {
            FeedbackCurrentMicroAmps = currentUa;
            ResidualFluxMicroPhi0 = resFlux;
            IsFluxLocked = locked;
        }
    }

    /// <summary>
    /// 10,000Hz 자속 큐비트 나노-SQUID 고속 자속 잠금 서보 엔진
    /// </summary>
    public ref struct FluxLockedLoopServoEngine
    {
        private readonly double _mutualInductancePhi0PerMicroAmp; // 코일-SQUID 상호 인덕턴스 [Phi0/uA]
        private readonly double _kp;
        private readonly double _ki;
        private readonly double _kd;
        private readonly double _maxCurrentLimitUa;

        private double _accumulatedCurrentUa;
        private double _prevFluxErrorPhi0;

        public FluxLockedLoopServoEngine(
            double mutualInductancePhi0PerMicroAmp,
            double kp,
            double ki,
            double kd,
            double maxCurrentLimitUa)
        {
            _mutualInductancePhi0PerMicroAmp = mutualInductancePhi0PerMicroAmp;
            _kp = kp;
            _ki = ki;
            _kd = kd;
            _maxCurrentLimitUa = maxCurrentLimitUa;
            _accumulatedCurrentUa = 0.0;
            _prevFluxErrorPhi0 = 0.0;
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public FluxLockControlOutput ProcessCycle(
            in SquidGradiometerTelemetryState state,
            double dtSeconds)
        {
            // 1. 전압 오차로부터 입력 자속 편위 Delta Phi [Phi0] 역산
            double voltError = state.PreampVoltageMilliVolts - state.SetpointVoltageMilliVolts;
            double fluxErrorPhi0 = voltError / Math.Max(1e-3, state.FluxToVoltSensitivityMvPerPhi0);

            // 2. PID 연산 (보상 전류 변화율 계산)
            double dFluxErr = (fluxErrorPhi0 - _prevFluxErrorPhi0) / dtSeconds;
            _prevFluxErrorPhi0 = fluxErrorPhi0;

            double deltaCurrentUa = _kp * fluxErrorPhi0 + _ki * fluxErrorPhi0 * dtSeconds + _kd * dFluxErr;
            _accumulatedCurrentUa += deltaCurrentUa;
            _accumulatedCurrentUa = Math.Clamp(_accumulatedCurrentUa, -_maxCurrentLimitUa, _maxCurrentLimitUa);

            // 3. 피드백 인가 후 잔류 자속 오차 [uPhi0] 추정
            double compensatedFlux = _accumulatedCurrentUa * _mutualInductancePhi0PerMicroAmp;
            double residualPhi0 = fluxErrorPhi0 - compensatedFlux;
            double residualMicroPhi0 = Math.Abs(residualPhi0 * 1e6);

            // 4. 자속 잠금 안정성 판정 (2.0 uPhi0 이하)
            bool isLocked = residualMicroPhi0 <= 2.0;

            return new FluxLockControlOutput(
                _accumulatedCurrentUa,
                residualMicroPhi0,
                isLocked);
        }
    }
}