[RF][HS3] Bring the HS3 import and export closer to the HS3 standard

Fix several deviations of RooFit's HS3 layer from the HS3 standard
(hep-statistics-serialization-standard master at cb3e9eb). None of the
changes depend on pending HS3 PRs; the ones that do follow in #23840.
Stricter checks only apply to documents that declare a recent enough
hs3_version, so files written by older ROOT versions remain readable.

Metadata and names:
* hs3_version must be a string. Its MAJOR.MINOR is parsed, and a
  warning is printed if it can't be parsed or is newer than what RooFit
  writes. Importers can query it with
  RooJSONFactoryWSTool::hs3VersionInput().
* Duplicate names of top-level objects are an error from HS3 0.3 on,
  and only a warning for older documents.
* On export, likelihoods are named "<analysis>_likelihood", analyses are
  named after their ModelConfig, and transformed helper functions that
  several pdfs share are written only once.

Import:
* The "default_domain" is optional. Without it, variables get the range
  of the first domain that lists them.
* Parameters that only appear in a parameter point are created. They
  are constant if "const" is true or if no domain lists them. A string
  value sets the label of a category. Index categories of combined
  distributions are now created before the parameter points.
* Observables of unbinned data without a domain range take their range
  from the "min"/"max" of the data axes. Infinite bounds (null) are
  supported.
* "init" of an analysis is restored as the ModelConfig snapshot under
  the same name. A missing parameter point is reported.
* An explicit "extended" flag of mixture_dist is checked against the
  number of coefficients.
* Malformed input is rejected instead of being read out of bounds:
  covariance and correlation matrices must be square, "errors" must have
  as many entries as "contents", and "edges" must contain at least two
  strictly ascending values.
* Errors of zero in binned data stay zero. Before, they could be read
  as squared weight = content.

Export:
* Axes of unbinned data only carry "name", "min" and "max".
* The ModelConfig snapshot is written as "init" of the analysis, which
  no longer has the side effect of loading the snapshot values.
* Ternaries in formulas are written as ifelse(c, a, b), and ifelse() is
  translated back to a ternary on import.

Type keys (the old keys are still imported, with a deprecation
warning):
* ARGUS_dist -> argus_dist
* binsampling -> binsampling_dist. Before, RooFit could not read back
  its own export.
* rate_extended_dist uses the fields "dist" and "rate" instead of "pdf"
  and "norm".

HistFactory:
* "LogNormal" is accepted as a constraint type, alongside "Lognormal".
  Log-normal constraints of gamma parameters are rejected instead of
  silently becoming Gaussian.
* The parameter of a normfactor is named after "parameter". "name" is
  only the label of the modifier.
* normsys/histosys modifiers without constraint are unconstrained from
  HS3 0.2 on, with one warning per channel. Older documents, and objects
  imported with importJSONElement(), keep the implicit unit Gaussian.
  On export, unconstrained modifiers are allowed. A normsys with a
  function as parameter is refused.
* The staterror constraint type is read from the modifier ("constraint",
  or "constraint_type" as written by ROOT 6.38 and 6.40.00), with the
  channel-level setting as fallback. It is written in both places, so
  Gaussian stat errors are no longer lost in a round trip.
* A modifier without interpolation and without "default_interpolation"
  is an error from HS3 0.3 on. Older documents keep code 4, with a
  deprecation warning.
* Fix the export of normsys modifiers recognized from formulas like
  1+0.1*alpha: hi/lo were written as 0.1/-0.1 instead of the absolute
  factors 1.1/0.9, and the constraint was dropped.

Other:
* Warnings of RooJSONFactoryWSTool are logged on the ObjectHandling
  topic. Before, they went to the IO topic, which no default stream
  shows.
* Add ModelConfig::GetSnapshotName().
* Update the RooFitHS3 developer documentation.
* Make the constraints and interpolation of the rf515_hfJSON tutorial
  explicit. The fit result is unchanged.

Files written with this version use the new type keys and ifelse(),
which ROOT 6.40 and older cannot read.

Assisted-by: claude-code:claude-opus-5-5
(cherry picked from commit d61fecf)

Author: cburgard

roofit/doc/developers/roofit_hs3.md

@@ -47,12 +47,16 @@ implementation(s) take precedence.
 ### Writing your own importers and exporters: Proxy-based
 
 Proxy-based implementations can be added very easily and without
-actually writing any `C++` code -- you only need to add a short item
-to a list in a `JSON` file, namely the
-[export keys](https://github.com/root-project/root/blob/master/etc/RooFitHS3_wsexportkeys.json)
+actually writing any `C++` logic -- you only need to add a short item
+to a `JSON` catalog, namely the
+[export keys](https://github.com/root-project/root/blob/master/roofit/hs3/src/RooFitHS3_wsexportkeys.cxx)
 for an exporter, or the
-[factory expressions](https://github.com/root-project/root/blob/master/etc/RooFitHS3_wsfactoryexpressions.json)
-for an importer.
+[factory expressions](https://github.com/root-project/root/blob/master/roofit/hs3/src/RooFitHS3_wsfactoryexpressions.cxx)
+for an importer. The built-in catalogs are `JSON` documents embedded as
+raw string literals in these two source files. They are compiled into
+the `RooFitHS3` library and loaded automatically when the library is
+loaded, so there are no separate `JSON` files to install or find at
+runtime.
 
 This works in the following way: Every `RooFit` class performs
 dependency tracking via proxies, which have names. This can be
@@ -67,7 +71,7 @@ interface. Hence:
    expression`.
 
 For the importer, an entry in the
-[factory expressions](https://github.com/root-project/root/blob/master/etc/RooFitHS3_wsfactoryexpressions.json)
+[factory expressions](https://github.com/root-project/root/blob/master/roofit/hs3/src/RooFitHS3_wsfactoryexpressions.cxx)
 needs to be added as follows:
 
 ``` {.json}
@@ -82,7 +86,7 @@ needs to be added as follows:
 ```
 
 Similarly, for the exporter, an entry in the
-[export keys](https://github.com/root-project/root/blob/master/etc/RooFitHS3_wsexportkeys.json)
+[export keys](https://github.com/root-project/root/blob/master/roofit/hs3/src/RooFitHS3_wsexportkeys.cxx)
 needs to be added as follows:
 
 ``` {.json}
@@ -97,12 +101,18 @@ needs to be added as follows:
 ```
 
 
-If you don't want to edit the central `json` files containing the
-factory expressions or export keys, you can also put your custom
-export keys or factory expressions into a different json file and load
-that using `RooFit::JSONIO::loadExportKeys(const std::string
+To contribute a catalog entry to `ROOT`, edit the embedded catalog in
+`roofit/hs3/src/RooFitHS3_wsexportkeys.cxx` or
+`roofit/hs3/src/RooFitHS3_wsfactoryexpressions.cxx` and rebuild `ROOT`.
+If you don't want to change `ROOT` itself, you can put your custom
+export keys or factory expressions into your own `JSON` file (with the
+same format as the embedded catalogs) and add them to the built-in ones
+at runtime using `RooFit::JSONIO::loadExportKeys(const std::string
 &fname)` and `RooFit::JSONIO::loadFactoryExpressions(const
-std::string &fname)`.
+std::string &fname)`. Both functions also have an overload that reads
+from a `std::istream`. You can inspect the currently known entries with
+`RooFit::JSONIO::printExportKeys()` and
+`RooFit::JSONIO::printFactoryExpressions()`.
 
 If either the importer or the exporter cannot be created with factory
 expressions and export keys, you can instead write a custom `C++`
@@ -121,9 +131,11 @@ in `ROOT`.
 Any importer should take the following form:
 
 ``` {.cpp}
+    using RooFit::Detail::JSONNode;
+
     class MyClassFactory : public RooFit::JSONIO::Importer {
     public:
-       bool importFunction(RooJSONFactoryWSTool *tool, const JSONNode &p) const override
+       bool importArg(RooJSONFactoryWSTool *tool, const JSONNode &p) const override
        {
           std::string name(RooJSONFactoryWSTool::name(p));
 
@@ -145,14 +157,24 @@ Any importer should take the following form:
     };
 ```
 
-If the class you are trying to import inherits from `RooAbsPdf` rather
-than from `RooAbsReal`, you should define `importPdf` instead of
-`importFunction`, with the same signature.
+The same `importArg` function is used for functions (inheriting from
+`RooAbsReal`) and pdfs (inheriting from `RooAbsPdf`). If the importer
+can't handle a given `JSON` node, it should return `false` so that the
+next importer is tried. The functions `importFunction` and `importPdf`
+of older `ROOT` versions are still called for backwards compatibility,
+so existing importers that override them keep working, but new code
+should override `importArg`.
 
 Once your importer implementation exists, you need to register it with the tool using a line like the following:
 
 ``` {.cpp}
-    RooFit::JSONIO::registerImporter("<json key>", new MyClassFactory(), true);
+    RooFit::JSONIO::registerImporter<MyClassFactory>("<json key>", true);
+```
+
+This is a shorthand for passing an instance owned by a `std::unique_ptr`:
+
+``` {.cpp}
+    RooFit::JSONIO::registerImporter("<json key>", std::make_unique<MyClassFactory>(), true);
 ```
 
 As there can be several importers for the same `json` key, the last
@@ -189,9 +211,20 @@ The implementation of an exporter works in a very similar fashion:
 Also this needs to be registered with the tool
 
 ``` {.cpp}
-    RooFit::JSONIO::registerExporter(MyClass::Class(), new MyClassStreamer(), true);
+    RooFit::JSONIO::registerExporter<MyClassStreamer>(MyClass::Class(), true);
 ```
 
+or equivalently
+
+``` {.cpp}
+    RooFit::JSONIO::registerExporter(MyClass::Class(), std::make_unique<MyClassStreamer>(), true);
+```
+
+If the `TClass` of your class is not available where you register the
+exporter, you can also pass the class name as a string instead of
+`MyClass::Class()`. If `exportObject` returns `false`, the next
+exporter is tried, and finally the export keys.
+
 For more complicated cases where members are lists of elements, the
 methods `is_seq()`, `set_seq()`, `is_map()`, `set_map()` and
 ranged-based for-loops via `children()` might come in handy.

roofit/hs3/inc/RooFitHS3/RooJSONFactoryWSTool.h

@@ -206,6 +206,9 @@ class RooJSONFactoryWSTool {
    std::string getStringAttribute(const std::string &obj, const std::string &attrib);
    void setStringAttribute(const std::string &obj, const std::string &attrib, const std::string &value);
 
+   /// The "hs3_version" of the document that is currently being imported, or an empty string outside of an import.
+   std::string const &hs3VersionInput() const { return _hs3VersionInput; }
+
 private:
    template <class T>
    T *requestImpl(const std::string &objname);
@@ -251,6 +254,7 @@ class RooJSONFactoryWSTool {
    const RooFit::Detail::JSONNode *_attributesNode = nullptr;
    RooFit::Detail::JSONNode *_rootnodeOutput = nullptr;
    RooFit::Detail::JSONNode *_varsNode = nullptr;
+   std::string _hs3VersionInput;
    RooWorkspace &_workspace;
 
    // objects to represent intermediate information

roofit/hs3/src/Domains.cxx

@@ -11,6 +11,7 @@
  */
 
 #include "Domains.h"
+#include "JSONIOUtils.h"
 
 #include <RooAbsBinning.h>
 #include <RooBinning.h>
@@ -29,15 +30,6 @@ constexpr static auto defaultDomainName = "default_domain";
 
 namespace {
 
-double readBound(RooFit::Detail::JSONNode const &node, const char *key, double defaultValue)
-{
-   if (!node.has_child(key)) {
-      return defaultValue;
-   }
-   auto const &bound = node[key];
-   return bound.is_null() ? defaultValue : bound.val_double();
-}
-
 void writeBound(RooFit::Detail::JSONNode &node, double value)
 {
    if (RooNumber::isInfinite(value)) {
@@ -54,6 +46,12 @@ void Domains::populate(RooWorkspace &ws) const
    auto default_domain = _map.find(defaultDomainName);
    if (default_domain != _map.end()) {
       default_domain->second.populate(ws);
+   } else {
+      // Without the RooFit-specific "default_domain", the variables are created with the range of the domain that
+      // mentions them.
+      for (const auto &domain : _map) {
+         domain.second.populate(ws);
+      }
    }
    for (const auto &domain : _map) {
       if (domain.first == defaultDomainName)
@@ -78,15 +76,20 @@ void Domains::writeVariable(RooRealVar &var) const
    auto default_domain = _map.find(defaultDomainName);
    if (default_domain != _map.end()) {
       default_domain->second.writeVariable(var);
+      return;
+   }
+   // Without the RooFit-specific "default_domain", use the first domain that mentions the variable.
+   for (const auto &domain : _map) {
+      if (domain.second.hasVariable(var.GetName())) {
+         domain.second.writeVariable(var);
+         return;
+      }
    }
 }
 
 void Domains::readJSON(RooFit::Detail::JSONNode const &node)
 {
-   auto default_domain_element = RooJSONFactoryWSTool::findNamedChild(node, defaultDomainName);
-   if (!default_domain_element) {
-      RooJSONFactoryWSTool::error("\"domains\" do not contain \"" + std::string{defaultDomainName} + "\"");
-   }
+   // The "default_domain" is written by RooFit, but it is not required by the HS3 standard.
    for (auto &domain : node.children()) {
       if (!domain.has_child("name")) {
          RooJSONFactoryWSTool::error("encountered domain without \"name\"");