PDL::Minuit(3pm)

1Minuit(3)             User Contributed Perl Documentation            Minuit(3)
2
3
4

NAME

6       PDL::Minuit -- a PDL interface to the Minuit library
7

DESCRIPTION

9       This package implements an interface to the Minuit minimization
10       routines (part of the CERN Library)
11

SYNOPSIS

13       A basic fit with Minuit will call three functions in this package.
14       First, a basic initialization is done with mn_init(). Then, the
15       parameters are defined via the function mn_def_pars(), which allows
16       setting upper and lower bounds. Then the function mn_excm() can be used
17       to issue many Minuit commands, including simplex and migrad
18       minimization algorithms (see Minuit manual for more details).
19
20       See the test file minuit.t in the test (t/) directory for a basic
21       example.
22

FUNCTIONS

24   mninit
25         Signature: (longlong a();longlong b(); longlong c())
26
27       info not available
28
29       mninit does not process bad values.  It will set the bad-value flag of
30       all output ndarrays if the flag is set for any of the input ndarrays.
31
32   mn_abre
33         Signature: (longlong l(); char* nombre; char* mode)
34
35       info not available
36
37       mn_abre does not process bad values.  It will set the bad-value flag of
38       all output ndarrays if the flag is set for any of the input ndarrays.
39
40   mn_cierra
41         Signature: (longlong l())
42
43       info not available
44
45       mn_cierra does not process bad values.  It will set the bad-value flag
46       of all output ndarrays if the flag is set for any of the input
47       ndarrays.
48
49   mnparm
50         Signature: (longlong a(); double b(); double c(); double d(); double e(); longlong [o] ia(); char* str)
51
52       info not available
53
54       mnparm does not process bad values.  It will set the bad-value flag of
55       all output ndarrays if the flag is set for any of the input ndarrays.
56
57   mnexcm
58         Signature: (double a(n); longlong ia(); longlong [o] ib(); char* str; SV* function; IV numelem)
59
60       info not available
61
62       mnexcm does not process bad values.  It will set the bad-value flag of
63       all output ndarrays if the flag is set for any of the input ndarrays.
64
65   mnpout
66         Signature: (longlong ia(); double [o] a(); double [o] b(); double [o] c(); double [o] d();longlong [o] ib(); SV* str)
67
68       info not available
69
70       mnpout does not process bad values.  It will set the bad-value flag of
71       all output ndarrays if the flag is set for any of the input ndarrays.
72
73   mnstat
74         Signature: (double [o] a(); double [o] b(); double [o] c(); longlong [o] ia(); longlong [o] ib(); longlong [o] ic())
75
76       info not available
77
78       mnstat does not process bad values.  It will set the bad-value flag of
79       all output ndarrays if the flag is set for any of the input ndarrays.
80
81   mnemat
82         Signature: (double [o] mat(n,n))
83
84       info not available
85
86       mnemat does not process bad values.  It will set the bad-value flag of
87       all output ndarrays if the flag is set for any of the input ndarrays.
88
89   mnerrs
90         Signature: (longlong ia(); double [o] a(); double [o] b(); double [o] c(); double [o] d())
91
92       info not available
93
94       mnerrs does not process bad values.  It will set the bad-value flag of
95       all output ndarrays if the flag is set for any of the input ndarrays.
96
97   mncont
98         Signature: (longlong ia(); longlong ib(); longlong ic(); double [o] a(n); double [o] b(n); longlong [o] id(); SV* function; IV numelem)
99
100       info not available
101
102       mncont does not process bad values.  It will set the bad-value flag of
103       all output ndarrays if the flag is set for any of the input ndarrays.
104
105   mn_init()
106       The function mn_init() does the basic initialization of the fit. The
107       first argument has to be a reference to the function to be minimized.
108       The function to be minimized has to receive five arguments
109       ($npar,$grad,$fval,$xval,$iflag). The first is the number of parameters
110       currently variable. The second is the gradient of the function (which
111       is not necessarily used, see the Minuit documentation). The third is
112       the current value of the function. The fourth is an ndarray with the
113       values of the parameters.  The fifth is an integer flag, which
114       indicates what the function is supposed to calculate. The function has
115       to return the  values ($fval,$grad), the function value and the
116       function gradient.
117
118       There are three optional arguments to mn_init(). By default, the output
119       of Minuit will come through STDOUT unless a filename $logfile is given
120       in the Log option. Note that this will mercilessly erase $logfile if it
121       already exists. Additionally, a title can be given to the fit by the
122       Title option, the default is 'Minuit Fit'. If the output is written to
123       a logfile, this is assigned Fortran unit number 88. If for whatever
124       reason you want to have control over the unit number that Fortran
125       associates to the logfile, you can pass the number through the Unit
126       option.
127
128       Usage:
129
130        mn_init($function_ref,{Log=>$logfile,Title=>$title,Unit=>$unit})
131
132       Example:
133
134        mn_init(\&my_function);
135
136        #same as above but outputting to a file 'log.out'.
137        #title for fit is 'My fit'
138        mn_init(\&my_function,
139                {Log => 'log.out', Title => 'My fit'});
140
141
142        sub my_function{
143           # the five variables input to the function to be minimized
144           # xval is an ndarray containing the current values of the parameters
145           my ($npar,$grad,$fval,$xval,$iflag) = @_;
146
147
148           # Here is code computing the value of the function
149           # and potentially also its gradient
150           # ......
151
152           # return the two variables. If no gradient is being computed
153           # just return the $grad that came as input
154           return ($fval, $grad);
155        }
156
157   mn_def_pars()
158       The function mn_def_pars() defines the initial values of the parameters
159       of the function to be minimized and the value of the initial steps
160       around these values that the minimizer will use for the first
161       variations of the parameters in the search for the minimum.  There are
162       several optional arguments. One allows assigning names to these
163       parameters which otherwise get names (Par_0, Par_1,....,Par_n) by
164       default. Another two arguments can give lower and upper bounds for the
165       parameters via two ndarrays. If the lower and upper bound for a given
166       parameter are both equal to 0 then the parameter is unbound. By default
167       these lower and upper bound ndarrays are set to  zeroes(n), where n is
168       the number of parameters, i.e. the parameters are unbound by default.
169
170       The function needs two input variables: an ndarray giving the initial
171       values of the parameters and another ndarray giving the initial steps.
172       An optional reference to a perl array with the  variable names can be
173       passed, as well as ndarrays with upper and lower bounds for the
174       parameters (see example below).
175
176       It returns an integer variable which is 0 upon success.
177
178       Usage:
179
180        $iflag = mn_def_pars($pars, $steps,{Names => \@names,
181                               Lower_bounds => $lbounds,
182                               Upper_bounds => $ubounds})
183
184       Example:
185
186        #initial parameter values
187        my $pars = pdl(2.5,3.0);
188
189        #steps
190        my $steps = pdl(0.3,0.5);
191
192        #parameter names
193        my @names = ('intercept','slope');
194
195        #use mn_def_pars with default parameter names (Par_0,Par_1,...)
196        my $iflag = mn_def_pars($pars,$steps);
197
198        #use of mn_def_pars explicitly specify parameter names
199        $iflag = mn_def_pars($pars,$steps,{Names => \@names});
200
201        # specify lower and upper bounds for the parameters.
202        # The example below leaves parameter 1 (intercept) unconstrained
203        # and constrains parameter 2 (slope) to be between 0 and 100
204        my $lbounds = pdl(0, 0);
205        my $ubounds = pdl(0, 100);
206
207        $iflag = mn_def_pars($pars,$steps,{Names => \@names,
208                               Lower_bounds => $lbounds,
209                               Upper_bounds => $ubounds}});
210
211        #same as above because $lbounds is by default zeroes(n)
212        $iflag = mn_def_pars($pars,$steps,{Names => \@names,
213                               Upper_bounds => $ubounds}});
214
215   mn_excm()
216       The function mn_excm() executes a Minuit command passed as a string.
217       The first argument is the command string and an optional second
218       argument is an ndarray with arguments to the command.  The available
219       commands are listed in Chapter 4 of the Minuit manual (see url below).
220
221       It returns an integer variable which is 0 upon success.
222
223       Usage:
224
225        $iflag = mn_excm($command_string, {$arglis})
226
227       Example:
228
229         #start a simplex minimization
230         my $iflag = mn_excm('simplex');
231
232         #same as above but specify the maximum allowed numbers of
233         #function calls in the minimization
234         my $arglist = pdl(1000);
235         $iflag = mn_excm('simplex',$arglist);
236
237         #start a migrad minimization
238         $iflag = mn_excm('migrad')
239
240         #set Minuit strategy in order to get the most reliable results
241         $arglist = pdl(2)
242         $iflag = mn_excm('set strategy',$arglist);
243
244         # each command can be specified by a minimal string that uniquely
245         # identifies it (see Chapter 4 of Minuit manual). The comannd above
246         # is equivalent to:
247         $iflag = mn_excm('set stra',$arglis);
248
249   mn_pout()
250       The function mn_pout() gets the current value of a parameter. It takes
251       as input the parameter number and returns an array with the parameter
252       value, the current estimate of its uncertainty (0 if parameter is
253       constant), lower bound on the parameter, if any (otherwise 0), upper
254       bound on the parameter, if any (otherwise 0), integer flag (which is
255       equal to the parameter number if variable, zero if the parameter is
256       constant and negative if parameter is not defined) and the parameter
257       name.
258
259       Usage:
260
261            ($val,$err,$bnd1,$bnd2,$ivarbl,$par_name) = mn_pout($par_number);
262
263   mn_stat()
264       The function mn_stat() gets the current status of the minimization.  It
265       returns an array with the best function value found so far, the
266       estimated vertical distance remaining to minimum, the value of UP
267       defining parameter uncertainties (default is 1), the number of
268       currently variable parameters, the highest parameter defined and an
269       integer flag indicating how good the covariance matrix is (0=not
270       calculated at all; 1=diagonal approximation, not accurate; 2=full
271       matrix, but forced positive definite; 3=full accurate matrix)
272
273       Usage:
274
275           ($fmin,$fedm,$errdef,$npari,$nparx,$istat) = mn_stat();
276
277   mn_emat()
278       The function mn_emat returns the covariance matrix as an ndarray.
279
280       Usage:
281
282         $emat = mn_emat();
283
284   mn_err()
285       The function mn_err() returns the current existing values for the error
286       in the fitted parameters. It returns an array with the positive error,
287       the negative error, the "parabolic" parameter error from the error
288       matrix and the global correlation coefficient, which is a number
289       between 0 and 1 which gives the correlation between the requested
290       parameter and that linear combination of all other parameters which is
291       most strongly correlated with it. Unless the command 'MINOS' has been
292       issued via the function mn_excm(), the first three values will be
293       equal.
294
295       Usage:
296
297         ($eplus,$eminus,$eparab,$globcc) = mn_err($par_number);
298
299   mn_contour()
300       The function mn_contour() finds contours of the function being
301       minimized with respect to two chosen parameters. The contour level is
302       given by F_min + UP, where F_min is the minimum of the function and UP
303       is the ERRordef specified by the user, or 1.0 by default (see Minuit
304       manual). The contour calculated by this function is dynamic, in the
305       sense that it represents the minimum of the function being minimized
306       with respect to all the other NPAR-2 parameters (if any).
307
308       The function takes as input the parameter numbers with respect to which
309       the contour is to be determined (two) and the number of points $npt
310       required on the contour (>4).  It returns an array with ndarrays
311       $xpt,$ypt containing the coordinates of the contour and a variable
312       $nfound indicating the number of points actually found in the contour.
313       If all goes well $nfound will be equal to $npt, but it can be negative
314       if the input arguments are not valid, zero if less than four points
315       have been found or <$npt if the program could not find $npt points.
316
317       Usage:
318
319         ($xpt,$ypt,$nfound) = mn_contour($par_number_1,$par_number_2,$npt)
320

AUTHOR

329       This file copyright (C) 2007 Andres Jordan <ajordan@eso.org>.  All
330       rights reserved. There is no warranty. You are allowed to redistribute
331       this software/documentation under certain conditions. For details, see
332       the file COPYING in the PDL distribution. If this file is separated
333       from the PDL distribution, the copyright notice should be included in
334       the file.
335
336
337
338perl v5.36.0                      2023-01-20                         Minuit(3)

NAME

DESCRIPTION

SYNOPSIS

FUNCTIONS

SEE ALSO

AUTHOR