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.
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)histCalc fails; if 0, simply evaluatebackupHistCalc; 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).
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.
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>