비접촉 원자간력 현미경(NC-AFM) qPlus 주파수 변조 & 1,000Hz 0-Alloc C# 분자 궤도 피코미터(pm) 서보 제어기

using System;
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;

namespace ZeliDesk.Defense.AtomicPhysics
{
    /// <summary>
    /// qPlus 센서 PLL 주파수 편이 및 진폭 입력 프레임
    /// </summary>
    [StructLayout(LayoutKind.Sequential, Pack = 8)]
    public readonly struct NcAfmSensorFrame
    {
        public readonly double TimestampSeconds;
        public readonly double FrequencyShiftHz;      // 주파수 편이 Delta f (Hz)
        public readonly double OscillationAmplitudePm;// 진동 진폭 A (pm)
        public readonly double CurrentZPositionPm;    // 현재 Z-피에조 위치 (pm)

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public NcAfmSensorFrame(double timestamp, double df, double amp, double z)
        {
            TimestampSeconds = timestamp;
            FrequencyShiftHz = df;
            OscillationAmplitudePm = amp;
            CurrentZPositionPm = z;
        }
    }

    /// <summary>
    /// NC-AFM Z-피에조 서보 제어 출력 프레임
    /// </summary>
    [StructLayout(LayoutKind.Sequential, Pack = 8)]
    public readonly struct NcAfmControlOutput
    {
        public readonly double CommandedZPositionPm;   // 지령 Z 위치 (pm)
        public readonly double EstimatedForcePiconewton;// 추정 원자간 힘 F_ts (pN)
        public readonly double ChemicalBondOrder;      // 추정 화학 결합 차수 (1.0=단일, 2.0=이중 등)
        public readonly bool IsCrashRiskAlarm;         // 팁-시료 충돌 위험 경보

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public NcAfmControlOutput(double targetZ, double force, double bondOrder, bool crashRisk)
        {
            CommandedZPositionPm = targetZ;
            EstimatedForcePiconewton = force;
            ChemicalBondOrder = bondOrder;
            IsCrashRiskAlarm = crashRisk;
        }
    }

    /// <summary>
    /// 1,000Hz 0-Alloc C# NC-AFM qPlus 분자 궤도 이미징 서보 엔진
    /// </summary>
    public ref struct NcAfmFrequencyModulationServoEngine
    {
        private const double QPlusSpringConstant = 1800.0; // k0 (N/m)
        private const double ResonanceFreq = 30000.0;      // f0 (Hz)
        private const double TargetDeltaF = -15.0;         // 목표 주파수 편이 세트포인트 (Hz)

        // PI 제어 게인 (Z축 피에조)
        private const double Kp = 2.5; // pm/Hz
        private const double Ki = 0.4; // pm/(Hz*s)

        private double _integralError;
        private double _lastTimestamp;
        private double _currentZ;
        private bool _isInitialized;

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public void Initialize(double initialZ)
        {
            _integralError = 0.0;
            _lastTimestamp = 0.0;
            _currentZ = initialZ;
            _isInitialized = true;
        }

        /// <summary>
        /// 1,000Hz(1ms 주기) 주파수 편이 에러 기반 피코미터 Z-서보 연산 틱
        /// </summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public NcAfmControlOutput ProcessTick(in NcAfmSensorFrame frame)
        {
            if (!_isInitialized)
            {
                Initialize(frame.CurrentZPositionPm);
            }

            double dt = frame.TimestampSeconds - _lastTimestamp;
            if (dt <= 0.0 || dt > 0.01) dt = 0.001; // 1ms 기본 주기
            _lastTimestamp = frame.TimestampSeconds;

            // 1. 주파수 편이 에러 산출 (세트포인트 추종)
            double error = TargetDeltaF - frame.FrequencyShiftHz;
            _integralError += error * dt;
            _integralError = Math.Clamp(_integralError, -100.0, 100.0);

            // 2. PI 제어 Z축 보정 변위 산출 (피코미터 단위)
            double deltaZ = Kp * error + Ki * _integralError;
            _currentZ += deltaZ;

            // 3. 근사 새더-자비스 역적분을 통한 원자간 수직 힘 F_ts (pN) 추정
            // 작은 진폭 한계: F_ts ~ 2 * k0 * A * (df / f0)
            double ampMeters = frame.OscillationAmplitudePm * 1e-12;
            double forceNewtons = 2.0 * QPlusSpringConstant * ampMeters * (frame.FrequencyShiftHz / ResonanceFreq);
            double forcePiconewtons = forceNewtons * 1e12;

            // 4. 단일 분자 화학 결합 차수(Bond Order) 추정 (파울리 척력 강도에 비례)
            // 파울리 척력이 클수록 결합 전자 밀도가 높음 (예: 삼중결합 > 이중결합 > 단일결합)
            double bondOrder = 1.0;
            if (forcePiconewtons > 15.0)
            {
                bondOrder = 1.0 + (forcePiconewtons - 15.0) / 25.0;
                bondOrder = Math.Clamp(bondOrder, 1.0, 3.2);
            }

            // 5. 팁-시료 충돌 위험 경보 (주파수 편이 +30Hz 초과 급격한 척력 유입 시)
            bool isCrashRisk = frame.FrequencyShiftHz > 30.0;

            return new NcAfmControlOutput(
                targetZ: _currentZ,
                force: forcePiconewtons,
                bondOrder: bondOrder,
                crashRisk: isCrashRisk
            );
        }
    }
}