add occupancy bookkeeping class and HIPO banks

[baltzell]

To reduce the calibration data volume from detector hit banks, this adds:

• occupancy bank schemas
• thread-safe OccupanceTable bookkeeping class with I/O helpers for standard indexed HIPO banks
• OccupanceEngine ready for all standard clas12 detectors.

The new occupancy banks currently look like this:

        "name": "OCC::FTOF::adc",
        "group": 500,
        "item": 14,
        "info": "Occupancy Bank",
        "entries": [
            { "name":"sector"    , "type":"B", "info":"sector"},
            { "name":"layer"     , "type":"B", "info":"layer"},
            { "name":"component" , "type":"S", "info":"component"},
            { "name":"hits"      , "type":"F", "info":"number of hits"}

• Finalize occupancy bank naming
• Bank group number
• Use FilteredBank for order-hijacking by denoising
• Check index count for all detectors
• Check for missing detectors
• Ignore bank rows with negative indices
• YAML variable, occupancyPrescale

The main consumer of these new occupancy banks is clas12-timeline.

Depends on #1380, #1381, #1382, #1383.

[c-dilks]

Is there any way to avoid the DRY violation here, and read occupancy.json somehow?

[baltzell]

That could surely be done.

[baltzell]

Negative indices definitely doesn't work:

java.lang.IllegalArgumentException: Index value out of range (0–65535) : -119
	at org.jlab.utils.groups.IndexedList.validateIndex(IndexedList.java:86)
	at org.jlab.utils.groups.IndexedList.add(IndexedList.java:99)
	at org.jlab.utils.groups.IndexedTable.addEntry(IndexedTable.java:95)
	at org.jlab.detector.calib.utils.OccupanceTable.fill(OccupanceTable.java:82)

Probably this means the addEntry isn't being used for translation tables in the decoder (there's a string-based alternative) ....

[baltzell]

Nope, IndexedTables in decoding always have positive indices (they're defined only by CCDB tables), and addEntryFromString has the same issue with negatives. The negative is created on bank writing.

Note, the swaps service will throw an exception for RICH's layer>128 hits.

[c-dilks]

Some info about group and item here on pp. 11 ff. of Mathieu's HIPO spec writeup:

https://code.jlab.org/ouillon/hipo4j/-/raw/691447f5a212a23a9561055cb9985e104828794f/specification/hipo-file-format.pdf?inline=false

(CC @raffaelladevita)