J.Adamczewski-Musch,
M.Al-Turany, D.Bertini, H.G.Essel, S.Linev
27 November 2013
Content
The
Go4 Analysis Framework Introduction V4.6
2.1.1 Go4 tasks with all
communications
2.1.3 Other analysis functions
3.2 Event classes, interface to MBS
3.5 Analysis base class TGo4Analysis
3.5.1 User subclass of TGo4Analysis
3.6.1 The go4analysis main program
3.6.2 Command line mode (batch)
3.6.3 Creating the user analysis
3.6.5 Analysis controlled by Go4 GUI
3.6.6 Analysis as server for multiple
Go4 GUIs
3.6.7 Configuration of analysis
3.6.8 Support of older analysis code
3.6.10 Start-up of GUI controlled analysis
3.6.11 Submit settings and run analysis
3.6.12 Shutdown of the analysis client
3.6.13 Disconnect or shutdown analysis
server
4.4 Simple example with one step
4.4.3 Auto-save file mechanism
4.5.4 Auto-save file mechanism
4.6.3 Steering methods in processor
function BuildEvent
4.7 Example with some advanced
tecniques
4.8 Example of analysis with a user
defined event source
5.1.1 File, Tools, Analysis menus
5.3.1 Launch analysis task in client
mode
5.3.2 Launch analysis task in server
mode
5.3.3 Connect to existing analysis
server
5.4.2 Analysis terminal window
5.4.3 Macro execution in the analysis
5.4.4 Auto-save file mechanism
5.4.6 User defined event sources
5.5.3 Analysis folder controls
5.5.7 Resetting and deleting objects
5.5.8 Histogram server connection
5.6.2 Remote mode (dynamic list
histogram)
5.6.3 Creating a new histogram
5.7.6 Draw options and axis scaling
5.7.7 Channel and window markers
5.8.1 Conditions editing in viewpanel
marker editor
5.8.4 Conditions bound to pictures
5.11.3 Parameters containing fitters
5.13 Histogram/condition information
6 Analysis Server for ROOT macros
6.1 Methods for object registration
6.2 Methods for run control and
execution
7 Control of remote Go4 analysis from
a ROOT session
7.3 Controlling the analysis by
command
8 Go4 analysis with DABC based
webserver
8.1 Startup of go4analysis with
webserver
8.2 Viewing analysis objects with web
browser
9 The Go4 Composite Event Classes
9.2 Application Programmers Interface
11 Table of Menu and Toolbar
Keyboard Shortcuts
13.1 New features in Go4 v4.6 (November
13)
13.2 New
features in Go4 v4.5 (July 11)
13.3 New
features in Go4 v4.4 (November
09)
13.4 New
features in Go4 v4.3 (June 09)
13.5 New
features in Go4 v4.2 (April
09)
13.6 New
features in Go4 v4.1 (October
08)
13.7 New
features in Go4 v4.0 (February
08)
13.8 New
features in Go4 v3.3 (May 07)
13.9 New features in Go4 v3.2 (July 06)
13.10 New features in Go4 v3.1 (May 06)
13.11 New features in Go4 v3.0
(November 05)
13.12 New features in Go4 v2.10 (June
05)
13.13 New features in Go4 v2.9
(February 05)
13.14 New features in Go4 v2.8
(September 04)
13.15 New features in Go4 v2.7 (June
04)
13.16 New features in Go4 v2.6 (May 04)
13.17 New features in Go4 v2.5
(December 03)
13.18 New features in Go4 v2.4 (August
03)
13.19 New features in Go4 v2.3 (May 03)
13.20 New features in Go4 v2.2 (April
03)
Layout used in this document:
Text Times New Roman, 10 pt
Verbatim text Courier new 9
pt
Menu items Arial bold 9 pt
Class names Arial
italics , 9 pt
Methods () Arial italics , 9 pt
Go4 screenshots
QT4 Style CDE, Font Arial 10pt
Icons
in text must be cut from bottom and diminuished to be in line.
Einfügen->Referenz->Querverweis:
Überschrift+Überschriftnummer/Seitenzahl
Einfügen->Referenz->Index
und Verzeichnisse: Eintrag festlegen, Indexeintrag+Aktuelle Seite. (search for Feld)
Index entries can be edited in text (first:second)
Index
aktualisieren (RMB)
Inhaltsverzeichnis
aktualisieren (RMB)
The Go4 (GSI Object Oriented On-line-Offline) Analysis Framework has been developed at GSI. It is based on the ROOT system of CERN. Therefore all functionality of ROOT can be used.
Go4 has two parts: the analysis framework itself and a Qt based GUI. Both can be used independently, or together. The separation of the analysis and GUI in two tasks is especially useful for on-line monitoring. The analysis runs asynchronously to the GUI which is (almost) never blocked. The same analysis can be run in batch/interactive mode or in remote GUI controlled mode. The GUI can be used stand alone as ROOT file browser and as histogram viewer for GSI standard histogram servers like MBS. Moreover, the analysis task can be run either as a client bound to one GUI (default), or can be started as an analysis server with the possibility to connect several GUIs (one controller and arbitrary number of observers with restricted commands).
gui150
The Go4
framework handles event structures, event processing, and event IO. The
analysis event loop is organized in steps: Each step has an input event, an output event, and an
event processor. The output event calls the event processor to be
filled. The event processor has also access to the input event. In the current
design the analysis is data driven. A first event object (input1) is filled
from some event source (input). An output event object (output1) is filled by
an event processor object (process1) which has access to both, input1 and output1.
Optionally the output event may be written to a file (file1). In the next step
the input event object (input2) can be either the output event object (output1)
from the previous step or retrieved from the file. The second output event
object (output2) is filled by the second event processor object (process2) and
can be optionally written to a second file.
The information needed to create the event and processor objects (which are deleted when the event loop terminates) is stored in step factories which are kept in the analysis.
The processor and output event classes have to be provided by the user. The input classes for standard GSI event sources are provided by Go4 (see chapter 3, page 10). Analysis and step factory classes are provided by Go4 or can be implemented by the user as subclasses.
gui148
For normal operation, the Go4 analysis steps are designed to run subsequently. But in addition, each analysis step has access to the output events of all other previous analysis steps, so it would be possible to let analysis steps logically run “in parallel”, all starting with the output event of the first step, and all delivering their results to the last step that may collect and combine them.
gui149
Outside the analysis steps the user functions UserPreLoop(), UserPostLoop(), and UserEventFunc() located in the user analysis class are executed as shown in the figure. In principle, they could be used to implement the full analysis without using the step mechanism. But for setting up a new analysis the use of steps is strongly recommended, because steps can be controlled by the GUI and offer event and IO management.
In the event loop, after processing the steps and UserEventFunc() the Go4 dynamic list processor is executed. This processor can be dynamically configured from the GUI to check conditions and/or fill histograms.
gui146
The Go4 concept consists of base classes (interfaces) for event structures, algorithms, and IO, which can be implemented by user subclasses or by framework plug-ins (general service classes) delivered with Go4. Class descriptions and reference guides are available on the Go4 Website http://go4.gsi.de.
The interface classes provided by Go4 (a detailed description is in the reference manual) are normally not seen by the user. Starting with the examples (see chapter 4, page 21) one can better study derived working classes.
TGo4EventElement: Defines the event structure and methods to clear this structure.
Input and output event structures of each step of the analysis are instantiated
once at initialization. In the event loop event first cleared (via Clear() method
call) and than filled by the source class, where BuildEvent function is defined.
TGo4EventSource:
The source of the event data. This can be e.g. a file of a certain format, or a
socket connection to an event server. The event source class has a BuildEvent(TGo4EventElement*) method, which fills
event structures. In addition, CheckEventClass(TClass*) method can be implemented to check event class during
initialization. The class constructor should open (connect) the source; the
destructor should close (disconnect) it properly.
TGo4EventStore:
An object responsible for storing the event data. This can be e.g. a local file
of a certain format, but may as well be a connection to some storage device.
The virtual method Store(TGo4EventElement*) is used to store the pointed event object. The class constructor
should open the storage; the destructor should close it properly.
TGo4EventProcessor: An object that contains the algorithm to convert an input event object into an output event object (both of class TGo4EventElement). This is a subclass of TGo4EventSource, since it delivers the filling of the output event from the input event. The event processor implementation has to “know” the input and output event classes. Actual code of converting the data (i.e. actually performing the analysis) should be implemented in BuildEvent method.
TGo4EventFactory:
Defines the actual implementations of all the above. Go4 uses a factory design
pattern to create all event class objects at initialization. The virtual
methods:
CreateInputEvent(), CreateOutputEvent(),
CreateEventSource(TGo4EventSourceParameter*), CreateEventStore(TGo4EventStoreParameter*),
CreateEventProcessor(TGo4EventProcessorParameter*) have to be defined in the user factory. They create the
respective objects and return the pointer to it. The default factory provides
methods
DefEventSource(classname), DefEventProcessor(objectname,
classname), DefInputEvent(objectname, classname) and DefOutputEvent(objectname,classname).
Simple examples of a running Go4 analysis can be found on
directories $GO4SYS/Go4ExampleSimple, $GO4SYS/Go4Example1Step, and
$GO4SYS/Go4Example2Step.
Go4 offers predefined implementations of the event base classes, including an interface to the GSI data acquisition Multi Branch System MBS, the GSI list-mode files, and ROOT files.
TGo4EventElement (base
class):
TGo4MbsEvent MBS event format 10-1
TGo4MbsSubEvent MBS
subevent format 10-1
TGo4CompositeEvent Base class for all composite event structures
TGo4ClonesElement Clonesarray container for composite event
TGo4EventSource (base class):
TGo4MbsFile (read
from *.lmd list-mode file with format 10,1)
TGo4MbsEventServer (connect to MBS event server)
TGo4MbsStream (connect to MBS stream server)
TGo4MbsTransport (connect to MBS transport server)
TGo4RevServ (connect to remote event server)
TGo4FileSource (read from *.root file from Go4 tree, i.e. one
file containing one TTree per analysis step)
TGo4EventStore (base
class):
TGo4FileStore (write to *.root file with Go4 tree, this file
can be used as TGo4FileSource later)
TGo4BackStore Use
TTree existing only in memory to view and analyze
event structures.
These classes can be used directly to write simple
analysis.
Using these
implementations, getting MBS event data into ROOT (without Go4 framework) could
look like this:
#include "Go4EventServer/Go4EventServer.h"
#include "Go4Event/TGo4EventEndException.h"
int main() {
TGo4EventSource* input = new TGo4MbsFile("file.lmd"); // MBS list-mode file
// TGo4EventSource* input= new TGo4MbsTransport("node"); // MBS transport server
// TGo4EventSource* input= new TGo4MbsStream("node"); // MBS stream server
// TGo4EventSource* input= new TGo4MbsEventServer("node"); // MBS event server
// TGo4EventSource* input= new TGo4RevServ("node"); // Remote event server
TGo4EventStore* output = new TGo4FileStore("output",1,5); // split level, compression
TGo4MbsEvent* event = new TGo4MbsEvent();
event->SetEventSource(input);
event->Init();
Int_t eof = 0, numEvents = 0;
while(eof==0) {
try{
event->Fill(); // read event
numEvents++; // eof throws exception
output->Store(event); // write to file
}
catch(TGo4EventEndException& ex) { eof=1; } // mark end of file
catch(...) { cout << "Error" << endl; eof=2; } // any other error
}
cout << "EOF after " << numEvents << " events" << endl;
}
The events in the ROOT
file can be retrieved by program, but not in tree viewers. For the use of tree
viewers, a new output event object should be filled and stored.
As mentioned above a Go4 analysis is organized in steps. The information needed to instantiate a step is kept in the step factory.
TGo4EventServerFactory (base class): (contains
factory methods that already know the above implementations. User step
factories must inherit from this class!)
TGo4StepFactory This
TGo4EventServerFactory can be used in most cases as user factory to
set up the analysis steps (example 1Step).
TGo4AnalysisStep objects of this class hold the definition of an analysis step.
Each analysis step has at least an input event object, an output event object and an event processor object. Additionally, it can have an event source (e.g. TGo4FileSource) and an event store (TGo4FileStore) instance. An analysis step is set up by a TGo4EventServerFactory subclass, i.e. TGo4StepFactory or a user defined subclass.
Objects used in Go4 are organized in ROOT folders. The folder
structure is sent to the GUI. Objects must be registered in the analysis to be
seen in the GUI browser. Registered objects can be located in the processors.
The top folders as seen in the GUI are shown on the left side. The methods to
register/locate objects are (pointer to the appropriate object, optional
subfolder as string, name including subfolder as string):
·
AddHistogram(pointer,subfolder), GetHistogram(name)
·
AddAnalysisCondition(pointer,subfolder), GetAnalysisCondition(name)
·
AddParameter(pointer,subfolder), GetParameter(name)
·
AddPicture(pointer,subfolder), GetPicture(name)
These methods are available in TGo4Analysis and TGo4EventProcessor subclasses. Objects created in a TGo4Analysis subclass can be located in all event processors. Objects created in event processors can be located in all subsequent event processors (steps).
Registered objects are stored/retrieved to/from the auto-save file, if enabled. Retrieval is done after creation of the analysis singleton before the creation of the steps. When an object retrieved from the auto-save file is created in a processor the retrieved object is replaced (stored data lost). When an object is created in the analysis singleton it will be replaced by the one retrieved from the auto-save file except histograms which are not retrieved in this case. This means that histograms created in the analysis singleton are always empty after startup.
Parameters used in the analysis are implemented by the user in classes derived from TGo4Parameter. Such objects are registered to the framework and can be edited by a generic parameter editor (see chapter 5.11.2, page 68). Parameter objects can be created in the user analysis or the event processor class. Parameter objects are loaded from an optional auto-save file after instantiation of the analysis and before instantiation of the processor objects. When created in the analysis the values set in the constructor are therefore overwritten by auto-save. To use the GUI editor, the UpdateFrom() method must be implemented to update the local (active) parameter object from the modified one delivered by the editor. In this method it is up to the user to ignore certain members or to execute whatever he wants. E.g. one could use parameters to execute commands. Parameters in the auto-save file can be edited. In the editor they can be saved/retrieved to/from files. Several mechanisms can be implemented to handle the parameter member values. The main question is how restricted the methods of modification should be.
1. Modify values only in the class constructor, then recompile. To prohibit changes by editor, the UpdateFrom() method could be just a no-op to avoid undocumented changes. The parameter object should be created and registered in the processor constructor (after possible auto-save restore). Pro: the parameter values are always strictly defined as coded. Con: the parameter values cannot be changed easily.
2. Modify values by editor, use auto-save to store. Create parameter object in analysis constructor. Auto-save must be enabled. Pro: parameter can modified by editor (UpdateFrom() method must be implemented) and changes will be restored from auto-save. Con: when the auto-save file must be deleted for some reasons. the latest values are lost.
3.
Use a macro to set values. This
macro must be executed in the processor constructor (after auto-save restore). UpdateFrom() could just execute
the macro to avoid undocumented changes. Pro: values are kept in a text file
and can be modified without recompile. Con: parameter cannot be changed by GUI
editor.
4.
Best combination: one can
use macro saveparam.C([file],wildcard,prefix) from $GO4SYS/macros creating macros
(one per parameter) to set all parameters to their current values,. The names
are built from prefix and parameter name. The macro can be executed in CINT
(then the parameters are taken from a file), or in the GUI or in the analysis.
The parameter is created in the analysis. Values are set from macro in processor
constructor. By this method parameter values can be edited by GUI, or macro can
be edited. Last version will be used independently of auto-save.
Example:
root[0].x
saveparam.C("myfile.root","*","setpar")
would produce macros setpar_par1.C,
setpar_par2.C etc. The macros have no arguments,
e.g. setpar_par1().
Conditions are objects holding window limits or polygons. One or two values can be checked against the limits or the polygon, respectively. In addition the conditions have test and true counters. They can be set to return always true or false or return the inverted test result. They can be edited by the GUI (see chapter 5.8.2, page 61). They can be used to steer the analysis flow. They are saved/retrieved to/from the auto-save file, if enabled. They can be edited in the auto-save file. In the editor they can be saved/retrieved to/from files. If a mechanism like for the parameters (4) is wanted, one can use macro savecond.C([file],wildcard,prefix) from $GO4SYS/macros creating macros (one per condition) to set all conditions to their current values,. The names are built from prefix and condition name. The macro can be executed in CINT (then the conditions are taken from a file), or in the GUI or in the analysis.
Example:
root[0].x savecond.C("myfile.root","*","setcon")
would produce macros setcon_cond1.C, setcon_cond2.C etc. The macros have three arguments: restore flags, restore counters, reset counters (0=no, 1=yes), e.g. setcon_cond1(1,0,1).
Once the user has defined his/her event class implementations, the analysis steps can be created and registered to the Go4 analysis framework. The actual framework consists of the TGo4Analysis class, which is a singleton (i.e. there is only one framework object in each process). This class provides all methods the user needs, it keeps and organizes the objects (histograms,...), it initializes and saves the data objects.
The user analysis is set up in a subclass of TGo4Analysis, i.e. TUserAnalysis. Constructor and destructor of this user class, in addition with the overridden virtual methods UserEventFunc(), UserPreLoop(), and UserPostLoop() specify the user analysis. If these functions are not needed, one can also use the TGo4Analysis class directly, as shown in the example Simple.
All analysis steps must be created with initial event parameters (input and output filenames) and auto-save settings. Additionally, some user objects may be created and registered here. Note that histograms created and registered here are saved to but not updated from the Go4 auto-save file. Persistent histograms of the analysis should be created in the UserPreLoop function. Existing conditions and parameters, however, are updated when the auto-save file is loaded. In the constructor of the TUserAnalysis class the analysis step objects are created, each containing instances of its user step factory. The analysis steps are registered at the TGo4Analysis framework, input and output events of subsequent steps are checked for matching. Furthermore, other objects like histograms, conditions or parameters can be created in the constructor and registered, so the framework is responsible for their persistence. Such objects can also be created in the step processors.
In addition to the event processors, the UserEventFunc() allows the user to specify analysis operations that are called once in each analysis cycle, e.g. filling certain histograms from the output events of all analysis steps. The UserEventFunc() makes it even possible to call an external analysis framework event by event without using the Go4 Analysis Steps at all, thus taking advantage of the Go4 object management and remote GUI features.
The UserPreLoop() and UserPostLoop() functions may define actions that are executed before starting, or after stopping the main analysis loop, respectively.
Once the user analysis class is defined, there are two modes of operation: The single-threaded batch mode, and the multi-threaded client mode that connects to the Go4 GUI.
Up to Go4 version 4.3 the user subclass of TGo4Analysis has been instantiated in the user main program MainUserAnalysis. In this case the arguments of the constructor could be chosen arbitrarily. With Go4 version v4.4 a standard main program (see next section) can replace the MainUserAnalysis. When using this main program the constructor of a TGo4Analysis derived user class is called with a standard argument list as it is used with main programs. The constructor of a user analysis must therefore be:
TUserAnalysis::TUserAnalysis(int argc, char** argv) : TGo4Analysis(argc, argv)
{
cout << "User analysis " << argv[0] << "created" << endl;
...
}
Note that argc is always > 0 and argv[0] is always the analysis name when called from standard main program.
Example
The user analysis could create one analysis step with input from an MBS file with the following code fragments (note that we use the standard Go4 step factory class and a fixed file name):
TUserAnalysis::TUserAnalysis(int argc, char** argv) : TGo4Analysis(argc, argv)
{
const char* userinput = “data.lmd”;
TGo4StepFactory* factory = new TGo4StepFactory("Factory");
// the objects specified here will be created by the framework later:
factory->DefEventProcessor("Proc","TUserProc");// object name, class name
factory->DefOutputEvent("Event","TUserEvent"); // object name, class name
TGo4MbsFileParameter* input = new TGo4MbsFileParameter(userinput);
TGo4AnalysisStep* step = new TGo4AnalysisStep("Analysis",factory,input,0,0);
step->SetSourceEnabled(kTRUE);
step->SetProcessEnabled(kTRUE);
AddAnalysisStep(step);
}
// Example of using the event loop
functions for a trivial counting of events
// fEvents must be defined in TUserAnalysis.h:
Int_t
TUserAnalysis::UserPreLoop() {
fEvents=0;
return 0;
}
Int_t TUserAnalysis::UserEventFunc() {
fEvents++;
return 0;
}
Int_t
TUserAnalysis::UserPostLoop() {
cout << " Total events: "
<< fEvents << endl;
return 0;
}
Contrary to previous Go4 versions, it is no longer required to provide a user main analysis program (typically called MainUserAnalysis). Instead, the standard go4analysis program instantiates and runs user code compiled into a shared library (typically called libGo4UserAnalysis.so). Most of the functionality previously implemented in MainUserAnalysis is now in the user analysis class (subclass of TGo4Analysis), which is instatiated by go4analysis. Existing analysis codes with explicit MainUserAnalysis program are still fully supported.
The main aim of batch mode is to process event data from files or other data source without GUI intervention. To run the analysis in batch mode, go4analysis is called from shell with several optional arguments. For instance, the command:
shell> go4analysis –file test.lmd –asf histos.root
will use file test.lmd as input and store all analysis objects (histograms, graphs) in file histos.root. The full description of the argument list is:
go4analysis
[RUN] [ANALYSIS] [STEP1] [STEP2] ...[USER]
RUN: configuration, relevant for application run mode
-lib name : user library to load
(default: libGo4UserLibrary)
-server [name] : run analysis in server mode,
name - optional analysis name
-gui name guihost
guiport : run analysis in gui mode,
used by GUI launch analysis
-http [port] : run analysis with web-server
running,
optionally port
can be specified, default 8080
-dabc
master_host:port : run analysis with
optional connection to dabc application,
which could
receive objects from running analysis
-run : run analysis in
server mode (default only run if source specified)
-norun : exclude automatical run
-number NUMBER : process NUMBER events in batch
mode
-hserver [name
[passwd]] : start histogram server
with optional name and password
-log [filename] : enable log output into filename
(default:go4logfile.txt)
-v -v0 -v1 -v2
-v3 : change log output
verbosity (0 - maximum, 1 - info, 2 - warn, 3 -errors)
-rate : display rate
information during run
-print [sub=N]
[hex|dec] : print events, see -help
print for more info
-help [topic] : show this help or for selected
topic
ANALYSIS: common analysis configurations
-name name :
specify analysis instance name
-asf [filename] :
enable store autosave file and set autosave filename (default
<Name>ASF.root)
-enable-asf
[interval] : enable store of autosave
file, optionally interval in seconds
-disable-asf :
disable usage of asf
-prefs
[filename] : load preferences (analysis configuration)
from specified file (default Go4AnalysisPrefs.root)
-no-prefs :
disable preferences loading
-maxtreesize
value : define maximum tree size, value can be: 2g,
1900m, 1900000000
STEP: individual step configurations
-step name :
select step by it's name, if not found, first step will be used
-step number :
select step by it's number (first step has number 0)
-enable-step :
enable step processing
-disable-step :
disable step processing
-file filename :
use file filename (lmd or lml) as MBS event source
-transport
server : connect to MBS transport server
-stream server :
connect to MBS stream server
-evserv server :
connect to MBS event server
-revserv server
[port] : connect to remote event server
-port number :
select custom port number for event source
-retry number :
select number of retries when connection to source was lost
-random :
use random generator as source
-user name :
create user-defined event source
-source
filename : read step input from the root file
-skip num :
skip num first events in mbs event source
-mbs-select first
last step : select events interval from mbs source
-timeout tm :
specify timeout parameter for event source
-enable-source :
enable step source
-disable-source :
disable step source
-store filename
[split buffersize compression] : write
step output into the root file
-overwrite-store : overwrite file, when store output
-append-store :
append to file, when store output
-backstore name :
create backstore for online tree draw
-enable-store :
enable step store
-disable-store :
disable step store
-enable-errstop :
enable stop-on-error mode
-disable-errstop : disable stop-on-error mode
-inpevt-class
name :
(re)define class name of input event
-outevt-class
name :
(re)define class name of output event
USER: user-defined arguments
-args [userargs] :
create user analysis with constructor (int argc, char** argv) signature
all following arguments will be provided as array of strings, first argument
- analysis name
A list of valid arguments can be obtained by launching go4analysis without any arguments. Execution of go4analysis can be terminated by pressing Ctrl-C. The analysis will regularly close all event sources, store results of processing in output files and then exit.
On startup go4analysis loads the shared user library and instantiates the user analysis. There is a possibility to pass extra configuration parameters to the user analysis constructor, calling go4analysis with -args or -x followed by a user specific parameter list. This list is passed to the analysis constructor:
Example
shell> go4analysis –name TestAna –args xxx.lmd
TUserAnalysis::TUserAnalysis(int argc, char** argv) : TGo4Analysis(argc, argv)
{
// argc is 2
// argv[0] is "TestAna"
// argv[1] is "xxx.lmd"
const char* userinput = “default.lmd”;
cout << "User analysis " << argv[0] << "created" << endl;
if (argc>1) userinput = argv[1];
TGo4MbsFileParameter* input = new TGo4MbsFileParameter(userinput);
...
}
Similar to the
argument list of the main() function argc defines number of parameters and argv contains parameter
values. First parameter in the list is always the analysis instance name (either
set in the GUI launch panel or by
–name argument, default is Go4Analysis). When go4analysis is started without user-specific arguments, only analysis
name will be in the list and argc is 1. The user argument list can also be specified in the Analysis launch
panel of the GUI.
In simple cases (only one step) it is not necessary to implement a user-specific analysis class at all. It is sufficient to implement a processor (and optionally an output event) class. In this case go4analysis will search for such classes in the loaded library and instantiate them, using the default TGo4Analysis instance and creating one default analysis step (named Analysis).
In the interactive GUI mode go4analysis provides all the infrastructure needed to manage the connection to the GUI. Usually, the Go4 GUI is started first and than user launches the analysis program via Launch analysis. Mainly for debugging purposes one can instead use in the GUI Prepare for client connection menu command and than start the analysis in an independent shell by command (same as it is called by GUI):
shell> go4analysis –gui SomeName guihost 5000
Here SomeName is an arbitrary analysis name, guihost is the host name where the GUI is started and 5000 is the port number (may be different, is printed when GUI starts). Same input/output arguments, as in batch mode, can be specified behind. On startup go4analysis creates the analysis framework and connects the multi-threaded analysis client to the Go4 GUI. After the connection is established, the complete analysis framework can be controlled from the GUI. In section 3.6.10, page 19 we describe in detail what is happening on startup of the analysis client and what effect the GUI control actions have.
When started from the GUI the analysis connects only this GUI and absolutely depends from it. If something happens with GUI or GUI just closed, analysis execution will be terminated. However, it is possible to run the analysis as a server, which allows to connect many GUIs (one controlling GUI and many observer GUIs).
The analysis is started as server independently from the GUI from a shell like in the batch mode but with argument –server
shell> go4analysis –server –stream mbs-server -norun
As in batch mode, in server mode analysis will start its event loop if input was specified. To prevent this, the -norun argument can be add. To force event loop execution with default analysis parameters, -run argument should be specified. An analysis to run in server mode can also be launched via Launch analysis menu command of the Go4 GUI when selecting the mode as server.
A Go4 GUI is able to connect any such started server. Login of GUI to the analysis server may be with observer, controller, or administrator role, respectively; their passwords can be set in user analysis code with DefineServerPasswords() method. There can be only one controller or administrator, but multiple observer GUIs. Observers may only view existing objects, but may not modify them or change analysis setup and running state. Controller may view and modify objects and analysis configuration, but is not allowed to terminate analysis server. Only Administrator may shutdown the analysis server.
See section 5.3.2, page 39 for more details on connection of the GUI client.
There are several methods to configure the analysis which can be combined in a defined order:
Constructor of user analysis class
In any case the constructor is called first. All steps must be created. One may set up all steps like setting input and output filenames, enable/disable steps. One may excecute a macro for that. One may use user arguments given by go4analysis command (behind –x) or in the Launch analysis panel (Args).
Go4 preferences file
When launched from GUI, or started from shell by go4analysis command with the –server or –gui option,
and settings had been saved before, these settings are now loaded from the file
overwriting the coded setup. Default file name is Go4AnalysisPrefs.root. With –noprefs or –prefs <file> one can disable this loading or specify a different file, respectively. In
the Analysis configuration panel a different file also can be loaded.
Arguments to go4analysis
When started from shell now the arguments of go4analysis are used and
overwrite the settings.
Hotstart file
When launched from GUI with hotstart file the complete setting from that file is used and overwrites the settings.
In previous go4 versions up to 4.3 it was required to have a user MainUserAnalysis program which was launched via the AnalysisStart.sh script. In most cases that executable can be used as is. Since version 4.4 the GUI directly calls the MainUserAnalysis executable (or program or script as specified in the Launch Analysis panel, see section 5.3, page 38) with same argument list as before. When AnalysisStart.sh script had been modified and therefore the old launch sequence is required, one should set shell variable GO4OLDLAUNCH=yes before starting the GUI.
In many real cases the go4analysis is able to correctly instantiate the user analysis, compiled into libGo4UserAnalysis.so library even if no (int, char**) constructor signature is implemented. To facilitate new Go4 functionality and flexibility, it is recommended to move user code from MainUserAnalysis to user analysis class, (i.e. TUserAnalysis) and remove MainUserAnalysis.
For launching the analysis on remote host from the GUI, password-less ssh login on this host must be enabled. It means, when typing “ssh hostname” command in the shell, no any password shall be requested. To configure such password-less login, a private/public key pair must be created and the public key must be copied to remote host:
shell> ssh-keygen –t rsa
shell> ssh-copy-id -i ~/.ssh/id_rsa.pub hostname
From historical reason there is still rudimentary support of rsh for analysis launch. rsh in no longer supported in GSI, therefore it is not so good tested as other launch methods. For use of rsh, make sure that the file .rhosts exists in user home directory and that it contains entries for the machine names you want to run the Go4 analysis client on. The file .rhosts could e.g. look like this:
node01
node02
localhost
When starting the Go4 analysis from GUI, the following actions take place in that order:
1.
The Launch
Analysis GUI panel started by reads settings from file $GO4SYS/etc/go4.prefs. Based on settings in this file, the launch command is composed and
executed. Depending on the analysis mode (client or server) either -server or
-gui argument lists are passed to the executable.
2. TGo4Analysis or user subclass (e.g. TUserAnalysis) is instantiated and initializes the analysis framework.
3. The analysis, if in client mode, connects to the Go4 GUI. Optionally, the Go4 histogram/object server is created. Note that the analysis in server mode does not connect automatically to the starting GUI, but waits for a separate connect request with login and password from any GUI. Only after this explicit connection the GUI gets control over the analysis server!
4.
The analysis settings are
loaded from the default preferences file Go4AnalysisPrefs.root. A message is sent to the GUI (if successful):
“Analysis
Client MyClient: Status Loaded from file Go4AnalysisPrefs.root”
Note that all settings specified before
in the compiled code (auto-save file name, event sources, etc.) are overwritten
if the preferences file exists.
5. The configuration settings are now changed by additional arguments, provided to go4analysis executable.
6.
The analysis objects are loaded
and updated from the auto-save file. The file name from the loaded analysis
settings is used, if existing. Otherwise, the filename specified in the
preceding user code by SetAuto-saveFile(const
chart* name) is used. If successful, a message is
sent to the GUI:
”Analysis
Client MyClient: Objects Loaded”.
If auto-saving was disabled completely by calling
SetAutoSave(kFALSE), the auto-save file is not opened here even if it exists, and no
objects are loaded! The “overwrite filename” option in the auto-save
settings must be disabled to recover objects of a previous auto-save file;
otherwise, all objects in an old file of the same name are lost!
7. The analysis settings are displayed on the GUI. At this moment, the analysis configuration window pops up and shows the active settings. Note that a GUI, connected to an analysis server, only in administrator mode can change the analysis configuration.
8.
End of analysis start-up. A
message is sent to the GUI:
“Analysis
Client MyClient has finished initialization”.
Note that now the analysis itself is not yet
initialized, i.e. the event and processor objects have not been created, and there are still no connections to event sources, etc.
At any
time the user may apply new settings to the analysis and start/stop the run. Note
that if the GUI runs as client connected to an analysis server, these
operations are permitted for controller or administrator login only. The
following is happening in the described order:
1. Submit the analysis settings. The settings as displayed in the analysis configuration window are sent to the analysis client.
i. First, an already existing analysis is closed (see below).
ii. The analysis is initialized with the new settings. Objects are loaded from the new auto-save file except auto-save is disabled by SetAutoSave(kFALSE). The file name is as specified in the configuration window.
iii. The event objects are created. Event sources and stores are opened. The constructors of all user events and event processors are executed. Note that any object (histogram, parameter, etc) which is created and registered in the user event constructors might replace an object of same name that was loaded from the auto-save file before! To continue working with the loaded objects, the user should request pointer to the object by name from the framework here. Only if the object was not found it should be created anew. Since Go4 v4.4 there are methods to return references to objects which are created only if not loaded from auto-save file.
After
submit, the Analysis browser can be refreshed by . When an analysis was running before, the new
analysis is started immediately and the refresh is done automatically.
2.
Start the analysis with :
i. The Go4 GUI will send the start command and refresh the view in the analysis browser.
ii. The UserPreLoop() function is executed once. Here transient pointers to data might be initialized, values from a user file might be read, etc.
iii. The Analysis event loop is starting. For each event the analysis steps, the dynamic list entries, and the UserEventFunc() are executed. The loop will run until the event source is at the end, an error occurs, or the stop command is applied by the user.
3.
Stop the analysis with :
i.
The event loop is halted. This
will not close the analysis itself, i.e. all event objects still exist, event
sources and -stores are still open. When restarting the analysis by ,
it will continue with the next event.
ii. The UserPostLoop() function is executed once. Here transient pointers should be reset to 0, user files might be written or closed, etc.
4. Save configuration settings: At any time the current settings can be saved to a preferences file. This will not affect the running analysis. Note that after changing the settings in the analysis configuration window they must first be submitted to save them!
5.
Load Settings: Loading analysis settings from a preferences file will
immediately close the running analysis. The closing actions are just as
described below. However, the loaded settings are not initialized until they
have been Submitted again from
the analysis configuration window!
The
analysis client is shut down with the button. This will take the following actions:
1. The connection between analysis and GUI is closed.
2. The destructor of the user analysis class is executed.
3.
Close of the analysis (this step can be executed by button ):
i. Objects are written to the previous auto-save file, if SetAutoSave(kTRUE).
ii. The event objects are deleted. Go4 event sources (.lmd files and MBS connections) are closed. Event stores (.root files) are finally written and closed. The destructors of all user events and event processor classes are executed. All references to the event objects are deleted from the Go4 folders.
iii. The dynamic list is reset. All pointers to non existing objects are cleaned up.
4. The analysis client executable terminates. The Go4 GUI is ready to connect the next analysis client.
The GUI may
disconnect the analysis server with the button. This
will neither stop the analysis nor shutdown the server task, but just close the
connections to this GUI. Additionally, when connected to an analysis
server, the GUI has a
button in the analysis toolbar and a menu for Shutdown Analysis server. This is permitted in administrator mode only! This will take the
following actions:
1.
Analysis server broadcasts
message about shutdown to all GUI clients connected. The GUIs will cease
monitoring activities and prepare for disconnect.
2.
The destructor of the user
analysis class is executed.
3.
Close of the analysis, see details in 3.6.12
4.
The analysis server disconnects
all GUI clients fast, i.e. without handshaking protocol, and terminates.
To begin with Go4, there are examples of analysis packages at $GO4SYS/Go4ExampleSimple, $GO4SYS/Go4Example1Step, $GO4SYS/Go4Example2Step, $GO4SYS/Go4ExampleAdvanced, $GO4SYS/Go4ExampleUserSource and $GO4SYS/Go4ExampleMesh. The differences are:
Example |
Analysis |
Step
factories |
Event
objects |
Steps |
Simple |
TGo4Analysis |
TGo4StepFactory |
TGo4EventElement |
Analysis |
1Step |
TXXXAnalysis |
TGo4StepFactory |
TXXXEvent |
Analysis |
2Step |
TXXXAnalysis |
TXXXUnpackFact |
TXXXUnpackEvent |
Unpack |
Advanced |
TXXXAnalysis |
TXXXUnpackFact |
TXXXUnpackEvent |
Unpack |
UserSource |
TYYYAnalysis |
TYYYUnpackFact |
TYYYRawEvent TYYYUnpackEvent |
Unpack |
Mesh |
TMeshAnalysis |
TGo4StepFactory |
|
13 different |
If one is going to develop a new analysis with Go4 it is recommended to start with one of the examples. The question is which one? To make this decision easier, here some considerations:
How many steps do I need? The usage of steps has two aspects:
đ modularity of the code: what is the natural granularity. Unpack, calibrate, filter, physics? Subdetectors?
đ design of data generations. Are there event filters?
đ storage versus computing. Are the processed data bigger than the raw? Is the analysis compute bound?
Modularity of analysis code could be achieved in a single step simply by a chain of function calls of one or several classes. However it would get complicated if one wants to disable functions because their successing function would need their data. This problem is solved by Go4 steps. The events filled by the step processors can be stored in ROOT files (trees). The steps produce data generations. These files can then be used as input for subsequent steps replacing the generating step which can be disabled. With two steps one needs at least one output event (filled and stored by first step) and processed by second step. Note that ROOT files produced by any step can be processed by stand-alone macros. In this sense there can be always a final step outside Go4 processing the files of the last step.
Therefore one should first think about data generations and structures.
Start with this example if you want just produce histograms from raw data. All coding is in one file. No output event file can be written. Histograms can be saved in ROOT file.
This example has an output event which can be stored in a ROOT file which can be processed by macros. In addition it has a user analysis class where the functions UserPreLoop, UserPostLoop and UserEventFunc are implemented.
In addition we have here two steps. This example also demonstrates how one can configure the analysis completely by a setup macro.
When using Go4 at GSI where it is already installed, Go4 is set up by
. go4login
Note that there must be a space behind the dot. To see all relevant environment variables use command
go4version
The output of this command would be helpful if you report problems.
Analysis example programs are started by
go4analysis
or from the GUI which is started by
go4
Copy the content of the directory $GO4SYS/Go4Example1(2)Step to a separate location. You can directly make and run the example. The package consists of the following files:
· Readme.txt
· Makefile
· Declaration (*.h) files
· Implementation (*.cxx) files
· XXXLinkDef.h - ROOTCINT class pragma definitions
Cleanup all previously generated files by:
shell> make clean
In all examples there is one string included in all class and file names: “XXX”. It is recommended to replace this by another string more specific for user task. This is done by rename.sh script, provided together with Go4 distribution. For example, change to “Ship” can be done with:
shell> $GO4SYS/build/rename.sh "XXX" "Ship"
Note that "Ship" will be part of all class and file names, therefore do not use a string which is already in any filename!
To build example, just:
shell> make all
This will create shared library libGo4UserAnalysis.so and libGo4UserAnalysis.rootmap.
The package $GO4SYS/Go4ExampleSimple contains a simplest running Go4 analysis. It contains only one default analysis step and uses the standard Go4 analysis classes TGo4Analysis, TGo4StepFactory and TGo4EventElement. Therefore the functions UserPreLoop(), UserPostLoop(), and UserEventFunc() are not available. No data can be stored in the output event. The example uses some conditions and some parameter objects. The step is reading events from a standard MBS event source, preferably the MBS random source, filling some histograms. No output file is written. The analysis processes up to eight long word values from up to two sub events.
Analysis must be launched via library libGo4UserAnalysis.so.
Processor class: TXXXProc
The analysis, analysis factory, and analysis step (all standard Go4 classes) are created in the go4analysis program automatically. The input can be specified via go4analysis input arguments. The only custom code is implemented in processor class. No user event class is used in this example. Members of TXXXProc are histograms, conditions and parameter pointers. In the constructor of TXXXProc the histograms, parameters and conditions are created. Method BuildEvent() - called event by event - gets a dummy output event pointer as argument, but cannot fill any output data. The input event pointer is retrieved from the framework. In the first part, data from the raw input MBS event are copied to arrays of TXXXProc. Two sub-events (crate 1,2) are processed. Then the histograms are filled, the 2d one with polygon conditions.
Parameter class TXXXParam
In this class one can introduce parameters values and use them in all steps. Parameters can be modified from GUI.
See also chapter 5.4.4, page 43. By default auto-save is enabled for batch, disabled with the GUI. The name of the file is built from the name of input (file, server) like <input>_AS.root. If autosave file enabled all objects are saved into this ROOT file at the end of the event loop. At startup the auto-save file is read and all objects are restored from that file. From GUI, objects are loaded from auto-save file when the Submit button is pressed. Note that histograms are not cleared. One can inspect the content of the auto-save file with the Go4 GUI.
All lines with **** are from the example classes.
shell> go4analysis -random
-number 100000
Event processor TXXXProc of name
XXXProc
Output event TGo4EventElement of
name XXXOutputEvent
GO4-*> Welcome to Go4 Analysis
Framework Release v4.3.2 (build 40302) !
GO4-*> Create factory Factory
GO4-*> Analysis: Added analysis
step Analysis
**** Main: starting analysis in
batch mode ...
GO4-*> Opening AutoSave file
Go4AutoSave.root , UPDATE mode
GO4-*> Analysis LoadObjects:
Loading from autosave file Go4AutoSave.root
LoadObjects with Dirscan...
GO4-*> AutoSave file
Go4AutoSave.root was closed.
GO4-*> Factory: Create input
event for MBS
**** Event MbsEvent-10-1 has source
Random class: TGo4MbsRandom
GO4-*> Factory: Create event
processor XXXProc
**** TXXXProc: Create instance
XXXProc
GO4-*> Factory: Create output
event XXXOutputEvent
**** Event XXXOutputEvent has
source XXXProc class: TXXXProc
GO4-*> AnalysisStepManager --
Initializing EventClasses done.
GO4-*> Analysis BaseClass
-- Initializing EventClasses done.
GO4-*> Analysis loop for 100000
cycles is starting...
GO4-*> Analysis Implicit Loop
has finished after 100000 cycles.
GO4-*> Opening AutoSave file
Go4AutoSave.root , RECREATE mode
GO4-*> AutoSave file
Go4AutoSave.root was closed.
**** TXXXProc: Delete instance
GO4-*> Analysis Step
Manager -- Analysis Steps were closed.
**** Main: Done!
Creating a new class
Provide the definition and implementation files (.h and .cxx)
Add class in XXXLinkDef.h
Then make all.
Most probably you will change TXXXParam to keep useful parameters.
Then definitely you will change TXXXProc to create your histograms, conditions, pictures, and finally write your analysis function BuildEvent().
The package $GO4SYS/Go4Example1Step contains a Go4 analysis with one analysis step. It uses the standard Go4 step factory TGo4StepFactory, but a user written TXXXAnalysis. In this class the functions UserPreLoop(), UserPostLoop(), and UserEventFunc() can be used. It uses some conditions and some parameter objects. The step is reading events from a standard MBS event source, preferably the MBS random source, filling some histograms and an output event. The analysis processes up to eight long word values from up to two sub events. All classes are defined and declared in two files (*.h and *.cxx). Additional descriptions are in the source files.
Analysis must be launched via library libGo4UserAnalysis.so.
Analysis class: TXXXAnalysis
In TXXXAnalysis the analysis step is created with the step factory and input and output parameters. Here the defaults are set concerning the event IO. Parameter objects of class TXXXControl also created.
Event class: TXXXEvent
Processor class: TXXXProc
The standard factory created in TXXXAnalysis keeps all information about the step. The TXXXEvent contains the data members to be filled in TXXXProc from the input event (MBS 10-1). The Clear() method must clear all these members (an array for each crate in the example). In the constructor of TXXXProc the histograms and conditions are created, and the pointers to the parameter objects (created in TXXXAnalysis) are retrieved. Function BuildEvent() - called event by event - gets the output event pointer as argument (TXXXEvent). The input event pointer is retrieved from the framework. In the first part, data from the raw input MBS event are copied to the members of output event TXXXEvent. Two sub-events (crate 1,2) are processed. Then the histograms are filled, the 2d one with polygon conditions.
Parameter class TXXXControl
This class has one member "fill" which is checked in TXXXProc->BuildEvent() to
fill histograms or not. The macro
setfill.C(n), n=0,1 can be used in the GUI to switch the filling on or off. It
creates macro histofill.C() which is actually used to set filling on or off (in TXXXProc). You can also modify histofill.C by editor before running
the analysis.
See also chapter 5.4.4, page 43. By default auto-save is enabled for batch, disabled with GUI. The name of the file is built from the input by
<input>_AS.root
If it is enabled all objects are saved into this ROOT file at the end of the event loop. At startup the auto-save file is read and all objects are restored from that file. When TXXXAnalysis is created, the auto-save file is not yet loaded. Therefore the objects created here are overwritten by the objects from auto-save file (if any), except histograms. From GUI, objects are loaded from auto-save file when the Submit button is pressed. Note that histograms are not cleared. One can inspect the content of the auto-save file with the Go4 GUI. Note that appropriate user libraries should be loaded into GUI to access data from auto-save file (see chapter 5.2, page 37).
All lines with **** are from the example classes.
shell> go4analysis
-file /GSI/lea/gauss.lmd
GO4-*> Welcome to Go4 Analysis Framework Release v4.3.2 (build
40302) !
GO4-*> Create factory Factory
**** Analysis: Create file input file.lmd
GO4-*> Analysis: Added analysis step Analysis
**** Main: starting analysis in batch mode ...
GO4-*> Opening AutoSave file Go4AutoSave.root , UPDATE mode
GO4-*> Analysis LoadObjects: Loading from autosave file
Go4AutoSave.root
LoadObjects with Dirscan...
GO4-*> AutoSave file Go4AutoSave.root was closed.
GO4-*> TGo4MbsFile: Open file /GSI/lea/gauss.lmd
GO4-*> Factory: Create input event for MBS
**** Event MbsEvent-10-1 has source /GSI/lea/gauss.lmd class:
TGo4MbsFile
GO4-*> Factory: Create event processor XXXProc
**** TXXXProc: Create instance XXXProc
**** TXXXControl: Histogram filling enabled
**** TXXXProc: Produce histograms
**** TXXXProc: Produce conditions
**** TXXXProc: Create condition
**** TXXXProc: Produce pictures
GO4-*> Factory: Create output event XXXEvent
**** TXXXEvent: Create instance XXXEvent
**** Event XXXEvent has source XXXProc class: TXXXProc
GO4-*> AnalysisStepManager
-- Initializing EventClasses
done.
GO4-*> Analysis BaseClass --
Initializing EventClasses done.
**** TXXXAnalysis: PreLoop
Input file: gauss.lmd
Tapelabel: DISK
UserName: goofy
RunID:
Explanation:
Comments:
GO4-*> Analysis loop is starting...
**** TXXXProc: Skip trigger event
First event #: 1
GO4-*> End of event source TGo4MbsFile:
/GSI/lea/gauss.lmd
-I-f_evt: no more event
**** TXXXAnalysis: PostLoop
Last event #: 16605 Total
events: 16605
GO4-*> Go4 EventEndException
appeared after 0 cycles.
**** TXXXAnalysis: Delete instance
GO4-*> Opening AutoSave file Go4AutoSave.root , RECREATE mode
GO4-*> AutoSave file Go4AutoSave.root was closed.
**** TXXXEvent: Delete instance
**** TXXXProc: Delete instance
GO4-*> Analysis Step Manager
-- Analysis Steps were closed.
**** Main: Done!
Creating a new class
Provide the definition and implementation files (.h and .cxx)
Add class in Go4UserAnalysisLinkDef.h
Then make all.
Most probably you will change TXXXParam to keep useful parameters.
Then you might change TXXXEvent to represent your event data.
Keep the Clear() method consistent with the data members!
Then definitely you will change TXXXProc to create your histograms, conditions,
pictures, and finally write your analysis function BuildEvent().
In TXXXAnalysis there are three more functions which eventually can be useful:
UserPreLoop () - called before event loop starts,
UserEventFunc() - called after each TXXXProc::BuildEvent(),
UserPostLoop () - called after event loop stopped.
The package $GO4SYS/Go4Example2Step contains an unpack step and an analysis step. It uses some conditions and some parameter objects. Step one is reading events from a standard MBS event source, preferably the MBS random source, filling some histograms and an output event. Step two uses this event as input and fills another output event and some more histograms. The analysis processes up to eight long word values from up to two sub-events.
The events are read from standard GSI event sources (in the GUI one can switch to MBS or event servers). Then the first user event processor is called (Unpack). This user event processor fills some histograms and the first user event (unpacked event) from MBS input event. Then the second user event processor is called (Analysis). This user event processor fills some other histograms and the second user event (calibrated event) from the first event. The events from the first and second step can optionally be stored in ROOT files (enabled from GUI). When a ROOT file with unpacked events exists, the first step can be disabled, and this file can be selected as input for the second step (from GUI).
In TXXXAnalysis the two steps are created. Here the defaults are set concerning the event IO. Then macro setup.C is executed at the end of TXXXAnalysis. Analysis must be launched from GUI via library libGo4UserAnalysis.so.
The whole step setup is done in macro setup.C. It gets two strings as argument which can be specified in command line
go4analysis
–x <type> <name>
or in the GUI Launch panel in the Args field. In setup.C the type string is used to determine the type of the source, the name string is used to compose file names:
idir/name.lmd or if string starts with @ @idir/name.lml
odir/name_AS.root
odir/name_unpacked.root
odir/name_analyzed.root
idir
and odir are
directories for the input and output files also specified in setup.C.
If the source type specified (-random, -transport, -stream, -file) is no file, name is used as MBS node name. When started from GUI, any Go4AnalysisPrefs file overwrites the settings from setup.C. When started from shell make sure that setup.C is correct!
The event filled: TXXXUnpackEvent
The processor: TXXXUnpackProc
The TXXXUnpackEvent contains the data members to be filled from the input event (MBS 10,1). Only the Clear() method must be changed to clear all these members.
The unpacking code is in the event processor TXXXUnpackProc. Members are histograms, conditions, and parameter pointers used in the event method BuildEvent().. In the constructor of TXXXUnpackProc the histograms and conditions are created, and the pointers to the parameter objects (created in TXXXAnalysis) are set. BuildEvent() called event by event and gets the output event as argument. The input event is retrieved from the framework. The first eight channels of crate one and two are filled in histograms Cr1Ch01-08 … Cr2Ch01-08, respectively. His1g is filled under condition cHis1 on channel 0, His2g under condition cHis2 on channel 1. When editing conditions cHis1,2 histograms His1,2 filled by channel 0,1 will be displayed automatically to set/display the condition values. Picture condSet shows histograms His1,2 on top, His1,2g at bottom. Open the condition editor in the view panel of the picture. Conditions cHis1,2 will be selectable. They are displayed in the pad where they should be set. Both conditions are attached to the picture (see chapter 5.8.4, page 63). Histogram Cr1Ch1x2 is filled for three polygon conditions: polycon, polyconar[0], polyconar[1], all on the same values as the histogram.
Processing the input event and filling an output event it might be necessary to control the following behaviour:
1. Specify if the output event shall be written to output file (if enabled)
Bool_t isValid;
. . . . – code - . . .
out_evt->SetValid(isValid); // isValid
must be set before to kTRUE or kFALSE
return isValid;
Note
that the default calling Fill method
will set the validity of out_evt to the return value! If one would have a Fill method implemented in TXXXUnpackEvent calling BuildEvent the return value could be
handled differently there. A subsequent step should
check at the beginning if the input event (output event from previous step) was
valid. If not, it should mark its own output event also not valid and return:
Bool_t isValid=kFALSE;
if((inp_evt==0) || !inp_evt->IsValid()){
// input invalid
out_evt->SetValid(isValid); // invalid
return isValid; // return the same validity
}
isValid=kTRUE;
. . . . – code - . . .
out_evt->SetValid(isValid);
return isValid;
2. Specify if the following steps shall be skipped (optional message) by macro calls
GO4_SKIP_EVENT
GO4_SKIP_EVENT_MESSAGE("Skipped Event
%d",count-1)
3. Specify if the analysis shall be stopped immediatedly by macro calls
GO4_STOP_ANALYSIS
GO4_STOP_ANALYSIS_MESSAGE("Stopped after
Event %d",count-1)
The event filled: TXXXAnlEvent
The processor: TXXXAnlProc
The step two is build in the same way as step one.
Note that the TXXXUnpackEvent is used two times: once as output of step one, and once as input of step two.
The TXXXUnpackEvent instance can be filled by previous unpack step, or can be retrieved from input file. Step one must be disabled in the second case. The user method BuildEvent() always gets the pointer to the correct event. Histogram Sum1 is filled by first 4 channels of crate 1 and first 4 channels of crate 2. All channels are gated with condition wincon1. Histograms Sum2,3 are filled similar, but without gate, and shifted by XXXPar1,2->frP1. Histogram Sum1calib is filled like Sum1 without gate but with values calibrated by method TXXXCalibPar->Energy() of parameter calipar.
With the TXXXParameter class one can store parameters, and use them in all steps. Parameters can be modified from GUI by double click. There is a macro setparam.C which sets the values. One can disable histogramming in both steps. This doubles the processing speed and is useful if one only wants to create listmode files.
There are a few conditions created in TXXXUnpackProc. One (polycon) is used in XXXUnpack() for the accumulation of histogram Cr1Ch1x2. Another one (wincon1) is used in BuildEvent() of TXXXAnlProc to fill histogram Sum1. Conditions can be modified by double click in the browser. One can attach a histogram to a condition or attach conditions to picture pads to ensure that the condition is displayed/set on the proper display.
The package $GO4SYS/Go4ExampleAdvanced contains an unpack step and an analysis step. It uses some conditions and some parameter objects. Step one is reading events from a standard MBS event source, preferably the MBS random source, filling some histograms and an output event. Step two uses this event as input and fills another output event and some more histograms. The analysis processes up to eight long word values from up to two sub events.
The events are read from standard GSI event sources (in the GUI one can switch to MBS or event servers). Then the first user event processor is called (Unpack). This user event processor fills some histograms and the first user event (unpacked event) from MBS input event. Then the second user event processor is called (Analysis). This user event processor fills some other histograms and the second user event (calibrated event) from the first event. The events from the first and second step can optionally be stored in ROOT files (enabled from GUI). When a ROOT file with unpacked events exists, the first step can be disabled, and this file can be selected as input for the second step (from GUI).
In TXXXAnalysis the two steps are created with their factories and input and output parameters. Here the defaults are set concerning the event IO. When called with a user argument, setup.C macro is executed at the end of TXXXAnalysis.
Two parameter objects are created (TXXXParameter). They can be used in both steps.
Analysis must be launched from GUI via library libGo4UserAnalysis.so, or from shell by
go4analysis –args file
The event filled: TXXXUnpackEvent
The processor: TXXXUnpackProc
The TXXXUnpackEvent contains the data members to be filled from the input event (MBS 10,1). In contrast to the Go4Example2Step, we apply the TGo4CompositeEvent classes here. Details on the event structure are discussed in Chapter 8 on page 81.
The unpacking code is in the event processor TXXXUnpackProc. Members are histograms, conditions, and parameter pointers used in the event method BuildEvent().. In the constructor of TXXXUnpackProc the histograms and conditions are created, and the pointers to the parameter objects (created in TXXXAnalysis) are set. BuildEvent() called event by event and gets the output event as argument. The input event is retrieved from the framework. The first eight channels of crate one and two are filled in histograms Cr1Ch01-08 … Cr2Ch01-08, respectively. His1g is filled under condition cHis1 on channel 0, His2g under condition cHis2 on channel 1. When editing conditions cHis1,2 histograms His1,2 filled by channel 0,1 will be displayed automatically to set/display the condition values. Picture condSet shows histograms His1,2 on top, His1,2g at bottom. Open the condition editor in the view panel of the picture. Conditions cHis1,2 will be selectable. They are displayed in the pad where they should be set. Both conditions are attached to the picture (see chapter 5.8.4, page 63). Histogram Cr1Ch1x2 is filled for three polygon conditions: polycon, polyconar[0], polyconar[1], all on the same values as the histogram.
The event filled: TXXXAnlEvent
The processor: TXXXAnlProc
The step two is build in the same way as step one.
Note that the TXXXUnpackEvent is used two times: once as output of step one, and once as input of step two.
The TXXXUnpackEvent instance can be filled by previous unpack step, or can be retrieved from input file. Step one must be disabled in the second case. The user method BuildEvent() always gets the pointer to the correct event. Histogram Sum1 is filled by first 4 channels of crate 1 and first 4 channels of crate 2. All channels are gated with condition wincon1. Histograms Sum2,3 are filled similar, but without gate, and shifted by XXXPar1,2->frP1. Histogram Sum1calib is filled like Sum1 without gate but with values calibrated by method TXXXCalibPar->Energy() of parameter calipar.
With the TXXXParameter class one can store parameters, and use them in all steps. Parameters can be modified from GUI by double click.
TXXXCalibPar is an example how to use fitters in parameters to calibrate histograms (more chapter 5.11.3, page 69). Please have a look at the Readme.txt file in this example directory for a detailled description of the calibration procedure.
There are a few conditions created in TXXXUnpackProc. One (polycon) is used in XXXUnpack() for the accumulation of histogram Cr1Ch1x2. Another one (wincon1) is used in BuildEvent() of TXXXAnlProc to fill histogram Sum1. Conditions can be modified by double click in the browser. One can attach a histogram to a condition or attach conditions to picture pads to ensure that the condition is displayed/set on the proper display.
The package Go4ExampleUserSource shows a simple example of a user defined event source reading data from an ASCII text file. Like the one step example, the package can be copied to a user working environment, and the class names can be renamed replacing the “TYYY-” prefix.
To apply a user defined event source, method CreateEventSource() of the user step factory must be re-implemented to react on a TGo4UserSourceParameter when selected in the controlling GUI, or set as argument for the go4analysis batch executable . It should then create a TGo4EventSource subclass that the user implements for his purpose. Note that method CreateInputEvent() should also be overwritten to create a raw event matching to the user event source, since the default of the base class TGo4EventServerFactory always delivers a TGo4MbsEvent.
In this example the event source class TYYYEventSource is prepared to handle any ASCII file containing columns of data separated by blank spaces. Each row is read and its values are converted in order into the Double_t fdData array of the raw event class TYYYRawEvent. The array expands automatically depending on the number of columns. Lines starting with “!” or “#” characters are treated as comments and are ignored. Thus these two classes need not to be modified for input of any ASCII files of that type. However, both the unpack procedure as specified in the event processor TYYYUnpackProc , and the unpack event class TYYYUnpackEvent, are depending on the column’s meanings here and must be adjusted. Additional information can be found in the README.txt file of the example package.
This example on Go4ExampleMesh shows how to set up a Go4 analysis of several steps that build a mesh of parallel analysis branches with different result generations. Additionally, one can see how the improved TGo4FileSource class supports partial input from a ROOT tree.
The setup of the mesh analysis is done in the constructor of the TMeshAnalysis class. As in the Go4Example1Step, the general TGo4StepFactory is used to specify the event objects by name and class name. An overall of 13 analysis steps is defined for this example. Generally, the analysis mesh consists in two different kinds of steps, the execution steps and the provider steps. The unpack step, however, is as in the other examples just delivering sample data from a TGo4MbsSource (standard Go4 gauss example).
The step structure of the example mesh is as sketched in this figure (arrows show dataflow):
These analysis steps do the actual analysis work, i.e. they convert some input event into the output event. This is the same as in the more simple examples (2-Step). However, to realize a mesh structure, the execution steps do not work directly on their own input event as assigned from the Go4 framework, but use the input event of one or more provider steps. The execution steps can access the input event pointers of any provider step by the provider step name, using the GetInputEvent("stepname") method. Note that the native input event of the execution steps is never used here (except for the very first "Unpack" step that processes the initial MBS event directly, without a provider step). There are no histogramming actions in the execution steps. To view the result data one has to use a dynamic list histogram or perform a TTree::Draw on the output event's tree, if existing.
These analysis steps do not perform any analysis work at all, but only make sure that their own input event is always set correctly for the following execution steps, depending on the data flow situation. Generally, there are two cases:
- the provider step reads the input event directly from a branch of a ROOT tree (TGo4FileSource). In this case, the input event remains the native input event of this step as created in the step factory.
- the provider step refers to the result event of a previous execution step.
In this case, the provider processor itself has to find the correct event pointer by name from the Go4 object management. The default Go4 framework mechanism to handle these two cases will not suffice here, since it was designed for a subsequent order of steps and not for a mesh with parallel execution branches.
To do this job, all provider steps use the TMeshProviderProc class as general event processor, and the TMeshDummyEvent class as pseudo output event. The TMeshDummyEvent is necessary, because the Go4 framework will always call the Fill() method of the step's output event to execute any action of the step. So TMeshDummyEvent::Fill() calls method TGo4ProviderProc::SetRealInput() to set the pointer to the desired input event correctly.
If the input event is not read from file (native input event of this step), the provider processor has to search for it by name using the method TGo4Analysis::GetEventStructure("name"). However, the Go4 framework so far does not offer any additional parameter to specify the name of the appropriate input for a provider step. Therefore, this example uses the trick to derive the event name search string from the name of the provider processor itself: the name of this processor (up to the "_") is the name of the required event. Note that TGo4StepFactory forbids to use same names for different objects, since the object name is used as pointer name in the ProcessLine() call; therefore the processor name can not be identical with the input event name, but must differ by the "_" extension.
Additionally, the provider steps use the new partial input feature of the TGo4FileSource class (since Go4v2.9). The name of the event structure defines the name of the TTree branch that should be read from the input file. The first three provider steps use different parts of the TMeshRawEvent each. If the input event name is set to the name of the corresponding tree branch (e.g. "RawEvent.fxSub1"), the file source will only read this branch from the tree. If the input event name is set to the full name of the raw event ("RawEvent", commented out in this example), the complete event is streamed, including the not used parts. Note that in both cases the event object must consist in the full TMeshRawEvent, although in the partial input case only one sub-event is filled. This is required for a proper event reconstruction due to the ROOT TTree mechanism. In this example, the partial event input might increase the process speed by a factor of 2 compared to the full event input.
Although the step configuration can be defined as usual from the analysis configuration GUI, not all combinations of enabled and disabled steps make sense to process a subpart of the complete analysis mesh. For example, if execution step 2 shall be processed, the corresponding provider step for its input event has to be enabled, too. Note that the standard step consistency check of the Go4 framework is disabled here to run such a mesh at all (SetStepChecking(kFALSE)). So it is user responsibility to ensure that all required event objects are available for a certain setup. Moreover, with >13 analysis steps the standard analysis configuration GUI becomes quite inconvenient.
Therefore, the example uses a Go4 parameter TMeshParameter for the easy setup of the configuration. This parameter has just a set of boolean flags to determine which execution step shall be enabled. Depending on this setup, the UpdateFrom() method of the parameter also enables or disables the required provider steps. However, the parameter does not contain the full information of the input file names for the providers yet (In a "real" application, this could be implemented in a similar way though).
Thus the configuration procedure
looks like this. The TMeshParameter is edited on the GUI
to enable the desired execution steps. The parameter is send to analysis and
switches the steps on and off. Then the analysis configuration GUI has to be
refreshed by the user pressing button to view
the new setup. Here the user may change the names of the event sources for the
provider steps, if necessary. After submitting these settings again from the configuration
GUI, the mesh setup is ready. Note that once the mesh is configured in this
way, the configuration can be stored completely in the analysis preferences and
restored on the next startup.
One could also think of a user defined GUI that handles both the setup of the TMeshParameter, and the rest of the analysis configuration in one window. This would offer the additional advantage that it could show the structure of the analysis mesh in a graphical way. However, such a user GUI is not delivered here, but can be created according to the hints given in package Go4UserGUI (see chapter 5.16, page 74).
One way to test the example could look like this:
§ Enable the first unpack step, disable the rest of the mesh. Use TGo4MbsRandom as event source for the Unpack and fill the output event TMeshRawEvent into a ROOT tree (switch on TGo4FileStore of unpack step). Do this until a reasonable number of events are processed.
§ Disable the unpack step, enable one or more of the subsequent execution steps. The input for the first 3 provider steps should be the ROOT file that was produced before. Note that the first providers could also read their sub-events from different files. Eventually, produce further output trees from the execution steps.
§ Change the setup in a way that only one branch of the mesh is processed, e.g. only Exec3 and Final.
§ Change the setup in a way that only a certain generation of events is processed, e.g. only Exec1, Exec2, and Exec3, writing output files of their results. Alternatively, let only Exec12 and Final work, reading their provider inputs from these output files.
§ Change the example code and recompile to add another execution branch, e.g. with new steps for InputProvider4, Exec4, OutputProvider4, and collect the results in the existing final step. New classes TMeshB4InputEvent, TMeshB4AnlProc, and TMeshB4OutputEvent should be defined for this (these can be derived from the corresponding classes as existing for the Exec3 branch).
§ Create a new mesh analysis from this template that matches your analysis structure.
The GUI ist started from shell by command
go4
The following picture shows the GUI with all elements. On the right side you see the Go4 browser. The left side will be the display panel. Below is the Tree viewer, and under this the message window, the mbs monitor, and the analysis status display. With Show/Hide in the Settings one can configure the layout and save/restore it. All buttons in the top row are also available as pull down menus commands.
gui300
This would be the minimal look of a running analysis (the date is updated from the analysis):
There are many keyboard shortcuts to handle windows and actions. See chapter 11, page 90.
The icons in the
top line are grouped into three segments corresponding to the first three pull
down menus File, Tools, and Analysis.
Pull down |
Icon |
Function |
File |
|
Open: opens local ROOT file |
|
|
Open Remote: open TNetFile, TWebFile or TRFIOFile to access remote data |
|
|
Connect DABC: open connection to DABC data socket (optional) |
|
|
Open HServer: open connection to gsi histogram server |
|
|
Save memory: save content of the memory browser into a ROOT file |
|
|
Close all files: close all ROOT files opened in file browser |
|
|
Exit: closes
window and exit from GUI |
Tools |
|
View Panel: creates window (canvas) to display histogram(s) |
|
|
Fit Panel: opens fit panel |
|