# How do I fix my model?

*This article is incomplete or needs expanding. Please help out by adding your comments.*

When you reach the stage of creating complex MODELs with ASCEND you will inevitably find that some models don't work as you would have wished. This fact can sometime present itself in the form of cryptic error messages. This page aims to clarify how some of these messages arise, what they mean, and how to *fix* your model in such cases.

## Contents

## Pivoting errors

- Pivoting errors arise when your NLA's jacobian matrix is singular. This happens as a result of multiply linearly dependent equations, which essentially means that you may have written the same equation twice, or expressions that are in some way redundant.
- Pivoting errors can also arise due to badly-initialised variables. This happens, for example, when attempting to solve for a temperature in a superheated region by varying an enthalpy value set with its initial guess in the saturation region: in that case, changing enthalpy causes no change in temperature, leading ASCEND to think that temperature is not related to enthalpy -- a pivoting problem.

## Structural singularity errors

- This kind of error means that, from the the way the variables are arranged in the particular relations present in your model, it is possible to see that a solution can not be determined.
- Check that you don't somehow have the same equation written twice in two different ways.
- Check for redundant mass conservations and energy conservation equations. This is an especially easy mistake to make when writing equations containing flow loops.

## Row rank deficiency

- For example: "System is row rank deficient (12 dependent equations)"
- This error arises during block decomposition of your model -- trying to figure out which equations will be used to solve which free variables.
- The error is saying that there are more equations than needed based on the number of equations.
- If you look at the incidence matrix for your system, there will be some unassigned relations at the bottom of the window. These are the 'redundant' equations. Maybe you inadvertently wrote equivalent versions of the same equations more than once. For example, if you have equations "a=b", "b=c" and "c=a" then the third equation is redundant and should be removed from your model.
- This issue could also arise when you have an error relating to conditional logic in your model, such as CASE or WHEN statements.
- Note that this error comes from a
*structural*rather than*numerical*analysis of the equations in your system.

## Failure to converge

- Make sure your model is 'square' first of all. If the number of unknowns does not match the number of equations, ASCEND's solvers like QRSlv may still attempt to proceed with an under/overspecified problem, but that is almost always
*not*what you want. Get the problem square first, by FIXing or FREEing more variables to get it right. - A model that does not converge may be simply a wrong model. Check that your equations all makes sense first of all.
- Make sure you initialise your variables to have variables within the ballpark of the values you expect for their solution (see METHODs and default_self) This can be especially important when your problem has non-smooth equations such as thermodynamic property relationship eg T(p,h).
- Sometimes you may need to adjust solver parameters.
- For example, some models need to use the QRSlv 'RELNOMSCALE' option, instead of 'ABSOLUTE' scaling. An alternative strategy in such cases is to change the nominal value of variables in your model. The GUI can be used to identify badly-scaled variables.
- If your model doesn't converge before reaching the iteration limit you can try using the QRSlv 'iterationlimit' option. The default iteration limit should be OK in most cases, though, and if your model needs a lot more iterations then it might be an indication that there is a better way to expression your problem, so consider that as well.

- Try applying some manual scaling to variables far from their nominal values.
- Make sure you're using the right kind of solver. You should use an NLA solver for NLA problems, optimisation solvers, for optimisation problems, and so on.
- Try to write your equations in terms of multiplication operations rather than division operations. This generally improves the numerical behaviour.
- Try to write your equations in forms that are applicable over the full range of real numbers. For example, it try to use 'exp' functions instead of 'log' functions.
- Try rerranging your equations into another form.
- Sometimes failing to provide suitable uper and lower bounds to your variables will lead the solver to get 'off track'. See also below.

## zbrent: root must be bracketed

This error arises when QRSlv attempts to use the Brent algorithm, which requires initial (upper and lower bound values) either side of the solution to the equation. ASCEND only attempts to use Brent algorithm when a block contains only a single equation and it can't be directly (algebraicly) solver using the 'direct solve' routine in ASCEND (which is fairly simplistic, actually).

In these cases the problem is often resolved by setting suitable upper_bound and lower_bound for the unknown variable in the equation causing the problems. The Diagnose tool can be used to identify that variable.

One case where it's possible to be surprised by this error is when you have trigonometric functions like 'sin' and 'cos'. In such cases, the Brent solver can still fail, if it just happens that the upper and lower bounds on your angle variable fail to bracket the root. A smaller angular range will help to fix the problem.

## Function range error

- If you receive errors/warnings like "Function range error" and/or "pow_d0: -0.111803 raised to power 0.7 undefined: returning 0.215" then ASCEND is warning you that evaluation of certain functions in your model are causing range errors. For example, one can not calculate the square root of negative numbers (in ASCEND: there is no support for complex numbers). There are some so-called "safe-mode" functions that provide numerically sensible behaviour in these cases that can still sometimes allow the solver to 'find its way home', however this doesn't always work. In those cases, the problem can be resolved by looking at which variables and functions (
`X^Y`,`sqrt`,`ln`, etc) could be causing the problem, and set upper and/or lower bounds for that variable such that ASCEND doesn't set those variables in invalid regions. - Often these problems can be avoided by using physically meaningful variable declarations. For example "
`T IS_A temperature`" will automatically given you a variable whose lower bound is set to zero. - Use
`upper_bound`and`lower_bound`statements in your METHODS to make such initialisations permanent, but you can test using the PyGTK GUI by right-clicking a variable and manually setting the bounds, then attempting to re-solve.

## 'catch_Word_model'

- If you see this error when trying to load your model in ASCEND, it usually means you have made a serious syntax error. A good way to fix such errors is to pare your model back to basics, and then to gradually add bits back again until you see identify the cause of the problem.
- Occasionally, it seems that this error messages goes away simply by reloading your model file (ctrl-F5 in PyGTK GUI). This is probably a bug.
- This error message's name comes from an early attempt in the ASCEND code to give users a helpful suggestion when they inadvertently entered their model into Microsoft Word instead of a text editor!

## Integer arithmetic

- Be careful that ASCEND assumes integer arithmetic if it encounters only integer variables. This means that
`(1/2)`= 0, but`(1.0/2)`= 0.5. It's easy to make mistakes with this!