# 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.table`s 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
                  rock UHS  +  target Vs30  ─►  fitSaF()  ─►  site-amplified UHS

    [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
      Rrup  = 100                           # rupture distance (km)
    )
    # returns a data.table with Tn, p, Sa, SaF, AF

Two reference vignettes deepen this workflow: `vignette("dynamic-site-response", package = "newmark")` covers the methodology side (Ishihara, Gazetas–Dakoulas, ST17); function-level docs are at `?getSiteProperties`, `?getCylinderRoots`, `?fitModel.Ts`, `?Vs30toSID`, `?SIDtoVs30`, `?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
      Rrup    = 100,
      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, Dn, IDn)     all NS 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")`.

## Workflow 4 — Seismic coefficient

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

    kmax <- invertDnDraws(
      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 normalised pseudostatic coefficient is K_h = k_max / mean rock-level PGA, expressed as a percentage.

## See also

- `vignette("newmark-quickstart", package = "newmark")` — minimal Workflows 3 + 4 example with the bundled NBCC UHS.
- `vignette("dynamic-site-response", package = "newmark")` — the dsra-side methodology for Ts and the site-amplification model.
- `vignette("ensemble-formulation", package = "newmark")` — mathematical derivation of the probabilistic propagation, monotone projection, and inversion.