Skip to content

FLAF

FLAF — the Flexible LAW-based Analysis Framework — is the shared software framework behind several CMS Higgs-sector analyses at CERN. It turns CMS NanoAOD files into the analysis ntuples, histograms, plots and statistical results that go into a physics paper.

FLAF organises this work as a chain of tasks managed by LAW (the Luigi Analysis Workflow). You describe what you want (for example, "the final plots for the 2022 data"); LAW figures out which intermediate steps are needed, runs only those, and can dispatch them to the CERN HTCondor batch system or to the grid through CRAB.

New here? You are in the right place.

These docs assume no prior experience with LAW, Luigi or batch computing. If your background is physics rather than software engineering, start with Key terms and the Getting started track — every concept is introduced from scratch.

The big picture

FLAF is shared by three analyses — HH→bb̄ττ, HH→bb̄WW and H→μμ — which all run the same pipeline. From CMS NanoAOD to final results, the stages are:

flowchart TD
    NANO[("CMS NanoAOD<br/>(Rucio datasets or skims on storage)")] --> IFT["InputFileTask<br/>resolve the file lists"]
    IFT --> ATF["AnaTupleFileTask<br/>produce analysis ntuples, one per file"]
    ATF --> ATM["AnaTupleMergeTask<br/>merge into larger files, normalise MC"]
    ATM --> HTP["HistTupleProducerTask<br/>compute analysis observables"]
    HTP --> HFN["HistFromNtupleProducerTask<br/>fill histograms"]
    HFN --> HM["HistMergerTask<br/>merge histograms per variable"]
    HM --> HP["HistPlotTask<br/>make plots"]
    HM --> STAT["Statistical inference<br/>datacards, limits, pulls & impacts"]

Each box below the NanoAOD input is a LAW task, except statistical inference, which comes from the StatInference and inference submodules of the HH analyses. The picture leaves out the helpers that LAW schedules in between: AnaTupleCostProbeTask (measures the per-event cost before production), AnaTupleFileListBuilderTask / AnaTupleFileListTask (plan the merge) and AnalysisCacheTask / AnalysisCacheAggregationTask (run payload producers such as DNNs, and combine their outputs per dataset where needed, before HistTupleProducerTask); PreHistTupleProductionTask is an extra entry point that runs the whole production up to the caches in one go. You normally run only the last task you care about — LAW pulls in everything upstream automatically. The whole pipeline is explained step by step in the full-workflow walkthrough and on the Data flow page.

How to read these docs

The documentation is organised so you can enter at the level you need.

What FLAF is — and is not

  • FLAF is a framework, not an analysis. It lives in the cms-flaf/FLAF repository and is included as a git submodule inside each analysis repository. You never clone FLAF on its own to run an analysis — you clone an analysis repository (which brings FLAF with it). See Architecture and Installation.
  • FLAF provides the common machinery: the task definitions, the configuration system, the environment setup, the storage abstraction and the CI. The physics specifics (which signals, which observables, which categories) live in each analysis repository and are documented there — see Analyses.

Getting help

  • Something went wrong? Check Troubleshooting first — it collects the most common pitfalls and their fixes.
  • An unfamiliar word? The Glossary translates framework vocabulary into analyst terms.
  • Found a docs problem? Use the edit icon on any page to open a pull request, or open an issue on GitHub.