Project

General

Profile

Actions
History

OUT OF DATE?

We are in the process of having a Spill Schema file within MAUS instead of this. That file would autogenerate this. Hopefully sometime in 2011 (if it is 2012, 2013, or 2018 and you are reading this, delete!) it'll be done.

Data Structure Overview

persistency_considerations

MICE is an accelerator physics experiment done with particle physics detectors. Accordingly, the DAQ and analysis software are more like those seen in particle physics experiments where you have the frequently valid assumption that each event is independent. In accelerator physics packages, one has to worry about cumulative effects between all the particles in the accelerator (ie. space-charge effects, beam-beam effects, wakefields, etc.). However, in particle physics packages particles after they are created never interact with anything other than the detector and fields. For the purposes of MICE, this is similarly true and the data-structure tries to enforce that while still allowing effects like pile-up within a detector.

Given this independence clause between particles, we follow the paradigm of modern particle physics software: analysis tools shouldn't need to know if they are running on data or MC. This is particularly important when trying to study effects like trigger or reconstruction efficiencies and biases, which will be the largest systematic uncertainties for the detectors. So what should the data-structure in MAUS look like then?

There is already a data-structure within the MICE experiment: the DAQ structure. Let's assume that the DAQ event corresponds to a spill instead of being a readout between spills, which is part of the DAQ design to do things like pedestal runs. This DAQ event is created on a per spill basis and the unpacker operates on data spill-by-spill. Within this DAQ event (ie. spill) there are triggers and within those triggers 'particles'. For instance, a trigger could be actually be caused by two events causing pile-up.

MAUS uses a similar setup. The data structure within MAUS is a JSON document: use JsonCpp within C++ and the JSON module within Python.

MC/Data

Spill

Member Name Type Units Comments
"triggers" trigger none
"digits" digit N/A An array of digitized hits
"mc" array N/A Array of MC Particles
"errors" associative array N/A An array of produced errors.
"spill_number" unsigned int N/A A unique spill number starting from 0
"virtual_plane" associative array N/A A dictionary that takes 'z' coordinates to length 2 array of MC Tracks then MC Steps

Triggers

Particles

Digits

Member Name Type Units Comments
"channel_id" associative array n/a Please consult the channel identification table
"adc_counts" integer n/a the number of charge ADC counts read out by the electronics
"tdc_counts" integer n/a the number of time TDC counts read out by the electronics

Produced errors

Any processor can create an error. For example, if MapPyVirtualPlanes wasn't told what planes to search for then the error it produces should be:


spill["errors"]["MapPyVirtualPlanes"] = "something funky happened.  please do this"

and this format should be followed for all processors.

In addition to specific components of MAUS complaining, one may also have issues with the core of MAUS. Below is the list of errors that the internals of MAUS can produce:

Member Name Type Units Comments
"unparsable_json_document" string N/A This error variable is set when the input JSON file cannot be parsed. The text associated with it is the error information
"missing_branch" string N/A An expected branch was missing: see error text for which it was.
"bad_type" string N/A Something had the wrong type: see error text for which it was.

Channel ID

The channel identification (ID) refers to what channel of a detector a hit was recorded in. The channel ID has a different format for every detector however all hits must include a field called "type" such that future programs understand how to interpret the hit. Below are the formats of the channel ID for various different types. This channel ID will allow you to fetch the calibration for this specific channel.

TOF

Member Name Comments
"type" This will always be equal to "TOF"
"plane" TOF plane
"slab" Which TOF slab
"station_number" This can be 0, 1, or 2 for TOF0, TOF1, or TOF2, respectively
"pmt" Only applicable to digitzed hits. This can either be 1 or 2. If this field doesn't exist (for example: MC hits) then only a slab is refered to.

SciFi Tracker

Member Name Comments
"type" This will always be equal to "Tracker"
"fiber_number" Tracker fiber number
"plane_number" Which tracker plane
"station_number" Tracker station number
"tracker_number" Tracker number: 1 is upstream of 2

EMR

Member Name Comments
"type" This will always be equal to "EMR"
"layer" EMR layer [0..47]
"bar" EMR bar in that layer [0..58]

MC

MC Particles

Member Name Type Units Comments
"hits" associative array N/A Array of MC Hits
"tracks" associative array N/A Array of MC Tracks
"particle_id" integer PDG Particle encoding This is the PDG particle encoding.
"position": associative array mm A three vector: position["x"] is the 'x' position, etc.
"unit_momentum" associative array N/A A unit vector three vector: unit_momentum["x"] is the 'x' momentum, etc.
"energy" double MeV the energy of the particle

MC Hits

Member Name Type Units Comments
"channel_id" associative array n/a Please consult the channel identification table
"tracks" associative array n/a Please consult the MC tracks table
"energy_deposited" double MeV/c^2 The amount of energy deposited in this detector channel
"time" double nanosecond the time of the hit
"path_length" double millimeter the path-length through this channel
"particle_id" integer PDG Particle encoding This is the PDG particle encoding. However, if the PDG code refers to a Geantino by being equal to zero then two particles hit.
"mass" double MeV/c^2 The particle's mass
"charge" double positron charge The particle's charge
"position" associative array N/A A three vector: position["x"] is the 'x' position, etc.
"momentum" associative array N/A A three vector: momentum["x"] is the 'x' momentum, etc.

MC Tracks

Tracks are string indexed. For instance, the first track is labeled 'track1'.

Member Name Type Units Comments
"initial_position" associative array N/A A three vector: initial_position["x"] is the 'x' position at the start of the track, etc.
"initial_momentum" associative array N/A A three vector: initial_momentum["x"] is the 'x' momentum at the start of the track, etc.
"final_position": associative array N/A A three vector: final_position["x"] is the 'x' position at the end of the track, etc.
"final_momentum" associative array N/A A three vector: momentum["x"] is the 'x' momentum at the end of the track, etc.
"particle_id" integer PDG Particle encoding This is the PDG particle encoding.
"track_id" integer track number The track number of this track. This is useful when looking at "parent_track_id"
"parent_track_id" integer track number The track number of this track's parent (ie. where it originated)
"steps" numerically-indexed array N/A Please see the MC Steps table. There are steps.size() steps and the first step is steps0.

MC Steps

Member Name Type Units Comments
"energy_deposited" double MeV The amount of energy deposited for this step. This refers to the amount of energy just lost when getting to this position
"position": associative array N/A A three vector: position["x"] is the 'x' position, etc.
"momentum" associative array N/A A three vector: momentum["x"] is the 'x' momentum, etc.

Updated by Tunnell, Christopher over 11 years ago ยท 49 revisions