Fundamental period of the truncated shear beam for every profile realization

Solves, for each realization of simulateSoilProfiles(), the fundamental period of the truncated shear beam directly from the realization's own layers with solveWedgePeriod(), and keeps beside it the analytic period of the truncated shear beam evaluated on the realization's fitted mo and VSo, with the controls of both. The resulting population of periods stays paired with the other properties of each realization: it can be summarized with summarizeProfiles(), naming "Ts" or "TsAnalytic" among its properties, or propagated further. This is the calculation-before-summary route; the compatibility route of buildShearTable() evaluates the analytic period on summary rows instead.

Usage

propagateBeamPeriod(profiles, lo, method)

Arguments

profiles

The result of simulateSoilProfiles() or propagateSitePeriod(): one row per realization with columns Hs, mo, VSo and layers, the list column of layer tables whose thicknesses add up to Hs or exceed it by less than the deepest layer (section Height; see solveWedgePeriod()).

lo

One truncation ratio of the geometry strictly between 0 and 1, see buildGeometry().

method

The solution method of the root model of the analytic route: "exact", or the surrogate "lm" or "nlm"; see buildRootModel().

Value

A copy of profiles with these columns appended, one value per realization paired with the other properties of its row: lo; Ts (s), the numerical fundamental period of the realization's layers trimmed to Hs; TsMeshChange, its relative change under mesh doubling; TsAnalytic (s), the period of the analytic route; TsAnalyticDifference, TsAnalytic / Ts - 1; TsDivergent, TRUE when abs(TsAnalyticDifference) exceeds 0.10; and an, anExact and anWithinSupport, the root of the analytic route and its diagnostics. The population is that of profiles; TsMeshChange, TsAnalyticDifference and TsDivergent are numerical diagnostics, not physical dispersion. An invalid realization stops the call with its row.

Settings

Every layer of a realization is divided into two linear elements, and the mesh-doubling control of solveWedgePeriod() repeats the solve with four, so Ts is the period on four elements per layer. A realization is flagged divergent when the analytic period differs from the numerical one by more than 10 percent, \(|T_{s,analytic}/T_s - 1| > 0.10\); the flag rejects nothing. Both values are design settings.

Height

The \(\lceil H_s / h \rceil\) layers of sampleSoilLayers() reach below Hs when Hs is not a multiple of h. Before the numerical period, the deepest layer of such a realization (largest zm) is trimmed so that the thicknesses add up to Hs: the trimmed geometry is the one Ts uses. Only that thickness changes; the properties of every layer stay those sampled, and TsAnalytic keeps the Hs, mo and VSo of the row. The layers column is returned untrimmed, so the site period of propagateSitePeriod() is that of the sampled column. A sum that already meets the equality of solveWedgePeriod() is solved as it is; an excess not smaller than the deepest layer stops the call with the row. This is a design decision.

Analytic route

TsAnalytic takes the apex-to-base height \(H_s/(1 - \lambda_o)\) of evaluateBeamPeriod() and the first characteristic root at mo and lo from evaluateRoot() with method. Each mo is the exponent of the profile that characterizeProfile() fits from the crest, used with the roots of the apex-origin profile of Dakoulas and Gazetas (1985): an approximation that the theory base measures on a continuous profile at 1.4 to 6.0 percent for \(m = 0.5\) and \(\lambda\) from 0.075 to 0.35, and whose size for each realization is TsAnalyticDifference, flagged by TsDivergent. Ts makes no such approximation: it is the period of the realization's layered shear beam.

Examples

set.seed(20260915)
Profiles <- simulateSoilProfiles(Hs = 10, USCS = c("ML", "MH"), NS = 3, h = 1,
                                 water = 0, POP = 100, Vref = 760)
Periods <- propagateBeamPeriod(Profiles, lo = 0.351, method = "nlm")
Periods[, .(mo, VSo, Ts, TsAnalytic, TsDivergent)]
#>           mo      VSo        Ts TsAnalytic TsDivergent
#>        <num>    <num>     <num>      <num>      <lgcl>
#> 1: 0.2980117 178.0648 0.2045104  0.1923922       FALSE
#> 2: 0.5459589 195.3620 0.1951046  0.1798033       FALSE
#> 3: 0.5433113 186.2848 0.2023160  0.1885153       FALSE