단일 광자 눈사태 광다이오드(SPAD) 가이거 모드 & 1,000Hz 0-Alloc C# 능동 퀜칭 3D 라이다 서보 엔진

using System;
using System.Runtime.CompilerServices;

namespace ZeliDesk.Stem.Optoelectronics
{
    /// <summary>
    /// SPAD 가이거 모드 라이다 텔레메트리 구조체 (16-byte 스택 전용)
    /// </summary>
    public readonly ref struct SpadLidarState
    {
        public readonly float ExcessBiasVolts;     // 설정 과잉 바이어스 전압 V_ex (V)
        public readonly float PhotonDetectionEff;  // 추정 광자 검출 효율 PDE (0.0~1.0)
        public readonly float DarkCountRateKHz;    // 암계수율 DCR (kHz)
        public readonly float HoldOffTimeNs;       // 능동 퀜칭 홀드오프 시간 (ns)

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public SpadLidarState(float vEx, float pde, float dcr, float holdOff)
        {
            ExcessBiasVolts = vEx;
            PhotonDetectionEff = pde;
            DarkCountRateKHz = dcr;
            HoldOffTimeNs = holdOff;
        }
    }

    /// <summary>
    /// 1,000Hz Zero-Allocation SPAD 능동 퀜칭 및 바이어스 적응 서보 엔진
    /// </summary>
    public ref struct SpadQuenchingServoEngine
    {
        private readonly float _breakdownVoltageV;   // 다이오드 항복 전압 (e.g. 58.5V)
        private readonly float _trapLifetimeNs;      // 반도체 트랩 전하 방출 수명 (e.g. 80ns)
        private float _currentExcessBiasV;           // 현재 과잉 바이어스
        private float _currentHoldOffNs;             // 현재 퀜칭 홀드오프 시간

        private const float MaxAllowedDcrKHz = 2.0f; // 최대 허용 암계수율
        private const float MaxExcessBiasV = 5.0f;   // 최대 안전 과잉 전압

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public SpadQuenchingServoEngine(float breakdownV, float trapLifetimeNs)
        {
            _breakdownVoltageV = breakdownV;
            _trapLifetimeNs = trapLifetimeNs;
            _currentExcessBiasV = 3.0f;
            _currentHoldOffNs = 100.0f;
        }

        /// <summary>
        /// 1ms 주기(1,000Hz) 1ms 계수 히스토그램 통계로부터 DCR 평가 및 바이어스/홀드오프 최적화 (0-Alloc)
        /// </summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public SpadLidarState Update1Khz(int photonCountIn1Ms, int noiseDarkCountsIn1Ms)
        {
            // 1) 1ms 간 발생한 암계수로부터 실시간 DCR (kHz) 산출
            float currentDcrKHz = noiseDarkCountsIn1Ms * 1.0f;

            // 2) 검출 효율 PDE 근사치 계산: PDE = 0.35 * (1 - exp(-0.6 * V_ex))
            float estimatedPde = 0.35f * (1.0f - MathF.Exp(-0.6f * _currentExcessBiasV));

            // 3) DCR이 허용치를 초과하면 과잉 바이어스 미세 하향 및 홀드오프 증가
            if (currentDcrKHz > MaxAllowedDcrKHz)
            {
                _currentExcessBiasV = MathF.Max(1.0f, _currentExcessBiasV - 0.05f);
                _currentHoldOffNs = MathF.Min(250.0f, _currentHoldOffNs + 5.0f);
            }
            else
            {
                // 노이즈가 안정적이면 감도 극대화를 위해 V_ex 미세 상향
                _currentExcessBiasV = MathF.Min(MaxExcessBiasV, _currentExcessBiasV + 0.02f);
                // 트랩 완화에 맞춰 홀드오프 단축 (최대 계수율 확보)
                _currentHoldOffNs = MathF.Max(_trapLifetimeNs * 1.2f, _currentHoldOffNs - 2.0f);
            }

            return new SpadLidarState(_currentExcessBiasV, estimatedPde, currentDcrKHz, _currentHoldOffNs);
        }
    }
}