Warning, /acts/docs/pages/material_map_json_format.md is written in an unsupported language. File is not indexed.
0001 @page material_map_json_format Material map JSON format
0002
0003 A material map is the file the material mapping writes and the
0004 @ref Acts::JsonMaterialDecorator "JsonMaterialDecorator" reads back to attach
0005 material to a tracking geometry. This page documents the on-disk layout as
0006 produced by @ref Acts::MaterialMapJsonConverter "MaterialMapJsonConverter" and
0007 @ref Acts::SurfaceMaterialJsonConverter "SurfaceMaterialJsonConverter".
0008
0009 The example below is not typed out by hand. It is generated from the converters
0010 by the `MaterialJsonDocumentation` unit test, which fails if this file stops
0011 matching what the code writes; run that test with `ACTS_UPDATE_DOC_EXAMPLES=1`
0012 to refresh it after a format change. It is deliberately as small as the format
0013 allows, and shows the three surface payloads that differ in shape plus one
0014 volume entry. The remaining payload types differ only in the keys tabulated
0015 further down.
0016
0017 @include examples/material_map_example.json
0018
0019 ## Document layout
0020
0021 The document has two top level keys, `Surfaces` and `Volumes`. Each holds a
0022 @ref Acts::GeometryHierarchyMapJsonConverter "geometry hierarchy map" document,
0023 which is a header naming the container -- `acts-geometry-hierarchy-map`, with a
0024 `format-version` and a `value-identifier` -- followed by a flat list of
0025 `entries`.
0026
0027 An entry carries the non-zero levels of its @ref Acts::GeometryIdentifier
0028 (`volume`, `boundary`, `layer`, `approach`, `sensitive`) next to a `value`
0029 object. Levels that are zero are omitted, which is why the homogeneous entry
0030 above shows `volume` and `boundary` but no `layer`. For material maps the
0031 `value` object has a single `material` key. An entry whose `material` is
0032 missing or `null` is skipped when reading, which is how a geometry dump can
0033 list surfaces that carry no material yet.
0034
0035 ## Surface material payloads
0036
0037 The value under `material` is a self-describing payload. Its `type` tag selects
0038 the decoder and is authoritative: a missing or unknown tag is an error, the
0039 payload is never guessed from the keys that happen to be present.
0040
0041 | `type` | C++ type | Payload keys |
0042 |--------------------------|-------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|
0043 | `homogeneous` | @ref Acts::HomogeneousSurfaceMaterial | `data` |
0044 | `binned` | @ref Acts::BinnedSurfaceMaterial | `binUtility`, `data` |
0045 | `proto` | @ref Acts::ProtoSurfaceMaterial | `binUtility` |
0046 | `proto-grid` | @ref Acts::ProtoGridSurfaceMaterial | `axis_specs` |
0047 | `grid` | @ref Acts::GridSurfaceMaterial | `accessor` |
0048 | `merged-material-marker` | @ref Acts::MergedMaterialMarker | none |
0049
0050 Two more keys are common to all of them:
0051
0052 - `mapMaterial` steers the material mapping. Reading a payload with
0053 `mapMaterial: false` yields no material at all, so this is also how a surface
0054 is flagged out of the mapping. Proto material without any binning is written
0055 with `mapMaterial: false` for that reason.
0056 - `mappingType` is one of `PreMapping`, `Default`, `PostMapping` or `Sensor`
0057 and tells the mapper where along the propagation the material should be
0058 assigned. It is absent from the `grid` and `merged-material-marker`
0059 payloads, which do not participate in the deprecated mapping path.
0060
0061 ### Material slabs
0062
0063 Wherever material itself is stored, it is a slab: the opaque
0064 @ref Acts::Material parameter vector plus a thickness. The vector currently
0065 holds radiation length, interaction length, relative atomic mass, nuclear
0066 charge and molar density in ACTS native units, but it is deliberately opaque --
0067 read it through the converter rather than by index, since more parameters may
0068 be appended later. Vacuum is written as a `null` vector, as in the empty second
0069 bin of the binned entry above.
0070
0071 ### `homogeneous` and `binned`
0072
0073 `homogeneous` is one slab for the whole surface. The slab sits in a nested
0074 array for historical reasons: it is the degenerate case of the `binned` matrix,
0075 which pairs a @ref Acts::BinUtility with the slabs it addresses. That matrix is
0076 indexed `[bin of the second binning][bin of the first binning]`, so the one
0077 dimensional binning of the example gives a single row of two slabs.
0078
0079 ### `proto` and `proto-grid`
0080
0081 Binning instructions for the material mapping that carry no material yet.
0082 `proto` expresses the binning as a @ref Acts::BinUtility, exactly as `binned`
0083 does but without the `data`. `proto-grid` expresses it as an `axis_specs` list
0084 of @ref Acts::AxisSpec, which is the representation the grid based material
0085 uses; each spec has a `type`, a `bins` count, a `range`, a `boundary_type` and
0086 a `direction`. Exactly two specs are required.
0087
0088 ### `grid`
0089
0090 The whole grid material family shares one tag, and one C++ class:
0091 @ref Acts::GridSurfaceMaterial. The payload is a grid under `accessor`, made of
0092 a list of `axes` and a `data` list of `[local bins, value]` pairs. The local bin
0093 indices are **one based** and follow the axis order of `axes`.
0094
0095 The grid is always two dimensional, and lookup is local: `loc0` addresses axis
0096 0 and `loc1` axis 1 directly. There is no global (position) lookup and hence no
0097 coordinate-transform description in the payload.
0098
0099 What sits in a bin depends on `accessor.type`, which names the storage backend:
0100
0101 | `accessor.type` | Bin value | Extra keys |
0102 |--------------------|-----------------|--------------------------------|
0103 | `direct` | a material slab | none |
0104 | `indexed` | an index | `storage_vector` |
0105 | `globally_indexed` | an index | `storage_vector` **or** `store` |
0106
0107 `indexed`, shown in the example, keeps a slab store next to the grid and the
0108 bins index into it, which pays off as soon as several bins share the same slab.
0109 Note that the store index is unrelated to the bin number: the single bin of the
0110 example holds index 1, the second entry of its `storage_vector`.
0111
0112 `globally_indexed` is the same, except that the store may be shared with other
0113 surfaces. A standalone payload inlines the store as `storage_vector` and stays
0114 self-contained; when a document-wide store table is in use, the entry instead
0115 references it by id under `store`, so the sharing survives the round trip
0116 rather than being flattened into one copy per surface. The two are mutually
0117 exclusive: an entry carrying `store` can only be read with the table that
0118 defines it.
0119
0120 ### `merged-material-marker`
0121
0122 A sentinel left behind by @ref Acts::Portal::merge when the material of two
0123 merged portal surfaces had to be dropped. Its payload is just the tag and
0124 `mapMaterial`; it carries no material, only the information that something was
0125 lost here.
0126
0127 ## Volume material payloads
0128
0129 Volume material entries are written by a separate, older converter and use
0130 their own tags: `homogeneous` (a single @ref Acts::Material parameter vector
0131 under `data`, as in the example above), `proto` (a `binUtility` only), and
0132 `interpolated2D` / `interpolated3D` (a `binUtility` plus one parameter vector
0133 per bin). The tags overlap with the surface ones by accident; the two lists
0134 live under different top level keys and are never mixed.
0135
0136 ## Stable surface assignment keys
0137
0138 For configuration, mapping, and application, see
0139 @ref material_mapping_stable_keys in the material-mapping guide.
0140
0141 Maps with keyed assignments add a `KeyedSurfaces` section:
0142
0143 ```json
0144 {
0145 "KeyedSurfaces": [
0146 {
0147 "key": "tracker/barrel/outer",
0148 "geometry_id": 123,
0149 "material": { "type": "homogeneous", "mapMaterial": true, "data": [[{ "material": null, "thickness": 0.0 }]] }
0150 }
0151 ]
0152 }
0153 ```
0154
0155 The array is alongside the existing `Surfaces` and `Volumes` sections, without
0156 a separate version header. Keyed assignments appear only in `KeyedSurfaces`;
0157 they are not also emitted in `Surfaces`. The `geometry_id` recorded during
0158 mapping is diagnostic only. Each entry contains the key, geometry ID, and
0159 material payload. The material payload uses
0160 @ref Acts::SurfaceMaterialJsonConverter. Keyed entries use an array so duplicate keys
0161 can be detected before insertion. Distinct keys may have the same recorded
0162 ID, allowing maps from independent geometry builds to be combined. Combining
0163 maps must reject duplicate keys rather than overwrite them.
0164
0165 Standalone proto-material payloads store the optional key as `material_key`.
0166
0167 Merge markers retain an `origins` array containing the original `geometry_id`
0168 and, when present, `material_key`. Repeated merges flatten the original inputs
0169 into this array. Geometry IDs may be zero if the merge preceded ID assignment.
0170 The marker remains an error sentinel, never a valid material-map assignment.
0171
0172 The ROOT material writers currently reject keyed assignments; use JSON or
0173 CBOR to preserve the keys. ID-only JSON maps retain their existing format.
