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        sub my_function{
142           # the five variables input to the function to be minimized
143           # xval is an ndarray containing the current values of the parameters
144           my ($npar,$grad,$fval,$xval,$iflag) = @_;
145
146           # Here is code computing the value of the function
147           # and potentially also its gradient
148           # ......
149
150           # return the two variables. If no gradient is being computed
151           # just return the $grad that came as input
152           return ($fval, $grad);
153        }
154
155   mn_def_pars()
156       The function mn_def_pars() defines the initial values of the parameters
157       of the function to be minimized and the value of the initial steps
158       around these values that the minimizer will use for the first
159       variations of the parameters in the search for the minimum.  There are
160       several optional arguments. One allows assigning names to these
161       parameters which otherwise get names (Par_0, Par_1,....,Par_n) by
162       default. Another two arguments can give lower and upper bounds for the
163       parameters via two ndarrays. If the lower and upper bound for a given
164       parameter are both equal to 0 then the parameter is unbound. By default
165       these lower and upper bound ndarrays are set to  zeroes(n), where n is
166       the number of parameters, i.e. the parameters are unbound by default.
167
168       The function needs two input variables: an ndarray giving the initial
169       values of the parameters and another ndarray giving the initial steps.
170       An optional reference to a perl array with the  variable names can be
171       passed, as well as ndarrays with upper and lower bounds for the
172       parameters (see example below).
173
174       It returns an integer variable which is 0 upon success.
175
176       Usage:
177
178        $iflag = mn_def_pars($pars, $steps,{Names => \@names,
179                               Lower_bounds => $lbounds,
180                               Upper_bounds => $ubounds})
181
182       Example:
183
184        #initial parameter values
185        my $pars = pdl(2.5,3.0);
186
187        #steps
188        my $steps = pdl(0.3,0.5);
189
190        #parameter names
191        my @names = ('intercept','slope');
192
193        #use mn_def_pars with default parameter names (Par_0,Par_1,...)
194        my $iflag = mn_def_pars($pars,$steps);
195
196        #use of mn_def_pars explicitly specify parameter names
197        $iflag = mn_def_pars($pars,$steps,{Names => \@names});
198
199        # specify lower and upper bounds for the parameters.
200        # The example below leaves parameter 1 (intercept) unconstrained
201        # and constrains parameter 2 (slope) to be between 0 and 100
202        my $lbounds = pdl(0, 0);
203        my $ubounds = pdl(0, 100);
204
205        $iflag = mn_def_pars($pars,$steps,{Names => \@names,
206                               Lower_bounds => $lbounds,
207                               Upper_bounds => $ubounds}});
208
209        #same as above because $lbounds is by default zeroes(n)
210        $iflag = mn_def_pars($pars,$steps,{Names => \@names,
211                               Upper_bounds => $ubounds}});
212
213   mn_excm()
214       The function mn_excm() executes a Minuit command passed as a string.
215       The first argument is the command string and an optional second
216       argument is an ndarray with arguments to the command.  The available
217       commands are listed in Chapter 4 of the Minuit manual (see url below).
218
219       It returns an integer variable which is 0 upon success.
220
221       Usage:
222
223        $iflag = mn_excm($command_string, {$arglis})
224
225       Example:
226
227         #start a simplex minimization
228         my $iflag = mn_excm('simplex');
229
230         #same as above but specify the maximum allowed numbers of
231         #function calls in the minimization
232         my $arglist = pdl(1000);
233         $iflag = mn_excm('simplex',$arglist);
234
235         #start a migrad minimization
236         $iflag = mn_excm('migrad')
237
238         #set Minuit strategy in order to get the most reliable results
239         $arglist = pdl(2)
240         $iflag = mn_excm('set strategy',$arglist);
241
242         # each command can be specified by a minimal string that uniquely
243         # identifies it (see Chapter 4 of Minuit manual). The comannd above
244         # is equivalent to:
245         $iflag = mn_excm('set stra',$arglis);
246
247   mn_pout()
248       The function mn_pout() gets the current value of a parameter. It takes
249       as input the parameter number and returns an array with the parameter
250       value, the current estimate of its uncertainty (0 if parameter is
251       constant), lower bound on the parameter, if any (otherwise 0), upper
252       bound on the parameter, if any (otherwise 0), integer flag (which is
253       equal to the parameter number if variable, zero if the parameter is
254       constant and negative if parameter is not defined) and the parameter
255       name.
256
257       Usage:
258
259            ($val,$err,$bnd1,$bnd2,$ivarbl,$par_name) = mn_pout($par_number);
260
261   mn_stat()
262       The function mn_stat() gets the current status of the minimization.  It
263       returns an array with the best function value found so far, the
264       estimated vertical distance remaining to minimum, the value of UP
265       defining parameter uncertainties (default is 1), the number of
266       currently variable parameters, the highest parameter defined and an
267       integer flag indicating how good the covariance matrix is (0=not
268       calculated at all; 1=diagonal approximation, not accurate; 2=full
269       matrix, but forced positive definite; 3=full accurate matrix)
270
271       Usage:
272
273           ($fmin,$fedm,$errdef,$npari,$nparx,$istat) = mn_stat();
274
275   mn_emat()
276       The function mn_emat returns the covariance matrix as an ndarray.
277
278       Usage:
279
280         $emat = mn_emat();
281
282   mn_err()
283       The function mn_err() returns the current existing values for the error
284       in the fitted parameters. It returns an array with the positive error,
285       the negative error, the "parabolic" parameter error from the error
286       matrix and the global correlation coefficient, which is a number
287       between 0 and 1 which gives the correlation between the requested
288       parameter and that linear combination of all other parameters which is
289       most strongly correlated with it. Unless the command 'MINOS' has been
290       issued via the function mn_excm(), the first three values will be
291       equal.
292
293       Usage:
294
295         ($eplus,$eminus,$eparab,$globcc) = mn_err($par_number);
296
297   mn_contour()
298       The function mn_contour() finds contours of the function being
299       minimized with respect to two chosen parameters. The contour level is
300       given by F_min + UP, where F_min is the minimum of the function and UP
301       is the ERRordef specified by the user, or 1.0 by default (see Minuit
302       manual). The contour calculated by this function is dynamic, in the
303       sense that it represents the minimum of the function being minimized
304       with respect to all the other NPAR-2 parameters (if any).
305
306       The function takes as input the parameter numbers with respect to which
307       the contour is to be determined (two) and the number of points $npt
308       required on the contour (>4).  It returns an array with ndarrays
309       $xpt,$ypt containing the coordinates of the contour and a variable
310       $nfound indicating the number of points actually found in the contour.
311       If all goes well $nfound will be equal to $npt, but it can be negative
312       if the input arguments are not valid, zero if less than four points
313       have been found or <$npt if the program could not find $npt points.
314
315       Usage:
316
317         ($xpt,$ypt,$nfound) = mn_contour($par_number_1,$par_number_2,$npt)
318

AUTHOR

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

NAME

DESCRIPTION

SYNOPSIS

FUNCTIONS

SEE ALSO

AUTHOR