열모세관 마랑고니 대류(Thermocapillary Marangoni Convection) 나노 액적 조작 & 1,000Hz 0-Alloc C# 랩온어칩 비접촉 열유체 서보 엔진

using System;
using System.Runtime.CompilerServices;

namespace ZeliDesk.Stem.Microfluidics
{
    /// <summary>
    /// 마랑고니 액적 상태 텔레메트리 구조체 (16-byte 스택 전용)
    /// </summary>
    public readonly ref struct MarangoniDropletState
    {
        public readonly float PositionXMicron;   // 액적 X 중심 위치 (um)
        public readonly float VelocityUmPerSec;  // 순간 이동 속도 (um/s)
        public readonly float MarangoniNumber;   // 무차원 마랑고니 수 (Ma)
        public readonly float AppliedTempGradK;  // 인가된 온도 구배 (K/mm)

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public MarangoniDropletState(float posX, float vel, float ma, float grad)
        {
            PositionXMicron = posX;
            VelocityUmPerSec = vel;
            MarangoniNumber = ma;
            AppliedTempGradK = grad;
        }
    }

    /// <summary>
    /// 1,000Hz Zero-Allocation 열모세관 마랑고니 액적 조작 서보 엔진
    /// </summary>
    public ref struct MarangoniDropletServoEngine
    {
        private readonly float _targetXMicron;     // 목표 액적 X 좌표 (um)
        private readonly float _gammaT;            // 열모세관 계수 (mN/(m*K))
        private readonly float _viscosityMu;       // 유체 동점도 (mPa*s)
        private readonly float _dropletHeightH0;   // 액적 중심 높이 (um)
        private readonly float _thermalDiffAlpha;  // 열확산계수 (m^2/s)
        private float _lastPositionX;              // 직전 X 좌표
        private float _lastGradKPerMm;             // 직전 인가 온도 구배

        private const float MaxGradLimitKPerMm = 25.0f; // 히터 과열 방지 한계치
        private const float CriticalMarangoniNum = 120.0f; // 불안정성 발생 임계 Ma

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public MarangoniDropletServoEngine(float targetX, float gammaT, float mu, float h0, float alpha)
        {
            _targetXMicron = targetX;
            _gammaT = gammaT;
            _viscosityMu = mu;
            _dropletHeightH0 = h0;
            _thermalDiffAlpha = alpha;
            _lastPositionX = targetX;
            _lastGradKPerMm = 0.0f;
        }

        /// <summary>
        /// 1ms 주기(1,000Hz) 액적 위치 궤적 피드백 및 마이크로 히터 PWM 분배 연산 (0-Alloc)
        /// </summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public MarangoniDropletState Update1Khz(float currentXMicron, float dtSeconds, Span<float> outHeaterPwmDuties)
        {
            // 1) 순간 이동 속도 산출 (um/s)
            float velocity = (currentXMicron - _lastPositionX) / dtSeconds;
            _lastPositionX = currentXMicron;

            // 2) 위치 오차(P) 및 댐핑(D) 기반 요구 온도 구배 (K/mm)
            float positionErrorUm = _targetXMicron - currentXMicron;
            float targetGradKPerMm = (positionErrorUm * 0.08f) - (velocity * 0.004f);
            targetGradKPerMm = Math.Clamp(targetGradKPerMm, -MaxGradLimitKPerMm, MaxGradLimitKPerMm);

            // 3) 마랑고니 수 Ma = (gamma_T * deltaT * L) / (mu * alpha) 계산
            float charLengthM = _dropletHeightH0 * 1e-6f;
            float deltaTKelvin = MathF.Abs(targetGradKPerMm) * (charLengthM * 1000.0f);
            float maNumber = (_gammaT * 1e-3f * deltaTKelvin * charLengthM) / 
                             (_viscosityMu * 1e-3f * _thermalDiffAlpha);

            // Ma가 임계치 이상일 경우 진동 방지를 위해 구배 완화
            if (maNumber > CriticalMarangoniNum)
            {
                targetGradKPerMm *= (CriticalMarangoniNum / maNumber);
            }

            _lastGradKPerMm += (targetGradKPerMm - _lastGradKPerMm) * 0.2f;

            // 4) 2채널 차동 히터 PWM 듀티 분배 (Left vs Right)
            float baseDuty = 0.35f;
            float diffDuty = (_lastGradKPerMm / MaxGradLimitKPerMm) * 0.30f;
            outHeaterPwmDuties[0] = Math.Clamp(baseDuty - diffDuty, 0.0f, 1.0f); // 좌측 히터
            outHeaterPwmDuties[1] = Math.Clamp(baseDuty + diffDuty, 0.0f, 1.0f); // 우측 히터

            return new MarangoniDropletState(currentXMicron, velocity, maNumber, _lastGradKPerMm);
        }
    }
}