eqSolve¶
Purpose¶
Solves a system of nonlinear equations.
Format¶

{ x, retcode } =
eqSolve
(&F, start)¶ Parameters:  &F (scalar) – a pointer to a procedure which computes the value at x of the equations to be solved and returns them in a column vector.
 start (Kx1 vector) – starting values.
Returns:  x (Kx1 vector) – solution.
 retcode (scalar) –
the return code:
1 Norm of the scaled function value is less than __Tol. x given is an approximate root of \(F(x)\) (unless __Tol is too large). 2 The scaled distance between the last two steps is less than the steptolerance (_eqs_StepTol). x may be an approximate root of \(F(x)\), but it is also possible that the algorithm is making very slow progress and is not near a root, or the steptolerance is too large. 3 The last global step failed to decrease norm2(F(x))
sufficiently; either x is close to a root of \(F(x)\) and no more accuracy is possible, or an incorrectly coded analytic Jacobian is being used, or the secant approximation to the Jacobian is inaccurate, or the steptolerance is too large.4 Iteration limit exceeded. 5 Five consecutive steps of maximum step length have been taken; either norm2(F(x))
asymptotes from above to a finite value in some direction or the maximum step length is too small.6 x seems to be an approximate local minimizer of norm2(F(x))
that is not a root of \(F(x)\). To find a root of \(F(x)\), restarteqSolvefrom()
a different region.
Global Input¶
The following are set by eqSolveSet:

\_eqs_JacobianProc
pointer to a procedure which computes the analytical Jacobian. By default,
eqSolve()
will compute the Jacobian numerically.

\_eqs_MaxIters
scalar, the maximum number of iterations. Default = 100.

\_eqs_StepTol
scalar, the step tolerance. Default = \(\_\_macheps^{\frac{2}{3}}\).

\_eqs_TypicalF
Kx1 vector of the typical \(F(x)\) values at a point not near a root, used for scaling. This becomes important when the magnitudes of the components of \(F(x)\) are expected to be very different. By default, function values are not scaled.

\_eqs_TypicalX
Kx1 vector of the typical magnitude of x, used for scaling. This becomes important when the magnitudes of the components of x are expected to be very different. By default, variable values are not scaled.

\_eqs_IterInfo
scalar, if nonzero, iteration information is printed. Default = 0.
The following are set by gausset()
:

\__Tol
scalar, the tolerance of the scalar function \(f = 0.5*\left\leftF(x)\right\right^2\) required to terminate the algorithm. Default = 1e5.

\__altnam
Kx1 character vector of alternate names to be used by the printed output. By default, the names
X1, X2, X3...
orX01, X02, X03...
(depending on how__vpad
is set) will be used.

\__output
scalar. If nonzero, final results are printed.

\__title
string, a custom title to be printed at the top of the iterations report. By default, only a generic title will be printed.

\__vpad
scalar. If
__altnam
is not set, variable names are automatically created. Two types of names can be created:0 Variable names are not padded to give them equal length. For example, X1, X2, ..., X10, ...
1 Variable names are padded with zeros to give them an equal number of characters. For example, X01, X02, ..., X10, ...
This is useful if you want the variable names to sort properly.
Examples¶
// Reset all eqSolve global variables
eqSolveSet();
// Procedure to compute nonlinear equations
proc (1) = f(x);
local f1, f2, f3;
// Function one
f1 = 3*x[1]^3 + 2*x[2]^2 + 5*x[3]  10;
// Function two
f2 = x[1]^3  3*x[2]^2 + x[3] + 5;
// Function three
f3 = 3*x[1]^3 + 2*x[2]^2  4*x[3];
retp(f1f2f3);
endp;
// Procedure to compute Jacobian
proc (1) = fjc(x);
local fjc1, fjc2, fjc3;
fjc1 = 9*x[1]^2 ~ 4*x[2] ~ 5;
fjc2 = 3*x[1]^2 ~ 6*x[2] ~ 1;
fjc3 = 9*x[1]^2 ~ 4*x[2] ~ 4;
retp(fjc1fjc2fjc3);
endp;
// Starting values
start = { 1, 12, 1 };
// Set pointer to Jacobian procedure
_eqs_JacobianProc = &fjc;
// Perform estimation and print report
{ x, tcode } = eqSolve(&f, start);
=========================================================
EqSolve Version 14.0.1
=========================================================
F(X) at final solution: 0.93699762

Termination Code = 1:
Norm of the scaled function value is less than __Tol;


VARIABLE START ROOTS F(ROOTS)

X1 1.00000 0.54144351 4.4175402e006
X2 12.00000 1.4085912 6.6263102e006
X3 1.00000 1.1111111 4.4175402e006

Remarks¶
The equation procedure should return a column vector containing the result for each equation. For example, consider a twoequation system given by:
proc (1) = f(var);
local x1, x2, eqns;
// Set x1
x1 = var[1];
// Set x2
x2 = var[2];
// Preallocate output vector
eqns = zeros(2,1);
// Equation 1
eqns[1] = x1^2 + x2^2  2;
// Equation 2
eqns[2] = exp(x11) + x2^3  2;
retp(eqns);
endp;
Note that the first equation in the system is contained in the first row of eqns
and the second equation is in the second row of eqns
.
Source¶
eqsolve.src