Distributions

Introduction

The GAMOS distribution classes represent one-dimensional functions, which assing an output value for each input variable of the a given variable. In other words, they represent one-dimensional functions:

y = f(x)

In fact the correspondence between x and y values is read from a file, so that any arbitrary function shape can be easily defined.

There are currently three users of GAMOS distributions. We briefly describe them here and give further details in the corresponding section:

  • To bias a primary generator distribution. In this case the output values represent the probabilities of occurrence of the variables (e.g. position coordinate X, direction angle theta, energy, time).
  • To define the weights in importance sampling. A GAMOS data should be defined so that the input values are those of the data at each track step.
  • To define the index corresponding to each value for the classifier GmClassifierByDistribution. A GAMOS data should be defined so that the input values are those of the data at each track or track step.

Creating a distribution

A distribution has to be created with the command

/gamos/distribution DISTRIBUTION_NAME DISTRIBUTION_CLASS

where DISTRIBUTION_NAME is the name you give to the distribution, which will be used to assign it to an object and to define its parameters; and DISTRIBUTION_CLASS is the class name (see below for the list available distribution classes).

Assigning a GAMOS data

Except in the use of a GAMOS distribution is for primary generator biasing, you have to assign a GAMOS data. This data is the variable of the distribution, i.e. it will be used to extract the input value for each track or track step. To assign a data the following parameter should be used:

/gamos/setParam DISTRIBUTION_NAME:Data DATA_NAME

Reading values from a file

Many of the distributions described below need to read the data from a file. The parameter

/gamos/setParam DISTRIBUTION_NAME:FileName FILE_NAME

defines the name of the file that contains the distribution data. This file is a two column set of values, where the first column gives the input values (x) and the second the output values (y). After being read the input values are ordered in increasing order. To calculate the output value corresponding to an input value, each distribution uses its own algorithm, see below. If the input value is smaller than the minimum value in the file or bigger than the maximum value, an exception will be thrown, as the value cannot be calculated.

It is also possible to read the data from a histogram in ROOT or CSV format. In this case an extra parameter has to be provided to set the name of the histogram:

/gamos/setParam DISTRIBUTION_NAME:HistoName HISTO_NAME

The input values are taken as the centres of the histogram bins. The minimum and maximum values read are extended to the lower and upper edge of the histogram axis, i.e. minus and plus half a bin. If the input value is between this minimum and the lowest bin centre, the output is interpolated using the lowest and second lowest bins. Similarly for values between the maximum and the highest bin centre.

The type of the file will be automatically determined from the file name: if it ends by .csv it will be taken as a CSV format histogram file, if it ends by .root it will be taken as a ROOT format histogram file, else it will be taken as a text file. If you do not want to follow this convention then you have to set the file type explicitly by using the parameters:

/gamos/setParam DISTRIBUTION_NAME:FileNameCSV FILE_NAME

/gamos/setParam DISTRIBUTION_NAME:FileNameROOT FILE_NAME

Numeric distributions

A numeric distribution is a distribution where the input and output values are numbers. There are several classes of numeric distributions:

  • GmGaussianDistribution. The sigma and constant value of the Gaussian distribution has to be given as two extra parameters when the distribution is created. To assign the data, the following parameter must be used: /gamos/setParam DISTRIBUTION_NAME:Data DATA_1_NAME SIGMA CONSTANT
  • GmPolynomialDistribution. It can serve to define any polynomial distribution: f(x) = a_0 + a_1 * x + a_2 * pow(x,2) + …. The parameters a_i are given as extra parameters when the distribution is created. The number of extra parameters defines the order of the polynomial: POLYNOMIAL_ORDER = NUMBER_OF_PARAMETERS - 1. To assign the data, the following parameter must be used: /gamos/setParam DISTRIBUTION_NAME:Data DATA_1_NAME A0 A1 A2 …

The other numeric distributions are general ones: they read the input - output relationship from a file, so that any distribution shape can be defined. The distribution finds among the list of read input values (after ordering them) the two that are closest (i.e. one bigger and one smaller); then it interpolates the two output values corresponding to these two input values. The difference between the distributions described below lies in the way this interpolation is done.

GAMOS will check if the data value is inside the interval defined by the minimum and maximum of the distribution. If it is smaller, it will assign an index 0, if it is bigger it will assign an index INT_MAX (2^32). In both cases a warning will be printed. If you do not want to allow this behaviour, but you want that the job is stopped if the datais out of limits, you have to set the parameter:

/gamos/setParam DISTRIBUTION_NAME:AllowOutOfLimits 0

  • GmNumericDistributionLinLin. Interpolates linearly in the input and linearly in the output: f(x) = f(x_S) + (x-x_S)/(x_B-x_S)*(f(x_B)-f(x_S)) (where x_S and x_B are the closest smaller and bigger values of x read from the file).
  • GmNumericDistributionLogLin. Interpolates logarithmically in the input and linearly in the output: f(x) = f(x_S) + (log(x)-log(x_S))/(log(x_B)-log(x_S))*(f(x_B)-f(x_S)) (where x_S and x_B are the closest smaller and bigger values of x read from the file).
  • GmNumericDistributionLinLog. Interpolates linearly in the input and logarithmically in the output: f(x) = f(x_S) + exp( (x-x_S)/(x_B-x_S)*(log(f(x_B))-log(f(x_S))) ) (where x_S and x_B are the closest smaller and bigger values of x read from the file).
  • GmNumericDistributionLogLog. Interpolates logarithmically in the input and logarithmically in the output: f(x) = f(x_S) + exp( (log(x)-log(x_S))/(log(x_B)-log(x_S))*(log(f(x_B))-log(f(x_S))) ) (where x_S and x_B are the closest smaller and bigger values of x read from the file).
  • GmNumericDistributionLower. Takes the value corresponding to the closest smaller value: f(x) = f(x_S).
  • GmNumericDistributionUpper. Takes the value corresponding to the closest bigger value: f(x) = f(x_B).

String distributions

A string distribution is a distribution where the input values are strings (e.g. particle names, process names, volume names) and the output values are numbers. The values must be defined in a text file similar to the one for numeric distributions: two columns where the first column is a list of names and the second column the values that correspond to each name.

String data distribution

The GmStringDistribution is a general string distribution. It takes the value from the data associated to it, which has to be of type string (see chapter on Analysis

Geometrical biasing distribution

The GmGeometricalBiasingDistribution is a special distribution that serves to do geometrical biasing. For each track step it checks if the step is at a volume boundary and if so it calculates the output value as the division between the value at the end and the value at the beginning of the step (the PostStepPoint and PreStepPoint), else it returns 1. The file is supposed to contain in the first column the list of volume names and in the second the list of weights. Two data has to be assigned to it, what can be done with the parameters:

/gamos/setParam DISTRIBUTION_NAME:DataPre DATA_NAME

/gamos/setParam DISTRIBUTION_NAME:DataPost DATA_NAME

These data should be one of the volume data: FinalLogicalVolume and InitialLogicalVolume FinalPhysicalVolume and InitialPhysicalVolume, FinalTouchable and InitialTouchable, etc. But this is not enforced, so that you may find another use for this distribution.

If your geometry is complicated it may happen that at some place there is a frontier between two volumes with too different weights, so that if a track traverses this frontier it gets a too high index. To avoid this you may set a maximum value of the index with the parameter:

/gamos/setParam DISTRIBUTION_NAME:MaxValue VALUE

Another trick to give more flexibility to your biasing is to avoid that a tracks receives a weight given by this distribution several times

Ratio of distributions

You may define a distribution whose value is defined as the ratio of two distribution values. The distribution class is named GmDistributionRatio. The two distributions has to be defined with the parameters:

/gamos/setParam DISTRIBUTION_NAME:DistributionPre DISTRIBUTION

/gamos/setParam DISTRIBUTION_NAME:DistributionPost DISTRIBUTION