Common Errors and Troubleshooting

When running hydraulic simulations, you may occasionally encounter error messages or unexpected results. Because R-THYM relies on the EPANET calculation engine, many diagnostic messages reflect fundamental constraints of pipe network physics. However, some issues may arise specifically from R-THYM’s orchestration, such as control link conflicts, power topology constraints, or PID stability.

Network Connectivity Issues

The most common hydraulic error is the inability to solve the network equations (often resulting in an Error 110). This indicates that the solver cannot balance flow or energy.

• Network is Disconnected: The solver classifies a network as disconnected if there is no path of open links between a junction with demand and a source of water (reservoir or tank).
  • R-THYM Tip: If you are modeling power, verify your electrical topology. A pump that is physically connected to the pipe network but disconnected from a power source will effectively act as a closed link in the hydraulic model.
• Unsolvable Equations: This can occur if unrealistic parameters are assigned to components, or if a demand node is physically isolated. If your system was functioning and then failed after a change, double-check that your recent edits haven't inadvertently closed a critical isolation valve or tripped a power switch.

Pump and Equipment Operation

EPANET issues warnings when equipment operates outside its defined parameters.

• Outside Curve Range: If a pump is required to deliver more head than its shutoff head, EPANET may close the pump. This can cause downstream nodes to become disconnected from a water source.
• R-THYM Surge Overrides: If you see a pump acting unexpectedly, check if a surge override is active. If a pump is signaled to turn off but a Control Link is actively holding it in a "surge override" state to close a valve, the pump will continue running until the valve reaches its closed position.

System Unbalance and Oscillation

A "System Unbalanced" condition occurs when the solver cannot converge to a solution within the allowed number of trials. This is often caused by oscillation, where components rapidly switch status between trials.

• PID Instability: If your Control Links use PID control, an overly aggressive "Proportional" or "Derivative" gain can cause the pump or valve to oscillate rapidly between states (e.g., turning on and off every few seconds).
  • Troubleshooting: Try reducing the PID gain settings or increasing the deadband in your Control Link settings to dampen the response.
• Conflicting Rules: Ensure that multiple Control Links are not targeting the same component with conflicting logic (e.g., one rule trying to open a valve while another tries to close it).

Negative Pressures

Negative pressures often indicate a "starved" network. While EPANET can perform a Demand Driven Analysis (DDA) that reports negative pressures, these are physically unrealistic.

• Troubleshooting: Negative pressure usually indicates that demand nodes can only receive water through links that have been closed off or are at capacity.
  • R-THYM Mass Balance: If you see negative pressures alongside tank level errors, check if your tank is empty (0%) or full (100%). R-THYM’s mass balance safety net enforces these limits by throttling flows, which can sometimes manifest as reduced pressure in downstream junctions if the system is starved of supply.

External Review & Diagnostic Exports

If you cannot identify the cause of an error through the UI, you can export your model and results for external review.

• Model Configuration: You can export your entire model structure as a JSON or INP file via the File -> Export Model menu. Reviewing these files allows you to inspect every property, link, and control configuration in a text-based format, which is often easier for spotting typo-related errors or invalid parameter bounds.
• Simulation Traces: If a simulation produces nonsensical results, use the Data menu to generate MOC or EPS Summary Reports. Exporting these as a .zip archive gives you a full CSV trace of every component's performance at every time step. Comparing these raw time-series logs against your expected behavior is the most effective way to pinpoint exactly when and where a simulation diverged from your expectations.

Summary Checklist for Troubleshooting

1. Electrical Path: If using power links, is the component tracing back to a valid, active Power Source (Grid, Battery, or Generator)?
2. Control Logic: Are there conflicting Control Links targeting the same component? Are your PID settings too aggressive?
3. Component Settings: Are your pump curves defined correctly? Does the shutoff head match your system requirements?
4. Mass Balance: Is a tank empty? R-THYM’s mass balance logic will automatically throttle flow to prevent impossible tank levels, which may be the "root cause" of the pressure drop you are observing.
5. Simulation Options: If you are seeing "System Unbalanced" in a complex network, you may need to adjust the Hydraulic Options in your project settings to increase the number of allowable trials.