sepehr/Entropyk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Entropyk/_bmad-output/implementation-artifacts/7-6-component-calibration-parameters.md

10 KiB
Raw Permalink Blame History

Story 7.6: Component Calibration Parameters (Calib)

Status: review

Story

As a R&D engineer matching simulation to real machine test data, I want calibration factors (Calib) on components, so that simulation results align with manufacturer test data and field measurements.

Acceptance Criteria

  1. Calib Implementation (AC: #1)

    • Compressor and Expansion Valve support f_m (default 1.0): ṁ_eff = f_m × ṁ_nominal
    • Pipe and Heat Exchanger support f_dp (default 1.0): ΔP_eff = f_dp × ΔP_nominal
    • Evaporator and Condenser support f_ua (default 1.0): UA_eff = f_ua × UA_nominal
    • Compressor support f_power (default 1.0): Ẇ_eff = f_power × Ẇ_nominal
    • Compressor support f_etav (default 1.0): η_v,eff = f_etav × η_v,nominal (displacement models; AHRI 540: f_m suffices)
    • Default 1.0 = no correction; typical range [0.8, 1.2]

  2. Serialization & Persistence (AC: #2)

    • Calib struct serializable in JSON (short keys: f_m, f_dp, f_ua, f_power, f_etav)
    • Loading from JSON restores Calib values
    • Traceability metadata can include calibration_source (test data hash or identifier)

  3. Calibration Workflow Documentation (AC: #3)

    • Document recommended order: f_m → f_dp → f_ua → f_power (prevents parameter fighting)
    • Reference: alphaXiv, Buildings Modelica, EnergyPlus, TRNSYS, TIL Suite

  4. Validation Against Test Data (AC: #4)

    • With calibrated components, results match test data within configurable tolerance
    • Example targets: capacity ±2%, power ±3% (industry typical)
    • Unit tests verify scaling (f=1.0 unchanged, f=1.1 scales by 10%)

Tasks / Subtasks

  • Define Calib struct (AC: #1)
    • Create Calib { f_m, f_dp, f_ua, f_power, f_etav } in crates/core
    • Default: all 1.0; serde with short keys; validation: 0.5 ≤ f ≤ 2.0
    • Document each factor with component mapping and literature ref
  • Add f_m to Compressor and Expansion Valve (AC: #1)
    • Compressor: ṁ_out = f_m × ṁ_ahri540
    • Expansion Valve: scale mass flow if orifice model; else f_m on inlet flow
  • Add f_power and f_etav to Compressor (AC: #1)
    • f_power: Ẇ_out = f_power × Ẇ_ahri540
    • f_etav: for displacement models; AHRI 540: use f_m only, f_etav=1.0
  • Add f_dp to Pipe and Heat Exchanger (AC: #1)
    • Pipe: ΔP_eff = f_dp × ΔP_darcy_weisbach
    • Heat Exchanger: scale refrigerant-side ΔP if modeled
  • Add f_ua to Evaporator and Condenser (AC: #1)
    • Heat transfer models: UA_eff = f_ua × UA_nominal before Q = UA × ΔT_lm
  • JSON serialization (AC: #2)
    • Calib in component schema; round-trip test
    • Optional calibration_source in metadata
  • Documentation and tests (AC: #3, #4)
    • Dev Notes: calibration order and literature refs
    • Unit tests: f_m, f_dp, f_ua, f_power scaling
    • Integration test: calibrated cycle vs synthetic test data

Dev Notes

Naming: Calib (short for Calibration Factors)

Struct name: Calib — 5 chars, standard in HVAC/refrigeration literature ("calibration factors").

Field names (short, JSON-friendly):

Field Full name Effect Components
f_m mass flow factor ṁ_eff = f_m × ṁ_nominal Compressor, Expansion Valve
f_dp pressure drop factor ΔP_eff = f_dp × ΔP_nominal Pipe, Heat Exchanger
f_ua UA factor UA_eff = f_ua × UA_nominal Evaporator, Condenser
f_power power factor Ẇ_eff = f_power × Ẇ_nominal Compressor
f_etav volumetric efficiency η_v,eff = f_etav × η_v,nominal Compressor (displacement)

Literature: Calibration Coefficients in HVAC/Refrigeration Software

EnergyPlus (RP-1051, DX/Chillers):

  • Biquadratic capacity/EIR curves: c₁…c₆
  • Part-Load Fraction (PLF): a + b(PLR) + c(PLR)²
  • Case Latent Heat Ratio, ambient correction curves

Modelica Buildings (Heat Pumps):

  • etaEle: Electro-mechanical efficiency
  • PLos: Constant power losses (W)
  • leaCoe: Leakage coefficient (kg/s)
  • UACon, UAEva: Thermal conductance (W/K)
  • volRat: Built-in volume ratio
  • V_flow_nominal: Refrigerant volume flow at suction
  • Optimization minimizes |modeled − manufacturer_data|

TRNSYS (Type 941, Heat Pumps):

  • Correction Factor: multiplier on interpolated capacity/power from performance map
  • Heat Loss Coefficient (U-value) for storage

TIL Suite (EN 12900 / ARI 540):

  • 10-coefficient polynomial for ṁ and P
  • Heat Transfer Multiplier (evaporator/condenser zones)
  • Zeta value / friction factor multiplier for pressure drop

Compressor Efficiency (alphaXiv, Purdue):

  • Volumetric efficiency η_v: λ factor for clearance-volume model
  • Isentropic efficiency η_is: friction factor, heat transfer factor
  • Calibration: η_v and η_is scaled to match test bench

Calibration Workflow (sequential):

  1. f_m — mass flow (compressor power + ṁ measurements)
  2. f_dp — pressure drops (inlet/outlet pressures)
  3. f_ua — heat transfer (superheat, subcooling, capacity)
  4. f_power — compressor power (if f_m insufficient)

Previous Story Intelligence

Story 1-4 (Compressor AHRI 540):

  • crates/components/src/compressor.rs
  • ṁ from M1, M2; Ẇ from M3–M6 (cooling) or M7–M10 (heating)
  • Apply f_m on ṁ, f_power on Ẇ

Story 1-5 (Heat Exchanger):

  • crates/components/src/heat_exchanger/ — LmtdModel, EpsNtuModel
  • Scale UA before Q = UA × ΔT_lm

Story 1-6 (Expansion Valve):

  • Isenthalpic; ṁ continuity. Apply f_m if flow model exists.

Story 1-8 (Pipe):

  • Darcy-Weisbach; apply f_dp on ΔP

Technical Requirements

Calib struct:

/// Calibration factors for matching simulation to real machine test data.
/// Short name: Calib. Default 1.0 = no correction. Typical range [0.8, 1.2].
/// Refs: Buildings Modelica, EnergyPlus, TRNSYS, TIL Suite, alphaXiv.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct Calib {
    /// f_m: ṁ_eff = f_m × ṁ_nominal (Compressor, Valve)
    #[serde(default = "one", alias = "calib_flow")]
    pub f_m: f64,
    /// f_dp: ΔP_eff = f_dp × ΔP_nominal (Pipe, HX)
    #[serde(default = "one", alias = "calib_dpr")]
    pub f_dp: f64,
    /// f_ua: UA_eff = f_ua × UA_nominal (Evaporator, Condenser)
    #[serde(default = "one", alias = "calib_ua")]
    pub f_ua: f64,
    /// f_power: Ẇ_eff = f_power × Ẇ_nominal (Compressor)
    #[serde(default = "one")]
    pub f_power: f64,
    /// f_etav: η_v,eff = f_etav × η_v,nominal (Compressor displacement)
    #[serde(default = "one")]
    pub f_etav: f64,
}
fn one() -> f64 { 1.0 }

Validation: 0.5 ≤ f ≤ 2.0. Reject otherwise.

File Structure

New: crates/core/src/calib.rs (or calibration.rs)

Modified:

  • crates/components/src/compressor.rs — f_m, f_power, f_etav
  • crates/components/src/pipe.rs — f_dp
  • crates/components/src/heat_exchanger/model.rs — f_ua
  • crates/components/src/expansion_valve.rs — f_m
  • crates/core/src/lib.rs — export Calib

Testing

  • test_calib_default_all_one
  • test_f_m_scales_mass_flow
  • test_f_dp_scales_pressure_drop
  • test_f_ua_scales_heat_transfer
  • test_f_power_scales_compressor_power
  • test_calib_json_roundtrip
  • test_calib_aliases_backward_compat (calib_flow → f_m)

References

  • Epic 7.6: planning-artifacts/epics.md
  • Buildings.Fluid.HeatPumps.Calibration: simulationresearch.lbl.gov/modelica
  • EnergyPlus VRF: bigladdersoftware.com/epx/docs
  • TRNSYS Type 941: Correction Factor
  • TIL Suite: Zeta, heat transfer multiplier
  • alphaXiv: calib_flow, calib_dpr, UA, η_vol, η_is
  • Reddy RP-1051: Calibration methodology
  • Purdue IIAR: Volumetric/isentropic efficiency calibration

Optional / Future (out of scope for this story)

  • f_cap: Capacity correction factor (TRNSYS, EnergyPlus) — system-level Q scaling; for component-level, f_ua suffices.
  • PLF / Part-Load: EnergyPlus PLF curve — transient/cycling; steady-state out of scope.

Dev Agent Record

Agent Model Used

Auto (dev-story workflow)

Debug Log References

Completion Notes List

  • Calib struct added in crates/core (calib.rs) with serde, validation 0.5–2.0, and doc with calibration order.
  • Compressor: calib field, f_m on mass_flow_rate(), f_power on power_consumption_cooling/heating; calib(), set_calib().
  • Expansion valve: calib field, f_m in mass flow residual and jacobian; calib(), set_calib().
  • Pipe: calib field, f_dp in pressure_drop(); calib(), set_calib().
  • HeatExchanger: calib field; LmtdModel and EpsNtuModel: ua_scale, effective_ua(), set_ua_scale(); exchanger syncs calib.f_ua to model.
  • Evaporator and Condenser: calib() and set_calib() delegate to inner HeatExchanger.
  • Unit tests: test_f_m_scales_mass_flow, test_f_power_scales_compressor_power, test_f_dp_scales_pressure_drop, test_f_ua_scales_heat_transfer; core: test_calib_json_roundtrip, test_calib_aliases_backward_compat.

File List

  • crates/core/src/calib.rs (new)
  • crates/core/src/lib.rs (modified)
  • crates/core/Cargo.toml (modified: dev-deps serde_json)
  • crates/components/src/compressor.rs (modified)
  • crates/components/src/expansion_valve.rs (modified)
  • crates/components/src/pipe.rs (modified)
  • crates/components/src/heat_exchanger/exchanger.rs (modified)
  • crates/components/src/heat_exchanger/model.rs (modified)
  • crates/components/src/heat_exchanger/lmtd.rs (modified)
  • crates/components/src/heat_exchanger/eps_ntu.rs (modified)
  • crates/components/src/heat_exchanger/evaporator.rs (modified)
  • crates/components/src/heat_exchanger/condenser.rs (modified)
  • _bmad-output/implementation-artifacts/sprint-status.yaml (modified)
  • _bmad-output/implementation-artifacts/7-6-component-calibration-parameters.md (modified)

Change Log

  • 2026-02-17: Story 7-6 implemented. Calib in core; f_m, f_power on compressor; f_m on expansion valve; f_dp on pipe and heat exchanger (field); f_ua on LMTD/ε-NTU and evaporator/condenser. JSON round-trip and scaling unit tests added.