---------------------------------------------------------------------------

                                SOLVESYS 4.01

         Simultaneous Nonlinear Equations and Least Squares Solver
                            for the HP48G series

                     Copyright 1994-1998, Sune Bredahl


     This is a text conversion of the original HTML manual available at 
     http://www.student.dtu.dk/~c947086/hp48.html. This text version lacks
     screen shots and documentation updates present in the HTML manual.				
     

                        Disclaimers and Legal Issues
                         Version 4.01 Release Notes
                             What is SOLVESYS?
                               Installation
                                 Examples
                        Modifying Error Tolerances
                           Termination Messages
                         How to Contact the Author



---------------------------------------------------------------------------

DISCLAIMERS AND LEGAL ISSUES

---------------------------------------------------------------------------

     SOLVESYS.LIB AND THIS MANUAL ARE PRESENTED WITHOUT WARRANTIES,
     EXPRESSED OR IMPLIED. THE AUTHOR MAKES NO GUARANTEE AS TO THE
     FITNESS OF THIS SOFTWARE. SOLVESYS.LIB CAN BE COPIED FREELY
     PROVIDED THIS MANUAL IS DISTRIBUTED WITH IT. SOLVESYS.LIB MAY NOT
     BE USED FOR COMMERCIAL PURPOSES WITHOUT PERMISSION FROM THE
     AUTHOR.


---------------------------------------------------------------------------

VERSION 4.01 RELEASE NOTES

---------------------------------------------------------------------------

     The present library is a completely rewritten version of
     SOLVESYS. Since most of the interface has changed, I suggest you
     read the entire manual even if you're familiar with previous
     versions of the program.

     SOLVESYS now includes support for nonlinear least squares
     problems (overdetermined systems). The major application of this
     is datafitting, but SOLVESYS is not limited to this case.
     Underdetermined systems are now treated as an error to avoid
     "false" solutions (e.g. due to an unassigned constant)

     Two main features known from v3.1 and earlier releases have been
     removed; analytic derivatives (just wasn't worth it compared to
     the speed of numeric derivatives) and ranges for variables (too
     much overhead for little gain). Also there's no "complex number"
     switch in v4.0, but complex valued results are allowed if complex
     numbers are also given as start guesses.

     Two new error tolerances are available, one for the least squares
     case (cosine test) and a tolerance for the convergence of the
     iterate values. The latter applies to both zero finding and least
     squares.

     SOLVESYS 4.0 does not include a stack version of the solver. If
     you need this feature, you must stick to version 3.1.


---------------------------------------------------------------------------

VERSION 4.01 ADDENDUM

---------------------------------------------------------------------------

     SOLVESYS 4.01 (released January 11, 1998) fixes a bug in the v4.0 
     library: 

     Using the solver after "Too many unknowns" error will in certain 
     situations generate random errors or even cause a memory clear! More 
     precisely, the bug occurs if trying to solve a system with at least 
     one constant defined but still more unknowns than equations. This 
     correctly produces a "Too many unknowns" error but when trying to 
     solve the system again with altered variable definitions, SOLVESYS 
     returns some error or what is worse. Thanks to Carlos Hartwich for 
     reporting the bug. 

     Furthermore a change to the converge tests used by the solver has 
     been implemented. This should fix some potential convergence 
     problems for linear least-squares. This change causes the LSQ value 
     in the INFO box not be updated/computed until XTOL has been 
     satisfied.


---------------------------------------------------------------------------

WHAT IS SOLVESYS?

---------------------------------------------------------------------------

     SOLVESYS is an easy-to-use (I hope) graphical environment for
     solving systems of nonlinear equations and least squares
     problems. The library works exclusively on the HP48G/GX series
     and is less than 4 kb in size.

     SOLVESYS is designed to solve sets of m linear or nonlinear
     equations in n unknowns. Generally, any kind of equations are
     acceptable but due to the efficiency of the solver, the most
     linear representation of an equation is always preferable.

     When m=n, the problem is obviously to zero all equations. If m>n,
     the equations are generally inconsistent so instead SOLVESYS
     searches for a least squares solution, i.e. the minimizer of the
     sum of squared equation deviations. Least squares solving is
     commonly used in datafitting applications. The case n>m is
     subject to error.

     Systems of nonlinear equations must be solved iteratively, i.e.
     the user must guess an approximate root from which the solver
     obtains a next approximation which again is used as an
     approximation and so on. The bad thing is that if you don't know
     what the answer looks like, you may have to try out many
     different starting guesses before the solver succeeds. On the
     other hand, if you can provide decent starting values, you'll be
     rewarded. In fact, if the initial guesses are very good, a system
     of nonlinear equations can be solved in the same time as a system
     of linear equations!

     SOLVESYS is based on a globally convergent modification of the
     multidimensional Newton-Raphson method. The original source for
     this is Dennis and Schnabel [1] and is also well described in
     Press et al. [2]. For nonlinear least-squares problems, this
     extends to a damped Gauss-Newton method.

     [1] Dennis, J.E., and Schnabel, R.B. 1983, Numerical Methods for
     Unconstrained Optimization and Nonlinear Equations (Englewood
     Cliffs, NJ: Prentice-Hall).
     [2] Press, W.H. et al. 1992, Numerical Recipes in C: The Art of
     Scientific Computing. 2nd ed. (Cambridge: University Press).



---------------------------------------------------------------------------

INSTALLATION

---------------------------------------------------------------------------

     To install SOLVESYS on your HP48G/GX:

       1. Transfer SOLVESYS.LIB to the HP48G/GX.
       2. Recall the library to the stack and press n [STO], where n
          is the desired RAM port (0 if you have a HP48G). After
          storing the library, you can purge the original copy to save
          memory.
       3. Turn the HP48 off, then on. This adds SOLVESYS to your
          library menu.

     The checksum for SOLVESYS.LIB is # A20Ah, 3964.5 bytes.

     To remove SOLVESYS.LIB:

       1. Put the library ID (n: 1550) in the stack
       2. Execute the sequence: [DUP][DETACH][PURGE]

     If the HP48 gives an "Object in use" error at this point, press
     [ON]+[C] and repeat the above steps.

     To transfer SOLVESYS.LIB to another HP48G/GX:

       1. Put the library ID (n: 1550) in the stack and press [RCL].
       2. Store the returned library in any variable
       3. Transfer this variable to the other HP48 - use binary
          transfer.



---------------------------------------------------------------------------

EXAMPLES

---------------------------------------------------------------------------

     ZERO FINDING IN C^2
     
     The equations;

                          R=n+n^2+i*k*cos(n+i*k)-k^2
                        T=n+i*k*sin^2(n+i*k)-cos(n+i*k)

     should be solved for the complex valued variables (n,k) for given
     values of (R,T). In this example, we will use R=10 and T=3.

     When SOLVESYS is started (from the library menu) an equation set
     editor opens. Here's where you enter the equations to be solved
     (use [CLEAR] if some equations already appear here). Press [ADD]
     to enter the first equation 'R=N*(N+1)+K*(i*COS(N+i*K)-K)' and
     hit [ENTER]. Press [ADD] and enter the next equation
     'T=N+i*K*SQ(SIN(N+i*K))-COS(N+i*K)' and hit [ENTER]. 

     The equation set is ready so press [OK]. SOLVESYS now analyzes
     the equations for variables and displays the Current Values
     dialog box where guesses of the unknown variables must be
     provided. Since the unknown variables (n,k) are complex, we will
     try 1+i for both. The known variables R=10 and T=3 are assigned
     by placing the values in square brackets. 

     Press [SOLVE]. After a few iterations, a solution is found, Press
     [INFO] to get more information about this result.

     The values should be correct to 4 significant digits so we can
     use k=0.506+2.379i and n=2.357+0.310i.

     You can copy the current values to the stack using the [->STK]
     menukey. To quit, first press [ON] to return to the equation set
     editor and press [ON] again to exit.



     FITTING PRESSURE OBSERVATIONS

     A useful application of least squares solving is curvefitting
     where one is attempting to fit m observations to an expression of
     n unknown parameters for which the "best-fit" values are
     required. If each observation is inserted in the expression, the
     result is a system of m "observational" equations in n unknowns.
     The library utility FITEQ may be used to create this equation
     set. An example follows.

     The relationship between the measured pressure and temperature in
     saturated steam can be written as

                            Y=a*ALOG[b*T/(c+T)]+eY

      where Y is the measured pressure of the steam at various values
                      of a controllable temperature T
            a, b and c are unknown parameters (to be estimated)
      eY is a normally distributed measurement error (of Y) with mean
                           zero and variance v.

     The following data were collected.

     T: 0    10   20    30    40    50    60     70     80     85     90     95     100    105
     Y: 4.14 8.52 16.31 32.18 64.62 98.76 151.13 224.74 341.35 423.36 522.78 674.32 782.04 920.01

     Half the job in nonlinear least squares is to obtain some guesses
     of the parameters to solve for. In this example, the T=0 value in
     the first measurement causes a=4.14 in the regression equation so
     we can use this as a starting value. Furthermore by inserting
     a=4.14 in the next two "observational" equations we have;

                         8.52=4.14*ALOG[10*b/(c+10)]
                       16.31=4.14*ALOG[(20*b/(c+20)]

     Taking LOG on both sides of both equations and multiplying with
     (b+10) and (c+20) respectively gives;

                   (c+10)*LOG(8.52)=LOG(4.14)*(c+10)+10b
                  (c+20)*LOG(16.31)=LOG(4.14)*(c+20)+20b

     which are just two linear equations with the solution
     (b,c)=(5.93,179). Thus an initial guess such as (a,b,c)=(4,6,180)
     seems reasonable.

     Now we're ready to solve the real problem. The utility FITEQ is
     used to create the 14 equations needed. First store the data as
     vectors (or lists) in global variables such as 'T' and 'Y' in the
     current directory. Then apply FITEQ with the arguments;

     3: 'Y(k)=A*ALOG(B*T(k)/(C+T(k)))'
     2: 'k'
     1: 14

     where the level 2 variable is the data index used in the level 3
     expression and level 1 is the number of observations. Make sure
     the variables { A B C } do not exist in the current or parent
     directories.

     When finished with FITEQ, start SOLVESYS and the equation set
     editor appears. The equations are already created so just press
     [OK] and fill in our initial guesses (a,b,c)=(4,6,180).

     Press [SOLVE] and a few iterations, the solver has found a
     minimizer. You can press [INFO] to get additional information about 
     the current result (see below for a description of these
     diagnostics).

     This tells us that the values should be correct to almost 5
     significant digits but we can do with less. If we use
     (a,b,c)=(5.27,8.56,295) then the best fit function is
     Y(T)=5.27*ALOG[8.56T/(295+T)].

     Since the rms error of the equations is 41.45, the error sum of
     squares (SSE) is 41.45^2=1718. The estimated variance v of the
     measurement error eY is SSE/(m-n)=1718/11=156.2.

     Be aware that the solver can't distinguish between a local or
     global minimum. This means that the choice of starting values is
     very crucial. Given poor starting values, the solver could just
     as well converge towards any of the local minima listed below
     (and there are even more!):

     (a,b,c)=(4.14,-168,1), eq=1603
     (a,b,c)=(4.14,infinity,-infinity), eq=1603
     (a,b,c)=(305,infinity,0), eq=1127
     (a,b,c)=(0,infinity,infinity), eq=1083

     A good initial guess is not only a real time-saver, it will also
     pick out the right (global) minimum for you.


---------------------------------------------------------------------------

ERROR TOLERANCES

---------------------------------------------------------------------------

     It's possible to modify certain error tolerances used by the
     solver although you should not meddle too much with the default
     values. In the Current Values dialog box, press the [TOL] menukey
     to open the Tolerance dialog box;

     XTOL:
          Tolerance for the relative change in the iterate values.
          XTOL is useful for nonlinear problems only and should be
          disabled (set XTOL=105 or so) for linear problems to make
          sure the solver exits after the first iteration (which is
          enough for linear problems). A value of 10-p basically
          corresponds to p significant digits of the computed result,
          but values of XTOL below 10-6 should not be trusted to
          comply with this. The default value is 10-3 corresponding to
          3 significant digits.
     EQTOL:
          Tolerance for the rms (root mean square) error of the
          equations. This is primary for zero finding but will also be
          used for zero-residual least squares problems. E.g. with
          {xy=9,x+y=6} the rms error at (x,y)=(2.9,3.1) is
          [(8,99-9)2+(6-6)2]= 0.01. EQTOL defaults to 10-5 which
          should be sufficient for most purposes.
     LSQTOL:
          Tolerance for a cosine test (Dennis & Schnabel) used for
          least squares problems. The test returns values between 0
          and 1 where a value close to 0 indicates a least squares
          minimizer. The cosine test is rather strict and will usually
          be close to 1 even near a minimum so I suggest using
          0.1>LSQTOL>0.001 and not lower. The default value is 0.01.
          You can disable this test with LSQTOL=1 so that only XTOL is
          used (which is normally sufficient for nonlinear least
          squares). LSQTOL does not apply to zero-residual least
          squares problems (EQTOL is used in this case).

     You can view the actual test values by pressing the [INFO]
     menukey in the Current Values dialog box.

     Note that the solver always iterates once before it checks for
     convergence so it's not necessary to change any of these
     tolerances in order to improve an existing solution.



---------------------------------------------------------------------------

TERMINATION MESSAGES

---------------------------------------------------------------------------

     Some (more or less) common error and termination messages
     returned by SOLVESYS are listed below.

     RETURN MESSAGES FROM THE SOLVER:

     Zero:
          A result satisfying EQTOL and XTOL was found.
     Minimum:
          A result satisfying LSQTOL and XTOL was found. It is not
          guaranteed to be a global minimum if several mimima exists.
     Bad Guess(es):
          This happens if the initial values provided are too far away
          from any solution. Typically this means convergence to a
          local minimizer of the sum of squared equation deviations.
     Non-Real Result:
          A complex valued result occurred although no complex initial
          values were provided. This is caused by a variable moving
          into a region where some equation do not evaluate to a real
          number, such as LN(X) for negative X. Either, you must
          provide better initial values or in simpler cases you can
          try to rearrange the equations to avoid any complex domain
          functions. Be aware that the HP48 power function (^) often
          is the culprit of these errors since it returns complex
          results for negative arguments raised to a non integer
          power. For example, the expression '(-1)^(1/3)' evaluates to
          a complex result instead of -1. You can fix this by
          replacing 'X^(a/b)' with 'XROOT(b,X^a)'.
     Undefined Result:
          (Math exception.) Calculation such as 0/0 occurred or the
          XROOT function was used with arguments that cannot give a
          real-valued result. In either case, try with other starting
          guesses.
     Infinite Result:
          (Math exception.) Calculation such as 1/0 occurred. Try with
          other starting guesses.

     INITIALIZATION ERRORS:

     All Variables Known:
          All variables were defined as constants (i.e. placed in
          square brackets).
     Too Many Unknowns:
          The number of unknowns is greater than the number of
          equations. Although the solver in principle can handle this
          situation too, a solution to such a system is unlikely to be
          of any interest.
     Constant?:
          At least one equation does not contain any unknowns.
     Inconsistent Units:
          Units are not supported. Note that SOLVESYS automatically
          strips off units for the CONST() function.

     FITEQ ERRORS:

     Invalid User Function:
          A referenced data variable (such as 'T' in the example
          above) does not contain a list or vector of data values.
     Bad Argument Value:
          The number of observations argument passed to FITEQ is
          greater than the number of observations present in at least
          one of the data vectors or lists.



---------------------------------------------------------------------------

HOW TO CONTACT THE AUTHOR

---------------------------------------------------------------------------

     Feel free to e-mail me if you have any comments, questions,
     problems or suggestions. Also if you find any bugs (or what you
     think is a bug), please notify me.

     Hope you like the program,

     Sune Bredahl
     c947086@student.dtu.dk or
     sune_bredahl@hotmail.com

     The latest version of SOLVESYS and other information regarding
     the program are available from:

     www.student.dtu.dk/~c947086/hp48.html
