diff --git a/doc/content/examples/example11.md b/doc/content/examples/example11.md new file mode 100644 index 0000000000..78c8d70b59 --- /dev/null +++ b/doc/content/examples/example11.md @@ -0,0 +1,6 @@ + + +# Example 11: Baseline Correction Example Set + +!alert construction +A comprehensive set of examples that will demonstrate use of [source/functions/BaselineCorrection.md] will become available here soon. Please see [Issue `#344`](https://github.com/idaholab/mastodon/issues/344) for more information and updates. diff --git a/doc/content/source/functions/BaselineCorrection.md b/doc/content/source/functions/BaselineCorrection.md index 5edae740ac..ccba5f3adf 100644 --- a/doc/content/source/functions/BaselineCorrection.md +++ b/doc/content/source/functions/BaselineCorrection.md @@ -1,18 +1,20 @@ # Baseline Correction -`BaselineCorrection` is a [`Function`](syntax/Functions/index.md) object that applies a [!ac](BLC) 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: +`BaselineCorrection` is a [`Function`](syntax/Functions/index.md) object that applies a [!ac](BLC) to an acceleration time history, $\ddot{u}(t)$. The corrections are performed by first computing the nominal (*uncorrected*) velocity, $\dot{u}(t)$, and displacement, $u(t)$, 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) +\ddot{u}^{\ast}(t) = \ddot{u}(t) - \ddot{P}_{A}(t) - \ddot{P}_{V}(t) - \ddot{P}_{D}(t) \, , \, \, \, \forall \, t \in \mathbb{R} -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. 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. The [#theory] section will explain how the corrections are made in greater detail. +where $P_{A}$, $P_{V}$, and $P_{D}$ are the least squares approximations of the acceleration, velocity, and displacement, respectively, and the overhead dots represent their derivative order. + +The corrected velocity, $\dot{u}^{\ast}$, and the corrected displacement, $u^{\ast}$, are obtained by integrating [corrected-accel]. The output for this function object is, by default, the corrected acceleration, $\ddot{u}^{\ast}$. However, a user may request that the output be $\dot{u}^{\ast}$ or $u^{\ast}$, as well. Finally, after one of the three kinematic variables has been adjusted, the corrected ordinates are linearly interpolated with respect to simulation time to ensure accurate results at any given real-valued time instance. Optionally, a scale factor may be applied to the final output. !alert note 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]. Please see the [#usage] section for more information about how to control the adjustments. +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}_{A}$, $\ddot{P}_{V}$, or $\ddot{P}_{D}$, would result in their values being zero in [corrected-accel]. Please see the [#scheme] section for more information about how the adjustments are made. ## Numerical Formulation id=theory -This method for [!ac](BLC) of acceleration time histories was first presented by [!citet](brady1966) and later expanded upon by [!citet](pan2016). 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): +This method for [!ac](BLC) of acceleration time histories was first presented by [!citet](brady1966) and later expanded upon by [!citet](pan2016). To begin understanding the MASTODON implementation, consider a given acceleration, $\ddot{u}$, specified at $N$ discrete time instances. 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 @@ -20,40 +22,39 @@ This method for [!ac](BLC) of acceleration time histories was first presented by !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. +Here, the size of a time increment, $\Delta t$, will depend on the acceleration record, and could vary between time steps, in which case, $\Delta t_{i} = t_{i + 1} - t_{i}$. When evaluating [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: +A least squares approximation is found by minimizing the area bounded by the square difference between the nominal record and the best-fit, $n$-th order, polynomial itself. For example, a best-fit polynomial of $\ddot{u}$ can be determined 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 +\dfrac{\partial}{\partial C_{k}} \int_{t_{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 - 1$, 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 to solve for the unknown polynomial coefficients: +where $T = t_{N - 1}$ , i.e., the value corresponding to the final time-step, 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 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 +\sum_{j = 0}^{n} \dfrac{\left(j^{2} + 3 j + 2 \right) T^{k + j + 1}}{k + j + 1} C_{j} = \int_{t_{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], is referred to as the linear +normal equation+. The definite integrals on the right-hand side of [linear-normal] is evaluated with a modified form of Newmark's method, i.e., +In terms of Linear Algebra jargon, [linear-normal], or [linear-normal-system], is referred to as the linear +normal equation+. The definite integrals on the right-hand side of [linear-normal] are 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} +I = \int_{t_{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$. +Once all components in $\mathbf{K}$ and in $I$ are known, any method for solving a dense, nonsymmetric, nonhomogenous, square system of equations can be applied to solve [linear-normal-system] for the unknown vector of fitting coefficients, $C = \begin{Bmatrix} C_{0} && C_{1} && \cdot \cdot \cdot && C_{n} \end{Bmatrix}^{\intercal}$. 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$, because $\mathbf{K}$ becomes ill-conditioned. -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 corrected 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 the [#scheme] section). +The equations presented so far are exclusive to finding the acceleration correction and were given for demonstration purposes. The procedure thus followed may also be applied to the velocity and displacement corrections as demonstrated in [!citet](pan2016). 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]. The values for the corrected 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 the [#scheme] section). !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}$ | +| Best-fit | 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)$ | +| $P_{A}$ | $\small \displaystyle \dfrac{\partial}{\partial C_{k}} \int_{t_{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_{t_{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_{t_{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 @@ -66,10 +67,10 @@ Once the polynomial coefficients, $C_{k} \, \forall \, k = 0, 1, ..., n$, have b \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 corrections always occur in a specific sequence and accumulate as each correction type is applied (see the [#example] section to understand what this means). +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)$, and assigns them a shorthand identifier. 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 may vary between combinations It is also important to note that the corrections always occur in a specific sequence and accumulate as each correction type is applied. !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. + 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 an acceleration correction, +V+ denotes a velocity one, and +D+ denotes a displacement one. Combination identifiers are assigned based on these notations. | Combination | $\bm{P(t)}$ | | - | - | | +A+ | $P_{A}(t)$ | @@ -147,16 +148,18 @@ The `BaselineCorrection` object requires, as input, some sort of record of an ac !listing baselinecorrection/half_sine_scaled.i block=Functions id=example-1 - caption=Sample input syntax for `BaselineCorrection` with the `time_values` and `acceleration_values` parameters used to input a half-sine acceleration time history. The corrected acceleration is multiplied by the factor provided for the `scale_factor` parameter before being returned. + caption=Sample input syntax for `BaselineCorrection` with the `time_values` and `acceleration_values` parameters used to input a half-sine acceleration time history. The corrected displacement is multiplied by the factor provided for the `scale_factor` parameter before being returned. !listing baselinecorrection/twenty_sines_with_bc.i block=Functions id=example-2 caption=Sample input syntax for `BaselineCorrection` with the `data_file` parameter used to input a twenty-cycle sinusoidal acceleration time history. Note that if no input for the `time_name` and `acceleration_name` parameters is provided, it is assumed that time values are in the first row or column of the delimited file and accelerations are in the second. -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 +A+, while those shown in [example-2] produces combination +AVD+. +The `series_type` parameter controls which kinematic variable is output. For example, since `series_type = displacement` was provided in [example-1], and since `scale_factor = 4.886` was also provided, the output will be $4.886 u^{\ast}$ interpolated through time. Whereas in [example-2], the output will be $\ddot{u}^{\ast}$ interpolated through time, since `series_type = acceleration` and `scale_factor = 1` are the defaults. + +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, $P_{A}$, $P_{V}$, and $P_{D}$, when formulating the corrected time histories. That is, if a value is specified, then a polynomial of that type and order will be found. Control of these three parameters alone leads to the different combinations of corrections presented in [correction-combos]. For example, the set of inputs shown in [example-1] produces combination +A+, while those shown in [example-2] produces combination +AVD+. -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 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 [linear-normal-system] tends to become unstable when attempting to satisfy polynomials of larger order. 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. For multiple cycles of certain transcendental or quasi-transcendental functions, finding the right correction can be difficult, if not impossible. The [examples/example11.md] page provides several examples that should clarify why 1) it is important to choose a suitable polynomial order, and 2) that such a choice is not necessarily a trivial one. !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. It is important to try to avoid an *overcorrection*! @@ -169,9 +172,8 @@ The corrected acceleration output from the `BaselineCorrection` object can be pa !listing baselinecorrection/twenty_sines_with_bc.i id=example-3 - caption=Sample input file that supplies a `BaselineCorrection` object for a `PresetAcceleration` object's `'function'` parameter (see the [#demo-5] section for further details). - -The input file shown in [example-3] is an extension of [example-1] that solves a simple structural dynamics problem. This problem is described in the [#demo-5] section. + block=Functions ICs BCs + caption=Sample input file that supplies a `BaselineCorrection` object for a `PresetAcceleration` object's `'function'` parameter (see the [examples/example11.md] page for further details). !alert tip title=Free Vibration Periods When an acceleration boundary condition suddenly comes to a half at time $T$, i.e., $\ddot{u}(T) = 0$, but $\dot{u}(T) \ne 0$ and $u(T) \ne 0$, this can cause displacement drifts during the subsequent free vibration period, $t \ge T$, even if the acceleration were baseline corrected. To circumvent this behavior, consider using the [`TimePeriod`](source/controls/TimePeriod.md) object to activate a [`DirichletBC`](source/bcs/DirichletBC.md) object that controls $u(t), \, \forall \, t \ge T$. @@ -181,13 +183,3 @@ When an acceleration boundary condition suddenly comes to a half at time $T$, i. !syntax inputs /Functions/BaselineCorrection !syntax children /Functions/BaselineCorrection - -!!! -The `complete` setting for the `!acronym list` command is currently broken in `moose/python/MooseDocs/extensions/acronym.py`, but is easily fixable - the invocation of `getAcronyms()` on line 157 is passing `complete=True` by default. - -TODO: Add the following when it gets fixed: - -## List of Acronyms - -!acronym list complete=False -!!!