Full pipeline overview

Scope

newmark is an R package: every workflow in this overview reads its inputs from R objects in memory and returns R objects in memory (data.tables plus, for getCylinderRoots(), a numeric scalar). No function writes to disk. Project-scale orchestration on a hazard grid — looping over scenarios, persisting intermediate tables, aggregating across models or sites — is the consumer’s responsibility; one example consumer is the oqt command-line tool, but newmark itself does not depend on it and works identically when called from any R session.

The four workflows

[Workflow 1]  Dynamic site response
              soil profile + USCS  ─►  getSiteProperties()  ─►  Ts, mo, Go, VSo
              analytic rock spectrum + target Vs30 ─► fitSaFMixture()

[Workflow 2]  Hazard import
              OpenQuake classical/disagg  ─►  buildGMDP()  ─►  AEPTable, UHSTable, RMwTable

[Workflow 3]  Displacement curves                          ◄─── Ts from W1
              site UHS  ─►  getDnKy()  ─►  ky grid           ◄─── UHS from W1+W2
              site UHS + ky + Ts + Mw  ─►  fitDnCurve()  ─►  list(curve, draws)

[Workflow 4]  Seismic coefficient
              draws + Da  ─►  invertDnDraws()  ─►  kmax(d*)

Workflows 1 and 2 are independent. Workflow 3 consumes Ts from Workflow 1 and the site-amplified UHS from Workflows 1+2. Workflow 4 consumes the per-realisation draws from Workflow 3.

Workflow 1 — Dynamic site response

Two sub-steps. The first builds the soil profile and the fundamental period; the second amplifies the rock UHS to the target Vs30.

library(newmark)
library(data.table)

# 1.1 — synthetic soil profile and dynamic properties
SiteProps <- getSiteProperties(
  Hs     = 30,                          # total height to hard ground (m)
  USCS   = c("GC", "CL", "ML"),         # USCS codes, top to bottom
  h      = 1.00,                        # discretisation step (m)
  NR     = 100,                         # Monte Carlo realisations
  levels = c(0.16, "mean", 0.84)
)
# returns a data.table with Hs, level, Go, mo, Ts, VSo, VS30, ...

Ts  <- SiteProps[level == "mean", Ts]
mo  <- SiteProps[level == "mean", mo]
VSo <- SiteProps[level == "mean", VSo]

# 1.2 — site amplification to a target Vs30
saf <- fitSaF(
  uhs   = uhs_rock,                     # rock UHS data.table (Tn, p, Sa)
  vs30  = 350,                          # target site Vs30 (m/s)
  vref  = 760,                          # reference rock Vs30
  ns    = 1000                          # Monte Carlo size
)
# returns a data.table with Tn, p, Sa, SaF, AF

# Deterministic integration of a quantile-defined UHS:
saf_q <- fitSaF(
  uhs               = uhs_rock,
  vs30              = 350,
  vref              = 760,
  integrationMethod = "quadrature",
  quadratureOrder   = 64
)

For OpenQuake PSHA, the canonical path is different: pass one complete mean-plus-seven-fractile spectrum to fitSaLognormal(), discard the input fractiles, assign the returned parameters one component key with unit weight, and pass that analytic component to fitSaFMixture(). Quantile input remains supported for distributions already defined in that form, such as the current MCE envelope; it is not an OpenQuake fallback.

Two reference vignettes deepen this workflow: vignette("dynamic-site-response", package = "newmark") covers the methodology side (Ishihara, Gazetas–Dakoulas, NGA-East site response); function-level docs are at ?getSiteProperties, ?getCylinderRoots, ?fitModel.Ts, ?Vs30toSID, ?SIDtoVs30, ?fitSaLognormal, ?fitSaFMixture, and ?fitSaF.

Workflow 2 — Hazard import

Convert OpenQuake classical-PSHA and disaggregation output into the table shapes consumed downstream.

gmdp <- buildGMDP(
  path    = "/path/to/openquake/output",
  IDo     = "GMM",
  engine  = "openquake",
  vref    = 760,
  TRo     = c(100, 200, 500, 1000, 2000, 2500, 5000, 10000)
)
# returns a list with $AEPTable, $UHSTable, $RMwTable

buildGMDP() accepts both engine = "openquake" (zipped XML output) and engine = "user" (Excel files supplied by the analyst). See ?buildGMDP for the full signature.

Workflow 3 — Displacement curves

Build the k_y grid and run the coherent Monte Carlo over the six-model ensemble.

ky     <- getDnKy(saf, Ts = Ts)         # default 30 log-spaced points
result <- fitDnCurve(
  uhs     = saf,                        # site-amplified UHS
  ky      = ky,
  Ts      = Ts,
  Mw      = 6.8,                        # representative magnitude
  NS      = 200,                        # Monte Carlo size
  weights = c(AM88 = 1, JB07 = 0, BT07 = 1, SR08 = 1, BM17 = 0, BM19 = 1),
  NFC     = "D100"                      # near-fault component selector for BM19
)
# result$curve  data.table(ky, p, Dn, IDn, w)  with quantiles + ensemble per ky
# result$draws  data.table(ky, s, PGA.s, Dn, IDn)  all realisations per model

The single-scenario sampling in fitDnCurve() (one PGA, Sa(1.3 T_s), Sa(1.5T_s) tuple drawn per realisation, correlated by the full Baker-Jayaram inter-period matrix) and the shared z^(n) across models (ρ = 1) are explained in vignette("ensemble-formulation", package = "newmark"). PGA.s is the sampled PGA in g; retaining it allows an AM88 draw below the stored k_y grid to be inverted on its physical branch.

Workflow 4 — Seismic coefficient

Invert the per-realisation draws to the design k_max at the chosen displacement targets.

kmax <- invertDnDraws(
  draws   = result$draws,
  Da      = c(0.5, 2.5, 5.0, 25.0),     # target displacements (cm)
  weights = c(AM88 = 1, JB07 = 0, BT07 = 1, SR08 = 1, BM17 = 0, BM19 = 1),
  p       = c(0.16, 0.84)                # report quantiles alongside the mean
)
# returns a data.table(Da, p, kmax) — kmax in g

The aggregation mirrors the Dn ensemble: each model contributes its distribution of inverted roots with its epistemic weight.

The normalised pseudostatic coefficient is K_h = k_max / mean rock-level PGA, expressed as a percentage.