functionOfTime

functionOfTime

Stores values calculated as a function of time and time-step, usually for the purpose of combining results from other histories

Histories of kind=functionOfTime are ostensibly that: they record a value that depends on the time \(t\) and time-step \(n\). However, their main purpose is to look up results from other Histories and other Vorpal objects, and combine them in different ways.

If one places a UserFunc of kind=historyFunc inside histCalc (see historyFunc), then histCalc can use the result from another history in its calculation. It’s important that one pay attention to the order of histories in the input file: usually one wants the other history (referenced by the historyFunc) to precede the history that uses it.

functionOfTime Parameters

histCalc (code block, required)

An Expression <Expression histCalc> that takes two arguments, t (a scalar float) and n (a scalar integer). Typically this Expression will contain local functions that look up values in other Vorpal objects (e.g., fieldFunc).

backupHistCalc (code block, optional)

An Expression <Expression backupHistCalc> with the same argument- and result-types as <Expression histCalc>, to be evaluated if evaluation of histCalc fails, and if warningLevel < 3.

lastResortHistCalc (code block, optional)

An Expression <Expression lastResortHistCalc> with the same argument- and result-types as <Expression 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.

Note

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).

functionOfTime History Example

<History frequencyEstimate>
 kind = functionOfTime
 <Expression applySteps>
  expression = (n > 0)
 </Expression>
 <Expression histCalc>
  <UserFunc freqSqrEstWeight>
    kind = historyFunc
    history = frequencyMoments
    index = [0]
  </UserFunc>
  <UserFunc freqSqrEstSum>
    kind = historyFunc
    history = frequencyMoments
    index = [1]
  </UserFunc>
  <UserFunc freqSqrEstSumSqr>
    kind = historyFunc
    history = frequencyMoments
    index = [2]
  </UserFunc>
  $ F2_AVGexpr = (freqSqrEstSum(0)/freqSqrEstWeight(0))
  $ MSDEVexpr = (freqSqrEstSumSqr(0)/freqSqrEstWeight(0) - F2_AVGexpr^2)
  expression = vector( \
     sqrt(F2_AVGexpr), \
     if(MSDEVexpr > 0., MSDEVexpr, 0.) )
  resultVecDescriptions = [ "frequency estimate (Hz)"  "mean square deviation of frequency-squared (Hz^4)" ]
 </Expression>
</History>