Menu: General, Solver, XA Settings... (shown only when XA is the selected solver).
WARNING: This is an advanced feature. Changing these settings can make calculations fail or produce invalid results. There is no need to make changes unless you are seeing "Failure to solve" error messages during calculations.
The XA linear program solver has a number of internal settings that control how close to feasible a solution must be, how close to an integer an integer variable must be, how it guards against numerical trouble while it pivots, which simplex algorithm it runs, how long a single solve may take, and how it searches for an integer solution. WEAP normally leaves all of them at their defaults. This dialog lets an experienced user change them for the current area, to troubleshoot a calculation that ends with an XA "failure to solve" message, that is unusually slow, or that returns results that look numerically wrong.
Before you change anything
These settings change the arithmetic of every solve in every timestep, not just the one that failed. A setting that makes one timestep solve can shift every result slightly. Most failures to solve in WEAP come from the model itself (e.g., an input that is orders of magnitude off) and are better fixed there.
The settings serve two purposes. The first is diagnosis: finding out why a calculation fails, for example by turning on Relaxed to learn whether the integer variables are the cause, or by loosening a tolerance to learn whether XA is rejecting a solution that is feasible to within rounding. Once you know the cause and have fixed it in the model, return the settings to the defaults. The second is a cure: a setting that keeps the calculation from failing, for example a small loosening of a tolerance that removes the failures to solve without otherwise changing the results, or a different simplex algorithm that solves a large model in less time. Such a setting can stay in place.
Either way, change one setting at a time and note what it did. Before you keep a custom setting, compare the results with the default settings against the results with the custom settings, for the timesteps that did solve with both, to make sure the results have not changed significantly and are still valid (a script using the API below can run and compare the two calculations). Do not change settings on a model that is calculating without failures in the hope of improving it: it is far easier to make it worse.
The dialog
Use default values: the boxes show the default values, for reference, and cannot be edited. This is the normal state.
Set custom values: WEAP sends the values shown to XA each time it starts the solver. Switching back to the defaults keeps your custom values; they return when you choose custom again. A blank value means that setting is not sent, so XA keeps its own value (for the limits, that means no limit).
Reset to Defaults: puts every custom value back to its default. Available only when custom values are chosen.
When you press OK with custom values chosen, WEAP first sends them to a temporary XA solver and checks which ones XA accepts. XA rejects a value it considers unreasonable (return code 207) or a setting it does not know (205). Only accepted settings are sent to the real solver, and you are told which ones were refused.
The settings are saved with the area (in its Area.ini file), so they travel with the area and are not applied to other areas. Every change is recorded in the area's change history (the History tab), and a change that affects the solver marks the results for recalculation. While custom values are in use, the XA Settings... item on the Solver menu is checked, and Help, About (and every error report) lists the values that differ from the defaults. Settings made by a script (see "Scripting the settings" below) are saved the same way.
Feasibility tolerances
| Setting | Default | What it does and when to change it |
| Tolerance Primal | 1e-7 | A constraint violated by less than this amount counts as satisfied. Loosen it (for example to 1e-6) when XA reports infeasibility on a model you believe is feasible: XA may be rejecting a solution that is feasible to within rounding. Tightening it rarely helps. |
| Tolerance Dual | 1e-7 | A reduced cost smaller than this counts as zero, which is how XA decides that no further improvement is possible. Loosen it when XA cycles or runs to its iteration limit without declaring optimality. |
| Ltolerance, Utolerance | 5e-6, 5e-6 | How far below (L) or above (U) an integer an integer variable may be and still be accepted as that integer. WEAP uses integer variables for some constraints and allocations. When a calculation fails with an integer infeasibility, loosening these (for example to 1e-4) is the first thing to try. XA's manual warns that the accepted non-integer value is then used as it stands in the constraints and the objective. |
Numerical stability settings
These guard the simplex arithmetic itself. They matter when a model is badly scaled, for example flows in cubic metres per second alongside costs in billions, and XA reports a numerical error, loses feasibility after having found it, or gives different answers from one run to the next.
| Setting | Default | What it does and when to change it |
| Markowitz | 4 | Trades numerical stability against sparsity when XA factorizes the basis. 1 is the most stable and the slowest; large values (100, 1000) keep the factors sparse but can be unstable. Set it to 1 as the first experiment on a numerical failure. (XA stores and reports the reciprocal: 4 appears as 0.25 in XASettings.txt, see below.) |
| RejPivot | 1e-6 | The smallest pivot XA will accept before it looks for another entering column. XA's manual says that raising it, for example to 1e-4, improves numerical stability at the cost of a few more iterations. |
| Ypivot | 1e-10 | Marginal values smaller than this are rejected when choosing the column to leave the basis. Pivoting on very small values causes instability; raising this value avoids that, but raising it too far can make XA pivot into an infeasible basis. Change it only together with RejPivot and in small steps. |
| ReInvertFreq | 200 | How many pivots XA makes before it refactorizes the basis from scratch. Lowering it (50 or 100) throws away accumulated rounding error more often, which usually reduces the number of iterations on an unstable model, at the cost of more time per refactorization. |
| Scale | No | Whether XA scales the problem before solving: Yes scales rows and columns, 2 scales rows only, No does not scale. WEAP's copy of XA does not scale unless told to. Scaling normally helps a badly scaled model, but on some models it hurts; if a model fails, try Yes, then rows only. |
Simplex algorithm
These change the path XA takes to the optimum, not the optimum itself (for a well-posed problem). They are the settings to try when solves are slow or when XA stalls on a degenerate model.
| Setting | Default | What it does and when to change it |
| DualSimplex | No | No runs the primal simplex algorithm (what WEAP has always used), Yes the dual simplex. XA's manual says a model often solves significantly faster with one or the other, and that the dual usually wins when the solve starts from a previous basis. N2 and Y2 run both algorithms at once on a machine with two or more cores and take whichever finishes first (on a single core N2 runs the primal, Y2 the dual); this also acts as a fallback when one algorithm stalls. Try Yes, then N2, on a slow or time-limited model. (Results may differ in the last digits, because a degenerate problem can have more than one optimal solution.) |
| Crash | 0 | How XA builds the starting basis: 0 minimizes primal infeasibility, 1 minimizes dual infeasibility, 2 does both, 3 starts from an all-slack basis. A different starting point can route around a degenerate or numerically bad path. Try 3, then 1. |
| Pricing | 3 | The rule for choosing the entering column: 0 standard reduced-cost pricing, 1 automatic switch to DEVEX, 2 infeasible DEVEX, 3 feasible DEVEX, 4 both. Like Crash, a different rule can avoid a bad path; 0 is the simplest and a good first alternative. |
| Eliminate | Yes | Whether XA presolves the problem (removes redundant rows and columns and tightens bounds) before the simplex runs. No turns presolve off. A presolver can declare a problem infeasible on its own, so when XA reports infeasibility on a model you believe is feasible, try No: if the model then solves, the presolve is the problem. Expect slower solves with No, and possibly more integer infeasibilities, so return to Yes afterwards. |
Limits per solve
| Setting | Default | What it does and when to change it |
| TimeLimit | 30 | The most time, in seconds (or h:mm:ss), XA may spend on one solve, so that a solve that goes nowhere ends as a failure to solve instead of a frozen program. A very large model that genuinely needs longer can raise it (for example 120). When the limit is reached on an integer problem, XA returns the best integer solution found so far. Blank removes the limit. |
| Iteration | 2147483647 | The most simplex iterations XA may make in one solve; effectively unlimited by default. A limit (for example 100000) ends a cycling solve by iteration count instead of by time. |
Integer (branch and bound) settings
WEAP declares integer or binary variables for some constraints (for example a reservoir's maximum outflow constraint). When a model has many of them, XA's search for the best integer solution (branch and bound) can take most of the solve time or run into the time limit. These settings steer that search.
| Setting | Default | What it does and when to change it |
| Relaxed | No | Yes solves the problem as if every integer variable were continuous and stops there. A diagnostic: if a calculation that fails with an integer infeasibility succeeds with Relaxed Yes, the integer restrictions are the problem. Results computed with Relaxed Yes are not valid results. |
| Strategy | 1 | Which branch-and-bound strategy XA uses: 1 and 2 are XA's own methods (1 is the default), 3 minimum change in the objective, 4 column order, 6 the column closest to its integer bound, 7 always branch up, 8 always branch down, 9 the column farthest from its bound, 10 random. Adding A or B (for example 6B) makes XA spend less time estimating the value of each branch, which is faster but may not find the best integer solution. XA's manual suggests trying 1, 6 and 9 and the A and B variants when an integer problem is slow. |
| LimitSearch | (none) | Stops the search early at a good-enough integer solution. (5%) accepts the first integer solution within 5% of the best possible one; 5% (without the parentheses) searches only within 5% of the continuous optimum; a plain number is an absolute bound on the objective. XA's manual calls Strategy 1 or 6 with LimitSearch (5%) its generally good setting. Too tight a value can end with no integer solution at all. |
| StopAfter | (none) | Seconds (or h:mm:ss) XA keeps looking for a better integer solution after it has found the first one. StopAfter 10 returns a good solution within the time limit rather than running out of time while trying to prove it is the best. |
| StopUnchanged | (none) | Seconds XA keeps searching without finding a better integer solution before it stops and returns the best so far. The same idea as StopAfter, counted from the last improvement. |
| IBounds | 1 | The upper bound XA gives an integer variable that arrives with no upper bound. The default 1 silently turns such a variable into a binary one. If a user-defined integer LP variable without an upper bound seems stuck at 0 or 1, raise this (for example 1000), or better, give the variable an explicit upper bound. |
Suggested order
1. Integer infeasibility: loosen Ltolerance and Utolerance; confirm with
Relaxed Yes that the integer restrictions are the cause.
2. Infeasible or unbounded on a model you believe is fine: loosen Tolerance
Primal, then Tolerance Dual.
3. Numerical error, or feasibility lost after it was found: Markowitz 1,
then RejPivot 1e-4, then ReInvertFreq 100, then Scale Yes or 2.
4. Slow solves or time limit reached: DualSimplex Yes, then N2; then Crash
3 or Pricing 0; for a model with many integer variables, Strategy 6 or 9
and LimitSearch (5%), then StopAfter 10; raise TimeLimit as a last resort.
5. Whatever helped, look for the cause in the model. Return the settings
to the defaults once the model is fixed, or keep them if they cure the
failures and a comparison shows the results are otherwise unchanged.
Scripting the settings
The same settings can be read and changed from a script (VBScript, Python, ...) through WEAP's API, which makes it easy to calculate an area several times with different settings and compare the runs:
WEAP.XASetting("Name") reads or sets one setting by name
(Primal, Dual, Ltolerance, Utolerance, Markowitz, RejPivot, Ypivot, ReInvertFreq,
Scale, DualSimplex, Crash, Pricing, Eliminate, TimeLimit, Iteration, Relaxed,
Strategy, LimitSearch, StopAfter, StopUnchanged, IBounds), for example WEAP.XASetting("DualSimplex")
= "N2" or WEAP.XASetting("Markowitz") = 1. The value
is first tried on a temporary copy of XA; a value XA rejects raises an error
and is not saved. Setting a value turns custom settings on. Reading returns
the custom value, whether or not custom settings are on.
WEAP.XAUseCustomSettings (True or False) is the dialog's Default/Custom
choice.
WEAP.XAResetSettings puts every custom value back to its default.
Example (VBScript):
WEAP.XAResetSettings
WEAP.XAUseCustomSettings = True
WEAP.XASetting("DualSimplex") = "N2"
WEAP.XASetting("Markowitz") = 1
WEAP.Calculate
MsgBox WEAP.CalculationTime & " s, " & WEAP.NumLPFailures & " LP failures"
WEAP.XAUseCustomSettings = False
Python (pywin32) cannot assign to a call, so write WEAP.SetXASetting("DualSimplex", "N2").
Checking that XA is using the settings
WEAP records the settings it sent and XA's answer to each in the file Debug.txt in the Areas folder (lines beginning "XA:"), once each time an area is opened or the settings are changed.
Whenever the settings are active, WEAP also asks XA to print its complete parameter table to the file XASettings.txt in the area's folder, after any custom settings have been sent, so you can see the values XA is really holding. The file is written once each time an area is opened or the settings are changed. XA uses its own names for the settings:
| Setting | Line in XASettings.txt |
| Tolerance Primal | SET XTOZERO |
| Tolerance Dual | SET REDUCEDC |
| Ltolerance, Utolerance | SET LTOLERAN, SET UTOLERAN |
| Markowitz | SET MARKOWIT, shown as 1 divided by the value (4 appears as 0.25) |
| RejPivot | SET REJPIVOT |
| Ypivot | SET YPIVOT |
| ReInvertFreq | The second SET REINVERT line (the first is a different, internal setting) |
| Scale | SET SCALE: 0 = No, 1 = Yes, 2 = rows only |
| DualSimplex | SET DUALSIMP: NO or YES (N2 shows as NO and Y2 as YES; the two-core variants are not shown separately) |
| Crash, Pricing | SET CRASH, SET PRICING |
| Eliminate | Not shown (the PRESOLVE line does not change) |
| TimeLimit, Iteration | SET TIMELIMI (seconds), SET ITERATIO |
| Relaxed, Strategy | SET RELAXED, STRATEGY |
| LimitSearch | LIMITSEARCH (the line appears only once a value has been set) |
| StopAfter, StopUnchanged | STOPAFTE, STOPUNCH (seconds; 2000000001 means no limit) |
| IBounds | SET IBOUNDS |
If two calculations with different settings give identical results, that is not unusual for a small, well-scaled model: these settings only matter when a solve is close to the limits of double-precision arithmetic or has more than one optimal solution. Compare the XASettings.txt files from the two runs to confirm the settings differed.