cryosim/validation/envelope.py

"""Validation envelope checks for CryoSim operating conditions.

The pump has been tested in a specific envelope (from LEARNINGS.md S10):
- Discharge pressure: 0-380 bar (high confidence <=350, moderate 350-380, extrapolation >380)
- Speed: VFD 6-42% -> ~0.06-0.42 speed fraction (model uses 0.3-0.8 as reasonable)
- Inlet pressure: 6-11 bar
- Inlet temperature: 50-76 K
"""

from dataclasses import dataclass


@dataclass
class EnvelopeCheck:
    """Result of an envelope validation check."""
    status: str  # "VALIDATED", "EXTRAPOLATING", or "OUTSIDE_RANGE"
    message: str
    html_banner: str


def check_envelope(Pexit: float, speed: float) -> EnvelopeCheck:
    """Check if operating point is within validated test envelope.

    Args:
        Pexit: Discharge pressure [bar/barg].
        speed: Speed fraction [0-1].

    Returns:
        EnvelopeCheck with status, message, and optional HTML banner.
    """
    warnings = []

    # Pressure check
    if Pexit <= 350:
        p_status = "validated"
    elif Pexit <= 380:
        p_status = "moderate"
        warnings.append(f"Pressure {Pexit:.0f} bar is at edge of test range (350-380 bar)")
    elif Pexit <= 600:
        p_status = "extrapolating"
        warnings.append(f"Pressure {Pexit:.0f} bar exceeds test range (max 380 bar) — extrapolation")
    else:
        p_status = "outside"
        warnings.append(f"Pressure {Pexit:.0f} bar is well beyond test range — low confidence")

    # Speed check (VFD 6-42% maps to ~0.06-0.42, but model uses fractional speed)
    if 0.3 <= speed <= 0.8:
        s_status = "validated"
    elif 0.2 <= speed <= 1.0:
        s_status = "extrapolating"
        warnings.append(f"Speed {speed:.2f} is outside well-tested range (0.3-0.8)")
    else:
        s_status = "outside"
        warnings.append(f"Speed {speed:.2f} is far outside tested range — results unreliable")

    # Overall status
    if p_status == "outside" or s_status == "outside":
        status = "OUTSIDE_RANGE"
    elif p_status == "extrapolating" or s_status == "extrapolating":
        status = "EXTRAPOLATING"
    elif p_status == "moderate":
        status = "EXTRAPOLATING"
    else:
        status = "VALIDATED"

    # Build message and HTML
    if status == "VALIDATED":
        message = "Operating within validated test envelope"
        html = ""  # No banner needed
    elif status == "EXTRAPOLATING":
        message = "Extrapolating beyond validated range: " + "; ".join(warnings)
        html = (
            '<div style="background:#fff8f0; border-left:4px solid #b85c00; '
            'padding:8px 12px; margin-bottom:8px; font-size:12px; '
            'font-family:JetBrains Mono,monospace;">'
            f'<strong>EXTRAPOLATION</strong> — {"; ".join(warnings)}'
            '</div>'
        )
    else:
        message = "Outside validated range: " + "; ".join(warnings)
        html = (
            '<div style="background:#fff0f0; border-left:4px solid #c01a1a; '
            'padding:8px 12px; margin-bottom:8px; font-size:12px; '
            'font-family:JetBrains Mono,monospace;">'
            f'<strong>OUTSIDE VALIDATED RANGE</strong> — {"; ".join(warnings)}. '
            'Results should be treated with skepticism.'
            '</div>'
        )

    return EnvelopeCheck(status=status, message=message, html_banner=html)