켈빈 프로브 힘 현미경(KPFM) 국소 접촉 전위차 & 1,000Hz 0-Alloc C# 나노 일함수 맵핑 서보 엔진

using System;
using System.Runtime.CompilerServices;

namespace ZeliDesk.Stem.SurfacePhysics
{
    /// <summary>
    /// KPFM 일함수 텔레메트리 구조체 (16-byte 스택 전용)
    /// </summary>
    public readonly ref struct KpfmState
    {
        public readonly float ContactPotentialVolt; // 복조된 접촉 전위차 V_cpd (V)
        public readonly float SampleWorkFunctionEv;  // 연산된 시료 국소 일함수 Φ_sample (eV)
        public readonly float ResidualForceErrorPv;  // 잔류 F_ω 오차 전압 (pV)
        public readonly float CommandedDacVolt;      // 1ms 널링 지령 전압 V_dc (V)

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public KpfmState(float vCpd, float phi, float error, float dac)
        {
            ContactPotentialVolt = vCpd;
            SampleWorkFunctionEv = phi;
            ResidualForceErrorPv = error;
            CommandedDacVolt = dac;
        }
    }

    /// <summary>
    /// 1,000Hz Zero-Allocation KPFM 일함수 널링 서보 엔진
    /// </summary>
    public ref struct KpfmNullingServoEngine
    {
        private readonly float _calibratedTipWorkFunctionEv; // 팁 기준 일함수 (e.g. 5.1 eV for Au)
        private readonly float _kpGain;                      // 비례 제어 게인
        private readonly float _kiGain;                      // 적분 제어 게인
        private float _integralError;                        // 적분 누적 오차
        private float _lastVdc;                              // 직전 출력 전압

        private const float MaxDacLimitV = 10.0f;            // DAC 최대 출력 전압 범위 (±10V)

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public KpfmNullingServoEngine(float tipWorkFunctionEv, float kp, float ki)
        {
            _calibratedTipWorkFunctionEv = tipWorkFunctionEv;
            _kpGain = kp;
            _kiGain = ki;
            _integralError = 0.0f;
            _lastVdc = 0.0f;
        }

        /// <summary>
        /// 1ms 주기(1,000Hz) 디지털 록인 앰프 F_omega 복조치 기반 V_dc 널링 및 일함수 산출 (0-Alloc)
        /// </summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public KpfmState Update1Khz(float lockInFOmegaVolt, float dtSeconds)
        {
            // 1) F_omega 신호는 (V_dc - V_cpd)에 비례하므로 에러로 정의
            float forceError = lockInFOmegaVolt;
            _integralError += forceError * dtSeconds;
            _integralError = Math.Clamp(_integralError, -2.0f, 2.0f); // 안티 와인드업

            // 2) PI 제어기를 통해 F_omega를 0으로 소거하는 V_dc 갱신
            float deltaVdc = (_kpGain * forceError) + (_kiGain * _integralError);
            _lastVdc -= deltaVdc;
            _lastVdc = Math.Clamp(_lastVdc, -MaxDacLimitV, MaxDacLimitV);

            // 3) 널링 상태에서 V_cpd = V_dc 이므로 시료 국소 일함수 계산
            // Phi_sample = Phi_tip - e * V_cpd (전자기학 규약)
            float estimatedVcpd = _lastVdc;
            float sampleWorkFunction = _calibratedTipWorkFunctionEv - estimatedVcpd;

            return new KpfmState(estimatedVcpd, sampleWorkFunction, forceError * 1e6f, _lastVdc);
        }
    }
}