원자간력 현미경(AFM) 튜닝포크(qPlus) 서브-옹스트롬 주파수 변조 & 1,000Hz 0-Alloc C# 비접촉 원자력 위상 잠금 서보 엔진

using System;
using System.Runtime.CompilerServices;

namespace ZeliDesk.Stem.Nanotechnology.NcAfm
{
    /// <summary>
    /// qPlus 튜닝포크 센서 계측 및 피에조 상태 구조체 (0-Alloc Stack Only)
    /// </summary>
    public readonly ref struct QplusTelemetry
    {
        public readonly float FrequencyShiftHz;    // [Hz] PLL 복조 주파수 편이 (Delta_f)
        public readonly float OscillationAmplitudePm; // [pm] 튜닝포크 진폭 (예: 50pm)
        public readonly float PhaseErrorDeg;       // [deg] 90도 공진 위상 오차
        public readonly float CurrentZPositionPm;  // [pm] 현재 Z-압전 스캐너 위치
        public readonly float ResonatorQualityQ;   // [무차원] 센서 Q 팩터 (예: 25,000)
        public readonly float NominalFrequencyHz;  // [Hz] 고유 진동수 f0 (예: 30,000)
        public readonly float SpringConstantNm;    // [N/m] qPlus 강성 (예: 1,800)

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public QplusTelemetry(
            float frequencyShiftHz,
            float oscillationAmplitudePm,
            float phaseErrorDeg,
            float currentZPositionPm,
            float resonatorQualityQ,
            float nominalFrequencyHz,
            float springConstantNm)
        {
            FrequencyShiftHz = frequencyShiftHz;
            OscillationAmplitudePm = oscillationAmplitudePm;
            PhaseErrorDeg = phaseErrorDeg;
            CurrentZPositionPm = currentZPositionPm;
            ResonatorQualityQ = resonatorQualityQ;
            NominalFrequencyHz = nominalFrequencyHz;
            SpringConstantNm = springConstantNm;
        }
    }

    /// <summary>
    /// NC-AFM Z-축 및 위상 잠금 서보 제어 연산 결과
    /// </summary>
    public readonly ref struct QplusControlResult
    {
        public readonly float ForceGradientNm;        // [N/m] 국소 원자력 구배 (dF/dz)
        public readonly float CommandedZDeltaPm;     // [pm] 1ms 주기 Z-축 위치 보정량
        public readonly float NewCommandedZPm;       // [pm] 차기 Z-스캐너 절대 위치
        public readonly float EnergyDissipationMev;  // [meV/cycle] 분자간 에너지 소산
        public readonly bool IsTipCrashRisk;         // 원자 탐침 충돌 위험 플래그
        public readonly bool IsFrequencyLocked;      // PLL 위상 잠금 정상 유지 여부

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public QplusControlResult(
            float forceGradientNm,
            float commandedZDeltaPm,
            float newCommandedZPm,
            float energyDissipationMev,
            bool isTipCrashRisk,
            bool isFrequencyLocked)
        {
            ForceGradientNm = forceGradientNm;
            CommandedZDeltaPm = commandedZDeltaPm;
            NewCommandedZPm = newCommandedZPm;
            EnergyDissipationMev = energyDissipationMev;
            IsTipCrashRisk = isTipCrashRisk;
            IsFrequencyLocked = isFrequencyLocked;
        }
    }

    /// <summary>
    /// 1,000Hz 0-Alloc NC-AFM qPlus 서브-옹스트롬 위상 잠금 서보 엔진
    /// </summary>
    public static class NcAfmServoEngine
    {
        private const float ProportionalGain = 1.25f; // [pm/Hz] 비례 게인
        private const float IntegralGain = 0.05f;     // 적분 게인
        private const float MaxAllowedShiftHz = 50.0f; // 최대 허용 주파수 편이 (충돌 한계)
        private const float RetractStepPm = 250.0f;    // 비상 후퇴 이동량

        /// <summary>
        /// 1ms 제어 주기 동안 주파수 편이 설정점 추적 및 Z-압전 나노스캐너 위치 제어
        /// </summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static QplusControlResult ComputeServoCycle(
            in QplusTelemetry telemetry, 
            float targetFrequencyShiftHz, 
            ref float integratedError)
        {
            // 1. Giessibl 공식 역산을 통한 원자간력 구배 dF/dz 산출 [N/m]
            // df = - (f0 / (2 * k)) * (dF/dz) -> dF/dz = -2 * k * df / f0
            float forceGradient = (-2.0f * telemetry.SpringConstantNm * telemetry.FrequencyShiftHz) / telemetry.NominalFrequencyHz;

            // 2. 팁 충돌 위험 검출 (주파수 편이가 한계치를 초과하여 급격한 단거리 파울리 척력 영역 진입 시)
            bool crashRisk = MathF.Abs(telemetry.FrequencyShiftHz) > MaxAllowedShiftHz;

            // 3. PLL 주파수 잠금 건전성 검증 (위상 오차 5도 이내)
            bool isLocked = MathF.Abs(telemetry.PhaseErrorDeg) < 5.0f;

            // 4. 주파수 편이 추적 PI 제어 루프
            float error = targetFrequencyShiftHz - telemetry.FrequencyShiftHz;
            integratedError += error * 0.001f; // 1ms dt

            // 안티-와인드업 적분 클램핑
            if (integratedError > 100.0f) integratedError = 100.0f;
            else if (integratedError < -100.0f) integratedError = -100.0f;

            float deltaZPm = 0.0f;
            if (crashRisk)
            {
                // 즉시 비상 후퇴 (표면에서 멀어지는 방향으로 강제 이동)
                deltaZPm = RetractStepPm;
            }
            else
            {
                // 인력 영역(음의 편이): 표면으로 접근(-) / 척력 영역(양의 편이): 표면에서 후퇴(+)
                deltaZPm = (error * ProportionalGain) + (integratedError * IntegralGain);
            }

            // 1ms 당 최대 이동 속도 제한 (스캐너 보호: 50pm/ms)
            deltaZPm = Math.Clamp(deltaZPm, -50.0f, 50.0f);
            float newZPositionPm = telemetry.CurrentZPositionPm + deltaZPm;

            // 5. 사이클당 분자간 감쇠 에너지 소산 계산 (단위: meV)
            // E_diss = pi * (k * A^2 / Q) * (delta_gain)
            float ampMeters = telemetry.OscillationAmplitudePm * 1e-12f;
            float eDissJoules = MathF.PI * (telemetry.SpringConstantNm * ampMeters * ampMeters / telemetry.ResonatorQualityQ);
            float eDissMev = (eDissJoules / 1.602176634e-19f) * 1000.0f;

            return new QplusControlResult(
                forceGradientNm: forceGradient,
                commandedZDeltaPm: deltaZPm,
                newCommandedZPm: newZPositionPm,
                energyDissipationMev: eDissMev,
                isTipCrashRisk: crashRisk,
                isFrequencyLocked: isLocked
            );
        }
    }
}