# USERMOD: help and advice

Consult the reference manual for further details and worked examples.
W.G.Bardsley, University of Manchester, U.K.

Using standard mathematical notation

Note that, at any point in the model definition section of a user-defined-model file, expressions in standard mathematical notation can be used from version 7.1.6 onwards, as long as they start with the token begin{expression} and end with the token end{expression}. For instance, to define model f(1) as a cubic equation you could use the following.

    begin{expression}
    f(1) = p(1) + p(2)x + p(3)x^2 + p(4)x^3
    end{expression}

Examples illustrating this alternative technique using expressions can be viewed according to the following scheme.

    usermod1_e.tf1 is equivalent to usermod1.tf1
    usermod1_e.tf2 is equivalent to usermod1.tf2
    usermod1_e.tf3 is equivalent to usermod1.tf3, etc.

Details can be read in the file w_readme.f10 using the [View] option from the main Simfit menu, or from the [Summary of commands] option provided with this program.

Developing user defined mathematical models

This program accepts user defined models to:

1. check the format for correct syntax;
2. evaluate and check the order of stack operations;
3. plot one or many functions over prescribed ranges;
4. plot surfaces with functions of two variables;
5. estimate one- or multi-dimensional integrals;
6. locate a zero of a function between set limits;
7. find simultaneous zeros of n functions of n unknowns;
8. minimize a function with bounds on the variables; or
9. plot parametric equations: r(theta), [x(t),y(t)], etc.

The best way for you to develop your own models is to start by analysing one of the test files provided, using this program. Then, your own model can be developed by editing a starting default model file supplied, using your specified text editor. You are strongly advised to start by reading in the straight line model file usermod1.tf1, because you can easily check all the stack operations, plots, areas, zeros for yourself. Model files can be used by MAKDAT (for simulation), QNFIT (for curve fitting) or DEQSOL (for differential equations).

This program will only read in ASCII text model files that are formatted according to the SIMFIT user-model conventions.

- For 1 function of 1 variable ... see usermod1.tf?
- For 1 function of 2 variables ... see usermod2.tf?
- For 1 function of 3 variables ... see usermod3.tf?
- For scalar differential equations ... see usermodd.tf?
- For systems of n differential equations ... see deqmodn.tf?
  (where n = the number of equations, i.e. n = 1, 2, 3, etc.)
- For n functions of m variables ... see usermodn.tf?
- There are also many *.mod example model files
- When a model file is accepted the model name is displayed
  (otherwise an error message is issued so you can de-bug)
- You change parameters interactively or from data files
- As a model is evaluated the stack instructions are listed
- You can plot functions of 1,2 variables
- For 1 equation you can find zeros (roots) or integrate over a range.

More details of the SIMFIT user model file format can be found in the w_readme.f? files, the Simfit manual and the paper: Bardsley, W.G. and Prasad, N. Computers Chem. Vol 21, No. 2, pp. 71-82, 1997

Developing your own model files

First use one of the appropriate test files, to get the hang of things. Then read it into a text editor (or print) and imitate.

Evaluating a model
As the model is evaluated the successive stack instructions are displayed, with critical colour changes and error messages.

Plotting
Functions g(x,y) and one or n functions f(x) can be plotted and you can change the range, number of points, line-types, symbols or the mapping scheme. Up to 12 y(x) curves can be plotted, but you can choose which functions to assign to your y coordinates. This is valuable when you have a large number of equations, but only want to plot a chosen sub-set with selected symbols. To do this you just decide which f(x) to assign to the y(x) plotted.

Parameters p(i) and specified y(i,x) values in differential equations.
These can be set interactively or input from vector type files.

Zeros and integrals
With just one function of 1 variable you can find a zero of the model, i.e. a root of: y - f(x) = 0, in a chosen range, and you can also find the area under the curve (AUC) between limits.

Advice concerning one f(x)

Start by using usermod1.tf1 which is a straight line. Make sure you know how to evaluate, plot, find zeros and integrate. If your starting estimates for root finding give f(A) and f(B) of the same sign, the program will attempt to enlarge the interval (A,B), but it will not allow A or B to change sign. That is up to you. If the Simpsons rule integral is not close to the value from the adaptive quadrature you should investigate sub-ranges.

Advice concerning n functions f(x)

Start with usermodn.tf1 (4 trigonometric functions) to find out how to select y = f(x) to be plotted from a set of n functions.

Advice concerning g(x,y) and h(x,y,z)

Practise with the plane defined in usermod2.tf1 but note that this is not a good model to explore surface and contour plots. Program MAKDAT gives more control over plotting z = g(x,y). Try evaluating the plane h(x,y,z) defined in usermod3.tf1.

Advice concerning differential equations

This program only evaluates systems of n differential equations so you can check the stack operations. To integrate, plot and fit you should use program DEQSOL.

Advice concerning n functions of m variables

Such models are required when using program QNFIT to fit many functions at the same time to independent data sets. They are also required to find zeros of systems on n nonlinear equations in n unknowns by iterative procedures. If the maxmimum number of variables in the set is 3 you should define the variables as x, y and z in the usual way, but a special technique is needed for more than 3 variables.

What to do when m > 3

In this instance use y(1), y(2), ..., y(m) as the variables in the model file, just like using y(i) in the right hand sides of differential equations. You cannot use x, y, z notation at the same time as y(i) notation, and you only use y(i) when m > 3. Examine usermodn.tf1 (4 functions 1 variable), usermodn.tf2 (2 functions 2 variables), usermodn.tf3 (3 functions 3 variables) and usermodn.tf4 (9 functions 9 variables). Use the last three to see how to find zeros of n functions in n unknowns. You will need good starting estimates with usermodn.tf4, such as all the y(i) = 0 or all y(i) = -1 to get it to work. Study usermodn.tf4 carefully if you intend to use multifunction mode.

Editing parameters

This program initialises all parameters to defaults, but you will sometimes need to alter these defaults as now described.

p(i), where i = 1, 2, ..., number of parameters
The p(i) are set to 1 but you can change the values to check stack operation or alter the function definitions for plotting, root finding or integrating. Note that in differential eqns. the last n parameters are the initial conditions, y(i), where i = 1, 2, ..., number of equations (= number of variables) In this program the y(i) are used to provide starting estimates for finding zeros of n functions in n variables.

epsabs and epsrel
The default values for epsabs and epsrel should be satisfactory for absolute and relative error tolerances when locating zeros or estimating integrals by quadrature. However, with difficult root-finding problems, or multi-dimensional integrals it may be necessary to increase these values to achieve IFAIL = 0.

blim(i), tlim(i), where i = 1, 2, ..., m = number of variables
These are bottom and top limits for multidimensional integrals for n functions of m variables. Note that blim(i) =< tlim(i).

Bounds constrained quasi-Newton optimization

1. The model must have n + 1 equations for a function of n variables, f(1) being the function and f(2) to f(n + 1) the partial derivatives. Study test file optimum.mod for the Rosenbruck test function with 3 equations and 2 variables.
2. The number of limited memory corrections stored for the quasi-Newton hessian is MHESS, where 3 < MHESS =< 17.
3. FACTR should be about 1.0e12 for low precision, 1.0e7 for medium precision and 1.0e1 for extremely high precision.
4. Convergence will be presumed when (using absolute values) [F_k - F_{k+1}]/Max(F_k, F_{k+1}, 1) < FACTR*epsmch, or, Max(projected gradient(i)) <= PGTOL
5. The limits and starting estimates (xbot, xmid, xtop) can be set by editing the defaults or by reading in from a file.

The progress of optimization can be followed by setting IPRINT to print every IPRINT iterations, and by displaying the final gradient vector. However, usermod always creates w_usermod.err with LBFGSB messages and iterate.dat with iteration details. For a detailed analysis set IPRINT > 100, which causes all the optimization data to be written to w_usermod.err.