pcb-afm-simulation-system/web/backend/app/metrics_constants.py

"""Metric key definitions - single source of truth for the Web backend.

This MUST stay in sync with:
- src/solver_core.py METRIC_DEFINITIONS (local solver)
- scripts/robust_motorcad.py METRIC_DEFINITIONS (robust solver)

When adding a new metric, update all three locations.
"""

# All known metric keys produced by Motor-CAD result parsing.
METRIC_KEYS = frozenset({
    # Torque
    "tavg_nm",              # Average torque (virtual work) [Nm]
    "tmax_nm",              # Max torque [Nm]
    "tmin_nm",              # Min torque [Nm]
    "ripple_pct",           # Torque ripple [%]
    "ripple_nm",            # Torque ripple [Nm]
    "ripple_abs_nm",        # Absolute torque ripple [Nm]
    "shaft_torque_nm",      # Shaft torque [Nm]
    "stall_torque_nm",      # Stall torque [Nm]
    "torque_constant",      # Torque constant Kt [Nm/A]
    # Efficiency / power
    "efficiency_pct",       # System efficiency [%]
    "input_power_w",        # Input power [W]
    "output_power_w",       # Output power [W]
    "em_power_w",           # Electromagnetic power [W]
    "power_factor",         # Power factor
    # Losses
    "total_losses_w",       # Total losses [W]
    "copper_loss_w",        # DC copper loss [W]
    "iron_loss_w",          # Stator iron loss [W]
    "magnet_loss_w",        # Magnet loss [W]
    # Electrical
    "back_emf_v",           # Back EMF line-line rms [V]
    "back_emf_thd_pct",     # Back EMF THD [%]
    "phase_current_peak_a", # Phase current peak [A]
    "line_current_rms_a",   # Line current rms [A]
    # Speed
    "shaft_speed_rpm",      # Shaft speed [rpm]
    "no_load_speed_rpm",    # No-load speed [rpm]
    # Thermal
    "winding_temp_c",       # Winding temperature [C]
})

# Metrics that are always required for a valid result.
REQUIRED_METRICS = frozenset({
    "tavg_nm",
    "ripple_pct",
    "efficiency_pct",
    "total_losses_w",
})

# Human-friendly labels for display.
METRIC_LABELS = {
    "tavg_nm": "Average Torque [Nm]",
    "tmax_nm": "Max Torque [Nm]",
    "tmin_nm": "Min Torque [Nm]",
    "ripple_pct": "Torque Ripple [%]",
    "ripple_nm": "Torque Ripple [Nm]",
    "ripple_abs_nm": "Torque Ripple (abs) [Nm]",
    "shaft_torque_nm": "Shaft Torque [Nm]",
    "stall_torque_nm": "Stall Torque [Nm]",
    "torque_constant": "Torque Constant [Nm/A]",
    "efficiency_pct": "Efficiency [%]",
    "input_power_w": "Input Power [W]",
    "output_power_w": "Output Power [W]",
    "em_power_w": "EM Power [W]",
    "power_factor": "Power Factor",
    "total_losses_w": "Total Losses [W]",
    "copper_loss_w": "Copper Loss [W]",
    "iron_loss_w": "Iron Loss [W]",
    "magnet_loss_w": "Magnet Loss [W]",
    "back_emf_v": "Back EMF [V]",
    "back_emf_thd_pct": "Back EMF THD [%]",
    "phase_current_peak_a": "Phase Current (peak) [A]",
    "line_current_rms_a": "Line Current (rms) [A]",
    "shaft_speed_rpm": "Shaft Speed [rpm]",
    "no_load_speed_rpm": "No-load Speed [rpm]",
    "winding_temp_c": "Winding Temp [C]",
}

# Metric optimization direction: "higher" is better, "lower" is better.
# Used by result_analyst for target comparison and best-point selection (C1 fix).
METRIC_DIRECTIONS = {
    "tavg_nm": "higher",
    "tmax_nm": "higher",
    "tmin_nm": "higher",
    "stall_torque_nm": "higher",
    "torque_constant": "higher",
    "efficiency_pct": "higher",
    "output_power_w": "higher",
    "em_power_w": "higher",
    "power_factor": "higher",
    "shaft_speed_rpm": "higher",
    "no_load_speed_rpm": "higher",
    "ripple_pct": "lower",
    "ripple_nm": "lower",
    "ripple_abs_nm": "lower",
    "total_losses_w": "lower",
    "copper_loss_w": "lower",
    "iron_loss_w": "lower",
    "magnet_loss_w": "lower",
    "back_emf_thd_pct": "lower",
    "winding_temp_c": "lower",
    # Neutral / informational (no optimization direction)
    "shaft_torque_nm": "higher",
    "input_power_w": "neutral",
    "back_emf_v": "neutral",
    "phase_current_peak_a": "neutral",
    "line_current_rms_a": "neutral",
}