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

AUTHOR

248       This file copyright (C) 2007 Andres Jordan <ajordan@eso.org>.  All
249       rights reserved. There is no warranty. You are allowed to redistribute
250       this software/documentation under certain conditions. For details, see
251       the file COPYING in the PDL distribution. If this file is separated
252       from the PDL distribution, the copyright notice should be included in
253       the file.
254

FUNCTIONS

256   mninit
257         Signature: (int a();int b(); int c())
258
259       info not available
260
261       mninit does not process bad values.  It will set the bad-value flag of
262       all output piddles if the flag is set for any of the input piddles.
263
264   mn_abre
265         Signature: (int l(); char* nombre; char* mode)
266
267       info not available
268
269       mn_abre does not process bad values.  It will set the bad-value flag of
270       all output piddles if the flag is set for any of the input piddles.
271
272   mn_cierra
273         Signature: (int l())
274
275       info not available
276
277       mn_cierra does not process bad values.  It will set the bad-value flag
278       of all output piddles if the flag is set for any of the input piddles.
279
280   mnparm
281         Signature: (int a(); double b(); double c(); double d(); double e(); int [o] ia(); char* str)
282
283       info not available
284
285       mnparm does not process bad values.  It will set the bad-value flag of
286       all output piddles if the flag is set for any of the input piddles.
287
288   mnexcm
289         Signature: (double a(n); int ia(); int [o] ib(); char* str; SV* funcion; int numelem)
290
291       info not available
292
293       mnexcm does not process bad values.  It will set the bad-value flag of
294       all output piddles if the flag is set for any of the input piddles.
295
296   mnpout
297         Signature: (int ia(); double [o] a(); double [o] b(); double [o] c(); double [o] d();int [o] ib(); SV* str)
298
299       info not available
300
301       mnpout does not process bad values.  It will set the bad-value flag of
302       all output piddles if the flag is set for any of the input piddles.
303
304   mnstat
305         Signature: (double [o] a(); double [o] b(); double [o] c(); int [o] ia(); int [o] ib(); int [o] ic())
306
307       info not available
308
309       mnstat does not process bad values.  It will set the bad-value flag of
310       all output piddles if the flag is set for any of the input piddles.
311
312   mnemat
313         Signature: (double [o] mat(n,n))
314
315       info not available
316
317       mnemat does not process bad values.  It will set the bad-value flag of
318       all output piddles if the flag is set for any of the input piddles.
319
320   mnerrs
321         Signature: (int ia(); double [o] a(); double [o] b(); double [o] c(); double [o] d())
322
323       info not available
324
325       mnerrs does not process bad values.  It will set the bad-value flag of
326       all output piddles if the flag is set for any of the input piddles.
327
328   mncont
329         Signature: (int ia(); int ib(); int ic(); double [o] a(n); double [o] b(n); int [o] id(); SV* funcion; int numelem)
330
331       info not available
332
333       mncont does not process bad values.  It will set the bad-value flag of
334       all output piddles if the flag is set for any of the input piddles.
335
336
337
338perl v5.12.3                      2011-03-31                         Minuit(3)

NAME

DESCRIPTION

SYNOPSIS

FUNCTIONS

SEE ALSO

AUTHOR

FUNCTIONS