MINT Tutorial

This tutorial is designed to demonstrate some of the MINT's basic features and how they can be applied to Dalitz fits using the MOJITO fitting tools.

Tutorial Contents

Getting Your Own Copy Of MINT 2

On lxplus - MINT is now available under the Gauss project. Simply enter getpack Gen/Mint in your preferred directory, choose the latest version if prompted. NOTE: Currently this is 'old' MINT, not MINT2. MINT2 is much better. Use the method below to get MINT2. Soon, we'll switch from MINT to MINT2 in Gauss (but we felt in Gauss, stability was more important than sophistication, so we kept MINT there while MINT2 was still under development and changing rapidly.)

Locally - You can check MINT2 out from svn using the command:

svn co https://svn.cern.ch/reps/lhcb/packages/trunk/Gen/Mint2

Checking the ROOT enviroment

On lxplus - enter SetupProject LHCb or a similar root dependent project, to configure your root enviroment.

Locally - download a copy of root from http://root.cern.ch/drupal/content/downloading-root, and follow the instructions given in the user's guide http://root.cern.ch/drupal/content/users-guide.

Getting Started

Start by taking a look in the Users folder which is found at /Gen/Mint/src/Users. Here you should create your own user folder, an example of which is provided in the directory. Simply type mkdir MyName to create a new directory and create another one within this directory by using mkdir MyName/MyTutorial. Copy across the ampFit.cpp and Makefile from the TutorialUser/MyTutorial folder. cp TutorialUser/MyTutorial/ampFit.cpp MyName/MyTutorial/ will do this for you. Choose the 4BodyModel.txt example in the MyTutorial folder and copy that across too. Now, go to your new project folder and type make -j 8 into the command line to compile the ampFit with the MINT and MOJITO libaries. This may take a minute.

Generating Some Monte Carlo

The .txt file is a standard input file for MINT. It contains the Amplitude Model in question, whether for generating MC or fitting a data set and certain variables for the fit. The ampFit and txt file provided will allow you to generate MC of a 4 body decay. Do this by typing ./ampFit < 4BodyModel.txt into the command line. MINT will generate a lot of output to the screen, it is ususally best to 'pipe' this to an output file, while detaching the the process with &, such as ./ampFit < 4BodyModel.txt > out.txt &

While this runs, take a look at the input file again. Various options are given, which should look like this:

"Phases given in" "degrees"

"Event Pattern" 421 -211 211 211 -211

"Nevents" 2000

"IntegPrecision" 1.0e-2

"IntegMethod" "efficient"

IntegratorSource "New"

*IntegratorInputFile "sgIntegrator"

*InputFileName "TutorialDataSample.root"

OutputRootFile "GeneratedMC.root"

The first option alows the user to switch between units of degrees and radians, for use in the declaring phases (see below). Event Pattern describes the decay process to be modelled, using pdg Id numbering. The first number corresponds to the parent, while the others are the final state daughters. Pdg values can be looked up online or found in the mass_widths.cvs file, located here: Mint/src/Mojito/ParticleProperties/src/mass_width.cvs. Nevents is the number of MC events we will generate. Integ Precision, Method, Source and Input File are used during the fit of a model to data and can be ignored for now. The Input File Name would be the name of a data sample to fit to, in the your user directory. Finally the Output Root File is the name to give your newly generated MC, as saved in .root file format. Within a .txt file, any line beginning with an * is ignored by MINT.

Named Parameters

All these options are called "Named Parameters" within MINT, and are fully customisable in the ampFit.cpp file. Lets introduce a simple switch, to turn on and off whether we save our MC. Open up the ampFit.cpp file, using emacs ampFit.cpp or any other text editor you prefer. Scroll or search for the ampFit function and you should see a series of NamedParameter declarations, many of these names should look familiar to you. Declare your own by adding a line like this:

NamedParameter<int> MCFileSave("MCFileSave",1);

By doing this we have achieved a few things. There is now an int type variable called MCFileSave that we can use in the ampFit() function, which has a default value of 1. However, we can now change the value of this int from the .txt file with the line:

MCFileSave 0

To make use of our new Named Parameter put an if statement around eventList.saveAsNtuple( OutputRootFile); so that it looks like:

if( MCFileSave ){

eventList.saveAsNtuple( OutputRootFile);

}

Once you're done, be sure to save your ampFit.cpp file and type make again in the command line.

MINT root file format

MINT has a specific structure to its root files, which allows it to read in and write event data in a uniform way. If your job has finished, you should see a new file called GeneratedMC.root in your directory. To look at the structure of the file, use root's built-in GUI by typing root -l to start a root session, followed by TBrowser x (any character string can replace the x) to launch it.

Click on the GeneratedMC.root file in the left hand coloumn and you will see something like the image above. A Mint ntuple contains a TTree (called DalitzEventList by default) with a series of brances detailing properties of the parent or daughter particles, these are numbered in the same order as the Event Pattern, seen in the options file. For each particle the pdg number, energy and momentum in x,y and z are stored. The naming system follows the sequence _number_particlename_Datatype . The particle name will be followed be either a 0, # or ~ to signify zero, positve or negative charge respectively. Datatype is either pdg, E, Px, Py or Pz to signify the storage of a pdg, energy or momentum value.

As MINT generates MC in the rest frame of the parent, the energy and momentum of the particle numbered zero, should have energy and momentum values of zero. If desired, MINT can generate MC with boosted parents.

Two further branches exist, weight, which allows reweighting by the user and genPdf. This records the value of the probability density function at the point in phase space that the event was generated, essentially, this retains information on the Model used to generate the dataset. When inputing data, this can be set to 1.

Fitting a Model to Data

Now lets use MINT to fit a data file. The ampFit.cpp you have is designed to generate MC quickly, you can turn this off by setting your Named Parameter to 0. There is fitting code, included in the file, but it has been commented out. Reverse this by deleting the /* and */ characters where you see them. Save the progress and type make again.

The sample root file can be found at /afs/cern.ch/work/j/jbenton/public/TutorialFiles , so copy it across. Uncomment the Input File Name option (remove the *) and ensure it names the new root file.

The TutorialFiles directory also contains a folder called sgIntegrator. This is a type of folder generated and used by MINT during fits. It essentially saves information of a particular model, which speeds up the fit to different data samples. The user has full control of the use and creation of these folders, but for now just copy this one into your MyTutorial directory. The ampfit program will look for it automatically.

Now run the ampFit as before with ./ampFit < 4BodyModel.txt > out.txt &

When your fit is finished, have a look at the output. The fit results are displayed in a table of fit fractions, toward the end of the output and look like this:

FRACTIONS:

^^^^^^^^^^

(1) D0->a(1)(1260)+(->rho(770)0(->pi+,pi-),pi+),pi- = 0.508108 +/- 0.0237427(fit) +/- 0.0047835(integ)

(2) D0->a(1)(1260)-(->rho(770)0(->pi-,pi+),pi-),pi+ = 0.370076 +/- 0.0188176(fit) +/- 0.00283202(integ)

(3) D0->rho(770)0(->pi+,pi-),rho(770)0(->pi+,pi-) = 0.190838 +/- 0.0173364(fit) +/- 0.00204818(integ)

To complement this table there is also a list of inteference terms directly below the total fractions, to help you apprectiate the complex contributions of the fit. You can also look at the final fit values of amplitude and phase, compared to the initial values in the .txt file model, under the header MinuitParameterSet::( FitResult - StartValue)/error .

Various plots should also appear in the directory. The datFit plots show projections of both the data (in blue) and a sample ditribution of the fit model (red line). This red line may appear 'jagged" due to insufficent statistics, which can be improved by requesting a higher precision or supplying more events (when independent efficency events are used). Matching the red line to the blue distribution generally indicates are good fit.

An Aside on sgIntegrator: Using the ampFit as given, the sgIntegrator folder would have been read before attempting the fit, or if it did not already exist, created afterward. If a different model is to be used, with components not already included the last time, the sgIntegrator will impede the fit process. You can either delete this folder using rm -r sgIntegrator or change the Integrator Input File option name. The saving of sgIntegrators can be switched off entirely in the ampFit.cpp file.

Fit Quality

Although you can visually inspect the fit plots, MINT is also capable of providing a quantitative measure of fit quality, the Chi squared per bin and Chi squqred per degree of freedom. Have another look at your ampFit, find the option bool doChi and set it equal to true, taking note of the filename passed to DiskResidentEventList chi2Events(""). Note, if you wanted to change there options frequently, you could do so more easily by making them Named Parameters as above.

Again make and run ampFit. This time the ampFit will look for the given file name, read in the events, reweight them based on the likelihood model fit and then calcualte a Chi square comparision to your data sample. This is why we pass the MC you generated earlier, which used the same basic model.

Once your fit is complete, the Chi Square per degree of freedom is reported at the bottom of the output.

Improving Our Model

Until now we have been using fixed models, but MINT allows the user to include a wide variety of components for fitting or generating. For a list of possible resonances look in the AllKnownDecayTrees.txt file in your directory, which is produced each time the ampFit is run.

Open the options file again and look at the list of components. Each has a name in quotation marks followed by a series of numbers. Lets look at the following example:

"D0->rho(770)0(->pi+,pi-),rho(770)0(->pi+,pi-)_Re" 0 0.058 0.05 0.0 0.0

"D0->rho(770)0(->pi+,pi-),rho(770)0(->pi+,pi-)_Im" 0 -0.100458947 0.05 0.0 0.0

As you can probably tell, this describes the decay of D0 to four pions via two rho(770) mesons. The _Re and _Im denote the real and imaginary componets of the wave function. Similarly we could have _Amp and _Phase with the Phase unit decided with the "Phases given in" option.

The first number shown is the fix value, which tells MINT to either float this component of the model (0) or fix it (2). The second is the initial value. This is either the value it is fixed to or the start position for an iterative fit. The final three control the iteration process and are the step change per iteration, the minimum and maximum boundaries repectively.

In a fit, it is good practice to fix at least one component (both the real and imaginary parts) as this aids in convergence. The choice of component is unimportant as the phase convention is arbitary.

MINT assumes the spin wave of the D0 is an S type, unless otherwise specified. Lets add a D-wave component to see if that improves the model. Copy the last component in your model and paste it again, below. Use square brackets at the end of the particle name to describe a different spin state and type a captial D so that it looks like this:

"D0[D]->rho(770)0(->..........."

Make sure to vary the numbers a little to distinguish this new component from the rest, but leave the fix value as 0.

There is another type of decay route that MINT can calulate, where the spin is constant but the daughter masses are non resonant. Effectively the daughters do not add consistently to the same mass. For these situations we can use the NonResV0 'particle', which we can eaily combine with other resonances, such as the f(2)(1270).

First, start with the parent "D0-> add the first resonance NonResV0 then whatever they decay into (->pi+,pi-). Seperate with a comma and add the remaining particles ,f(2)(1270)0(->pi+,pi-). Finish the name with either the _Re", _Im" or _Amp" and _Phase" identifiers. All together, the new decay component looks like:

"D0->NonResV0(->pi+,pi-),f(2)(1270)0(->pi+,pi-)_Re"

Fit the new Model to your sample and compare with you previous fit. Use both the Chi square per degree of freedom and the fit plots to make up your mind. The output has a lot of other valuable information too, including a covariance matrix to show any high correlations between components.

For more examples of what can be achieved with MINT, look in the ExampleUser folder for a variety of ampFit.cpp files and Model options.

Useful Links

An old copy of MINT can also be download from Jonas's webpage, http://www.phy.bris.ac.uk/people/rademacker_j/. This avoids the use of CERN computing credentials but is not updated as regularly as the svn and Gauss versions.

Other Tutorials

These are similar but complementary tutorials:

• Mint Tutorial 1 - introduction to MINT
• Mint Tutorial 2 - Introduction to MintDalitz/Mojito