Project

General

Profile

A description of the demo system » History » Version 26

John Freeman, 04/13/2016 04:41 PM

1 1 John Freeman
h1. A description of the demo system
2 1 John Freeman
3 5 John Freeman
h2. Intro
4 5 John Freeman
5 19 John Freeman
artdaq-demo and artdaq-core-demo serve as an example of how components of the artdaq and artdaq-core packages, described below, can be pieced together to create a functioning DAQ system; a careful study of the packages along with their associated documentation in this wiki is intended to provide DAQ designers the knowledge base they need to develop their own, experiment-specific daq systems. artdaq-demo and artdaq-core-demo provide:
6 5 John Freeman
7 17 John Freeman
** Examples of various types of art modules useful for DAQ systems (online monitoring, etc.)
8 5 John Freeman
9 17 John Freeman
** Overlay classes, to provide an interface to an experiment's raw data which separates its users from the low-level details of the data layout. artdaq-core-demo provides an overlay for a commonly used board, the CAEN digitizer unit V172x, as well as a toy overlay designed to help users learn about how to design their own. 
10 5 John Freeman
11 6 John Freeman
** artdaq::CommandableFragmentGenerator -derived classes capable of simulating DAQ input, allowing users to learn about running an artdaq-based system without needing to interface with actual DAQ hardware
12 5 John Freeman
13 17 John Freeman
** A set of scripts, the use of which is described in [[Running a sample artdaq-demo system]], that the user can run to simulate a full DAQ system run, using the artdaq::CommandableFragmentGenerator -derived class demo::ToySimulator to simulate production of data fragments represented by the toy overlay class, and then processing the data by running art modules and and writing the result to disk
14 1 John Freeman
15 23 John Freeman
!artdaq-demo_package_dependencies.png!
16 23 John Freeman
17 26 John Freeman
_The following diagram shows the process types and some of the DAQ functions that are provided in artdaq. The boxes that are shown in green are part of what is provided by artdaq. The boxes shown in orange correspond to plugins that each experiment develops for their particular needs. Details are given throughout this wiki page._
18 25 John Freeman
19 25 John Freeman
!artdaq-layout.png!
20 25 John Freeman
21 17 John Freeman
h2. artdaq-core-demo and artdaq-core
22 1 John Freeman
23 17 John Freeman
h3. artdaq-core-demo: overlays
24 1 John Freeman
25 17 John Freeman
The overlays are defined in artdaq-core-demo; specifically, the V172x overlay is in artdaq-core-demo/artdaq-core-demo/Overlays/V172xFragment.hh and the toy overlay is in artdaq-core-demo/artdaq-core-demo/Overlays/ToyFragment.hh. The reason we have a separate package for the overlays is that the interface to the raw data which they provide is something that can be used in offline as well as online analysis; online-specific code related to the movement of data is located in artdaq and artdaq-demo. artdaq-core-demo depends on artdaq-core; typically an experiment's overlays are defined in a package usable by both offline and online, which depends on artdaq-core. 
26 5 John Freeman
27 18 John Freeman
h3. artdaq-core: the underlying data representation and the artdaq::Fragment class
28 17 John Freeman
29 17 John Freeman
The raw data from an experiment which uses an artdaq-based DAQ system is wrapped in an class called artdaq::Fragment. This class is defined in artdaq-core and overlay classes should have a constructor which takes a const reference to an artdaq:;Fragment object. An artdaq::Fragment object is the basic unit of data in artdaq-based DAQ systems; it contains some elementary information about itself, the most important of which are the "fragment ID", corresponding to a section of an experiment's detector, and the "sequence ID", used to uniquely label an event in the experiment. An "event" in an experiment using an artdaq-based DAQ system consists of fragments with a predefined set of fragment IDs all sharing the same sequence ID. Along with this basic info which all artdaq::Fragment objects contain (known as an artdaq::Fragment "header"), an artdaq::Fragment object can also contain a "payload", the raw data describing the physics as well as potential experiment-specific metadata such as the serial number of the upstream DAQ board where the fragment was created, the sample rate frequency, etc.
30 17 John Freeman
31 21 John Freeman
h2. artdaq-demo and artdaq 
32 1 John Freeman
33 25 John Freeman
The artdaq package provides users the tools (scripts, base classes, and applications) with which to create a DAQ system but does not itself provide a full workable DAQ. artdaq-demo is an example of how a user could create a DAQ system off of artdaq. In order to understand how artdaq-demo works, some components of artdaq first need to be understood; descriptions are provided below. Before reading the descriptions, the more visually inclined readers may want to scroll down to look at the UML deployment diagram showing how an artdaq-based DAQ can be distributed on an experiment's hardware, and the conceptual diagram showing how the various components relate to one another. Once this overview is read, developers and/or the curious can go to [[How to write a fragment generator]] for details on how to develop their own, experiment-specific DAQ software components. 
34 24 John Freeman
35 5 John Freeman
h3. The artdaq::CommandableFragmentGenerator class
36 5 John Freeman
37 21 John Freeman
The artdaq::CommandableFragmentGenerator class interface describes the basic state transition model of artdaq, including initialization, starting, stopping, and shutting down of the DAQ system. A user can override its virtual functions in a derived class to obtain fragments from an experiment's upstream hardware- or alternatively, write a simulation class for the experiment. The demo::ToySimulator class found in artdaq-demo/artdaq-demo/Generators/ToySimulator_generator.cc is an example of such a simulation, and is employed in the standard artdaq-demo run scripts.
38 5 John Freeman
39 16 Ron Rechenmacher
For more information on the artdaq state machine, see the diagrams "here":https://cdcvs.fnal.gov/redmine/documents/948
40 16 Ron Rechenmacher
41 5 John Freeman
h3. The BoardReaderMain application
42 5 John Freeman
43 18 John Freeman
In a running artdaq-based DAQ system, a BoardReaderMain process is typically in charge of receiving data from a predefined subset of an experiment's DAQ hardware, storing it in an artdaq::Fragment object's payload, and adding a fragment ID and sequence ID. BoardReaderMain receives state transition commands (the main ones being init, start, stop, shutdown), and sends them to the fragment generator class derived from CommandableFragmentGenerator. Each BoardReaderMain process is in charge of some predefined set of fragment IDs- usually just a single one. 
44 5 John Freeman
45 5 John Freeman
h3. The EventBuilderMain application
46 5 John Freeman
47 18 John Freeman
Each EventBuilderMain application receives fragments from all BoardReaderMains; a given EventBuilderMain application will be in charge of a subset of the total number of events passing through the DAQ system, if there's more than one such process in use. Containing knowledge of what set of fragment IDs constitutes a complete event, EventBuilderMain will receive fragments and whenever it determines it has enough fragments for a complete event will then send the complete event to an art thread it's running which then allows the event to be processed by an optional series of art modules, and will send the complete art event to the AggregatorMain processes for further art processing.
48 5 John Freeman
49 1 John Freeman
h3. The AggregatorMain application
50 1 John Freeman
51 18 John Freeman
Unlike an EventBuilderMain process, both AggregatorMain processes see the full set of events passing through the DAQ system. Typically, they're tailored to different tasks - one is focused on writing processed events to a file on disk using the RootOutput module provided by art, and the other runs experiment-specific analyzer art modules which allow for online monitoring. As the online monitoring AggregatorMain sees the art events provided by the diskwriting AggregatorMain in shared memory (ensuring online monitoring modules can't exert backpressure on the system), both AggregatorMains need to be on the same host - as can be seen in the deployment diagram. 
52 5 John Freeman
53 13 John Freeman
h3. Sample artdaq deployment diagram
54 13 John Freeman
55 15 John Freeman
The following is a UML (Universal Modeling Language) diagram of a sample deployment of an artdaq-based DAQ system running on a detector consisting of two components, each of which is interfaced with a BoardReaderMain application, both running on the same host; additionally, there are two EventBuilderMains running on two desktops and two AggregatorMains running on a single desktop.
56 15 John Freeman
57 14 John Freeman
!deployment2.png!
58 10 John Freeman
59 5 John Freeman
h2. artdaq-demo
60 6 John Freeman
61 20 John Freeman
artdaq-demo comes with a pair of scripts, start2x2x2System.sh and manage2x2x2System.sh, which can be run in separate terminal windows to execute a sample DAQ system. The "2x2x2" refers to the use of two BoardReaderMains, two EventBuilderMains, and two AggregatorMains. start2x2x2System.sh primarily serves as a wrapper around artdaq's pmt.rb script (pmt == "process management tool")  which sets up the MPI environment and checks that it's possible to communicate with the processes used in the system via the XML-RPC protocol, which will be necessary in order to send them transition commands. manage2x2x2System.sh primarily serves as a wrapper around artdaq-demo's DemoControl.rb script, which itself defines how the demo is to be run in that it's in charge of sending the FHiCL control code used to initialize the various artdaq applications comprising the DAQ system (where FHiCL is the "Fermilab Hierarchical Command Language":https://cdcvs.fnal.gov/redmine/projects/fhicl/wiki ). In order to see what those FHiCL strings are, you can include a "-v" among the options to manage2x2x2System.sh when initializing, e.g., "manage2x2x2System.sh -v -m on init", in which case *.fcl files for each process will be written to the directory out of which you're running. For more on this, see [[Running a sample artdaq-demo system]] .
62 9 John Freeman
63 9 John Freeman
Now that you've read up a bit on artdaq-demo and the packages it depends on, you can obtain your own copy of it by following the instructions at [[Installing and building the demo]].