A user function

The calling sequences for the four subroutines required to create a user component are:

      SUBROUTINE UINFO(IPAR, CNAME, NPAR)
      INTEGER   IPAR, NPAR
      CHARACTER CNAME*(*)
C---
C IPAR    I    The parameter number.
C CNAME     O  The name of the parameter IPAR.  Note if IPAR=0, then
C              -return the name of the model.
C NPAR      O  The number of parameters in your user model.
C---
C*********
      SUBROUTINE ULIMIT(PVAL, PLIM, NT, NPAR)
      REAL      PVAL(*), PLIM(3,*)
      INTEGER   NT, NPAR
C---
C PVAL(*)   I/O  The current parameter values
C PLIM(1,*) I    If <0 then the corresponding parameter is frozen
C NT        I    Pointer to first parameter value in array PVAL(*)
C NPAR      I    Number of parameters
C---
C*********
      REAL FUNCTION UFNY(X, PVAL, NT, NPAR)
      REAL      X, PVAL(*)
      INTEGER   NT, NPAR
C---
C X       I    The current X value
C PVAL    I    The current parameter values
C NT      I    Pointer to first parameter value in array PVAL(*)
C NPAR    I    Number of parameters
C---
C*********
      SUBROUTINE UDERIV(X, PVAL, PLIM, DERIV, NT, NPAR)
      REAL      X, PVAL(*), PLIM(3,*), DERIV(*)
      INTEGER   NT, NPAR
C---
C X       I    The current X value
C PVAL    I    The current parameter values
C PLIM    I    The constraints array
C DERIV     O  The calculated derivative
C NT      I    Pointer to first parameter value in array PVAL(*)
C NPAR    I    Number of parameters
C---

When FIT starts, it calls UINFO with IPAR set equal to 0 to get the name of the user component and the number of parameters. This component name will be included in the names of the built-in components, and therefore, should not match any existing component name (such as CONS, LINE, etc.) If the user component is selected, then UINFO will be called for each parameter to get the name of that parameter.

ULIMIT is always called after any parameter values have been changed and before UFNY is called. The purpose of ULIMIT is two-fold. First, it should check the parameter values in PVAL and adjust any that may cause a problem in UFNY (for example, if UFNY divides by a parameter value, then ULIMIT should ensure that the parameter does not equal zero). Second, ULIMIT can be used to set up any initial data that UFNY needs. Since, UFNY is often called many times with the same parameter set, this can result in a speedup. The parameter values are stored in PVAL(NT) to PVAL(NT+NPAR-1). The PLIM array contains SIG, PLO, and PHI. If PLIM(1,I) is less than zero, then that parameter is frozen and you should not adjust the parameter value. Also, if PLIM(2,I)<PLIM(3,I), then an effective range is active and you should not adjust a parameter outside that range.

UFNY is the function that actually calculates user component at location X with parameter values given by PVAL.

UDERIV should calculate the derivative of the UFNY function with respect to each parameter. The version contained in UFNYDEMO.FOR evaluates the derivative numerically and hence you may be able to use it without modification. If you use that method you should try to scale the problem so that parameter values are in the range .1-100, values outside this range work, but the convergence can be slower.

If PLIM(1,I)=-1 then that parameter is frozen and hence you do not need to calculate the derivative. If PLIM(1,I)<-1 then the parameter has been set equal to another parameter and you should calculate the derivative in the normal manner (the FIT routine assumes that the derivative has been correctly calculated).

If you able to compute the analytic derivative of your function with respect to the parameter values, then you should use it, as an accurate derivative can greatly improve the fitting process. NOTE, slow convergence is most often due to the derivative being incorrectly calculated. If you find that c² drops slowly, and that FIT is unable to precisely locate the minimum, then you should carefully check both your equations and the UDERIV implementation for typical errors, such as an incorrect sign.

Once you have a working function, you should test it in PLT. Use the MOdel ? command to see if your component is listed. If not make sure you have linked a new version, and that your are running that new version. Next define a model that is composed only of your new component, and enter a resonable set of parameters. Do not attempt to fit at this time, but rather just plot the data and model. Use the Fit Plot 200 command to ensure that the function is evaluated at 200 points over the visible range. Is the plotted function what you expected? If it is not then you should carefully examine your code.

Once the function is doing what you expect, then you can try to fit it. If certain parameter values can cause a program crash, then you should write a version of ULIMIT that prohibits these values.