Skip to content

Latest commit

 

History

History
460 lines (354 loc) · 32.3 KB

debugging_models.md

File metadata and controls

460 lines (354 loc) · 32.3 KB

Debugging Models in CoolSolve

This guide explains how to diagnose and fix solver failures in CoolSolve. It is based on the workflow used to fix the condenser_3zones.eescode model and applies to other models that fail at the solver level.

Overview

When a model fails to solve, the typical causes are:

  1. Convergence problems – Newton solver cannot find a solution (line search failure, max iterations, poor initial guess)
  2. Algebraic loops – Large strongly connected components (SCCs) that are difficult to solve
  3. Invalid physics – CoolProp errors from out-of-range temperatures, pressures, or enthalpies
  4. Procedure/function issues – Bugs or unit mismatches in user-defined procedures

Step 1: Run in Debug Mode

Always start by running the model in debug mode to gather diagnostic information:

./coolsolve -d input.eescode

This creates a folder <input>_coolsolve/ (or <input>_coolsolve/ next to the input file) containing:

File Use for diagnosis
report.md Block summary, solver status, largest block size, branch kept by each $IF/$IFNOT
solver_errors.md Error type (LineSearchFailed, MaxIterations, Diverged, EvaluationError)
solver_trace.md Per-block Newton iterations, residual norms
evaluator.md Block evaluation status, max residuals at current state
coolsolve_residuals.md Equation-by-equation LHS, RHS, residual values: at the solution, or where the solve stopped (the blocks solved at their solution, the failed block at its solver's last iterate, the later blocks at their guesses)
solver_final_residuals.md After a failure: every equation of the block that did not converge at its solver's last iterate, with its residual F, its scale S and its weighted residual rho as the convergence test computes it (abs(F)/w, 0 within the rounding level 64 eps S), worst first; the variables of the block with their last change and their guess
equations.md Which equations are in each block

Quick Win — "Try Harder" (GUI)

Before diving into the diagnosis below, click the Try Harder button in the GUI (shortcut: Ctrl+Enter after a failed solve). It re-runs the model with the full Deep Search pipeline (deepSearchPipeline), forces structural tearing, symbolic reduction and equation scaling (enableEquationScaling) on, and engages multi-start according to multiStartMode. If the failure was due to a poor initial guess or an algebraic loop that tearing can crack, Try Harder recovers it in one click — no manual diagnosis required.

  • If Try Harder succeeds, the model is fine; the default pipeline simply needed more fire-power. To make Deep Search the default, set solverPipeline to the full chain in coolsolve.conf.
  • If Try Harder also fails, proceed to Step 2 to interpret the error and apply the structured workflow below.
  • Editing the model, the initials, or the configuration restores the normal Solve button.

Outside the GUI, the equivalent is to send {"deepSearch": true} to the POST /api/v1/solve endpoint — see GUI §6.2.

Step 2: Interpret the Error

LineSearchFailed

  • Meaning: The Newton step direction is valid, but no step size satisfies the line search (e.g. step would push variables into invalid region, or Armijo condition not met).
  • Typical causes: Poor initial guess, variables near physical limits, ill-conditioned Jacobian.
  • Check: solver_trace.md – residual at failure, step norm. If residual is small (e.g. < 1), the solution may be very close. solver_final_residuals.md names the equations that are not met, worst first.

MaxIterations

  • Meaning: Newton did not converge within the iteration limit (default 100).
  • Typical causes: Large algebraic loop, poor initials, slow convergence.
  • Check: solver_trace.md – does the residual decrease or stall? A stall near a small residual suggests a near-solution. solver_final_residuals.md lists the equations that hold the residual (rho above the tolerance) and the variables still at their guess.

EvaluationError (CoolProp)

  • Meaning: CoolProp rejected an input (e.g. enthalpy outside valid range, pressure too low).
  • Typical causes: Incorrect initial values, wrong units (e.g. P=1 interpreted as 1 Pa instead of 1 bar), cascaded errors from a previous block.
  • Check: Error message for the exact invalid input. Inspect coolsolve_residuals.md for suspicious values (e.g. enthalpy = 1.0 instead of ~4e5 for air).

A CALL ERROR stops the calculation at an early iterate

  • Meaning: a CALL ERROR of a FUNCTION or PROCEDURE of the model was reached by an iterate that starts from the guesses (the initial guess, a Newton step, a line-search trial...), not necessarily by the solution. The EES help only says that the ERROR procedure halts the calculation; CoolSolve stops at once, as EES does: the status is EvaluationError and the message is that of the call, with the value of the iterate (CALL ERROR: x too small 1.00). No other solver or block is tried afterwards. (A CALL WARNING never stops the run, and nor does a CoolProp failure, which the solver recovers from.) The exploratory points that CoolSolve alone tries after a failure (the probes of the one-unknown solver, the multi-start candidates) are different: one that raises a CALL ERROR is skipped; when no multi-start candidate solves the block, its failure message ends with the CALL ERROR of the first candidate that raised one (multi-start candidate 1 (scale x0.1): CALL ERROR: ...).
  • Typical causes: a guard (IF (x < 2) THEN CALL ERROR(...)) that the solution respects but the default guess (1 for every unknown) or an early Newton step does not, e.g. a step that overshoots to a negative value.
  • Fix: give the unknowns that the guard concerns a value inside the allowed range, close to the solution, in the .initials file (or in the Variables table of the GUI). The message gives the value of the iterate that reached the error: a step that overshoots (e.g. to a negative value) is cured by a guess nearer the solution, as the first step of a Newton iteration is the one that leaves the range. A guard that is only a protection of the model against its own iterates (not a physical limit) can also be written so that it holds at the solution only, e.g. CALL WARNING, which is reported at the solution and ignored while iterating.
  • Check: the message of the block, and solver_trace.md for the iterates before the one that stopped.

SingularJacobian

  • Meaning: Jacobian is rank-deficient; Newton cannot compute a unique step.
  • Typical causes: Redundant equations, degenerate system, bad structural analysis.
  • Check: solver_singular_diagnostics.md – the residual and Jacobian at the failure. Its section Non-finite entries, zero rows and zero columns names the equations whose Jacobian row holds NaN/Inf (e.g. a derivative through ln(x) with x < 0) and the empty rows and columns (an equation whose derivatives all vanish at that point, an unknown on which no residual depends there). Rows follow the block's equations and columns its variables; with symbolic reduction the Jacobian is that of the reduced block and is given by index only. When it reports none, the matrix is numerically rank-deficient.

Diverged

  • Meaning: the Newton iteration ran away (the iterate is more than 10⁶ times larger than the starting point) and the derivatives underflowed to zero, so that no step could be computed. The Jacobian is not structurally singular: it became zero because the iterate left the region of the solution. (solver_singular_diagnostics.md is not written.)
  • Typical causes: an equation without a root (e.g. exp(x) = -1), or a root in a region the iteration jumps over, such as the pole of an equation hyperbolic in its unknown, with a poor initial guess.
  • Check: solver_trace.md – the residual does not decrease while ||dx|| explodes. Give an initial value on the side of the root (.initials) or check that the equation has a solution.

F changes sign across a jump, not through a root

  • Meaning: for a block of one equation, Newton1D found a sign change of the residual but the bracket shrank below stepTolerance with a large residual: F jumps there, it does not cross zero. The message gives the bracket and the residual on each side. A bracket of this kind is given up (it was once reported as a converged solution): the next sign change is tried, and the block fails only if none holds a root.
  • Typical causes: a pole of the equation; a CoolProp call that fails beyond that point (the edge of the validity domain of a fluid, e.g. an enthalpy below the triple point at the pressure) and returns its penalty value of 1E4, which turns the residual into a step. A flat region of the property across the saturation dome (T of a pure fluid is constant for every h inside it) does not cause it: F is continuous there.
  • Check: the [C001] warnings of the block for the failing CoolProp call, and solver_trace.md (iterations numbered 1000 and above are the bisection). Give an initial value on the side of the solution (.initials) or check that the equation has a solution.

Step 3: Identify the Failing Block

From report.md and solver_errors.md:

  • Note the block index and size (e.g. Block 38, size 62).
  • Large blocks (tens of equations) are algebraic loops and are hardest to solve.

From equations.md:

  • List the variables and equations in that block.
  • Look for coupling: shared variables, procedure calls, thermodynamic functions.

Step 4: Check Initial Values

  • Variables without values in .initials default to 1.0, which is often wrong (e.g. enthalpies, mass fractions).
  • Compare evaluator.md “Current State” with physically reasonable values.
  • If you have a reference solution, use those values in .initials.

Step 5: Break the Loop (Simplified Model)

For large algebraic loops that fail to converge, a practical approach is to fix one or more variables to reduce the loop size. Use a simplified model to obtain good initials, then solve the full model.

5.1 Create a Simplified Model

  1. Copy the original model to model_simple.eescode.
  2. Pick a variable that strongly couples the loop (e.g. a pressure, temperature, or mass fraction) and fix it to a known value from .initials.
  3. Replace the equation that originally determined it with an explicit assignment.

Example (condenser-style model):

" Original (in implicit block): P_r_su_cd is unknown "
" Simplified: fix condenser inlet pressure from initials "
P_r_su_cd=949215
  1. Ensure the system stays square (same number of equations and unknowns). Fixing one variable replaces one implicit equation with one explicit one, so the count stays the same.

5.2 Solve the Simplified Model

cp model.initials model_simple.initials
./coolsolve -g model_simple.eescode
  • If it solves, model_simple.initials is updated with the solution.

5.3 Transfer Initials to the Full Model

cp model_simple.initials model.initials
./coolsolve model.eescode
  • The full model often converges with these improved initials.

5.4 Choosing Variables to Fix

  • Pressures (e.g. condenser/evaporator inlet): often good candidates in HVAC/refrigeration.
  • Mass/energy fractions (e.g. zone splits): can decouple zone balances.
  • Temperatures at key points: useful when they are central to the loop.

Use equations.md and report.md to see which variables appear in the largest blocks.

Step 6: Fix Model Issues

Unit Mismatches (CoolProp)

  • Temperatures are in °C, never K. CoolSolve's unit system is fixed (see the warning at the top of the Language Reference): every T=... argument and every value returned by temperature(...), t_sat(...), T_CRIT, … is in degrees Celsius. CoolProp works internally in Kelvin; the °C ↔ K conversion is performed automatically by CoolSolve. Writing T=300 therefore means 300 °C (≈ 573 K), not 300 K — getting this wrong is a common source of EvaluationError from CoolProp.
  • CoolProp expects Pa for pressure. If the model uses bar or kPa, convert (e.g. P=101325 for 1 atm).
  • Example: specheat(cf$, T=t_bar_cf, P=1) may mean 1 bar in some contexts but 1 Pa in CoolProp → use P=101325.

A quality of 100 or -100

quality(...) is 100 for a superheated vapour and -100 for a compressed liquid, as in EES: a value outside [0, 1] says that the state is not in the dome (see Quality outside the saturation dome in the Language Reference). The warning Quality input x=100.000000 clamped to 1 (superheated) means that such a value was used as the quality input of another call (enthalpy(Water, P=P, x=x_1)); the final check of the solution then fails on that equation. Look at the state that gives the 100 or -100: in a cycle it is usually a temperature or an enthalpy that is not where the model expects it (a condenser outlet that is subcooled, a compressor suction that is superheated), or a quality that should have been an input. Test the phase with PHASE$(...) or compare the enthalpy with the saturation values instead of comparing the quality with 0 or 1.

A temperature outside the range of a NASA-Glenn species

OH, H, O, N, NO and NO2 are evaluated from the NASA-Glenn polynomials, which are defined from 200 K to 20000 K (NO2: 6000 K; Language Reference §5). Two messages say that a state is outside:

  • CoolProp evaluation failed in final solution: … NASA-Glenn data of NO2: T = 6273.15 K is outside the range 200 K to 6000 K (the range is in K, the model's temperatures are in °C): the temperature of the solution, or a constant, is out of the data. The same range applies to the temperature solved from h, u or s (… is not reached between 200 K and 6000 K).
  • … temperature 150 K is below the lowest temperature of the NASA-Glenn data of NO2 (200 K); an input that depends on the unknowns of its block is limited there during the iterations, so the solution would not satisfy this equation: the solver converged on the limit, the solution is below 200 K. Check the equation that gives the temperature (a heat balance with a wrong sign, a temperature in K written where °C is expected).

Between those, a Newton trial point below 200 K is limited to 200 K without a message: the solve is not lost.

CALL NASA(Species$, T : cp, h, s) (Language Reference §7) has the same range and says so: CALL NASA: NASA-Glenn data of NO2: T = 6273.15 K is outside the range 200 K to 6000 K (T in K in the message, in °C in the model; an EES file written for K needs T - 273.15). A trial temperature outside is limited on both sides, and a solution at the limit is refused (CALL NASA(NO2, T): temperature … K is below the lowest temperature of the NASA-Glenn data …). CALL NASA: unknown species 'XYZ'; the species of the NASA-Glenn table are … lists the 22 names the table holds. Outputs that are 1000 times too small or too large are the kJ of EES: the procedure gives J/kmol.

A heating value that is refused

LowerHeatingValue(Fuel) and HigherHeatingValue(Fuel) (Language Reference §3) take an ideal gas of C, H and O: LowerHeatingValue(Methane): the heating values are defined for the ideal gases … not for the real fluid Methane; use the ideal gas CH4 means that the fuel is written with the name of its real fluid; N2 is no fuel of the heating values, Air has no composition … and CO2 is a product of the combustion name a species that does not burn or is not a pure fuel of C, H and O. A liquid fuel of EES (ethanol, n-propanol) is the Unknown fluid error: give its heating value as a number. The result is in J/kg of fuel, whatever the EES file reads in kJ/kmol (multiply by the molar mass of the fuel, molarmass(X), to get J/kmol).

CALL CHEM_EQUIL: domain errors and a flame that does not converge

CALL CHEM_EQUIL (Language Reference §7) names the input it refuses: CALL CHEM_EQUIL: the temperature T = … K is outside the range of the NASA-Glenn data of the species of the mixture, 200 K to 6000 K (an EES file passes T in K and P in kPa: the procedure takes °C and Pa, so a temperature 273.15 too high or a pressure 1000 times too low is the usual cause), the ratio C\O = … is negative, … the mixture would form graphite (C\O ≥ 1 + H\O/4: a fuel-rich mixture beyond what CO, CO2 and CH4 hold). During the iterations an input that depends on the unknowns is limited to the domain; CALL CHEM_EQUIL: temperature … K is below the lowest temperature …; an input that depends on the unknowns of its block is limited there means the solver converged on that limit: check the energy balance that gives the temperature.

An adiabatic flame written as in the EES files, with the species enthalpies as unknowns of the block of the flame temperature (DUPLICATE i=1,14 ⏎ H[i] = MolarMass(…)*enthalpy(…, T=T_adiab) ⏎ END, then sum(ntot*x[i]*H[i], i=1,14)), can stop on a residual of about 1E-2 that Newton's method no longer reduces (LineSearchFailed or MaxIterations, the trace showing steps of 1E-7): the block holds enthalpies of 1E8 J/kmol beside mole fractions of 1E-20, and the QR of Newton's step drops directions of the small equations. First remedy: set enableEquationScaling = true in coolsolve.conf (equilibrated Newton steps, Language Reference §10), or click Try Harder, which turns it on. Without the option, sum the enthalpies of the products in a FUNCTION (the example of the Language Reference), or write them in MJ/kmol (H[i] = MolarMass(…)*enthalpy(…, T=T_adiab)/1E6).

Procedure Fixes

  • Procedures are a common source of issues. Check:
    • Correct mapping of inputs/outputs in CALL.
    • Pressure and temperature units in thermodynamic calls.
    • A body is a sequence of assignments executed in order (= and := alike), checked when the model is parsed (Language Reference §7). Three parse errors, with the line of the statement, stop the run:
      • implicit equation in PROCEDURE 'pq': the left-hand side of a body statement is not a variable (1/sqrt(f) = …). A body solves nothing: iterate explicitly in the body (REPEAT … UNTIL, e.g. a fixed-point iteration), or move the equation to the main program and pass its result as an input argument.
      • variable 'b' is read in PROCEDURE 'p' before it is assigned: the body reads a local that has no value yet (the locals of a body are not initialised). Usually the statements are in the wrong order (move the assignment up), the name is misspelt, or it is a variable of the main program, which a body does not see: add it to the input arguments of the routine and of every call. In a REPEAT loop, a variable read before its assignment in the loop needs a value before the loop. A source written for simultaneous solving (an EES SUBPROGRAM, or a body that reads its own output, such as the function's name, before computing it) must be rewritten as explicit assignments or moved to the main program.
      • FUNCTION 'ff' never assigns its output 'ff' (or a PROCEDURE output), on the header line: no statement of the body assigns that output; assign it (in every branch that can be taken) or remove it from the outputs.
    • A CALL WARNING of the model (diagnostic W001, warning (line N): … with the line of the call) describes the solution: the solver does not report the iterates that crossed the range on the way, so a warning that the model should raise but that is missing means the solution is inside the range.

Step 7: Solver Options (Advanced)

For difficult models, you can adjust SolverOptions in code (e.g. in runner.cpp or via a future CLI):

  • maxIterations – increase for large blocks (e.g. 500).
  • tolerance – loosen if near-convergence is acceptable. It applies to the residual of each equation relative to the size of its terms (Language Reference §10): the same absolute 1e-9 for terms of order 1, relative to the terms in a block whose equations all have terms below 1, and not below the rounding level of the terms above 7·10⁴.
  • lsRelaxedTolerance – accept convergence when line search fails but residual is small.

warning: x = … is below the solver tolerance (…) (W002). A variable solved by an implicit block has a value between 0 and tolerance (1e-9) in magnitude. Its digits are right only if its block holds nothing but tiny terms (the convergence test is then relative to them); beside terms of order 1 it is only known to 1e-9. Such a value is often a sign of a mistake: a quantity in the wrong unit (W instead of kW), a difference of two equal numbers (Q1 − Q2 = 1e-16 is rounding noise, not a flow), or a variable that should be 0. Check its equation; to silence the warning for a value that is really that small, write the equation explicitly (c = 2.33E-20). It is reported once per variable.

Example: condenser_3zones

This example shows how to diagnose and fix a failing model when you do not have correct initial values. The repository keeps condenser_3zones.initialsnotok (inadequate) and condenser_3zones.initials (working) for comparison.

Diagnosis

  1. Run in debug mode:

    ./coolsolve -d condenser_3zones.eescode

    Result: Block 38 (62 equations) fails with LineSearchFailed or MaxIterations.

  2. Inspect solver_final_residuals.md (the equations of block 38 that are not met, worst first, and its variables with their guess) and coolsolve_residuals.md: equations like h_cf_su_cd_sc = h_cf_su_cd show values of 1.0 instead of ~4e5. Variables without values in .initials default to 1.0; enthalpies should be ~4e5 J/kg for air.

  3. Inspect the two_phase_CD procedure: specheat(cf$, T=t_bar_cf, P=1) uses P=1. CoolProp expects Pa; 1 Pa is unphysical for air. Some solvers may treat 1 as 1 bar; CoolProp does not.

Fixes


**Fix: Obtain good initials via a simplified model**

The 62-equation block is a tight algebraic loop. Create a **temporary** simplified model to break it and get usable initials:

1. Copy the model to `condenser_3zones_simple.eescode`.
2. Add an explicit assignment for a key coupling variable, e.g. fix the condenser inlet pressure:
   ```ees
   P_r_su_cd=949215

(Use a value from .initials if available.) Ensure the system stays square. 3. Use existing initials for the simplified model (even partial ones may work once the loop is broken): cp condenser_3zones.initials condenser_3zones_simple.initials, or copy from .initialsnotok if that is all you have. 4. Solve and update initials:

./coolsolve -g condenser_3zones_simple.eescode
  1. Copy the solution to the full model:
    cp condenser_3zones_simple.initials condenser_3zones.initials
  2. Run the full model:
    ./coolsolve condenser_3zones.eescode
    It should converge. You can then delete condenser_3zones_simple.eescode and condenser_3zones_simple.initials; keep the updated condenser_3zones.initials.

Alternative: If fixing one variable is not enough, try fixing zone fractions (e.g. alpha_cd_sh, alpha_cd_tp) or other coupling variables. The aim is to shrink the algebraic loop so the simplified model solves, giving you good initials for the full model.

Dynamic (INTEGRAL) Models

Equation-based dynamic models (containing an INTEGRAL(...) call) take a different code path: CoolSolve time-marches the state variables and re-solves the algebraic subsystem at every step. See the Language Reference §12 for the syntax. When such a model fails or behaves oddly, start in debug mode:

./coolsolve -d integral_model.eescode

The debug folder gains two extra files for these models:

File Use for diagnosis
integral.md Problem summary: state vs algebraic variables, integration variable, interval, chosen method, step count, min/avg/max accepted step, rejected-step count, evaluations of the right-hand side, and a trajectory preview
integral_table.csv Full trajectory (integration variable first, then the $IntegralTable columns)

Common integration failures

"The integration stopped at … before reaching the upper limit" (integralMaxSteps). Only an adaptive run (RK45, BDF) can end this way: it did not reach the upper limit within its budget of attempted steps (accepted + rejected): 4 for each of integralMaxSteps, or for each of the (hi−lo)/step steps of the INTEGRAL call when there are more. A fixed-step method always takes (hi−lo)/step steps (the step of the INTEGRAL call, else integralFixedStep, else integralMaxSteps equal steps), so a long interval with a small step is not an error — it only takes time. Typical causes: the step size collapsed (RK45 rejecting many steps on a stiff system, or following a switch on a state, see below), or the budget is small for the interval. Fixes:

  • For RK45 on a stiff system: use integralMethod = BDF, with integralRelTol / integralAbsTol set to the accuracy needed (1e-4 / 1e-6 keeps the temperatures of the greenhouse models of the library within 0.03 K, see Dynamic Solving §2.3).
  • Raise integralMaxSteps, or loosen the tolerances.
  • Use a fixed-step method with the step in the model (5th INTEGRAL argument) or integralFixedStep: the step count is then (tf−t0)/step whatever integralMaxSteps says.

"Algebraic solve failed at t=… — The step h = … may be too large for RK4". With a fixed-step explicit method (RK4, EulerExplicit) a step above the stability limit of the model (set by its fastest dynamics) makes the states grow from step to step until an algebraic block can no longer be solved (a LineSearchFailed on a residual of 1E+40, a property call out of range). Reduce the step of the INTEGRAL call (or integralFixedStep), or use BDF, which adapts its step and is stable on stiff models.

"EulerImplicit: the iteration of the step from t = … to … did not converge". The Newton iteration that gives the state at the end of an implicit step did not converge, with the Jacobian of the previous steps, with one renewed at the predicted point, nor with one at every iterate (30 iterations); the message gives why and the largest residual of y_new − y − h·f(t+h, y_new). The step is not accepted, since its state would be off the trajectory: reduce the step, or use BDF, RK4 with a small step or RK45. A right-hand side that jumps with a state (an IF on a state variable) is the usual cause: the implicit step then has no solution.

"Step size dropped below minimum (…) at t=…: the last step was rejected because the Newton iteration …". BDF halved its step down to the minimum (the resolution of the integration variable, unless integralMinStep is set) and its implicit iteration still does not converge: the trajectory stays on a jump of the right-hand side with a state, as the intake IF(p - p_out, 0, m_dot) of examples/engine_weibe_cycle, where the pressure follows the outside pressure with a flow that switches on and off; there the implicit step has no solution however short it is. Use RK4, which steps across the switch (RK45 follows it with very short steps and needs a large integralMaxSteps), or write the switch as a continuous function of the state. Without such a reason (the steps were rejected by their error), the solution cannot be followed at the tolerances asked (a singularity, or integralMinStep set too large): loosen integralRelTol / integralAbsTol.

"The upper limit '…' of INTEGRAL() depends on the integration variable … or on a state". The limits and the step of INTEGRAL are read once, at the initial point: they may be variables or expressions of the model but must not depend on t or on a state. Compute them from parameters only.

$IntegralTable: '…' is not a variable of the model warning. A name of the directive matches no variable (check the spelling; separators are spaces, , and ;, case is ignored). Its column stays empty.

RK45 rejecting many steps. The rejectedSteps count in integral.md is high. The error estimate exceeds the tolerance repeatedly, so the controller shrinks h toward integralMinStep. This usually means the system is stiff for an explicit Runge–Kutta method. Use integralMethod = BDF (variable order, stable on stiff models), or fixed-step RK4 with a small step.

High-index DAE detected warning. A purely algebraic equation constrains a state variable without going through its derivative. This is emitted as a warning, not a hard error — legitimate index-1 thermal models routinely have state variables (e.g. temperatures) appearing in algebraic heat-transfer laws, so it does not by itself indicate a problem. It only matters if the algebraic subsystem is structurally non-square: then you see a separate squareness error, which means a true high-index constraint that needs index reduction (not yet supported — restructure the model so every state variable is defined through its derivative).

Inconsistent integration variable or limits. All INTEGRAL(...) calls in a model must share the same integration variable and the same [t0, tf] interval. CoolSolve rejects multi-interval / multi-variable integration with a clear message. The limits and the step may be constants, variables or expressions of the model, but must not depend on the integration variable or on a state (they are read once, at the initial point); calls with different limits are rejected.

Non-convergence of the algebraic subsystem at a step. If the per-step algebraic Solver fails (the same LineSearchFailed / MaxIterations errors covered in Steps 2–5 above), the march reports it. Apply the same initials/simplified-model workflow, noting that the algebraic variables must be well-conditioned at every step, not just the operating point.

Checking the result

Integral-declaring equations are skipped in the post-solve solution_check.md (their correctness is established by the trajectory). To sanity-check a result, compare the final tabulated value against a known analytical answer (the bundled integral_decay.eescode exercises y(t) = e^{-t}, giving y(4) ≈ 0.0183156), or inspect integral_table.csv for monotonicity / energy-balance trends.

Integral-specific pitfalls

Symptom Likely cause Workaround
The upper limit '…' of INTEGRAL() depends on the integration variable … A limit or the step uses t or a state (directly or through other equations) Compute the limit from parameters only
lookup table '…' not found (in PROCEDURE 'name') The table is not loaded: the message names the FUNCTION/PROCEDURE whose body made the call (none for the main program) Put <model>-<table>.csv next to the model file (or load the table in the GUI Lookup Tables tab); the table name is the part after the first hyphen
Unknown or unsupported function: IF with 5 arguments EES multi-threshold IF Rewrite with nested 3-arg IF(cond, true, false) where cond > 0
Empty column in *-integral.csv and a $IntegralTable: '…' is not a variable of the model warning A name of the directive that matches no variable (typo, wrong array element) Fix the name; separators (space, ,, ;) and case do not matter
PROCEDURE / CALL fails at first step Procedure-output block in reduced algebraic subsystem Inline simple outputs, or debug with -d and integral.md

Summary Checklist

  • Run with -d to generate debug output
  • Identify error type and failing block from solver_errors.md, report.md
  • Inspect solver_trace.md, evaluator.md, coolsolve_residuals.md
  • Check .initials and default values for unphysical guesses
  • Improve initials: fix missing/wrong values, or use simplified-model workflow (Step 5)
  • Fix unit mismatches (especially pressure) in procedures
  • Re-run full model with improved initials