cellFuncHist

Calculates a value in every cell, from a user-given function, which may reference fields, surfaces, etc., and combines all those values (e.g., by summing). This history is especially useful for surface and volume integrals, as well as peak fields.

Histories of kind=cellFuncHist are tensor histories that compute a result (a vector, or one-dimensional array of values) for every cell, and combine those results in some way to produce a result for the whole simulation.

For example, one might define the <UserFunc histCalc> to find a field value in a given cell, and multiply it by the volume of that cell. When the result is summed over all cells (reduceMethod = sum), it yields a volume integral.

Alternatively, one might use reduceMethod = max, in which case the maximum value (over all cells) would be returned.

cellFuncHist Parameters

These Histories take the following attributes:

lowerBounds (vectors of integers, optional, default=entire simulation): The lowerBounds and upperBounds specify the range of cells (with an exclusive upper bound, as usual in Vorpal) for which this history will perform its calculation.

upperBounds (vectors of integers, optional, default=entire simulation): The lowerBounds and upperBounds specify the range of cells (with an exclusive upper bound, as usual in Vorpal) for which this history will perform its calculation.

reduceMethod (required string in {sum, min, max}): The method by which the results from individual cells are combined to create the final result. If sum, the results are simply summed. If min or max, then the history result is the result from the cell for which the last component (of the histCalc result) is minimal or maximal, respectively.

histCalc (code block, required): A UserFunc <UserFunc histCalc> that takes one argument, named cell, which is a vector of NDIM integers specifying a grid-cell index. Typically this UserFunc will contain local functions that get recent information from other Vorpal objects (e.g., fieldFunc or gridBoundaryFunc). (See UserFunc Block)

lastResortHistCalc (code block, optional): A UserFunc <UserFunc lastResortHistCalc> with the same argument- and result-types as <UserFunc backupHistCalc>, to be evaluated if evaluation of backupHistCalc fails, and if backupWarningLevel < 3. If evaluation of this function fails, the simulation will halt.

resultVecDescriptions (vector of strings, optional): Associates a string description with each component of the history result, to be written in the dump file. If specified, the number of strings must equal the number of components in the history result; otherwise Vorpal will halt with an error.

warningLevel (integer in {0, 1, 2}, default 0)

Specifies what to do if evaluation of histCalc fails; if 0, simply evaluate: backupHistCalc; if 1, issue a warning only after the first failure, and evaluate backupHistCalc; if 2, issue a warning and evaluate backupHistCalc; if 3, halt the simulation. In a parallel simulation, evaluation may fail on one rank but not on another, so it may be important to search the output on each rank for warnings and error messages.

backupWarningLevel (same as warningLevel): The same as warningLevel, but applies to failure to evaluate backupHistCalc rather than histCalc. If backupWarningLevel is less than 3, and backupHistCalc fails, lastResortHistCalc will be evaluated instead (for that cell).

Use of backupHistCalc and lastResortHistCalc

Each cellFuncHist History has one to three <UserFunc>s that specify the function to be evaluated in each cell: histCalc, backupHistCalc, lastResortHistCalc. The function histCalc is evaluated for every cell; if, in any cell, evaluation fails, then backupHistCalc is evaluated for that cell instead; if evaluation fails again, lastResortHistCalc will be evaluated.

In such cases where field interpolation is performed, it is recommended that the backupHistCalc be used to obtain the same result, but (e.g, for a UserFunc of fieldFunc) with interpolationOrder = 0 (assuming the histCalc used a higher order). Since that might also fail, it is further recommended that lastResortHistCalc perform a fail-safe calculation that will not harm the final result, if possible; for example, when performing an integral, it might simply return 0.

While a small number of evaluation failures will hardly affect the result in many cases, there are of course cases that cannot tolerate such failures. In those cases, one should use the options warningLevel and backupWarningLevel to issue a warning or even halt the simulation if failure occurs.

If evaluation of lastResortHistCalc fails, the simulation will halt with an error message.

The use of UserFuncs that obtain values from other simulation entities allows cellFuncHist to be a very powerful tool, computing locations of peak field values, surface integrals, volume integrals, etc.

cellFuncHist History Example

The best place to see examples of powerful and complicated cellFuncHists is in the history macro file, hist.mac, which contains macros implementing CellFuncHists for calculating surface and volume integrals, etc.

# sum the values of field F
<History sum>
  kind = cellFuncHist
  reduceMethod = sum
  lowerBounds = [0 0 0]
  upperBounds = [NX NY NZ]
  # calculate history every fourth time step
  <Expression applySteps>
    expression = (mod(n, 4) == 0)
  </Expression>
  <UserFunc histCalc>
    kind = expression
    inputOrder = [cell]
    <Input cell>
      kind = uniformVector
      type = integer
      length = NDIM
    </Input>
    <UserFunc F>
      kind = fieldFunc
      result = fieldValue
      field = multiField.F
      interpolationOrder = 0
    </UserFunc>
    # since DX=1 and origin = 0, cell index and position are identical
      expression = F(cell)
  </UserFunc>
  resultVecDescriptions = ["sum of F"]
  # following is a rough memory size (in MB) that can always be
  # obtained: it's (very) small here for testing; normally it's best to
  # use the default value.
  maxMemChunkSize = 9.6e-5 # about 100 B
  # to use such a small value for testing, we need to set the following
  allowSmallMaxMemChunkSize = true
</History>