|
| 1 | +```@meta |
| 2 | +CollapsedDocStrings = true |
| 3 | +``` |
| 4 | + |
| 5 | +# OrdinaryDiffEqNewmark |
| 6 | + |
| 7 | +Newmark-β and generalized-α methods for second-order ODEs, typically in mass-matrix form. These are second-order time integrators, advancing the displacement and velocity with Newmark updates and solving a nonlinear residual for the acceleration directly. They arose from time stepping in structural and computational mechanics and are designed for such systems. |
| 8 | + |
| 9 | +## Key Properties |
| 10 | + |
| 11 | +These methods provide: |
| 12 | + |
| 13 | + - **Direct integration** of second-order ODEs, including mass-matrix form |
| 14 | + - **Unconditionally stable** parameter choices for structural dynamics |
| 15 | + - **Controllable high-frequency damping** via generalized-α's (`ρ∞`) |
| 16 | + - **Newmark-β and HHT-α** as special cases of generalized-α |
| 17 | + - **Adaptive time stepping** with the Zienkiewicz–Xie local truncation error estimate (Newmark-β) |
| 18 | + |
| 19 | +## When to Use Newmark Methods |
| 20 | + |
| 21 | +These methods are recommended for: |
| 22 | + |
| 23 | + - **Structural dynamics** and finite-element/Galerkin vibration problems |
| 24 | + - **Second-order ODEs** of the form `M a = f(u, v, t)` |
| 25 | + - **Problems needing algorithmic damping** of spurious high-frequency modes |
| 26 | + - **Mass-matrix second-order systems** arising from spatial discretizations |
| 27 | + - **Cases where RKN/symplectic methods are not the right fit** (implicit structural integrators with dissipation control) |
| 28 | + |
| 29 | +## Mathematical Background |
| 30 | + |
| 31 | +The generalized-α method evaluates the equations of motion at interpolated states: |
| 32 | + |
| 33 | +`M * aₙ₊αₘ = f(uₙ₊αf, vₙ₊αf, tₙ₊αf)` |
| 34 | + |
| 35 | +with |
| 36 | + |
| 37 | + - `aₙ₊αₘ = (1 - αₘ) * aₙ₊₁ + αₘ * aₙ` |
| 38 | + - `uₙ₊αf = (1 - αf) * uₙ₊₁ + αf * uₙ` |
| 39 | + - `vₙ₊αf = (1 - αf) * vₙ₊₁ + αf * vₙ` |
| 40 | + |
| 41 | +and the standard Newmark updates for `uₙ₊₁` and `vₙ₊₁`. Setting `αₘ = αf = 0` recovers Newmark-β; setting `αₘ = 0` recovers HHT-α. |
| 42 | + |
| 43 | +## Solver Selection Guide |
| 44 | + |
| 45 | + - **`NewmarkBeta`**: Classical Newmark-β. Default `β = 1/4`, `γ = 1/2` (average acceleration, second-order when `γ = 1/2`). |
| 46 | + - **`GeneralizedAlpha`**: Preferred when controllable high-frequency damping is needed. |
| 47 | + - **`GeneralizedAlpha(; rho_inf)`**: Recommended parameterization. `ρ∞ = 1` gives no algorithmic damping (equivalent to undamped Newmark); `ρ∞ = 0` gives maximum damping. Always unconditionally stable in [0, 1]. |
| 48 | + - **`GeneralizedAlpha(; alpha_hht)`**: HHT-α convenience (`α ∈ [-1/3, 0]`). Also unconditionally stable in that range. |
| 49 | + - **`GeneralizedAlpha(αm, αf, β, γ)`**: Explicit four-parameter construction. Can break unconditional stability if parameters are chosen poorly. |
| 50 | + |
| 51 | +### Unconditional stability |
| 52 | + |
| 53 | +**Newmark-β** is unconditionally stable when `γ ≥ 1/2` and `β ≥ (1/4) * (γ + 1/2)^2`. |
| 54 | + |
| 55 | +The default `β = 1/4`, `γ = 1/2` (average acceleration) sits on this bound and is second-order. `γ = 1/2` with `β < 1/4` (e.g. central difference `β = 0`) is only conditionally stable. `γ > 1/2` adds numerical damping but drops the method to first order. |
| 56 | + |
| 57 | +**Generalized-α** is unconditionally stable when `αₘ ≤ αf ≤ 1/2` and `β ≥ (1/4) * (1/2 + αf - αₘ)^2`. |
| 58 | + |
| 59 | +Second-order accuracy further requires `γ = 1/2 - αₘ + αf`. The `rho_inf` and `alpha_hht` constructors enforce these choices; the four-parameter form asserts the stability inequalities above at construction, so values that violate them will error rather than silently run unstably. |
| 60 | + |
| 61 | +## Installation |
| 62 | + |
| 63 | +To be able to access the solvers in `OrdinaryDiffEqNewmark`, you must first install them using the Julia package manager: |
| 64 | + |
| 65 | +```julia |
| 66 | +using Pkg |
| 67 | +Pkg.add("OrdinaryDiffEqNewmark") |
| 68 | +``` |
| 69 | + |
| 70 | +This will only install the solvers listed at the bottom of this page. |
| 71 | +If you want to explore other solvers for your problem, |
| 72 | +you will need to install some of the other libraries listed in the navigation bar on the left. |
| 73 | + |
| 74 | +## Example usage |
| 75 | + |
| 76 | +```julia |
| 77 | +using OrdinaryDiffEqNewmark |
| 78 | +function f1!(dv, v, u, p, t) |
| 79 | + dv .= -u |
| 80 | +end |
| 81 | +function f2!(du, v, u, p, t) |
| 82 | + du .= v |
| 83 | +end |
| 84 | +v0 = ones(2) |
| 85 | +u0 = zeros(2) |
| 86 | +prob = DynamicalODEProblem(f1!, f2!, v0, u0, (0.0, 5.0)) |
| 87 | +sol = solve(prob, NewmarkBeta(), dt = 0.1) |
| 88 | +sol_ga = solve(prob, GeneralizedAlpha(; rho_inf = 0.8), dt = 0.1) |
| 89 | +``` |
| 90 | + |
| 91 | +## Full list of solvers |
| 92 | + |
| 93 | +```@docs |
| 94 | +NewmarkBeta |
| 95 | +GeneralizedAlpha |
| 96 | +``` |
0 commit comments