HH (H → WW/ZZ/𝜏𝜏) → Multi-Leptons Analysis

Table of contents

• Introduction
• Installation (first time)
• Submodules Management Guide (Columnflow and cmsdb)
• Usage
• Useful links
• Contributors
• Development

Introduction

This is the code base for the Run2+Run3 iteration of the CMS HH Multileptons analysis.

The code is forked and for now heavily based on the UHH bersion of the HH → bb𝜏𝜏 analysis and still very much WIP. Expect remnants from the bb𝜏𝜏 analysis, crashes and bugs, you have been warned!

Please make sure you are subscribed to our e-group: cms-hh-multilepton@cern.ch It controls the acess to our indico etc. and is a good way to get updates for our meetings.

Also join our channel on mattermost. (You will need to join the CMS team first if not done so).

The code is currently developed with the Tallinn T2 (and lxplus) in mind. For further questions please, contact t****.l****@no-spam-cern.ch.

First time setup

# 1. fork then clone the project
git clone --recursive git@github.com:<your-github-user-name>/hhmultilepton2.git
cd hhmultilepton2

# 2. get a voms token
voms-proxy-init -voms cms -rfc -valid 196:00

# 3. copy the provided template to a new file (you can choose any <setup_name>):
cp .setups/template.sh .setups/<setup_name>.sh

# 4. open .setups/dev.sh in your editor and adjust any environment variables or paths as needed for your local setup.
# then source the main setup script with your custom setup name:
source setup.sh <setup_name> [sandbox_type]

source setup.sh --help
Arguments:
  <setup_name>     Name of the setup (random name of your choice)
  [sandbox_type]   Optional: choose between 'minimal' (default) or 'full'
Examples:
  source setup.sh dev            # uses 'minimal' environment from (sandboxes/venv_multilepton.sh)
  source setup.sh dev full       # uses 'full' environment from (sandboxes/venv_multilepton_dev.sh) 

Note: If you prefer not to use the provided template, you can still activate the environment manually by running: source setup.sh <setup_name> In this case, <setup_name> should not already exist under the .setups/ directory. When you run the command, the setup script will guide you interactively, prompting you to enter the required environment variables (as export commands). Once completed, these settings will be automatically saved to .setups/<setup_name>.sh.

Code can now be run but first storage locations for the tasks outputs should be checked as configured here. Currently outputs point to the user store of the T2_EE_Estonia on manivald so that outputs are also accessible remotely, but we will likely adapt this over time depending on the output. I.e large outputs available in a remote reachable location, smaller ones on local stores. Larger ones likely also split by user/cluster so that central versions can be reused. Can be configuered here.

Submodules Management Guide (Columnflow and cmsdb)

This directory contains submodules for the analysis framework, including columnflow and cmsdb. Note that columnflow itself has nested submodules (law and order).

modules/
├── columnflow/         # Main analysis framework
│   ├── law/            # Nested submodule
│   └── order/          # Nested submodule
└── cmsdb/              # CMS database utilities

Update All Submodules

Fetch and update all submodules to their latest upstream versions:

# Update all submodules recursively
git submodule update --remote --recursive

# Verify updates
git submodule status --recursive

Usage

1. Setup your enviorement (always):

voms-proxy-init -voms cms -rfc -valid 196:00

# source the setup and export env in the sorted file " .setups/dev.sh " in this case
source setup.sh dev

2. Try to run on 1 signal, 1 backgound and 1 data locally:

law run cf.PlotVariables1D \
    --version test \
    --producers default \
    --variables nmu \
    --datasets hh_ggf_htt_hvv_kl1_kt1_powheg,zz_pythia,data_e_c  \

3. And if the above run sucessfully, you can proceed to submit jobs via slurm/condor adding

    --workflow slurm \     # or
    --workflow htcondor \  # or
    --workflow crab \      # to be tested!?

Documentation

• Lives here: https://gitlab.cern.ch/hh-multileptons-full-analysis/hh-multileptons-doc
• Talks from most recent to oldest:
  • Higgs to leptons and rare decays meeting(14 Jan 2026)
  • HH roundtable session on the Run 3 analyses (Part 2) (6 Oct 2025)
  • Higgs to leptons and rare decays meeting (28 May 2025)
  • HH-Multilepton meeting (21 Aug 2025)

🙏 Contributors

Torben Lange 💻

Matheus Coelho 💻

Khawla Jaffel 💻

Useful links

• columnflow documentation
• CMS services:
  • HLT info browser
  • HLT config browser
  • GrASP
  • XSDB
  • DAS
  • NanoAOD documentation
  • Correctionlib files
• JME
• BTV
• Leptons:
  • Tau:
    • Run2 Twiki recommendation, Run3 Twiki recommendation
    • Correctionlib files
  • Muons:
    • Run3 HLT recommendation
  • Electrons:
    • Run3 HLT recommendation

Development

• Source hosted at GitHub
• Report issues, questions, feature requests on GitHub Issues
• Ideally also ping us on mattermost.
• For new features open a new branch before merging into master, ask for a code review by a felllow contributor and dont forget linting!
• Happy coding 😊