AIDT 온디바이스 STEM 방사광 X선 연속 나노결정학(SSX) 마이크로젯 시료 주입기 및 펨토초 레이저 펄스 동기화 서보 제어기

using System;
using System.Runtime.CompilerServices;

namespace ZeliDesk.Stem.Synchrotron.SerialCrystallography
{
    /// <summary>
    /// 미세유체 액적 주입기 실시간 광학 산란 계측 상태
    /// </summary>
    public readonly ref struct LiquidJetTelemetryState
    {
        public readonly double DropletVelocityMps;    // 액적 유속 [m/s]
        public readonly double TimeJitterMicroseconds;// X선 펄스 대비 도착 시간 지터 [us]
        public readonly double HeliumPressureKpa;     // 헬륨 가스 노즐 배압 [kPa]
        public readonly double ScatterIntensityVolts; // 결정 통과 광산란 신호 강도 [V]

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public LiquidJetTelemetryState(double vel, double jitter, double press, double scatter)
        {
            DropletVelocityMps = vel;
            TimeJitterMicroseconds = jitter;
            HeliumPressureKpa = press;
            ScatterIntensityVolts = scatter;
        }
    }

    /// <summary>
    /// 액적 주입기 압전 진동자 및 가스 밸브 제어 지령
    /// </summary>
    public readonly ref struct LiquidJetControlOutput
    {
        public readonly double PiezoDriveFreqKhz;     // 압전 노즐 구동 주파수 [kHz]
        public readonly double GasValveFlowCommand;   // 헬륨 압력 비례 밸브 개도율 [0.0 ~ 1.0]
        public readonly double EstimatedHitRatePct;   // 예측 X선 회절 명중률 [%]
        public readonly bool IsSynchronized;          // 펄스 동기화(<0.5us 지터) 달성 플래그

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public LiquidJetControlOutput(double freqKhz, double valve, double hitRate, bool sync)
        {
            PiezoDriveFreqKhz = freqKhz;
            GasValveFlowCommand = valve;
            EstimatedHitRatePct = hitRate;
            IsSynchronized = sync;
        }
    }

    /// <summary>
    /// 10,000Hz 연속 나노결정학(SSX) 마이크로젯 시료 동기화 서보 엔진
    /// </summary>
    public ref struct MicrojetSynchronizationServoEngine
    {
        private readonly double _nominalFreqKhz;
        private readonly double _nominalVelocityMps;
        private readonly double _kpJitter;
        private readonly double _kiJitter;
        private readonly double _kdJitter;
        private readonly double _kpVel;
        private readonly double _kiVel;

        private double _intJitter;
        private double _prevJitter;
        private double _intVel;

        public MicrojetSynchronizationServoEngine(
            double nominalFreqKhz,
            double nominalVelocityMps,
            double kpJitter,
            double kiJitter,
            double kdJitter,
            double kpVel,
            double kiVel)
        {
            _nominalFreqKhz = nominalFreqKhz;
            _nominalVelocityMps = nominalVelocityMps;
            _kpJitter = kpJitter;
            _kiJitter = kiJitter;
            _kdJitter = kdJitter;
            _kpVel = kpVel;
            _kiVel = kiVel;
            _intJitter = 0.0;
            _prevJitter = 0.0;
            _intVel = 0.0;
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public LiquidJetControlOutput UpdateCycle(
            in LiquidJetTelemetryState state,
            double dtSeconds)
        {
            // 1. 시간 지터(Timing Jitter) PID 보정 (주파수 미세 조절)
            _intJitter += state.TimeJitterMicroseconds * dtSeconds;
            double derJitter = (state.TimeJitterMicroseconds - _prevJitter) / dtSeconds;
            _prevJitter = state.TimeJitterMicroseconds;

            double deltaFreq = _kpJitter * state.TimeJitterMicroseconds + _kiJitter * _intJitter + _kdJitter * derJitter;
            double targetFreqKhz = Math.Clamp(_nominalFreqKhz + deltaFreq, _nominalFreqKhz - 50.0, _nominalFreqKhz + 50.0);

            // 2. 유속 오차 PI 보정 (가스 밸브 압력 조절)
            double velError = _nominalVelocityMps - state.DropletVelocityMps;
            _intVel += velError * dtSeconds;
            double valveCmd = 0.5 + (_kpVel * velError + _kiVel * _intVel);
            valveCmd = Math.Clamp(valveCmd, 0.05, 0.95);

            // 3. 지터 0.5us 이내 및 산란 신호 기반 명중률 추정
            double absJitter = Math.Abs(state.TimeJitterMicroseconds);
            bool isSync = absJitter <= 0.5;

            double hitRate = isSync ? Math.Clamp(85.0 - absJitter * 40.0, 10.0, 98.0) : 5.0;

            return new LiquidJetControlOutput(targetFreqKhz, valveCmd, hitRate, isSync);
        }
    }
}