[cburgard]

Important

Depends on #24005 (which depends on #24001). This branch is stacked on it: please review only the last 2 commits. It stays in draft until HS3 PR #147 is merged, and will be rebased when the PRs below it are merged.

Rebased onto master after 36821748060 ("Import and export through a typed representation of HS3 documents"). Where the commits conflicted with it, they were re-implemented on the typed HS3Document (parser, validator, writer) instead of the removed code; the messages of these commits say how ("Ported onto the typed HS3 document: …").

The first commit was part of #24005. HS3 moved category_conditional_dist and the categorical function from #119 to #147, so the ROOT side is split the same way.

This Pull request:

Reads and writes the HS3 category_conditional_dist of HS3 PR #147. It selects one of several sub-distributions by the value of categorical parameters and evaluates it conditioned on that value. This is the construction used for discrete profiling over alternative shape hypotheses.

It is read as a RooSimultaneous. RooSimultaneous and existing RooMultiPdf objects are written as category_conditional_dist. The penalty term of RooMultiPdf is dropped with a warning; how to represent it is the main open question, see below.

Changes or fixes:

1. category_conditional_dist ↔ RooSimultaneous

RooFit has this distribution as the "switch mode" of RooSimultaneous (since #23142). When its index category is not an observable, it evaluates to the component selected by the current state, and its expected number of events is the one of that component.

Direction	Change
Import	A category_conditional_dist becomes a RooSimultaneous over its categorical parameters, which must be declared by categorical axes of a domain.
Export	RooFit doesn't tell the two uses of a RooSimultaneous apart by the object, only by the normalization set. A combined distribution is the top-level pdf of a model, while a conditional one (e.g. a choice between alternative background shapes) is a building block of a model. So a RooSimultaneous that another pdf uses is written as category_conditional_dist, with categorical_parameter instead of columns. One that no other pdf uses is written as combined_dist, as before.
Import	A category_conditional_dist that no other distribution uses is read with a warning that it will be written back as a combined_dist. The pairing checks of a combined_dist with combined data in a likelihood use the type in the document.
Export	The value of a RooCategory in a snapshot is written to the parameter point as its label (categorical parameters), and the category is declared in the default domain. The columns of combined distributions are not parameters and are left out.

For the check of distinct variates of #24005 (section 8 there), a category_conditional_dist has the variates of its alternatives, which may share them: only one is selected. A RooSimultaneous that no other pdf uses is written as combined_dist, so if its alternatives share an observable, the export now fails with the shared-variate error instead of writing a combined_dist with the wrong meaning; the import warning for an unused category_conditional_dist says so.

The distinction by clients is a heuristic. A RooSimultaneous used in a product with constraint terms, for example, would be taken as conditional. It is the best criterion available without an explicit marker, and we would prefer a more reliable one in the future (see question 2).

Test: CategoryConditionalDist covers:

• import, with the category_conditional_dist used in a mixture_dist;
• the value for both states;
• the export, with the parameter in the domain and in the parameter point;
• a stable document;
• a RooSimultaneous built in RooFit can't be written as a combined_dist at the top level (its alternatives share the observable), and is a category_conditional_dist once a RooAddPdf uses it;
• in a likelihood, the alternatives' observable is a variate of the term that uses the category_conditional_dist;
• the warning for a category_conditional_dist that is not used;
• undeclared categorical parameters are an error.

2. RooMultiPdf → category_conditional_dist

Exporting a RooMultiPdf failed ("no export keys available"). It is now written as a category_conditional_dist:

• its category is the categorical parameter;
• the key of the pdf at list position i is the label of the state with index i, since RooMultiPdf selects by index;
• a pdf without a state of its index is an error.

The penalty term that RooMultiPdf adds to the likelihood (a correction for the number of free parameters of the selected pdf) has no HS3 representation yet. It is dropped with a warning, and its constants are not written. The category_conditional_dist is read back as a RooSimultaneous that evaluates to the same pdf, so the class doesn't survive a round trip.

Test: MultiPdfExport checks:

• the warning;
• the keys and components;
• no penalty constants in the document;
• the value of the read-back RooSimultaneous and of a mixture using it, for both states.

Questions for the RooFit maintainers

#23454 (comment) describes the plan to deprecate RooMultiPdf in favour of RooSimultaneous, and to pass the penalty term of discrete profiling as an argument at likelihood creation (createNLL()/fitTo()). This PR follows that direction: the import target is RooSimultaneous, and RooMultiPdf is only written. Two questions remain.

1. The penalty term. This is the central open question. If the penalty becomes an argument of the likelihood creation, then on the HS3 side it belongs to the likelihood or the analysis, not to the distribution. The note in HS3 #147 instead suggests writing it as a categorical function used by a distribution in aux_distributions. Which form fits the planned interface? Until this is settled, the export drops the penalty with a warning, and we would bring the answer to HS3.
2. Telling the conditional use apart. Is the criterion "used by another pdf" acceptable for now? Will the harmonized RooSimultaneous know about its conditional use more explicitly, so that the export can rely on it?

The same questions for RooMultiReal and the HS3 categorical function are collected in #24006.

Not covered, deferred

• The HS3 categorical function (→ RooMultiReal): #24006.
• The penalty term of RooMultiPdf (question 1).
• HS3 #147 requires that the categorical parameters never take a combination of values without an entry in components. The import doesn't check that a parameter's domain only contains labels with a component.

Behaviour changes users may notice

• Values of categorical parameters (RooCategorys in snapshots that are not columns of a combined distribution) appear in parameter points as strings.
• A RooSimultaneous that another pdf uses is written as category_conditional_dist instead of combined_dist.
• A RooMultiPdf can be exported, without its penalty term (warning), and comes back as a RooSimultaneous.

Checklist:

• tested changes locally
• updated the docs (if necessary)

Tests run (Linux, Ubuntu 26.04, GCC 15.2, RelWithDebInfo, -Droofit=ON -Dtesting=ON): testRooFitHS3 135 → 137 tests (2 new), testHistFactory 60, all passing. Each commit of this PR and of the rebased #24005 was built and tested on its own. clang-format clean.

AI assistance: Claude Code implemented the changes, the tests and this description under review of the author: claude-fable-5-1 the original category_conditional_dist commit; claude-opus-5-5 the split out of #24005, the structural distinction, and the RooMultiPdf export. The commits carry the corresponding Assisted-by trailers. The port onto the typed HS3 document of 3682174 was done by claude-opus-5-5 as well.

🤖 Generated with Claude Code