Wrote MooseDocs page for BaselineCorrection

(refs idaholab#296)

doc/content/source/functions/BaselineCorrection.md

@@ -0,0 +1,186 @@
+# Baseline Correction
+
+The `BaselineCorrection` function applies a baseline correction to an acceleration time history, $\ddot{u}(t)$, and outputs the adjusted values. The corrections are performed by first computing the nominal (*uncorrected*) velocity, $\dot{u}$, and displacement, $u$, by the [Newmark-beta method](manuals/theory/index.md#time-integration). An $n$-th order polynomial approximation of the acceleration, velocity, and/or displacement is then found by the method of least squares and each are successively subtracted from the nominal acceleration to obtain the corrected one, $\ddot{u}^{\ast}$. That is, the corrected acceleration time history is given by the following:
+
+!equation id=corrected-accel
+\ddot{u}^{\ast}(t) = \ddot{u}(t) - \ddot{P}_{A}(t) - \ddot{P}_{V}(t) - \ddot{P}_{D}(t)
+
+Here, $P_{A}$, $P_{V}$, and $P_{D}$ are the least squares approximations of the acceleration, velocity, and displacement time histories, respectively, and the overhead dots represent their derivative order. The [#theory] section will explain how the corrections are made in greater detail. Finally, after $\ddot{u}^{\ast}(t)$ has been computed in accordance with [corrected-accel], it is linearly interpolated with respect to the real simulation time to ensure accurate results. Optionally, a scale factor may be applied to the final output.
+
+!alert note prefix=False title=[Correction Combinations](#scheme)
+It is possible to apply corrections using a best-fit of only one or any combination of the three kinematic variables, for which, any unused polynomials, $\ddot{P}$, $\dot{P}$, or $P$, would result in their values being zero in [corrected-accel]. See [#usage] for more information about how to control the adjustments.
+
+## Numerical Formulation id=theory
+
+This method for baseline correction of acceleration time histories was first presented in +(source)+ and later expanded upon in +(source)+<!--eventaully include reference to future journal paper from Chris Wong-->. To begin understanding the MASTODON implementation, consider a given acceleration, $\ddot{u}$, specified over $N$ time intervals. The nominal velocity, $\dot{u}$, and the nominal displacement, $u$, are obtained by integrating with the [Newmark-beta method](manuals/theory/index.md#time-integration):
+
+!equation id=newmark-gamma
+\dot{u}_{i+1} = \dot{u}_{i} + [(1 - \gamma) \Delta t] \ddot{u}_{i} + (\gamma \Delta t) \ddot{u}_{i} \, , \, \, \, \forall \, i = 0, 1, 2, ..., N - 2
+
+!equation id=newmark-beta
+u_{i+1} = u_{i} + (\Delta t) \dot{u}_{i} + [(0.5 - \beta) (\Delta t)^{2}] \ddot{u}_{i} + [\beta (\Delta t)^{2}] \ddot{u}_{i+1}
+
+When computing [newmark-gamma] and [newmark-beta], it is assumed that $\dot{u}_{0} = 0$ and that $u_{0} = 0$. The initial nominal acceleration, $\ddot{u}_0$, may be any arbitrary value.
+
+A least squares approximation is evaluated by minimizing the area bounded by the square difference between the nominal record, e.g., $\ddot{u}(t)$, and the best-fit, $n$-th order, polynomial itself, e.g., $\ddot{P}_{A}(t)$. For example, a best-fit polynomial of $\ddot{u}$ can be found by solving the following equation:
+
+!equation id=least-squares
+\dfrac{\partial}{\partial C_{k}} \int_{0}^{T} [\ddot{u}(t) - \ddot{P}_{A}(t)]^{2} \, dt = 0 \, , \, \, \, \forall \, k = 0, 1, ..., n
+
+Here, $T$ is the length of the record, i.e., the value corresponding to the final time-step, $i = N$, and $C_{k}$ are the $(n + 1)$ unknown coefficients of the polynomial, $\ddot{P}_{A}$. Rearranging [least-squares] and evaluating, wherever immediately possible, leads to the following $(n + 1) \times (n + 1)$ system of equations, for which to solve for the unknown polynomial coefficients:
+
+!equation id=linear-normal
+\sum_{j = 0}^{n} \dfrac{\left(j^{2} + 3 j + 2 \right) T^{k + j + 1}}{k + j + 1} C_{j} = \int_{0}^{T} t^{k} \ddot{u}(t) \, dt
+
+[linear-normal] could be written in matrix notation, i.e.,
+
+!equation id=linear-normal-system
+\mathbf{K} C = I
+
+In terms of Linear Algebra jargon, [linear-normal] or [linear-normal-system] are referred to as the linear +normal equations+. The definite integrals on the right-hand side of [linear-normal] is evaluated with a modified form of Newmark's method, i.e.,
+
+!equation id=newmark-definite
+I = \int_{0}^{T} t^{k} \ddot{u}(t) \, dt = \sum_{i = 0}^{N - 1} [(1 - \gamma) \Delta t] t_{i}^{k} \ddot{u}_{i} + (\gamma \Delta t) t_{i + 1}^{k} \ddot{u}_{i + 1}
+
+Once all components in $\mathbf{K}$ and in $I$ are known, any method for solving a dense, nonsymmetric, square system of equations can be applied to solve [linear-normal-system].
+The MASTODON implementation uses [libMesh's `lu_solve()`](https://libmesh.github.io/doxygen/classlibMesh_1_1DenseMatrix.html) method. Note that, the solution tends to become computationally unstable for $n \ge 10$.
+
+<!--need to reference this table in the body text, the adjusted values depend on which corrections are applied so see next section-->
+The complete set of equations used to construct a linear normal equation to solve for the coefficients of all three polynomial approximation types, $P_{A}$, $P_{V}$, and $P_{D}$, are given in [formulas]. These formulas were derived according to the same logic used for [least-squares], [linear-normal], and [newmark-definite]. The values for the adjusted time histories, $\ddot{u}^{\ast}(t)$, $\dot{u}^{\ast}(t)$, and $u^{\ast}(t)$, in the three "Least Squares Approximation" equations, depend on which combination of best-fit curves are applied to the correction (see [#scheme]).
+
+!table id=formulas
+       caption=Complete set of equations for constructing linear normal equations for the three correction types.
+| Best-fit\\ Polynomial | Least Squares\\ Approximation | $\mathbf{K}$ | $\bm{I}$ |
+| - | - | - | - |
+| $P_{A}$ | $\small \displaystyle \dfrac{\partial}{\partial C_{k}} \int_{0}^{T} [\ddot{u}^{\ast}(t)]^{2} \, dt = 0$ | $\small \displaystyle \sum_{j = 0}^{n} \dfrac{\left(j^{2} + 3 j + 2 \right) T^{k + j + 1}}{k + j + 1}$ | $\small \displaystyle I = \sum_{i = 0}^{N - 2} [(1 - \gamma) \Delta t] t_{i}^{k} \ddot{u}_{i} + (\gamma \Delta t) t_{i + 1}^{k} \ddot{u}_{i + 1}$ |
+| $P_{V}$ | $\small \displaystyle \dfrac{\partial}{\partial C_{k}} \int_{0}^{T} [\dot{u}^{\ast}(t)]^{2} \, dt = 0$ | $\small \displaystyle \sum_{j = 0}^{n} \dfrac{\left(j + 2 \right) T^{k + j + 3}}{k + j + 3}$ | $\small \displaystyle I = \sum_{i = 0}^{N - 2} (\Delta t) t_{i}^{k + 1} \dot{u}_{i} + \newline \left[ \left(\dfrac{1}{2} - \beta \right) (\Delta t)^{2} \right] \left(t_{i}^{k + 1} \ddot{u}_{i} + (k + 1) t_{i}^{k} \dot{u}_{i} \right) + \newline \left[\beta (\Delta t)^{2} \right] \left(t_{i + 1}^{k + 1} \ddot{u}_{i + 1} + (k + 1) t_{i + 1}^{k} \dot{u}_{i + 1} \right)$ |
+| $P_{D}$ | $\small \displaystyle \dfrac{\partial}{\partial C_{k}} \int_{0}^{T} [u^{\ast}(t)]^{2} \, dt = 0$ | $\small \displaystyle \sum_{j = 0}^{n} \dfrac{T^{k + j + 5}}{k + j + 5}$ | $\small \displaystyle I = \dfrac{1}{2} \sum_{i = 0}^{N - 2} (\Delta t) \left(t_{i + 1}^{k + 2} u_{i + 1} + t_{i}^{k + 2} u_{i} \right)$ |
+
+### Correction Scheme id=scheme
+
+Once the polynomial coefficients, $C_{k} \, \forall \, k = 0, 1, ..., n$, have been determined from [linear-normal-system] by substituting the necessary formulae given in [formulas], corrections are applied to all three kinematic variables in the following, general, way:
+
+!equation id=all-corrections
+\ddot{u}^{\ast}(t) = \ddot{u}(t) - \ddot{P}(t) = \ddot{u}(t) - \sum_{k = 0}^{n} (k^{2} + 3 k + 2) C_{k} t^{k}
+\newline \, \newline
+\dot{u}^{\ast}(t) = \dot{u}(t) - \dot{P}(t) = \dot{u}(t) - \sum_{k = 0}^{n} (k + 2) C_{k} t^{k + 1}
+\newline \, \newline
+u^{\ast}(t) = u(t) - P(t) = u(t) - \sum_{k = 0}^{n} C_{k} t^{k+2}
+
+The values for $\ddot{P}$, $\dot{P}$, and $P$ in [all-corrections], depend on the combination of best-fit curves used. [correction-combos] presents all possible combinations of the best-fit polynomials whose sum equal $P(t)$. Each polynomial approximation, $P_{A}$, $P_{V}$, and $P_{D}$, takes on the same form given by the rightmost terms in [all-corrections], but the coefficients will be different for each. It is also important to note that the adjustments always occur in a specific sequence and accumulate as each correction type is applied. See the [#example] section to understand what this means.
+
+!table id=correction-combos
+       caption=List of all possible combinations of the three correction types, along with their values for $P(t)$ for use in [all-corrections]. Here, +A+ denotes the acceleration correction, +V+ denotes the velocity correction, and +D+ denotes the displacement correction.
+| Combination | $\bm{P(t)}$ |
+| - | - |
+| *null* | 0 |
+| +A+ | $P_{A}(t)$ |
+| +AV+ | $P_{A}(t) - P_{V}(t)$ |
+| +AD+ | $P_{A}(t) - P_{D}(t)$ |
+| +AVD+ | $P_{A}(t) - P_{V}(t) - P_{D}(t)$ |
+| +V+ | $P_{V}(t)$ |
+| +VD+ | $P_{V}(t) - P_{D}(t)$ |
+| +D+ | $P_{D}(t)$ |
+
+#### Correction Procedure Example id=example
+
+Consider combination "AVD." For this case, MASTODON will apply Baseline Correction by the following procedure:
+
+1. The adjusted acceleration time history that is substituted into the least squares approximation given in [formulas] is
+
+!equation
+\ddot{u}^{\ast}(t) = \ddot{u}(t) - \ddot{P}_{A}(t)
+
+2. Then, by [all-corrections], the velocity and displacement time histories are adjusted:
+
+!equation
+\dot{u}^{\ast}(t) = \dot{u}(t) - \dot{P}_{A}(t)
+
+!equation
+u^{\ast}(t) = u(t) - P_{A}(t)
+
+3. Before applying the velocity correction, the nominal time histories are updated:
+
+!equation
+\ddot{u}(t) = \ddot{u}^{\ast}(t), \, \, \, \dot{u}(t) = \dot{u}^{\ast}(t), \, \, \, u(t) = u^{\ast}(t)
+
+*Now, the nominal time histories reflect the adjustments from the acceleration correction.*
+
+4. Proceeding on with the velocity correction, the adjusted velocity time history that is substituted into the least squares approximation given in [formulas] is
+
+!equation
+\dot{u}^{\ast}(t) = \dot{u}(t) - \dot{P}_{V}(t) = \dot{u}(t) - \dot{P}_{A}(t) -\dot{P}_{V}(t)
+
+5. Then, by [all-corrections], the acceleration and displacement time histories are adjusted:
+
+!equation
+\ddot{u}^{\ast}(t) = \ddot{u}(t) - \ddot{P}_{V}(t) = \ddot{u}(t) - \ddot{P}_{A}(t) - \ddot{P}_{V}(t)
+
+!equation
+u^{\ast}(t) = u(t) - P_{V}(t) = u(t) - P_{A}(t) - P_{V}(t)
+
+6. Before applying the displacement correction, the nominal time histories are, once again, updated:
+
+!equation
+\ddot{u}(t) = \ddot{u}^{\ast}(t), \, \, \, \dot{u}(t) = \dot{u}^{\ast}(t), \, \, \, u(t) = u^{\ast}(t)
+
+*Now, the nominal time histories reflect the adjustments from the acceleration correction and the velocity correction.*
+
+7. Proceeding on with the displacement correction, the adjusted displacement time history that is substituted into the least squares approximation given in [formulas] is
+
+!equation
+u^{\ast}(t) = u(t) - P_{D}(t) = u(t) - P_{A}(t) - P_{V}(t) - P_{D}(t)
+
+8. Finally, by [all-corrections], the acceleration and velocity time histories are adjusted:
+
+!equation
+\ddot{u}^{\ast}(t) = \ddot{u}(t) - \ddot{P}_{D}(t) = \ddot{u}(t) - \ddot{P}_{A}(t) - \ddot{P}_{V}(t) - \ddot{P}_{D}(t)
+
+!equation
+\dot{u}^{\ast}(t) = \dot{u}(t) - \dot{P}_{D}(t) = \dot{u}(t) - \dot{P}_{A}(t) -\dot{P}_{V}(t) - \dot{P}_{D}(t)
+
+!alert tip prefix=False title=Corrections are Applied Sequentially and Cumulatively
+The corrections always occur in sequence, +A+ [!icon!arrow_forward] +V+ [!icon!arrow_forward] +D+. They will also accumulate for the case of multiple corrections. For example, the displacement correction for combination +VD+ will be applied to the displacement time history adjusted by the velocity correction, while the displacement correction for combination +D+ will be applied to the nominal time history.
+
+## Usage id=usage
+
+This function object requires, as input, some sort of record of an acceleration time history. This may be provided by specifying the `data_file` parameter, as demonstrated in [example-1], or, directly, by specifying the `time_values` and `acceleration_values` parameters, as demonstrated in [example-2].
+
+!listing twenty_sines.i
+         block=Functions
+         id=example-1
+         caption=Sample input syntax for `BaselineCorrection` with the `data_file` parameter used to input a 20-cycle sine wave acceleration time history.
+
+!listing half_sine.i
+         block=Functions
+         id=example-2
+         caption=Sample input syntax for `BaselineCorrection` with the `time_values` and `acceleration_values` parameters used to input a half-sine acceleration time history.
+
+The `beta` and `gamma` parameters are those used for Newmark Integration. Ideally, they should correspond to the values used elsewhere throughout the input file. The `accel_fit_order`, `vel_fit_order`, and `disp_fit_order` variables control whether or not to use the polynomials present in [corrected-accel] when formulating the corrected time histories. If a value is specified, then a polynomial of that type and order will be found. Note that these are the parameters that define which of the combinations, described in [correction-combos], is used. For example, the set of inputs shown in [example-1] produces combination +AVD+, while those shown in [example-2] produces combination +A+.
+
+The order of the approximating polynomials, $n$, which are set by the `accel_fit_order`, `vel_fit_order`, or `disp_fit_order` parameters, can be assigned a maximum integer value of nine, since the computations typically become unstable when attempting to find polynomials of orders greater than nine. The corrections are highly sensitive to the approximation order, and so it is recommended that a user run with several trial values until the desired result is achieved. In general, the order should be less than that which is required to produce a true best-fit curve of $\ddot{u}(t)$. For example, in [example-2], a half-sine wave was input. Since a half-sine wave could be, nearly, perfectly approximated by a certain quadratic function, the order for the corrections was set to one. However, for higher order inputs, such as the 20-cycle sine wave used in [example-2], finding the right correction configuration becomes tricky, and is a matter of user-preference. The [#demo] section provides several examples that should clarify why it is important to choose a suitable polynomial order.
+
+!alert tip title=Use the Fewest Polynomials with the Lowest Orders Possible
+When it is unclear which combination, and what approximation order, is the most suitable one, start by applying the simplest one: Combination +A+ with the order of $P_{A}$ being zero (constant). Then, incrementally increase the strength of the correction until a satisfactory result is achieved. The strongest correction possible is combination +AVD+ with all three, $P_{A}$, $P_{V}$, and $P_{D}$, being ninth-order.
+
+### Apply a Corrected Acceleration as a Boundary Condition id=apply-bc
+
+<!-- possibly explain how controls TimePeriod might help -->
+
+<!-- reference action system here when/if it becomes available-->
+
+*lorem ipsum*
+
+## Demonstration id=demo
+
+<!--explain why baseline correction is important - show a drifting function as a result of integrating an acceleration (reference #theory)-->
+
+*lorem ipsum*...
+
+!syntax parameters /Functions/BaselineCorrection
+
+!syntax inputs /Functions/BaselineCorrection
+
+!syntax children /Functions/BaselineCorrection
+
+<!--eventually, cite reference on future Chris Wong journal paper on this object-->