Geant4手册目录
Geant4: 9.2.  Analysis Manager Classes

9.2.  Analysis Manager Classes

The analysis manager classes provide uniform interfaces to the g4tools package and hide the differences between use of g4tools classes for the supported output formats (ROOT, AIDA XML, CSV and HBOOK).

An analysis manager class is available for each supported output format:

  • G4CsvAnalysisManger
  • G4RootAnalysisManger
  • G4XmlAnalysisManger
  • ExG4HbookAnalysisManger

For a simplicity of use, each analysis maneger provides the complete access to all interfaced functions though it is implemented via a more complex design.

The managers are implemented as singletons. User code will access a pointer to a single instance of the desired manager. The manager has to be created and deleted from the user code. All objects created via analysis manager are deleted automatically with the manager. The concrete types of the analysis manager as well as the handled g4tools objects, are hidden behind a namespace which is selected by including a dedicated include file. This allows the user to use all output technologies in an identical way via these generic types:

  • G4AnalysisManger: the public analysis interface
  • G4AnaH1[2,3]: one[two,three]-dimensional histogram
  • G4AnaP1[2]: one[two]-dimensional profile
  • G4Ntuple: ntuple

In addition to the G4AnalysisManager functions, a set of Geant4 UI commands for creating histograms and setting their properties is implemented in associated messenger classes.

In order to avoid a dependence of the Geant4 kernel libraries on CERNLIB the ExG4HbookAnalysisManger class is not included in the Geant4 analysis class category but in examples/extended/common/analysis together with all necessary configuration files for its build with the CERNLIB libraries.

9.2.1.  Analysis Manager

To use Geant4 analysis, an instance of the analysis manager must be created. The analysis manager object is created with the first call to G4AnalysisManager::Instance(), the next calls to this function will just provide the pointer to this analysis manager object. The client code is responsible for deleting the created object what is in our example done in the run action destructor.

The example of the code for creating the analysis manager extracted from the basic B4 example is given below:

#include "B4Analysis.hh"

B4RunAction::B4RunAction()
 : G4UserRunAction()
{ 
  // Create analysis manager
  G4AnalysisManager* analysisManager = G4AnalysisanalysisManagerager::Instance();
  analysisManager->SetVerboseLevel(1);
  analysisManager->SetFirstHistoId(1);
}

B4RunAction::~B4RunAction()
{
  delete G4AnalysisManager::Instance();  
}

It is recommended, but not necessary, to create the analysis manager in the user run action constructor and delete it in its destructor. This guarantees correct behavior in multi-threading mode. The code specific to the output format is hidden in B4Analysis.hh where the selection of the output format takes place.

#ifndef B4Analysis_h
#define B4Analysis_h 1

#include "g4root.hh"
//#include "g4xml.hh"
//#include "g4csv.hh"
#endif

The level of informative printings can be set by SetVerboseLevel(G4int). Currently the levels from 0 (default) up to 4 are supported.

The verbose level can be also set via the UI command:

/analysis/verbose level

9.2.2.  Files handling

The analysis manager can handle only one base file at a time. Below we give an example of opening and closing a file extracted from the basic example B4:

#include "B4Analysis.hh"

void B4RunAction::BeginOfRunAction(const G4Run* run) 
{ 
  // Get analysis manager
  G4AnalysisManager* analysisManager = G4AnalysisManager::Instance();
  
  // Open an output file
  analysisManager->OpenFile("B4");
}

void B4RunAction::EndOfRunAction(const G4Run* aRun)
{
  // Save histograms
  G4AnalysisManager* analysisManager = G4AnalysisManager::Instance();
  analysisManager->Write();
  analysisManager->CloseFile();
}

The following functions are defined for handling files:

  G4bool OpenFile(const G4String& fileName = "");
  G4bool Write(); 
  G4bool CloseFile(); 

The file name can be defined either directly with OpenFile(const G4String&) call or separately via SetFileName(const G4String&) function before calling OpenFile(). It is not possible to change the file name when a file is open and not yet closed. If a file extension is not specified in fileName, it is automatically completed according to a selected output format.

The file can be optionally structured in sub-directories. Currently only one directory for histograms and/or one directory for ntuples are supported. The directories are created automatically if their names are set to non-empty string values via SetHistoDirectoryName(const G4String&) and/or SetNtupleDirectoryName(const G4String&). This setting is ignored with the output formats which do not support this feature (XML, CSV).

The following commands for handling files and directories are available:

/analysis/setFileName name           # Set name for the output file
/analysis/setHistoDirName name       # Set name for the histograms directory
/analysis/setNtupleDirName name      # Set name for the histograms directory

Depending on the selected output format more files can be generated when more than one ntuple is defined in a user application. This is the case of XML and CSV, which do not allow writing more than one ntuple in a file. The ntuple file name is then generated automatically from the base file name and the ntuple name.

The analysis manager can handle only one base file at a time, but several base files can be generated sucessively from Geant4 session, typically one file is saved per run. A new file can be open only after a previous file was closed. An example of generated more files per session is provided in basic/B5 example and its run2.mac macro. Appending existing files is not supported. When an existing file is open again, its content is overwritten.

9.2.3.  Histograms

The code for handling histograms given in the following example is extracted the B4 example classes. In this example, the histograms are created in the run action constructor and they are filled in the end of event.

#include "B4Analysis.hh"

B4RunAction::B4RunAction()
 : G4UserRunAction()
{ 
  // Create analysis manager
  // ...

  // Creating histograms
  analysisManager->CreateH1("1","Edep in absorber", 100, 0., 800*MeV);
  analysisManager->CreateH1("2","Edep in gap", 100, 0., 100*MeV);
}

void B4aEventAction::EndOfEventAction(const G4Run* aRun)
{
  // Fill histograms
  G4AnalysisManager* analysisManager = G4AnalysisManager::Instance();
  analysisManager->FillH1(1, fEnergyAbs);
  analysisManager->FillH1(2, fEnergyGap);
}

9.2.3.1.  Creating Histograms

A one-dimensional (1D) histogram can be created with one of these two G4AnalysisManager functions:

  G4int CreateH1(const G4String& name, const G4String& title,
                 G4int nbins, G4double xmin, G4double xmax,
                 const G4String& unitName = "none",
                 const G4String& fcnName = "none",
                 const G4String& binSchemeName = "linear");

  G4int CreateH1(const G4String& name, const G4String& title,
                 const std::vector<G4double>& edges,
                 const G4String& unitName = "none",
                 const G4String& fcnName = "none");

where name and title parameters are self-descriptive. The histogram edgeds can be defined either via the nbins, xmin and xmax parameters (first function) representing the number of bins, the minimum and maximum histogram values, or via the const std::vector<G4double>& edges parameter (second function) representing the edges defined explicitly. The other parameters in both functions are optional and their meaning is explained in Section 9.2.3.6.

Two-dimensional (2D) and three-dimensional (3D) histograms can be created with one of these two functions analogous to those for 1D histograms:

  G4int CreateH2(const G4String& name, const G4String& title,
                 G4int nxbins, G4double xmin, G4double xmax, 
                 G4int nybins, G4double ymin, G4double ymax,
                 const G4String& xunitName = "none", 
                 const G4String& yunitName = "none",
                 const G4String& xfcnName = "none", 
                 const G4String& yfcnName = "none",
                 const G4String& xbinScheme = "linear",
                 const G4String& ybinScheme = "linear");
  
  G4int CreateH2(const G4String& name, const G4String& title,
                 const std::vector<G4double>& xedges,
                 const std::vector<G4double>& yedges,
                 const G4String& xunitName = "none", 
                 const G4String& yunitName = "none",
                 const G4String& xfcnName = "none", 
                 const G4String& yfcnName = "none");

  G4int CreateH3(const G4String& name, const G4String& title,
                 G4int nxbins, G4double xmin, G4double xmax, 
                 G4int nybins, G4double ymin, G4double ymax,
                 G4int nzbins, G4double zmin, G4double zmax,
                 const G4String& xunitName = "none", 
                 const G4String& yunitName = "none",
                 const G4String& zunitName = "none",
                 const G4String& xfcnName = "none", 
                 const G4String& yfcnName = "none",
                 const G4String& zfcnName = "none",
                 const G4String& xbinSchemeName = "linear",
                 const G4String& ybinSchemeName = "linear",
                 const G4String& zbinSchemeName = "linear");
   
  G4int CreateH3(const G4String& name, const G4String& title,
                 const std::vector<G4double>& xedges,
                 const std::vector<G4double>& yedges,
                 const std::vector<G4double>& zedges,
                 const G4String& xunitName = "none", 
                 const G4String& yunitName = "none",
                 const G4String& zunitName = "none",
                 const G4String& xfcnName = "none", 
                 const G4String& yfcnName = "none",
                 const G4String& zfcnName = "none");

The meaning of parameters is the same as in the functions for 1D histograms, they are just applied in x, y and z dimensions.

The histograms created with G4AnalysisManager get automatically attributed an integer identifier which value is returned from the "Create" function. The default start value is 0 and it is incremented by 1 for each next created histogram. The numbering of 2D and 3D histograms is independent from 1D histograms and so the first created 2D (or 3D) histogram identifier is equal to the start value even when several 1D histograms have been already created.

The start histogram identifier value can be changed either with the SetFirstHistoId(G4int) method, which applies the new value to all histogram types, or with the SetFirstHNId(G4int), where N = 1, 2, 3 methods, which apply the new value only to the relevant histogram type. The first method is demonstrated in the example.

The histogram names "1", "2" in the demonstrated example are defined to correspond the histograms identifiers in a similar way as in extended/analysis/AnaEx01 example. This choice is however fully in hands of the user who can prefer longer and more meaningful names.

All histograms created by G4AnalysisManager are automatically deleted with deleting the G4AnalysisManager object.

Histograms can be also created via UI commands. The commands to create 1D histogram:

/analysis/h1/create               # Create 1D histogram
   name title [nbin min max] [unit] [fcn] [binScheme]    

The commands to create 2D histogram:

/analysis/h2/create               # Create 2D histogram
  name title [nxbin xmin xmax xunit xfcn xbinScheme nybin ymin ymax yunit yfcn yBinScheme] 

The commands to create 3D histogram:

/analysis/h3/create               # Create 3D histogram
  name title [nxbin xmin xmax xunit xfcn xbinScheme nybin ymin ymax yunit yfcn yBinScheme nzbin zmin zmax zunit zfcn zBinScheme] 

9.2.3.2.  Configuring Histograms

The properties of already created histograms can be changed with use of one of these two functions sets. For 1D histograms:

  G4bool SetH1(G4int id,
               G4int nbins, G4double xmin, G4double xmax,
               const G4String& unitName = "none",
               const G4String& fcnName = "none",
               const G4String& binSchemeName = "linear");

  G4bool SetH1(G4int id,
               const std::vector<G4double>& edges,
               const G4String& unitName = "none",
               const G4String& fcnName = "none");

for 2D histograms:

  G4bool SetH2(G4int id,
               G4int nxbins, G4double xmin, G4double xmax, 
               G4int nybins, G4double ymin, G4double ymax,
               const G4String& xunitName = "none", 
               const G4String& yunitName = "none",
               const G4String& xfcnName = "none", 
               const G4String& yfcnName = "none",
               const G4String& xbinSchemeName = "linear",
               const G4String& ybinSchemeName = "linear");

  G4bool SetH2(G4int id,
               const std::vector<G4double>& xedges,
               const std::vector<G4double>& yedges,
               const G4String& xunitName = "none", 
               const G4String& yunitName = "none",
               const G4String& xfcnName = "none", 
               const G4String& yfcnName = "none");

and for 3D histograms:

  G4bool SetH3(G4int id,
               G4int nxbins, G4double xmin, G4double xmax, 
               G4int nzbins, G4double zmin, G4double zmax,
               G4int nybins, G4double ymin, G4double ymax,
               const G4String& xunitName = "none", 
               const G4String& yunitName = "none",
               const G4String& zunitName = "none",
               const G4String& xfcnName = "none", 
               const G4String& yfcnName = "none",
               const G4String& zfcnName = "none",
               const G4String& xbinSchemeName = "linear",
               const G4String& ybinSchemeName = "linear",
               const G4String& zbinSchemeName = "linear");

  G4bool SetH3(G4int id,
               const std::vector<G4double>& xedges,
               const std::vector<G4double>& yedges,
               const std::vector<G4double>& zedges,
               const G4String& xunitName = "none", 
               const G4String& yunitName = "none",
               const G4String& zunitName = "none",
               const G4String& xfcnName = "none", 
               const G4String& yfcnName = "none",
               const G4String& zfcnName = "none");

The histogram is accessed via its integer identifier. The meaning of the other parameters is the same as in "Create" functions.

Histogram properties can be also defined via UI commands. The commands to define 1D histogram:

/analysis/h1/set id nbin min max [unit] [fcn] [binScheme] # Set parameters

The commands to define 2D histogram:

# Set parameters for the 2D histogram of #id
/analysis/h2/set                  
  id nxbin xmin xmax xunit xfcn xbinScheme nybin ymin ymax yunit yfcn yBinScheme  

# Set parameters per dimension
/analysis/h2/setX id nbin min max [unit] [fcn] [binScheme] # Set x-parameters
/analysis/h2/setY id nbin min max [unit] [fcn] [binScheme] # Set y-parameters

The commands to define 3D histogram:

# Set parameters for the 3D histogram of #id
/analysis/h3/set =
  id nxbin xmin xmax xunit xfcn xbinScheme nybin ymin ymax yunit yfcn yBinScheme nzbin zmin zmax zunit zfcn zBinScheme 

# Set parameters per dimension
/analysis/h3/setX id nbin min max [unit] [fcn] [binScheme] # Set x-parameters
/analysis/h3/setY id nbin min max [unit] [fcn] [binScheme] # Set y-parameters
/analysis/h3/setY id nbin min max [unit] [fcn] [binScheme] # Set z-parameters

A limited set of parameters for histograms plotting, the histogram and the histogram axis titles, can be also defined via functions:

  G4bool SetH1Title(G4int id, const G4String& title);
  G4bool SetH1XAxisTitle(G4int id, const G4String& title);
  G4bool SetH1YAxisTitle(G4int id, const G4String& title);
  //
  G4bool SetH2Title(G4int id, const G4String& title);
  G4bool SetH2XAxisTitle(G4int id, const G4String& title);
  G4bool SetH2YAxisTitle(G4int id, const G4String& title);
  G4bool SetH2ZAxisTitle(G4int id, const G4String& title);
  //
  G4bool SetH3Title(G4int id, const G4String& title);
  G4bool SetH3XAxisTitle(G4int id, const G4String& title);
  G4bool SetH3YAxisTitle(G4int id, const G4String& title);
  G4bool SetH3ZAxisTitle(G4int id, const G4String& title);

The corresponding UI commands:

/analysis/h1/setTitle id title                  # Set title for the 1D histogram of #id
/analysis/h1/setXaxis id title                  # Set x-axis title for the 1D histogram
/analysis/h1/setYaxis id title                  # Set y-axis title for the 1D histogram

The same set of commands is available for the other histogram types and profiles, under the appropriate directory.

9.2.3.3.  Filling Histograms

The histogram values can be filled using the functions:

  G4bool FillH1(G4int id, G4double value, 
                G4double weight = 1.0);
  G4bool FillH2(G4int id, G4double xvalue, G4double yvalue,
                G4double weight = 1.0);
  G4bool FillH3(G4int id, 
                G4double xvalue, G4double yvalue, G4double zvalue,
                G4double weight = 1.0);

where the weight can be given optionally.

The histograms can be also scaled with a given factor using the functions:

  G4bool ScaleH1(G4int id, G4double factor);
  G4bool ScaleH2(G4int id, G4double factor);
  G4bool ScaleH3(G4int id, G4double factor);    

9.2.3.4.  Accessing Histograms

Besides the fast access to histograms via their integer identifiers, the histograms can be also accessed by their names using the G4AnalysisManager function providing the conversion from a name in a histogram identifier:

  G4int GetH1Id(const G4String& name, G4bool warn = true) const;
  G4int GetH2Id(const G4String& name, G4bool warn = true) const;
  G4int GetH3Id(const G4String& name, G4bool warn = true) const;

If a histogram with a given name is not found, a warning is issued unless it is explicitly disabled by the user. This way is however less efficient and it is not recommended for frequently called functions as e.g. Fill().

The analysis manager provides also the direct access to the g4tools histogram objects. The concrete histogram type is hidden behind a selected namespace. In example B4, the g4tools histogram functions mean() and rms() are called:

  G4AnalysisManager* analysisManager = G4AnalysisManager::Instance();
  if ( analysisManager->GetH1(1) ) {
    G4cout << "\n ----> print histograms statistic \n" << G4endl;
    G4cout << " EAbs : mean = " << analysisManager->GetH1(1)->mean() 
           << " rms = " << analysisManager->GetH1(1)->rms(), 
           << G4endl;
    // ...           
  }             

9.2.3.5.  Activation of Histograms

The activation option allows the user to activate only selected histograms. When this option is activated, only the histograms marked as activated are returned, filled or saved in a file. This feature is intensively used in extended/electromagnetic examples where all histograms are first created inactivated:

  G4AnalysisManager* analysisManager = G4AnalysisManager::Instance();
  analysisManager->SetActivation(true);
  // define histogram parameters name, title, nbins, vmin, vmax
  G4int id = analysisManager->CreateH1(name, title, nbins, vmin, vmax);
  analysisManager->SetH1Activation(id, false);

and then selected histograms are activated in macros, using the analysis "set" command:

/analysis/h1/set 1 100 0   50 cm        #track length of primary
/analysis/h1/set 2 100 0  300 none      #nb steps of primary

The activation option is not switched on by default. It has to be activated either via analysisManager SetActivation(true) call as above or via the UI command:

/analysis/setActivation true|false   # Set activation option

When no parameters need to be changed a histogram can be activated using "setActivation" command:

/analysis/h1/setActivation id true|false     # Set activation to histogram #id
/analysis/h1/setActivationToAll  true|false  # Set activation to all 1D histograms.

9.2.3.6.  Histograms Properties

The following properties, additional to those defined in g4tools, can be added to histograms via G4AnalysisManager:

  • Unit: if a histogram is defined with a unit, all filled values are automatically converted to this defined unit and the unit is added to the histogram axis title.
  • Function: if a histogram is defined with a function, the function is automatically executed on the filled values and its name is added to the histogram axis title. When a histogram is defined with both unit and function the unit is applied first. The available functions: log, log10, exp .
  • Binning scheme: user can select logarithmic binning scheme besides the linear one (default). The available binning schemes: linear, log .
  • Activation: see previous section.
  • ASCII option: if activated the histogram is also printed in an ASCII file when Write() function is called.
  • Plotting option: if activated the histogram is plotted in a file of Postscript format when Write() function is called. See more details in Section 9.2.5.

9.2.4.  Profiles

Profile histograms (profiles) are used to display the mean value of Y and its error for each bin in X. The displayed error is by default the standard error on the mean (i.e. the standard deviation divided by the sqrt(n).) An example of use of 1D profiles can be found in extended/electromagnetic/TestEm2. Though the functions for creating and manipulating profiles are very similar to those for histograms, they are described in this section.

9.2.4.1.  Creating Profiles

A one-dimensional (1D) profile can be created with one of these two G4AnalysisManager functions:

  G4int CreateP1(const G4String& name, const G4String& title,
                 G4int nbins, G4double xmin, G4double xmax,
                 G4double ymin = 0, G4double ymax = 0,
                 const G4String& xunitName = "none", 
                 const G4String& yunitName = "none",
                 const G4String& xfcnName = "none", 
                 const G4String& yfcnName = "none",
                 const G4String& xbinSchemeName = "linear");

  G4int CreateP1(const G4String& name, const G4String& title,
                 const std::vector<G4double>& edges,
                 G4double ymin = 0, G4double ymax = 0,
                 const G4String& xunitName = "none", 
                 const G4String& yunitName = "none",
                 const G4String& xfcnName = "none", 
                 const G4String& yfcnName = "none");

where name and title parameters are self-descriptive. The profile edgeds can be defined either via the nbins, xmin and xmax parameters (first function) representing the number of bins, the minimum and maximum profile values, or via the const std::vector<G4double>& edges parameter (second function) representing the edges defined explicitly. If ymin and ymax parameters are provides, only values between these limnits will be considered at filling time. The other parameters in both functions are optional and their meaning is explained in Section 9.2.4.4.

A two-dimensional (2D) profile can be created with one of these two functions analogous to those for 1D profiles:

  G4int CreateP2(const G4String& name, const G4String& title,
                 G4int nxbins, G4double xmin, G4double xmax,
                 G4int nybins, G4double ymin, G4double ymax, 
                 G4double zmin = 0, G4double zmax = 0,
                 const G4String& xunitName = "none", 
                 const G4String& yunitName = "none",
                 const G4String& zunitName = "none",
                 const G4String& xfcnName = "none", 
                 const G4String& yfcnName = "none",
                 const G4String& zfcnName = "none",
                 const G4String& xbinSchemeName = "linear", 
                 const G4String& ybinSchemeName = "linear");

  G4int CreateP2(const G4String& name, const G4String& title,
                 const std::vector<G4double>& xedges,
                 const std::vector<G4double>& yedges,
                 G4double zmin = 0, G4double zmax = 0,
                 const G4String& xunitName = "none", 
                 const G4String& yunitName = "none",
                 const G4String& zunitName = "none",
                 const G4String& xfcnName = "none", 
                 const G4String& yfcnName = "none",
                 const G4String& zfcnName = "none");

The meaning of parameters is the same as in the functions for 1D profiles, they are just applied in x, y and z dimensions.

The profiles created with G4AnalysisManager get automatically attributed an integer identifier which value is returned from the "Create" function. The default start value is 0 and it is incremented by 1 for each next created profile. The numbering of 2D profiles is independent from 1D profiles and so the first created 2D profile identifier is equal to the start value even when several 1D profiles have been already created.

The start profile identifier value can be changed either with the SetFirstProfileId(G4int) method, which applies the new value to both 1D and 2D profile types, or with the SetFirstPNId(G4int), where N = 1, 2 methods, which apply the new value only to the relevant profile type.

All profiles created by G4AnalysisManager are automatically deleted with deleting the G4AnalysisManager object.

Profiles can be also created via UI commands. The commands to create 1D profile:

/analysis/p1/create               # Create 1D profile
  name title [nxbin xmin xmax xunit xfcn xbinScheme ymin ymax yunit yfcn] 

The commands to create 2D profile:

/analysis/p2/create               # Create 2D profile
  name title [nxbin xmin xmax xunit xfcn xbinScheme nybin ymin ymax yunit yfcn yBinScheme zmin zmax zunit zfcn] 

9.2.4.2.  Configuring Profiles

The properties of already created profiles can be changed with use of one of these two functions sets. For 1D profiles:

  G4bool SetP1(G4int id,
               G4int nbins, G4double xmin, G4double xmax,
               G4double ymin = 0, G4double ymax = 0,
               const G4String& xunitName = "none", 
               const G4String& yunitName = "none",
               const G4String& xfcnName = "none", 
               const G4String& yfcnName = "none",
               const G4String& xbinSchemeName = "linear");

  G4bool SetP1(G4int id,
               const std::vector<G4double>& edges,
               G4double ymin = 0, G4double ymax = 0,
               const G4String& xunitName = "none", 
               const G4String& yunitName = "none",
               const G4String& xfcnName = "none", 
               const G4String& yfcnName = "none");

and for 2D profiles:

  G4bool SetP2(G4int id,
               G4int nxbins, G4double xmin, G4double xmax, 
               G4int nybins, G4double ymin, G4double ymax, 
               G4double zmin = 0, G4double zmax = 0,
               const G4String& xunitName = "none", 
               const G4String& yunitName = "none",
               const G4String& zunitName = "none",
               const G4String& xfcnName = "none", 
               const G4String& yfcnName = "none",
               const G4String& zfcnName = "none",
               const G4String& xbinSchemeName = "linear",
               const G4String& ybinSchemeName = "linear");

  G4bool SetP2(G4int id,
               const std::vector<G4double>& xedges,
               const std::vector<G4double>& yedges,
               G4double zmin = 0, G4double zmax = 0,
               const G4String& xunitName = "none", 
               const G4String& yunitName = "none",
               const G4String& zunitName = "none",
               const G4String& xfcnName = "none", 
               const G4String& yfcnName = "none",
               const G4String& zfcnName = "none");

The profile is accessed via its integer identifier. The meaning of the other parameters is the same as in "Create" functions.

Profiles properties can be also defined via UI commands. The commands to define 1D profile:

/analysis/p1/set                  # Set parameters for the 1D histogram of #id
  id nxbin xmin xmax xunit xfcn xbinScheme ymin ymax yunit yfcn  

The commands to create or define 2D profile:

/analysis/p2/set                  # Set parameters for the 2D profile of #id
  id nxbin xmin xmax xunit xfcn xbinScheme nybin ymin ymax yunit yfcn yBinScheme zmin zmax zunit zfcn 

A limited set of parameters for profiles plotting, the profile and the profile axis titles, can be also defined via functions:

  G4bool SetP1Title(G4int id, const G4String& title);
  G4bool SetP1XAxisTitle(G4int id, const G4String& title);
  G4bool SetP1YAxisTitle(G4int id, const G4String& title);
  //
  G4bool SetP2Title(G4int id, const G4String& title);
  G4bool SetP2XAxisTitle(G4int id, const G4String& title);
  G4bool SetP2YAxisTitle(G4int id, const G4String& title);
  G4bool SetP2ZAxisTitle(G4int id, const G4String& title);

The parameters can be also set via the same set of UI commands as the histogram parameters available under the appropriate directory.

9.2.4.3.  Filling Profiles

The profile values can be filled using the functions:

  G4bool FillP1(G4int id, 
                G4double xvalue, G4double yvalue, 
                G4double weight = 1.0);
  G4bool FillP2(G4int id, 
                G4double xvalue, G4double yvalue, G4double zvalue, 
                G4double weight = 1.0);

where the weight can be given optionally.

The profiles can be also scaled with a given factor using the functions:

  G4bool ScaleP1(G4int id, G4double factor);
  G4bool ScaleP2(G4int id, G4double factor);

9.2.4.4.  Profiles Properties

All histogram features described in sections "Accessing Histograms", "Activation of Histograms" and "Histograms Properties" (Section 9.2.3.4, Section 9.2.3.5 and Section 9.2.3.6) are also available for profiles.

9.2.5.  Plotting

Since Geant4 10.2 version it is possible to produce a graphics output file in the Postscript format containing selected histograms and profiles. Histograms and profiles plotting can be activated using G4AnalysisManager functions:

  G4AnalysisManager* analysisManager = G4AnalysisManager::Instance();
  analysisManager->SetH1Plotting(id, true); 
     // etc for H2, H3, P1, P2

or using the UI commands

/analysis/h1/setPlotting id true|false     # (In)Activate plottig for 1D histogram #id
/analysis/h1/setPlottingToAll true|false   # (In)Activate plottig for all 1D histograms.
       # etc. for h2, h3, p1, p2

If Geant4 libraries are built with support for Freetype font rendering, user can choose from three plotting styles:

  • ROOT_default: ROOT style with high resolution fonts (default)
  • hippodraw: hippodraw style with high resolution fonts
  • inlib_default: PAW style with low resolution fonts")

otherwise only the inlib_default style with low resolution fonts is available.

The page size of the graphics output is fixed to A4 format. Users can choose the page layout which is defined by the number columns and the number of rows in a page. Depending on the selected plotting style, the maximum number of plots is limited to 3 columns x 5 rows for the styles with high resolution fonts and to 2 columns x 3 rows for the inlib_default style.

Finally, users can also customize the plot dimensions, which represent the plotter window size (width and height) in pixels.

The customization of the plotting can be done via the UI commands in /analysis/plot directory:

/analysis/plot/setStyle  styleName
/analysis/plot/setLayout  columns rows
/analysis/plot/setDimensions  width height

Opening more configuration parameters for users customisation can be considered in future according to the users feedback.

9.2.6.  Ntuples

In the following example the code for handling ntuples extracted from basic example B4, from the B4RunAction and B4EventAction classes, is presented.

#include "B4Analysis.hh"

B4RunAction::B4RunAction()
 : G4UserRunAction()
{ 
  // Create analysis manager
  // ...
  
  // Create ntuple
  man->CreateNtuple("B4", "Edep and TrackL");
  man->CreateNtupleDColumn("Eabs");
  man->CreateNtupleDColumn("Egap");
  man->FinishNtuple();
}

void B4EventAction::EndOfEventAction(const G4Run* aRun)
{
  G4AnalysisManager* man = G4AnalysisManager::Instance();
  man->FillNtupleDColumn(0, fEnergyAbs);
  man->FillNtupleDColumn(1, fEnergyGap);
  man->AddNtupleRow();  
}

Since 10.0 release, there is no limitation for the number of ntuples that can be handled by G4AnalysisManager. Handling of two ntuples is demostrated in extended analysis/AnaEx01 example.

9.2.6.1.  Creating Ntuples

An ntuple can be created using the following set of functions:

  G4int CreateNtuple(const G4String& name, const G4String& title);

  // Create columns in the last created ntuple
  G4int CreateNtupleXColumn(const G4String& name);
  void  FinishNtuple();   
  
  // Create columns in the ntuple with given id
  G4int CreateNtupleXColumn(G4int ntupleId, const G4String& name);
  void  FinishNtuple(G4int ntupleId); 

The first set is demonstrated in the example. The columns can take the values of G4int, G4float, G4double or G4Stringtype which is also reflected in the CreateNtupleXColumn() function names. where X can be I, F, D or S .

It is also possible to define ntuple columns of std::vector of G4int, G4float or G4double values using the functions:

  // Create columns of vector in the last created ntuple
  G4int CreateNtupleXColumn(
          const G4String& name, std::vector<Xtype>& vector);

  // Create columns of vector in the ntuple with given id
  G4int CreateNtupleXColumn(G4int ntupleId, 
          const G4String& name, std::vector<Xtype>& vector);

where [X, Xtype] can be [I, G4int], [F, G4float] or [D, G4double].

When all ntuple columns are created, the ntuple has to be closed using FinishNtuple() function.

The ntuples created with G4AnalysisManager get automatically attributed an integer identifier which value is returned from the "Create" function. The default start value is 0 and it is incremented by 1 for each next created ntuple. The start ntuple identifier value can be changed with the SetFirstNtupleId(G4int) function.

The integer identifiers are also attributed to the ntuple columns. The numbering of ntuple columns is independent for each ntuple, the identifier default start value is 0 and it is incremented by 1 for each next created column regardless its type (I, F, D or S). (If the third ntuple column of a different type than double (int or float) is created in the demonstrated example, its identifier will have the value equal 2.) The start ntuple column identifier value can be changed with the SetFirstNtupleColumnId(G4int) function.

When calls to CreateNtuple-Column() and FinishNtuple() succeed the call to CreateNtuple(), the ntupleId argument need not to be specified even when creating several ntuples. However this order is not enforced and the second set of functions with ntupleId argument is provided to allow the user to create the ntuples and their columns in whatever order.

All ntuples and ntuple columns created by G4AnalysisManager are automatically deleted with deleting the G4AnalysisManager object.

9.2.6.2.  Filling Ntuples

The ntuple values can be filled using the functions:

  // Methods for ntuple with id = FirstNtupleId                     
  G4bool FillNtupleIColumn(G4int id, G4int value);
  G4bool FillNtupleFColumn(G4int id, G4float value);
  G4bool FillNtupleDColumn(G4int id, G4double value);
  G4bool FillNtupleSColumn(G4int id, const G4String& value);
  G4bool AddNtupleRow();

  // Methods for ntuple with id > FirstNtupleId (when more ntuples exist)                      
  G4bool FillNtupleIColumn(G4int ntupleId, G4int columnId, G4int value);
  G4bool FillNtupleFColumn(G4int ntupleId, G4int columnId, G4float value);
  G4bool FillNtupleDColumn(G4int ntupleId, G4int columnId, G4double value);
  G4bool FillNtupleSColumn(G4int ntupleId, G4int id, const G4String& value);
  G4bool AddNtupleRow(G4int ntupleId);

If only one ntuple is defined in the user application, the ntuple identifier, ntupleId, need not to be specified and the first set can be used. The second set of functions has to be used otherwise. When all ntuple columns are filled, the ntuple fill has to be closed by calling AddNtupleRow().

9.2.6.3.  Accessing Ntuples

The ntuples g4tools objects can be accessed by their identifier. The concrete ntuple type is hidden behind a selected namespace:

  G4AnalysisManager* analysisManager = G4AnalysisManager::Instance();
  // If only one ntuple is defined
  G4Ntuple* ntuple = analysisManager->GetNtuple();
  // If more ntuples 
  G4int ntuple id = ...;
  G4Ntuple* ntuple = analysisManager->GetNtuple(ntupleId);

9.2.7.  Parallel Processing

As well as all other Geant4 categories, the analysis code has been adapted for multi-threading. In multi-threading mode, the analysis manager instances are internally created on the master and thread workers and data accounting is processed in parallel on workers threads.

Histograms produced on thread workers are automatically merged on Write() call and the result is written in a master file. Merging is protected by a mutex locking, using G4AutoLock utility. Ntuples produced on thread workers are written on separate files, which names are generated automatically from a base file name, a thread identifier and eventually also an ntuple name. No merging of ntuples is performed.

No changes are required in the user client analysis code for migration to multi-threading. It is however recommended to instantiate and delete the analysis manager in the user run action constructor and destructor respectively. The master instance is necessary when histograms are used in the user application; in case only ntuples are in use, the master instance need not to be created.

The HBOOK output is not supported in multi-threading mode.

To simplify the scaling of a Geant4 application across nodes on a cluster Geant4 provides the support of MPI. In particular it is possible to run a hybrid MPI/MT application that uses MPI to scale across nodes and MT to scale across cores. This is demonstrated in the extended example parallel/MPI/exMPI03 which includes usage of Geant4 analysis.

9.2.8.  Coexistence of Several Managers

The specific manager classes are singletons and so it is not possible to create more than one instance of an analysis manager of one type, eg. G4RootAnalysisManager. However two analysis manager objects of different types can coexist. Then instead of the generic G4AnalysisManager typedef the concrete type of each manager has to be given explicitly.

#include "G4CsvAnalysisManager.hh"
#include "G4XmlAnalysisManager.hh"

G4CsvAnalysisManager* csvManager = G4CsvAnalysisManager::Instance();
G4XmlAnalysisManager* xmlManager = G4XmlAnalysisManager::Instance();

Or:

#include "g4csv_defs.hh"
#include "g4xml_defs.hh"

G4Csv::G4AnalysisManager* csvManager = G4Csv::G4AnalysisManager::Instance();
G4Xml::G4AnalysisManager* xmlManager = G4Xml::G4AnalysisManager::Instance();

9.2.9.  Supported Features and Limitations

The analysis category based on g4tools is provided with certain limitations that can be reduced according to the feedback from Geant4 users and developers.

Below is a summary of currently supported features in Root, Csv and Xml manager classes:

  • Histogram types: 1D, 2D, 3D of double
  • Profile types: 1D, 2D of double
  • Ntuple column types: int, float, double, G4String, std::vector<int>, std::vector<float>, std::vector<double>
  • Optional directory structure limited to one directory for histograms and/or one for ntuples

The Hbook analysis manager does not support 3D histograms, 2D profiles and G4String and std::vector ntuple column types.

<-- Chapter 9. Analysis  9.3. Analysis Reader Classes --> "