---
title: "Full pipeline overview"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Full pipeline overview}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE)
```

## 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.

```r
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.

```r
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.

```r
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.5*T*_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.

```r
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.