enex_analysis.enex_functions

Utility functions for energy, entropy, and exergy analysis.

This module contains helper functions organized into the following categories:

1. Friction and Flow Functions - darcy_friction_factor: Calculate Darcy friction factor - calc_Orifice_flow_coefficient: Calculate orifice flow coefficient - calc_boussinessq_mixing_flow: Calculate mixing flow based on Boussinesq approximation

2. Heat Transfer Functions - calc_h_vertical_plate: Natural convection heat transfer coefficient - calc_UA_tank_arr: Tank heat loss UA calculation - calc_lmtd_*: Log mean temperature difference calculations - calc_UA_from_dV_fan: Heat transfer coefficient from fan flow rate

3. Curve Fitting Functions - linear_function, quadratic_function, cubic_function, quartic_function

4. Exergy and Entropy Functions - generate_entropy_exergy_term: Calculate entropy and exergy terms - calc_exergy_flow: Calculate exergy flow rate due to material flow

5. G-function Calculations (Ground Source Heat Pumps) - f, chi, G_FLS: Helper functions for g-function calculation

6. TDMA Solver Functions - TDMA: Solve tri-diagonal matrix system - _add_loop_advection_terms: Add forced convection terms to TDMA coefficients

7. Heat Pump Cycle Functions - calculate_ASHP_*_COP: Air source heat pump COP calculations - calculate_GSHP_COP: Ground source heat pump COP calculation - calc_ref_state: Calculate refrigerant cycle states (with superheating/subcooling support) - find_ref_loop_optimal_operation: Find optimal operation point

8. Tank Functions - update_tank_temperature: Update tank temperature based on energy balance

9. Schedule Functions - _build_dhw_usage_ratio: Build schedule ratio array

10. Balance Printing Utilities - print_balance: Print energy/entropy/exergy balance

Functions

calc_HX_perf_for_target_heat(Q_ref_target[, ...])	ε-NTU 기반 공기측 열교환기 풍량 수치 해석.
calc_Orifice_flow_coefficient(D0, D1)	Calculate the orifice flow coefficient based on diameters.
calc_boussinessq_mixing_flow(T_upper, ...[, C_d])	Calculate mixing flow rate between two adjacent nodes based on Boussinesq approximation.
calc_mixing_valve_flows(dV_mix_out, alp)	Calculate volumetric flow rates at a 3-way mixing valve given a mixing ratio.
calc_mixing_valve_temp(T_tank_w_K, ...)	Calculate 3-way mixing valve output temperature and mixing ratio.
calc_stc_performance(I_DN_stc, I_dH_stc, ...)	Solar Thermal Collector (STC) 성능을 계산합니다.
cubic_function(x, a, b, c, d)	Cubic function: y = a*x³ + b*x² + c*x + d
linear_function(x, a, b)	Linear function: y = a*x + b
print_balance(balance[, decimal])	Print energy, entropy, or exergy balance dictionary in a formatted way.
quadratic_function(x, a, b, c)	Quadratic function: y = a*x² + b*x + c
quartic_function(x, a, b, c, d, e)	Quartic function: y = a*x⁴ + b*x³ + c*x² + d*x + e
update_tank_temperature(T_tank_w_K, Q_gain, ...)	Update tank temperature using the Crank-Nicolson implicit scheme.

enex_analysis.enex_functions.linear_function(x, a, b)

Linear function: y = a*x + b

enex_analysis.enex_functions.quadratic_function(x, a, b, c)

Quadratic function: y = a*x² + b*x + c

enex_analysis.enex_functions.cubic_function(x, a, b, c, d)

Cubic function: y = a*x³ + b*x² + c*x + d

enex_analysis.enex_functions.quartic_function(x, a, b, c, d, e)

Quartic function: y = a*x⁴ + b*x³ + c*x² + d*x + e

enex_analysis.enex_functions.print_balance(balance, decimal=2)

Print energy, entropy, or exergy balance dictionary in a formatted way.

This function prints balance information for subsystems, categorizing entries into in, out, consumed, and generated categories.

Parameters:

• balance (dict) – Dictionary containing balance information for subsystems. Structure: {subsystem_name: {category: {symbol: value}}} Categories: ‘in’, ‘out’, ‘con’ (consumed), ‘gen’ (generated)

• decimal (int, optional) – Number of decimal places for output (default: 2)

Returns:

Only prints output

Return type:

None

Example

>>> balance = {
...     "hot water tank": {
...         "in": {"E_heater": 5000.0},
...         "out": {"Q_w_tank": 4500.0, "Q_l_tank": 400.0},
...         "con": {"X_c_tank": 100.0}
...     }
... }
>>> print_balance(balance)

enex_analysis.enex_functions.calc_mixing_valve_temp(T_tank_w_K, T_tank_w_in_K, T_mix_w_out_K)

Calculate 3-way mixing valve output temperature and mixing ratio.

Mixes hot tank water with cold mains water to achieve the target service temperature T_mix_w_out_K.

Parameters:

• T_tank_w_K (float) – Current tank water temperature [K].

• T_tank_w_in_K (float) – Mains (cold) water supply temperature [K].

• T_mix_w_out_K (float) – Target delivery temperature [K].

Returns:

{'alp': float, 'T_mix_w_out': float, 'T_mix_w_out_K': float} - alp: hot-water fraction [0–1] - T_mix_w_out: actual service temperature [°C] - T_mix_w_out_K: actual service temperature [K]

Return type:

dict

enex_analysis.enex_functions.calc_mixing_valve_flows(dV_mix_out, alp)

Calculate volumetric flow rates at a 3-way mixing valve given a mixing ratio.

Parameters:

• dV_mix_out (float) – Total requested service/mixed flow rate [m³/s].

• alp (float) – Hot water mixing ratio [0-1].

Returns:

Dictionary containing generic mixing valve mass balances: - dV_hot_in: Flow rate drawn from the hot source [m³/s] - dV_cold_in: Flow rate drawn from the cold source [m³/s] - dV_mix_out: Total mixed flow rate [m³/s]

Return type:

dict

enex_analysis.enex_functions.calc_Orifice_flow_coefficient(D0, D1)

Calculate the orifice flow coefficient based on diameters.

Flow configuration:

-> | D0 D1 -> -> |

---

type D0:

float

param D0:

Pipe diameter [m]

type D0:

float

type D1:

float

param D1:

Hole diameter [m]

type D1:

float

returns:

C_d – Orifice flow coefficient (dimensionless)

rtype:

float

Notes

This is a simplified calculation. A more complete implementation should be based on physical equations.

enex_analysis.enex_functions.calc_boussinessq_mixing_flow(T_upper, T_lower, A, dz, C_d=0.1)

Calculate mixing flow rate between two adjacent nodes based on Boussinesq approximation.

Mixing occurs only when the lower node temperature is higher than the upper node, creating a gravitationally unstable condition.

Parameters:

• T_upper (float) – Upper node temperature [K]

• T_lower (float) – Lower node temperature [K]

• A (float) – Tank cross-sectional area [m²]

• dz (float) – Node height [m]

• C_d (float, optional) – Flow coefficient (empirical constant), default 0.1

Returns:

dV_mix – Volumetric flow rate exchanged between nodes [m3/s]

Return type:

float

Notes

TODO: C_d value should be calculated based on physical equations.

enex_analysis.enex_functions.calc_HX_perf_for_target_heat(Q_ref_target, T_a_in_C=None, T_ref_sat_K=None, A_cross=None, UA_design=None, dV_fan_design=None, is_active=True, exponent=0.71, T_ou_a_in_C=None, T_ref_evap_sat_K=None, T_ref_cond_sat_l_K=None)

ε-NTU 기반 공기측 열교환기 풍량 수치 해석.

This function determines the airflow that is needed to meet a specified heat transfer demand, accounting for dynamic changes in the overall heat transfer coefficient (UA) as a function of flow velocity based on the correlation for fin-and-tube heat exchangers by Wang et al. (2000) where UA ∝ velocity^0.71.

Parameters:

• Q_ref_target (float) – 목표 열전달량 [W] (항상 양수).

• T_a_in_C (float, optional) – 공기 입구 온도 [°C].

• T_ref_sat_K (float, optional) – 냉매 포화 온도 [K] (일정 온도측).

• A_cross (float) – HX 단면적 [m²].

• UA_design (float) – 설계 UA [W/K].

• dV_fan_design (float) – 설계 팬 풍량 [m³/s].

• is_active (bool) – 활성화 여부.

• exponent (float) – UA scaling exponent (default: 0.71).

• (optional) (# Legacy Aliases)

• T_ou_a_in_C (float, optional) – (하위 호환성) 과거 버전의 T_a_in_C 역할을 수행합니다.

• T_ref_evap_sat_K (float, optional) – (하위 호환성) 과거 버전의 T_ref_sat_K 역할을 수행합니다.

• T_ref_cond_sat_l_K (float, optional) – (하위 호환성) 과거 함수 시그니처 유지를 위한 미사용 파라미터입니다.

Returns:

Dictionary containing:

• dV_fan : Required air-side flow rate [m3/s]

• UA : Actual heat exchanger overall heat transfer coefficient at solution point [W/K]

• T_a_mid_C : air temperature between heat exchanger and fan [°C]

• Q_air : Heat transfer rate at operating point [W]

• epsilon : Effectiveness at operating point [–]

• converged : Whether the solver converged

Returns dict with all values as np.nan if is_active=False

Return type:

dict

enex_analysis.enex_functions.update_tank_temperature(T_tank_w_K, Q_gain, UA_tank, T0_K, C_tank, dt)

Update tank temperature using the Crank-Nicolson implicit scheme.

The governing ODE for a lumped-capacitance tank is:

C dT/dt = Q_gain - UA (T - T0)

Crank-Nicolson averages the loss term across both time levels:

T^{n+1} = [(C/dt - UA/2) T^n + Q_gain + UA T0] / (C/dt + UA/2)

This scheme is second-order accurate in time and unconditionally stable, eliminating the overshoot that Forward Euler can exhibit when dt is large relative to the thermal time constant C/UA.

Parameters:

• T_tank_w_K (float) – Current tank temperature [K].

• Q_gain (float) – Total heat gain rate [W] (condenser, UV, STC, refill, etc.).

• UA_tank (float) – Overall tank heat-loss coefficient [W/K].

• T0_K (float) – Dead-state / ambient temperature [K].

• C_tank (float) – Tank thermal capacitance [J/K] (= c_w * rho_w * V_tank * level).

• dt (float) – Time step [s].

Returns:

Updated tank temperature [K].

Return type:

float

enex_analysis.enex_functions.calc_stc_performance(I_DN_stc, I_dH_stc, T_stc_w_in_K, T0_K, A_stc_pipe, alpha_stc, h_o_stc, h_r_stc, k_ins_stc, x_air_stc, x_ins_stc, dV_stc, E_pump, is_active=True)

Solar Thermal Collector (STC) 성능을 계산합니다.

이 함수는 태양열 집열판의 열전달 분석을 수행합니다. enex_engine.py의 SolarAssistedGasBoiler.system_update() 로직을 참조하여 구현되었습니다.

Parameters:

• I_DN_stc (float) – 직달일사 [W/m²]

• I_dH_stc (float) – 확산일사 [W/m²]

• T_stc_w_in_K (float) – STC 입수 온도 (저탕조 온도) [K]

• T0_K (float) – 기준 온도 (환경 온도) [K]

• A_stc_pipe (float) – STC 파이프 면적 [m²]

• alpha_stc (float) – 흡수율 [-]

• h_o_stc (float) – 외부 대류 열전달계수 [W/m²K]

• h_r_stc (float) – 공기층 복사 열전달계수 [W/m²K]

• k_ins_stc (float) – 단열재 열전도도 [W/mK]

• x_air_stc (float) – 공기층 두께 [m]

• x_ins_stc (float) – 단열재 두께 [m]

• dV_stc (float) – STC 유량 [m3/s]

• E_pump (float) – 펌프 소모 전력 [W]

• is_active (bool, optional) – 활성화 여부 (기본값: True) is_active=False일 때 nan 값으로 채워진 딕셔너리 반환

Returns:

계산 결과 딕셔너리: - I_sol_stc: 총 일사량 [W/m²] - Q_sol_stc: 태양열 흡수 열량 [W] - Q_stc_w_in: STC 입수 열량 [W] - Q_stc_w_out: STC 출수 열량 [W] - ksi_stc: 무차원 수 [-] - T_stc_w_out_K: STC 출수 온도 [K] - T_stc_w_final_K: 펌프 열 포함 최종 출수 온도 [K] - T_stc_w_in_K: STC 입수 온도 [K] - T_stc_K: 집열판 평균 온도 [K] - Q_l_stc: 집열판 열 손실 [W] Returns dict with all values as np.nan (except T_stc_w_out_K, T_stc_w_in_K = T_stc_w_in_K) if is_active=False

Return type:

dict

Notes

• 모든 변수명에 _stc 접미사를 사용하여 STC 관련 변수임을 명확히 구분합니다.

• 열 손실은 Q_l_stc로 명명됩니다.

• 엔트로피 및 엑서지 계산은 제거되었으며, CSV 파일 후처리를 통해 계산해야 합니다.