Classifiers

Introduction

A classifier is a class that contains a method that receives a G4Step or a G4Track and returns a different index (an integer) depending on some given criteria. In other words it classifies the step or track and returns the index of its classification. These classes are unique to GAMOS, as Geant4 does not provide this functionality.

Classifiers can act on user actions or scorers. If one or several classifiers are set to act on a user action, it is up to the concrete user action to determine which use it makes of them, or to ignore them. The most common use of classifiers by user actions is to produce a different histogram or table for each classification index. For details on classifiers acting on scorers see the section on Scorers.

The use of user actions and scorers together with classifiers is a powerful means to obtain very detailed information on the simulation through simple user commands. See the tutorial in section Histograms and scorers for more details on this.

Several classifiers need some extra parameters (see list of classifiers below) that control their behaviour. To use these classifiers they have to be declared first with the following command

/gamos/classifier CLASSIFIER_NAME CLASSIFIER_CLASS PARAMETER_1 PARAMETER_2 …

where CLASSIFIER_NAME is the new name you want to give to a classifier to attach it to a user action or to a scorer, CLASSIFIER_CLASS is the name of the classifier class, and PARAMETER_1 PARAMETER_2 … are the values of the parameters that the classifier needs. Those classifiers that do not need any parameter, can be assigned directly to a user action or a scorer without giving them a new name: the name will be the one of the classifier class.

To attach one classifier to a user action you put its name after the user action name in the command line that selects it

/gamos/userAction USER_ACTION CLASSIFIER_NAME

or you can use a classifier to act on a scorer with the command

/gamos/scoring/assignClassifier2Scorer CLASSIFIER_NAME SCORER_NAME

If you want to use more than one classifier for a user action or a scorer, you have to use the classifier GmCompoundClassifier (see below).

Each classifier has a method, GetIndexName(G4int index), that returns a different name for each index value. If a classifier does not implement this method, the one in the base class returns the index number converted to a string. This method is used by user actions and scorers to add the index number to the name of the histograms, tables or scores.

Classifiers are plug-in’s, so that a user an create her/his own classifier and select it with a user command. To learn how to do this, see the instructions in the section Creating your plug-in, using the GmClassifierFactory, or the Histograms and scorers tutorial.

The following classifiers are currently implemented in GAMOS:

  • GmPSClassifierBy1Ancestor: It assigns a different index to different copy numbers of a volume. It has an extra parameter that sets the level of the ancestor; if it is N = 0, it will use the copy numbers of the volume itself, if it is N > 0, it will look for the copy numbers of the N-th ancestor
  • GmPSClassifierByAncestors: It assigns a different index to different copy numbers of the sensitive volume. It has two extra parameters that set the number of ancestor levels (NAncestor) and the maximum number of copies in a level (NShift). The index is built as a sum of NShift:sup:`N` * copyNumber_of_Nancestor from N=0 to N=NAncestor-1
  • GmClassifierByLogicalVolume: It assigns a different index to different logical volumes
  • GmClassifierByPhysicalVolume: It assigns a different index to different physical volumes
  • GmClassifierByPhysicalVolumeReplicated: See discussion about PhysicalVolumeReplicated filters
  • GmClassifierByRegion: It assigns a different index to different regions
  • GmClassifierByMaterial: It assigns a different index to different volume materials
  • GmClassifierByKineticEnergy: The user must define a minimum, a maximum and a width of the energy intervals. It creates kinetic energy (at PreStepPoint) intervals with these values and assigns a different index to different intervals
  • GmClassifierByProcess: It assigns a different index to different process names that define the G4Step
  • GmClassifierByParticleProcess: It assigns a different index to different particle-process name pairs that define the G4Step. This means that the ionisation for electrons and positrons will produce a different index, despite the process being called the same for both particles
  • GmClassifierByCreatorProcess: It assigns a different index to different track creator process names
  • GmClassifierByParticle: It assigns a different index to different particle types
  • GmClassifierByPrimaryParticle: It assigns a different index following the particle type for the primary that originated the current particle, or the particle itself if it is a primary
  • GmClassifierBySecondariesList: It builds a list of the secondary particle names in alphabetical order, without repeating names, and assigns a different index to each list
  • GmClassifierBySecondariesListExclude: It builds a list of the secondary particle names in alphabetical order, without repeating names, and assigns a different index to each list. When the classifier is defined, you can add as parameter a list of particles and they will be excluded from the list
  • GmClassifierByHadronicReaction: It builds the name of the hadronic reaction, and assigns a different index to each reaction name. The name is built taking into account the target nucleus, the projectile and the emitted particles, without taking into account the gammas, except in the case of neutron capture. Examples of reaction names are: Be9(n,p)Li9, Fe56(p,pn)Fe55, Pb208(a,p)Tl211
  • GmCompoundClassifier: This classifier receives a list of classifiers and builds an index as Classifier_1*NShift+Classifier_2*NShift*NShift+… Where NShift is defined by the parameter /gamos/setParam GmCompoundClassifier:NShift NSHIFT, that by default takes a value of 100. Be aware that the classifier index is stored as a 32-bit integer, so be careful that the index is not too big (bigger than 232).

Filters are plug-in’s, so that a user can create her/his own filter and select it with a user command. To learn how to do this, see the instructions in the section Creating your plug-in, using the GmClassifierFactory.

Setting indices to classifiers

In most classifiers by default the indices are built automatically as the objects of classification appear and they start with 0 and grow one by one. You may want to change this behaviour (it may be specially useful if you are using importance sampling). To do it you should use the command:

/gamos/classifier/setIndices VALUE_1 INDEX_1 VALUE_2 INDEX_2

where VALUE_ii are the names of the objects of classifications (logical volumes, process names, …), and INDEX_ii are the new indices. In the case of classifier GmClassifierByParticleProcess you need two values for each index: particle name and process name.

You should be careful to list all the values that may appear in the classifier. If not, GAMOS will automatically assign an index to the new values, starting with the number following the maximum index defined with the user command. The exceptions are the classifiers GmClassifierBy1Ancestor and GmClassifierByAncestors, for which all values should be given.

Classifiying on secondary data

As mentioned above the classifiers take the data to be classified from a G4Step or a G4Track. But when a classifier is used by GmSecondaryTrackHistosUA (see chapter on Analysis it may be useful that the classification is based on the data of the secondary particles created in the step. To get this behaviour it should be used the parameter:

/gamos/setParam CLASSIFIER_NAME:OnSecondary 1