科研 Skill
流体计算数值错误校验
error-handler-fluids
Handles common numerical errors in fluid calculations, such as division by zero and out-of-range physical values, with validation checks. Use when fluid code fails or returns unphysical results.
SKILL.md
Error Handler for Fluid Calculations
Robust error handling and validation framework for production-ready fluid mechanics calculations. Prevents common numerical errors, validates physical bounds, and provides graceful degradation strategies.
Overview
Fluid calculations are prone to numerical instabilities and physical constraint violations. This helper provides comprehensive error handling, input validation, and debugging tools to create production-ready code.
Common Errors in Fluid Calculations
1. Division by Zero Errors
Mach Number at Zero Velocity
# Dangerous - can divide by zero
M = V / a # If a (speed of sound) = 0, this fails
Causes:
- Zero or near-zero speed of sound at extreme temperatures
- Zero velocity in stagnation point calculations
- Undefined fluid properties at phase boundaries
Prevention:
- Check denominators before division
- Use epsilon values for near-zero comparisons
- Validate property calculations
2. Invalid Reynolds Numbers
Negative Reynolds Numbers
# Can occur with invalid inputs
Re = rho * V * D / mu # If any parameter is negative
Causes:
- Negative density (unphysical)
- Negative viscosity (calculation error)
- Negative dimensions (input error)
- Invalid property correlations
Prevention:
- Validate all inputs are positive
- Check property correlation validity ranges
- Ensure dimensional consistency
3. Temperature Out of Range
Property Correlation Failures
# Most correlations have limited validity
rho = water_density(T) # Fails if T outside 0-100°C range
Causes:
- Input temperatures outside correlation validity
- Supercritical conditions
- Phase change regions
- Cryogenic or high-temperature conditions
Prevention:
- Check temperature bounds before property calculations
- Validate against correlation validity ranges
- Provide appropriate warnings
4. Pressure Below Vapor Pressure
Cavitation Risk
# Physical impossibility in liquid systems
if P < P_vapor(T):
# Liquid will vaporize - calculation invalid
Causes:
- Low pressure in pump suction
- High velocity in pipe restrictions
- Elevated temperatures reducing vapor pressure margin
- Altitude effects on atmospheric pressure
Prevention:
- Calculate and check vapor pressure
- Implement Net Positive Suction Head (NPSH) checks
- Validate system pressure throughout flow path
5. Non-Converging Iterative Solvers
Friction Factor Iterations
# Colebrook equation may not converge
for i in range(max_iter):
f_new = solve_colebrook(Re, roughness, f_old)
if not converged:
# What to do here?
Causes:
- Poor initial guess
- Extreme parameter values
- Stiff equations
- Numerical instability
Prevention:
- Set maximum iterations
- Check convergence criteria
- Use stable initial guesses
- Implement fallback methods
6. Domain Errors in Mathematical Functions
Logarithm and Square Root Errors
# Common in pressure drop calculations
log(negative_value) # Math domain error
sqrt(negative_value) # Complex result in real calculation
Causes:
- Negative arguments to log/sqrt functions
- Complex number results in real calculations
- Numerical precision issues
Prevention:
- Validate function arguments
- Use absolute values where appropriate
- Check for numerical underflow/overflow
7. Unit Inconsistency Errors
Mixed Unit Systems
# Subtle bugs from unit mixing
P_psi = 150
rho_SI = 1000 # kg/m³
# Calculation uses mixed units - wrong result!
Causes:
- Mixing imperial and SI units
- Inconsistent temperature scales (°C vs K)
- Pressure units (absolute vs gauge)
Prevention:
- Standardize to single unit system
- Use unit-aware libraries (pint)
- Document units in variable names
Validation Checks
Physical Limits Validation
Temperature Bounds
def validate_temperature(T, T_min=-273.15, T_max=1000, unit='C'):
"""
Validate temperature is within physical and practical limits.
Physical minimum: absolute zero (-273.15°C)
Practical maximum: depends on application
"""
if unit == 'C':
if T <= -273.15:
raise ValueError(f"Temperature {T}°C below absolute zero")
elif unit == 'K':
if T <= 0:
raise ValueError(f"Temperature {T}K below absolute zero")
if T < T_min or T > T_max:
raise ValueError(f"Temperature {T}{unit} outside valid range [{T_min}, {T_max}]{unit}")
Pressure Bounds
def validate_pressure(P, P_min=0, P_max=None, allow_vacuum=False):
"""
Validate pressure is positive (or allow vacuum if specified).
Absolute pressure must be positive.
Gauge pressure can be negative (vacuum).
"""
if not allow_vacuum and P < 0:
raise ValueError(f"Absolute pressure {P} Pa cannot be negative")
if P_min is not None and P < P_min:
raise ValueError(f"Pressure {P} Pa below minimum {P_min} Pa")
if P_max is not None and P > P_max:
raise ValueError(f"Pressure {P} Pa exceeds maximum {P_max} Pa")
Flow Rate Validation
def validate_flow_rate(Q, Q_min=0, Q_max=None):
"""
Validate volumetric flow rate is non-negative.
"""
if Q < 0:
raise ValueError(f"Flow rate {Q} m³/s cannot be negative")
if Q_max is not None and Q > Q_max:
raise ValueError(f"Flow rate {Q} m³/s exceeds maximum {Q_max} m³/s")
Dimensionless Number Validation
def validate_reynolds_number(Re, warn_transition=True):
"""
Validate Reynolds number and warn about transition region.
"""
if Re < 0:
raise ValueError(f"Reynolds number {Re} cannot be negative")
if warn_transition and 2300 < Re < 4000:
warnings.warn(f"Reynolds number {Re} in transition region (2300-4000)")
return Re
Unit Consistency Checks
def check_dimensional_consistency(velocity, length, viscosity):
"""
Verify dimensions are consistent for Reynolds number calculation.
Re = V * L / nu
[dimensionless] = [m/s] * [m] / [m²/s]
"""
# Using pint for dimensional analysis
import pint
ureg = pint.UnitRegistry()
try:
V = ureg.Quantity(velocity)
L = ureg.Quantity(length)
nu = ureg.Quantity(viscosity)
Re = (V * L / nu).to_base_units()
if not Re.dimensionless:
raise ValueError("Reynolds number calculation not dimensionless!")
except pint.DimensionalityError as e:
raise ValueError(f"Dimensional inconsistency: {e}")
Numerical Stability Checks
def check_numerical_stability(value, min_val=1e-10, max_val=1e10):
"""
Check if value is in numerically stable range.
Prevents overflow, underflow, and loss of precision.
"""
if abs(value) < min_val:
warnings.warn(f"Value {value} may cause underflow")
if abs(value) > max_val:
warnings.warn(f"Value {value} may cause overflow")
if math.isnan(value):
raise ValueError("Calculation resulted in NaN")
if math.isinf(value):
raise ValueError("Calculation resulted in infinity")
Error Handling Strategies
1. Try-Except Blocks
Basic Error Handling
def safe_reynolds_number(V, D, nu):
"""
Calculate Reynolds number with error handling.
"""
try:
# Validate inputs
if V < 0 or D <= 0 or nu <= 0:
raise ValueError("Invalid inputs for Reynolds number")
# Check for division by zero
if nu < 1e-15:
raise ValueError("Kinematic viscosity too small (division by zero risk)")
Re = V * D / nu
# Check result
if math.isnan(Re) or math.isinf(Re):
raise ValueError("Invalid Reynolds number result")
return Re
except ValueError as e:
print(f"Error calculating Reynolds number: {e}")
return None
except Exception as e:
print(f"Unexpected error: {e}")
return None
2. Input Validation
Pre-calculation Validation
def validate_pipe_flow_inputs(V, D, rho, mu, roughness):
"""
Comprehensive input validation for pipe flow calculations.
"""
errors = []
# Velocity
if V < 0:
errors.append(f"Velocity {V} m/s cannot be negative")
elif V > 100:
errors.append(f"Velocity {V} m/s unusually high (check units)")
# Diameter
if D <= 0:
errors.append(f"Diameter {D} m must be positive")
elif D > 10:
errors.append(f"Diameter {D} m unusually large (check units)")
# Density
if rho <= 0:
errors.append(f"Density {rho} kg/m³ must be positive")
elif rho < 0.1 or rho > 20000:
errors.append(f"Density {rho} kg/m³ outside typical range")
# Viscosity
if mu <= 0:
errors.append(f"Viscosity {mu} Pa·s must be positive")
elif mu < 1e-6 or mu > 10:
errors.append(f"Viscosity {mu} Pa·s outside typical range")
# Roughness
if roughness < 0:
errors.append(f"Roughness {roughness} m cannot be negative")
elif roughness > D:
errors.append(f"Roughness {roughness} m cannot exceed diameter {D} m")
if errors:
raise ValueError("Input validation failed:\n" + "\n".join(errors))
return True
3. Graceful Degradation
Fallback Methods
def friction_factor_robust(Re, roughness, diameter, method='auto'):
"""
Calculate friction factor with multiple fallback methods.
"""
# Try exact Colebrook iteration first
if method == 'auto' or method == 'colebrook':
try:
return friction_factor_colebrook(Re, roughness, diameter, max_iter=50)
except (ValueError, RuntimeError) as e:
warnings.warn(f"Colebrook method failed: {e}, trying Swamee-Jain")
# Fallback to Swamee-Jain approximation
if method == 'auto' or method == 'swamee-jain':
try:
return friction_factor_swamee_jain(Re, roughness, diameter)
except (ValueError, RuntimeError) as e:
warnings.warn(f"Swamee-Jain failed: {e}, trying simple correlation")
# Final fallback to simple turbulent correlation
if Re >= 4000:
return 0.316 / Re**0.25
else:
return 64 / Re
4. Bounded Iterations
Safe Iterative Solvers
def solve_colebrook_safe(Re, rel_roughness, max_iter=100, tol=1e-6):
"""
Solve Colebrook equation with convergence monitoring.
"""
# Initial guess
f = 0.02
convergence_history = []
for iteration in range(max_iter):
f_old = f
# Colebrook-White equation
try:
term = rel_roughness/3.7 + 2.51/(Re * math.sqrt(f))
if term <= 0:
raise ValueError("Invalid argument to logarithm")
f = 1 / (-2 * math.log10(term))**2
except (ValueError, ZeroDivisionError) as e:
raise RuntimeError(f"Colebrook calculation error at iteration {iteration}: {e}")
# Check convergence
error = abs(f - f_old)
convergence_history.append(error)
if error < tol:
return f, iteration, convergence_history
# Check for divergence
if iteration > 10 and error > convergence_history[iteration-5]:
raise RuntimeError("Iteration diverging")
raise RuntimeError(f"Failed to converge after {max_iter} iterations")
Error Handling Decorators
Input Validation Decorator
def validate_positive(*arg_names):
"""
Decorator to validate that specified arguments are positive.
"""
def decorator(func):
def wrapper(*args, **kwargs):
# Get function signature
import inspect
sig = inspect.signature(func)
bound_args = sig.bind(*args, **kwargs)
bound_args.apply_defaults()
# Check specified arguments
for arg_name in arg_names:
if arg_name in bound_args.arguments:
value = bound_args.arguments[arg_name]
if value <= 0:
raise ValueError(f"{arg_name} must be positive, got {value}")
return func(*args, **kwargs)
return wrapper
return decorator
@validate_positive('velocity', 'diameter', 'viscosity')
def reynolds_number(velocity, diameter, viscosity):
"""Reynolds number with automatic validation."""
return velocity * diameter / viscosity
Physical Bounds Decorator
def validate_range(param_name, min_val=None, max_val=None):
"""
Decorator to validate parameter is within specified range.
"""
def decorator(func):
def wrapper(*args, **kwargs):
import inspect
sig = inspect.signature(func)
bound_args = sig.bind(*args, **kwargs)
bound_args.apply_defaults()
if param_name in bound_args.arguments:
value = bound_args.arguments[param_name]
if min_val is not None and value < min_val:
raise ValueError(f"{param_name} = {value} below minimum {min_val}")
if max_val is not None and value > max_val:
raise ValueError(f"{param_name} = {value} exceeds maximum {max_val}")
return func(*args, **kwargs)
return wrapper
return decorator
@validate_range('temperature', min_val=0, max_val=100)
def water_density(temperature):
"""Water density with automatic temperature validation."""
return 1000 - 0.1 * temperature # Simplified correlation
Error Logging Decorator
def log_errors(logger=None):
"""
Decorator to log errors and optionally re-raise.
"""
def decorator(func):
def wrapper(*args, **kwargs):
try:
return func(*args, **kwargs)
except Exception as e:
import logging
log = logger or logging.getLogger(func.__module__)
log.error(f"Error in {func.__name__}: {e}", exc_info=True)
raise
return wrapper
return decorator
Logging and Debugging
Calculation Logging
import logging
# Configure logging
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
handlers=[
logging.FileHandler('fluid_calculations.log'),
logging.StreamHandler()
]
)
logger = logging.getLogger('fluid_calcs')
def calculate_pressure_drop(Q, D, L, rho, mu, roughness):
"""
Calculate pressure drop with comprehensive logging.
"""
logger.info(f"Starting pressure drop calculation")
logger.debug(f"Inputs: Q={Q}, D={D}, L={L}, rho={rho}, mu={mu}, roughness={roughness}")
try:
# Calculate Reynolds number
V = 4 * Q / (math.pi * D**2)
Re = rho * V * D / mu
logger.debug(f"Velocity: {V:.3f} m/s, Reynolds: {Re:.0f}")
# Calculate friction factor
f = friction_factor(Re, roughness, D)
logger.debug(f"Friction factor: {f:.5f}")
# Calculate pressure drop
dP = f * (L/D) * (rho * V**2 / 2)
logger.info(f"Pressure drop: {dP:.2f} Pa")
return dP
except Exception as e:
logger.error(f"Calculation failed: {e}", exc_info=True)
raise
Debug Mode
class FluidCalculator:
"""
Fluid calculator with debug mode for detailed output.
"""
def __init__(self, debug=False):
self.debug = debug
def _log(self, message):
"""Internal logging."""
if self.debug:
print(f"[DEBUG] {message}")
def calculate_reynolds(self, V, D, nu):
"""Calculate Reynolds number with debug output."""
self._log(f"Input: V={V}, D={D}, nu={nu}")
# Validation
if nu < 1e-15:
self._log("Warning: viscosity very small")
Re = V * D / nu
self._log(f"Result: Re={Re}")
# Flow regime
if Re < 2300:
regime = "laminar"
elif Re < 4000:
regime = "transition"
else:
regime = "turbulent"
self._log(f"Flow regime: {regime}")
return Re
Diagnostic Tools
def diagnose_calculation_failure(func, *args, **kwargs):
"""
Diagnose why a calculation is failing.
"""
print("=" * 60)
print("CALCULATION DIAGNOSTICS")
print("=" * 60)
print(f"\nFunction: {func.__name__}")
print(f"Arguments: {args}")
print(f"Keyword arguments: {kwargs}")
# Check argument types
print("\nArgument types:")
for i, arg in enumerate(args):
print(f" arg[{i}]: {type(arg).__name__} = {arg}")
# Check for NaN/Inf
print("\nNumerical checks:")
for i, arg in enumerate(args):
if isinstance(arg, (int, float)):
if math.isnan(arg):
print(f" arg[{i}] is NaN!")
elif math.isinf(arg):
print(f" arg[{i}] is Inf!")
elif arg == 0:
print(f" arg[{i}] is zero (potential division issue)")
# Try to execute
print("\nAttempting calculation:")
try:
result = func(*args, **kwargs)
print(f" Success! Result: {result}")
return result
except Exception as e:
print(f" Failed with error: {type(e).__name__}: {e}")
import traceback
traceback.print_exc()
return None
Best Practices Summary
- Always validate inputs before calculations
- Check denominators before division operations
- Verify physical constraints (positive values, valid ranges)
- Use try-except blocks for error-prone operations
- Implement fallback methods for iterative solvers
- Log calculations for debugging and auditing
- Test edge cases (zero, very large/small values)
- Document assumptions and validity ranges
- Use decorators for consistent validation
- Provide clear error messages with context
When to Use This Helper
Essential for:
- Production code in safety-critical applications
- Automated calculation pipelines
- User-facing applications
- Long-running simulations
- Systems with varying input quality
May be overkill for:
- Quick prototypes
- Well-controlled research calculations
- Educational examples
- Single-use scripts
Additional Resources
See handler.py for complete implementation examples and best-practices.md for detailed guidance on production-ready fluid calculations.
示例提示词
帮我检查这段管道流量计算代码,看看有没有负雷诺数之类的数值错误。
所属插件
安装该插件会一并获得同领域的 36 个 Skill / MCP。
同插件的其他科研 Skill
- ANSYS Fluent CFD仿真自动化Automates ANSYS Fluent CFD setup, meshing, and batch runs via Python scripting, journal files, and the PyAnsys ecosystem. Use when a user wants to script or automate an ANSYS Fluent simulation.
- Cantera燃烧仿真Runs Cantera combustion simulations: flame temperature, ignition delay, laminar flame speed, PSR. Use for mechanism-based combustion analysis tasks.
- 离心泵气蚀风险评估Calculates NPSHa and NPSHr and assesses cavitation risk for centrifugal pumps, with prevention and detection guidance. Use when sizing suction piping or diagnosing pump cavitation.
- 气蚀评估物性数据库Looks up vapor pressure, NPSHr data, and correlations for cavitation risk assessment in pumps. Use when cavitation-analysis needs reference property or NPSHr data.
- 离心泵设计计算Designs centrifugal pumps from first principles using Euler equations, velocity triangles, and specific speed. Use for impeller sizing or new centrifugal pump design.
- COMSOL多物理场耦合仿真Sets up coupled fluid-structure interaction simulations in COMSOL Multiphysics, focused on pump vibration analysis. Use when a user wants to script or automate a COMSOL FSI model.
- CoolProp流体物性查询Queries thermodynamic and transport properties for 100+ pure and pseudo-pure fluids via the CoolProp library. Use when a calculation needs fluid density, viscosity, or enthalpy data.
- 工程计算环境初始化Sets up a Python session with engineering constants, Pint units, and plotting defaults. Use at the start of a calculation session.
- 流体力学分析工作流Guides a systematic fluid dynamics analysis from problem setup and domain definition through model selection to validation. Use when planning a CFD or analytical fluid mechanics study end to end.
- 经验公式流体物性速算Computes quick fluid property estimates (density, viscosity, vapor pressure) from empirical correlations without needing a database. Use for fast order-of-magnitude property checks.
- 管道流动与泵选型计算Computes pipe flow, pump sizing, friction factor, and compressible flow results with the fluids Python package. Use for quick, code-based fluid mechanics calculations.
- 工程工具与数据库清点Enumerates installed Python packages, databases, and simulation tools available in the current environment. Use at the start of a session to avoid recommending unavailable tools.
- 管路元件损失系数查询Looks up loss coefficients (K-values) and equivalent lengths for pipes, valves, and fittings in pump and piping systems. Use when computing system head loss.
- 流体与材料物性查询Looks up temperature-dependent fluid viscosities, densities, and other material properties for pump and heat-transfer calculations. Use when a calculation needs property data at a given temperature.
- 泵性能曲线绘制Creates professional engineering plots such as pump performance curves, CFD velocity contours, and publication-quality figures with matplotlib. Use when a result needs a plotted figure.
- NASA大气与航空流体数据Accesses atmospheric property profiles and standard-atmosphere models from NASA Earthdata for high-altitude and aerospace fluid analysis. Use when a task needs altitude-dependent atmospheric data.
- 管网图论建模Models hydraulic piping networks and multi-pump systems as graphs using NetworkX flow algorithms. Use for analyzing flow distribution across a branched or looped piping network.
- REFPROP高精度物性查询Queries high-accuracy thermodynamic and transport properties from the commercial NIST REFPROP database. Use when a calculation needs reference-quality fluid property data and REFPROP is licensed.
- 数值数组计算Performs numerical array operations with NumPy: velocity field processing, pump curve interpolation, linear systems, and matrix methods. Use for general numerical computation in engineering code.
- OpenFOAM仿真与后处理Runs and post-processes OpenFOAM CFD simulations with PyFoam, pyvista, and vtk for mesh setup, solver control, and visualization. Use for scripted OpenFOAM workflows outside ParaView.
- 泵性能曲线与相似定律Generates and interprets pump H-Q/efficiency/power/NPSH curves, applies affinity laws, and predicts off-design performance. Use for pump curve analysis.
- 工程单位换算与量纲分析Handles engineering units with automatic conversion and dimensional-consistency checking using the Pint library. Use whenever a calculation mixes units or needs unit safety.
- 容积式泵设计分析Designs and analyzes gear, piston, and screw positive-displacement pumps, including volumetric efficiency and slip. Use when the pump is positive-displacement rather than centrifugal.
- 泵效率优化Maximizes pump efficiency through hydraulic design changes and operational strategies such as trimming, VFD control, and system matching. Use when a pump is running inefficiently.
常见问题
流体计算数值错误校验能做什么?
Handles common numerical errors in fluid calculations, such as division by zero and out-of-range physical values, with validation checks. Use when fluid code fails or returns unphysical results。
如何安装流体计算数值错误校验?
在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「流体计算数值错误校验」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。
流体计算数值错误校验需要哪些权限?
该科研 Skill没有声明额外权限;执行具体操作时仍由 Agent 按自身规则请求确认。
流体计算数值错误校验经过官方审核吗?
是。SpeedSkills 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。