AIDT 온디바이스 STEM 방사광 X선 주사터널링현미경(STM-ESR) 단일 스핀 전자스핀공명 RF 피에조 팁 간극 서보 제어기

using System;
using System.Runtime.CompilerServices;

namespace ZeliDesk.Stem.Synchrotron.EsrStm
{
    /// <summary>
    /// 단일 원자 ESR-STM 터널링 전류 및 RF 바이어스 계측 상태
    /// </summary>
    public readonly ref struct EsrStmTelemetryState
    {
        public readonly double TunnelingCurrentPicoAmps; // 터널링 전류 It [pA]
        public readonly double SetpointCurrentPicoAmps;  // 목표 터널링 전류 설정치 [pA]
        public readonly double RfDriveFrequencyGhz;      // 인가된 RF 스핀 공명 주파수 [GHz]
        public readonly double StageTempKelvin;          // 극저온 스테이지 온도 [K]

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public EsrStmTelemetryState(double currentPa, double setpointPa, double rfGhz, double tempK)
        {
            TunnelingCurrentPicoAmps = currentPa;
            SetpointCurrentPicoAmps = setpointPa;
            RfDriveFrequencyGhz = rfGhz;
            StageTempKelvin = tempK;
        }
    }

    /// <summary>
    /// Z-피에조 팁 간극 제어 출력
    /// </summary>
    public readonly ref struct EsrStmControlOutput
    {
        public readonly double PiezoZCommandVolts;     // Z-피에조 구동 전압 [V]
        public readonly double EstimatedGapShiftPm;     // 간극 변위 추정치 [pm]
        public readonly double SpinResonanceSignalRatio;// ESR 피크 신호 대 잡음비 (SNR)
        public readonly bool IsSingleSpinLocked;       // 단일 스핀 결맞음 유지(<0.5pm) 플래그

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public EsrStmControlOutput(double pztVolt, double shiftPm, double snr, bool locked)
        {
            PiezoZCommandVolts = pztVolt;
            EstimatedGapShiftPm = shiftPm;
            SpinResonanceSignalRatio = snr;
            IsSingleSpinLocked = locked;
        }
    }

    /// <summary>
    /// 10,000Hz ESR-STM 단일 원자 피에조 팁 간극 서보 엔진
    /// </summary>
    public ref struct SingleAtomEsrStmServoEngine
    {
        private const double TwoKappaInv = 0.04545; // 1 / (2 * 1.1 A^-1) = 0.04545 nm/decade
        private readonly double _kp;
        private readonly double _ki;
        private readonly double _kd;
        private readonly double _piezoGainVoltsPerNm;
        private readonly double _maxPiezoVolts;

        private double _intLogErr;
        private double _prevLogErr;

        public SingleAtomEsrStmServoEngine(
            double kp,
            double ki,
            double kd,
            double piezoGainVoltsPerNm,
            double maxPiezoVolts)
        {
            _kp = kp;
            _ki = ki;
            _kd = kd;
            _piezoGainVoltsPerNm = piezoGainVoltsPerNm;
            _maxPiezoVolts = maxPiezoVolts;
            _intLogErr = 0.0;
            _prevLogErr = 0.0;
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public EsrStmControlOutput ProcessCycle(
            in EsrStmTelemetryState state,
            double dtSeconds)
        {
            // 1. 전류의 대수 오차 계산 (Log Error)
            double cur = Math.Max(1e-3, state.TunnelingCurrentPicoAmps);
            double set = Math.Max(1e-3, state.SetpointCurrentPicoAmps);
            double logErr = Math.Log(cur / set);

            // 2. PID 연산
            _intLogErr += logErr * dtSeconds;
            double dLogErr = (logErr - _prevLogErr) / dtSeconds;
            _prevLogErr = logErr;

            // 나노미터 단위 변위 보정량 [nm]
            double deltaZNm = TwoKappaInv * (_kp * logErr + _ki * _intLogErr + _kd * dLogErr);

            // 3. 피에조 전압 출력 및 제한
            double cmdVolt = Math.Clamp(deltaZNm * _piezoGainVoltsPerNm, -_maxPiezoVolts, _maxPiezoVolts);

            // 4. 피코미터 단위 간극 변위 추정치 [pm]
            double gapShiftPm = deltaZNm * 1000.0;

            // 5. 스핀 공명 결맞음 상태 판정 (간극 오차 0.5pm 이하)
            bool isLocked = Math.Abs(gapShiftPm) <= 0.5;
            double snr = isLocked ? Math.Clamp(25.0 - Math.Abs(gapShiftPm) * 10.0, 5.0, 30.0) : 1.5;

            return new EsrStmControlOutput(
                cmdVolt,
                gapShiftPm,
                snr,
                isLocked);
        }
    }
}