README.md

Introduction

This is the analysis code for the full Run-2 MET + s(bb) search for dark matter.

The aim is to implement CP recommendations and perform analysis selections to create histograms/trees from which final results are obtained. This code is based on XAMPPbase (XAMPP TWiki).

If this is your first time working with the XAMPP framework, have a look into the tutorial.

Setup

It is recommended to use the convenience wrapper scripts. They extract the installation/setup/update instructions from this README file and save you some error-prone typing or copying of commands.

Installing XAMPPmonoSbb (initial setup)

Start by setting up git and your kerberos credentials if on lxplus (NOTE : <USERNAME> is your personal username):

setupATLAS
lsetup git
kinit <USERNAME>@CERN.CH 

Next check out the code recursively to include the submodules (NOTE : This is using the ssh authentication URL, but you can use any of the https, ssh, or krb5, as you prefer):

# prepare shell by sourcing ATLAS local setup, set up git, create directory structure
source /cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/user/atlasLocalSetup.sh                           #!
lsetup git
mkdir analysis
cd analysis
# recursively clone analysis code with all submodules
git clone ssh://git@gitlab.cern.ch:7999/atlas-mpp-xampp/XAMPPmonoSbb.git --recursive source -b master
cd source
# set up ATLAS software (analysis release is specified in this line)
asetup AthAnalysis,$(grep FROM Dockerfile | cut -d : -f 2),centos7,here                                  #!
cd .. && mkdir -p build run                                                                           #!
# compile project
cd build                                                                                              #!
cmake ../source && make                                                                               #!
cd ../source                                                                                          #!
# export environment variables of project
source ../build/x86*/setup.sh                                                                         #!

The source folder will then act as your XAMPPmonoSbb project (all of this is defined by --recursive source) and includes the file .git of XAMPPmonoSbb. In this way you will keep the recommended structure of run source build (see https://twiki.cern.ch/twiki/bin/view/AtlasComputing/SoftwareTutorialxAODAnalysisInCMake). Note that in contrast to the example shown in the link the TestArea will be created in the top level directory analysis and not in the build directory analysis/build.

**Recommended install script:** you can also use the convenience install script. Follow these instructions instead:

# prepare shell by sourcing ATLAS local setup, set up git, create directory structure
source /cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/user/atlasLocalSetup.sh
lsetup git
mkdir analysis
cd analysis
# recursively clone analysis code with all submodules
git clone ssh://git@gitlab.cern.ch:7999/atlas-mpp-xampp/XAMPPmonoSbb.git --recursive source -b master
cd source
# execute install script
source XAMPPmonoH/scripts/install.sh

Setting up XAMPPmonoH (after initial setup)

After the initial setup, you can prepare your session by following these instructions:

# prepare shell by sourcing ATLAS local setup
cd analysis/source
# set up ATLAS software
source /cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/user/atlasLocalSetup.sh                           #=
asetup AthAnalysis,$(grep FROM Dockerfile | cut -d : -f 2),centos7,here                                  #=
# export environment variables of project
source ../build/x86*/setup.sh                                                                         #=

Recommended setup script: you can also use the convenience setup script. Follow these instructions instead:

cd analysis/source
source XAMPPmonoH/scripts/setup.sh

Submodules

This package uses submodules.

Running the Code

Interactive Jobs

An interactive job can be run using the runAthena.py script:

cd run/
python ../source/XAMPPmonoH/python/runAthena.py --jobOption XAMPPmonoH/runMonoH.py --testJob  --filesInput <MyInfile.root>

Where:

• --jobOption XAMPPmonoH/runMonoH.py is the used jobOptions file, in this case for the zero lepton analysis.
• --filesInput <MyInfile.root> is the input file, e.g.: root://eoshome.cern.ch//eos/user/x/xmonoh/ci/mc16_13TeV.410470.PhPy8EG_A14_ttbar_hdamp258p75_nonallhad.deriv.DAOD_EXOT24.e6337_e5984_s3126_r9364_r9315_p3563/DAOD_EXOT24.14183669._000678.pool.root.1

Grid Jobs

A single grid job (or multiple) can be submitted using the XAMPPbase/python/SubmitToGrid.py (XAMPPmonoH/python/SubmitToGrid.py) script. Before using this script, it is necessary to setup the proper grid authentication tools :

localSetupRucioClients 
localSetupPandaClient
voms-proxy-init -voms atlas

After this, you can use the script as (before: cd source):

python XAMPPbase/XAMPPbase/python/SubmitToGrid.py --jobOptions XAMPPmonoH/runMonoH.py -i <inputfile or list> --outDS <some name or version of output DS>

Or (this requires a list of samples, see for example this link):

python ${TestArea}/XAMPPmonoH/python/SubmitToGrid.py --jobOptions XAMPPmonoH/runMonoH.py --list <listToGrid.txt> --production <versionString> 

For more information about run arguments, do: python ${TestArea}/XAMPPbase/XAMPPbase/python/SubmitToGrid.py --help

Before launching a new production

Please have a look to the checklist!!!

There are also some tips and good practices for monitoring a grid production.

Bookkeeping

List of Samples

A full list of samples (data and MC) can be found here.

The derivation EXOT27 is used.

Creating new sample lists

To facilitate the error-prone task of creating new sample lists, a script can be used which checks the status of samples according to rucio and AMI and composes a sample list using a specified tag for the derivations.

To execute the script set up your TestArea first using asetup and set up panda, AMI and rucio while requesting a grid proxy.

localSetupRucioClients 
localSetupPandaClient
voms-proxy-init -voms atlas

Then execute the script using

python ${TestArea}/XAMPPmonoH/scripts/CreateSampleList.py

The necessary configuration settings are maintained in two files Sample list: XAMPPmonoH/data/samplelist.txt In this file all DSIDs of background processes considered in our search are documented together with a human-readable name. In addition in the same line as the DSID some options can be written to write the file to the list commented out or only be written to lists for certain derivations.

Configuration file: XAMPPmonoH/data/samplelist_config.json In this file the required derivations, rtags and ptags as well as other settings are configured.

Making Results

Produce a CutFlow

First, make sure you set SetupAlgorithm().RunCutFlow = True in your job options file.

To get the numbers printed on your screen:

cd run/
python ${TestArea}/XAMPPbase/XAMPPbase/python/printCutFlow.py -i <INPUTFILE generated above, e.g. MyOutFile.root> -a <ANALYSIS region, e.g. 0L_SR_Resolved or 0L_SR_Merged>

Tree Slimming

In order to reduce the ouput size of the trees two cuts are applied during the event selection (see here):

• MET trigger fired (0 lepton) or MET OR Single Muon Trigger fired (1 lepton)
• MET/METnoMu/pt(ll) > 150 GeV / 500 GeV (0 lepton / 1 lepton / 2 lepton), (resolved / merged)
• Lepton requirement (veto for 0 lepton, single muon for 1 lepton)
• 2 central small-R jets and 1 or more b-tags || 1 large-R jet
• tau and extended tau vetos
• mjj/mJ > 40 GeV

The tree slimming can be (de)activated by setting SetupMonoHAnaConfig().doProduction = True.

Development

Standard Development

If you would like to include your work in the codebase then we follow the

• Make a branch of XAMPPmonoH in the web browser : XAMPPmonoH/branches
• Clone the repository as you normally would
  • git clone --recursive ...
• Go into the repo and checkout the branch you will develop on
  • git checkout [YOUR_BRANCH]
• Develop as you normally would.
  • The submodules inside the project will not be affected.
  • You are compiling from the build/ directory so this will not affect the code you are developing in the top level XAMPPmonoH directory
• When you are finished developing on your branch commit and push the changes
  • git add FILES_TO_ADD
  • git commit FILES_TO_ADD -m "Descriptive commit message"
  • git push
• Go back to the branch browser (XAMPPmonoH/branches) and after verifying that your branch indeed does contain the changes you have made (look at the commit message), submit a merge request with the "Merge Request" button
  • At this point, the Continuous Integration job will be triggered by the .gitlab-ci.yml file
  • You can follow watch your CI job by following the link on the MR page
• If the CI job finishes successfully then your MR can be accepted by one of the responsibles for the project. Feel free to notify them on Mattermost/MonoHbb if they are not being responsive

If your development takes more than a few minutes, then it is likely that the branch from which you created your branch (the master branch) will have had changes made on top of it. It is necessary to incorporate these changes into your code before you submit your request or there will be conflicts. As such, during your development, if you know of such changes (perhaps by querying the commit log here then perform a pull to fold in these changes

• git pull origin master

Dependence Iteration

The XAMPP package depends on code from two main sources

• Athena Version : The athena release is the main codebase of ATLAS and the version currently being used can be found in the top level CMakeLists.txt file
• External Packages : These are included as submodules with a title like XAMPPbase@8a9e45a1 which itself is the base version of XAMPP framework.