Running Minuit in Fortran-callable mode.

The following Minuit subroutines are provided in order to allow the user to communicate with Minuit and perform all Minuit functions (define parameters, execute commands, etc.) directly from Fortran through subroutine calls. In the following list of subroutines, output arguments are indicated by appending a star * to its name. It should also be noted that for the Double Precision version of Minuit (recommended for all 32-bit machines such as IBM, Vax, Unix workstations, etc.), all the REAL arguments given below must be declared DOUBLE PRECISION.

Initialize Minuit

CALL MNINIT (IRD,IWR,ISAV)

Input parameters:

IRD

Unit number for input to Minuit.

IWR

Unit number for output from Minuit.

ISAV

Unit number for use of the SAVE command.

Specify a title for a problem

CALL MNSETI (CTITLE)

Input parameter:

CTITLE

Character string of up to 50 characters containing an identification text for the present job or fit.

Define a parameter, assigning values from variables

CALL MNPARM (NUM,CHNAM,STVAL,STEP,BND1,BND2,IERFLG*)

Input parameters:

NUM

Parameter number as referenced by user in FCN.

CHNAM

Character string of up to 10 characters containing the name which the user assigned to the given parameter.

STVAL

Starting value

STEP

Starting step size or approximate parameter error.

BND1

Lower bound (limit) on parameter value, if any (see below).

BND2

Upper bound (limit) on parameter value, if any (see below).

Output parameter:

IERFLG

Error return code: 0 if no error, >0 if request failed.

If BND1=BND2=0., then the parameter is considered unbounded, which is recommended unless limits are needed to make things behave well.

Define a parameter, assigning values from character string

Subroutine MNPARS defines a new (or redefines an old) parameter specifying values for its number, name, starting value, step size, and limits if any. All these values are given in one character string as if it was being read from the input stream. It can therefore be used in place of MNPARM if the character string format is more convenient than the calling sequence of MNPARM.

Calling sequence:

CALL MNPARS (CHSTR,ICONDN*)

Input parameter:

CHSTR

String specifies the parameter definition in the usual Minuit format, as on a data record (See 3.2.1). The fields are in the same order as the arguments to MNPARM

Output parameter:

ICONDN

Output condition

Possible values of output condition:

ICONDN=0

all OK

ICONDN=1

error, attempt to define parameter is ignored

ICONDN=2

end of parameter definitions (parameter number zero)

Example:

      CALL MNPARS(' 15  ''Lambda Mass''  1.2, 0.1' , ICONDN)

Execute a Minuit command

CALL MNEXCM (FCN,CHCOM,ARGLIS,NARG,IERFLG*,FUTIL)

Input parameters:

FCN

Name of the function being analyzed (to be declared EXTERNAL)

CHCOM

Character string containing the name of the Minuit command to be executed (see below).

ARGLIS

Array of dimension MAXARG, containing the numeric arguments to the command (if any),

NARG

Number of arguments specified (NARG$\leq$MAXARG),

FUTIL

Name of a function called by FCN (or =0 if not used). If used this function must be declared EXTERNAL.

Output parameter:

IERFLG

Error return code: 0 if the command was executed normally, >0 otherwise.

Executing a command by calling MNEXCM has exactly the same effect as reading the same command in data-driven mode, except that a few commands would make no sense and are not available in Fortran-callable mode (e.g. SET INPUT). The other difference is that control always returns to the calling routine from MNEXCM, even after commands END, EXIT, and STOP.

Execute a Minuit command specified as a character string

Subroutine MNCOMD causes the execution of the Minuit command specified as the second argument. It therefore works like MNEXCM, except that it accepts the entire command with arguments as one character string. This is more convenient in many cases and avoids problems of word length matching (DOUBLE PRECISION constants).

CALL MNCOMD (FCN,CHSTR,ICONDN*,FUTIL)

Input parameters:

FCN

Name of the function being analyzed (to be declared EXTERNAL)

CHSTR

The full Minuit command with arguments (CHARACTER)

FUTIL

Name of a function called by FCN (or =0 if not used). If used this function must be declared EXTERNAL.

Output parameter:

ICONDN

Error return code: 0 if the command was executed normally, >0 otherwise.

Some abnormal conditions:

ICONDN=1

command was blank, ignored

ICONDN=2

command line was unreadable, ignored

ICONDN=3

command was unknown, ignored

ICONDN=4

abnormal termination (e.g., MIGRAD not converged)

Get the current value of a parameter

This routine is the inverse of MNPARM and can for instance be used after a fit.

CALL MNPOUT (NUM,CHNAM*,VAL*,ERROR*,BND1*,BND2*,IVARBL*)

Input parameter:

NUM

Parameter number as referenced by user in FCN and about which information is required.

Output parameters:

CHNAM

Character string of up to 10 characters containing the name which the user assigned to the given parameter.

VAL

Current parameter value (fitted value if fit has converged),

ERROR

Current estimate of parameter uncertainty (or zero if constant)

BND1

Lower limit on parameter value, if any (otherwise zero).

BND2

Upper limit on parameter value, if any (otherwise zero).

IVARBL

Internal parameter number if parameter is variable, or zero if parameter is constant, or negative if parameter is undefined.

Get the current status of minimization

CALL MNSTAT (FMIN*,FEDM*,ERRDEF*,NPARI*,NPARX*,ISTAT*)

Output parameters:

FMIN

The best function value found so far

FEDM

The estimated vertical distance remaining to minimum

ERRDEF

The value of UP defining parameter uncertainties

NPARI

The number of currently variable parameters

NPARX

The highest (external) parameter number defined by user

ISTAT

A status integer indicating how good is the covariance matrix:

0

Not calculated at all

1

Diagonal approximation only, not accurate

2

Full matrix, but forced positive-definite

3

Full accurate covariance matrix (After MIGRAD, this is the indication of normal convergence.)

Get the current value of the covariance matrix

CALL MNEMAT (EMAT*,NDIM)

Input parameter:

NDIM

Integer variable specifying the number of rows and columns the suer has reserved in EMAT to store the matrix elements. NDIM should be at least as large as the number of parameters variable at the time of the call, otherwise the user will get only part of the full matrix.

Output parameter:

EMAT

Array declared as DIMENSION EMAT(NDIM,NDIM) which is to be filled with the (external) covariance matrix.

Access current parameter errors

CALL MNERRS (NUM,EPLUS*,EMINUS*,EPARAB*,GLOBCC*)

Input parameter:

NUM

Parameter number. If NUM>0, this is taken to be an external parameter number; if NUM<0, it is the negative of an internal parameter number.

Output parameters:

EPLUS

The positive MINOS error of parameter NUM.

EMINUS

The negative MINOS error (a negative number).

EPARAB

The ``parabolic'' parameter error, from the error matrix.

GLOBCC

The global correlation coefficient for parameter NUM. This is a number between zero and one which gives the correlation between parameter NUM and that linear combination of all other parameters which is most strongly correlated with NUM.

Note that this call does not cause the errors to be calculated, it merely returns the current existing values. If any of the requested values has not been calculated, or has been destroyed (for example, by a redefinition of parameter values) MNERRS returns a value of zero for that argument. Thus the call to MNERRS will normally follow the execution of commands MIGRAD, HESSE, MNContour, and/or MINOS.

Find a function contour with the MNContour method

CALL MNCONT (FCN,NUM1,NUM2,NPT,XPT*,YPT*,NFOUND*,FUTIL)

Input parameters:

FCN

Name of the function being treated (to be declared EXTERNAL)

NUM1/2

Parameter numbers with respect to which the contour is to be determined (external).

NPT

The number of points required on the contour (>4).

FUTIL

Name of a function called by FCN (or =0 if not used). If used this function must be declared EXTERNAL.

Output parameters:

XPT

Array of x-coordinates of contour points with values for parameter NUM1. It must be declared with a DIMENSION XPT(NPT).

YPT

Array of y-coordinates of contour points with values for parameter NUM2. It must be declared with a DIMENSION YPT(NPT).

NFOUND

The number of points actually found on the contour. If all goes well, this will be equal to NPT, but it can be negative (if the input arguments are not valid), or zero if less than four points have been found, or less than NPT if the program could not find NPT points.

Note that alternatively MNContour can be calculated by calling MNEXCM to issue the MNContour command, but then the user does not have Fortran access to the actual point coordinates XPT and YPT.

Switch to command-reading mode

This facility can be useful when one wants to continue interactively.

CALL MNINTR (FCN,FUTIL)

Input parameters:

FCN

Name of the function being treated (to be declared EXTERNAL)

FUTIL

Name of a function called by FCN (or =0 if not used). If used this function must be declared EXTERNAL.

The call to MNINTR will cause Minuit to read commands from the unit IRD (originally specified by the user in his call to MNINIT, IRD is usually 5 by default, which in turn is usually the terminal by default). Minuit then reads and executes commands until it encounters a command END, EXIT, RETurn, or STOP, or an end-of-file on input (or an unrecoverable error condition while reading or trying to execute a command), in which case control returns to the program which called MNINTR.

Set logical unit number for input

Sets logical unit number of input unit from which Minuit will read the next command.

CALL MNINPU (NUNIT, IERR*)

Input parameters:

NUNIT

The I/O unit number, which must be a valid unit, opened for reading (Minuit makes no checks at this level and will not attempt to open any files.)

IERR

returned as zero unless Minuit's internal buffer which stores unit numbers is full, which is a fatal error. If NUNIT is specified as zero, Minuit returns to reading the previous unit (which is why it has to store them).