Run the Newmark steps of a project

Produces the ts, dn and kmax products of a hazard project declared by a JSON contract. It reads the contract, reads the hazard inputs, calls the in-memory calculations (getGeometry(), getTs(), fitDnProducts(), getDnTables(), fitKmaxProducts(), getKmaxTable()) and replaces each product atomically. It is the only function of the package that reads and writes the project's Newmark products; buildGMDP() reads a directory of hazard exports, and every other calculation receives and returns tables.

Usage

runProcess(
  file = "newmark.json",
  root = getwd(),
  steps = c("ts", "dn", "kmax"),
  sites = character(),
  models = character(),
  seed = NULL,
  dryRun = FALSE
)

Arguments

file

Path of the JSON contract, resolved against root when it is relative.

root

Project root; the paths of the contract are resolved against it. It must exist.

steps

Character vector with any of "ts", "dn" and "kmax"; they always run in that order.

sites

Site identifiers to process; empty selects every site with a rock file.

models

Model identifiers; when given they must include ID.gmdp.

seed

Optional non-negative integer that seeds ts through set.seed(), which replaces the caller's random stream. NULL leaves that stream alone and lets ts consume it; dn keeps its own per-demand seeds either way. The message of ts reports the seed it used. Without ts the seed has no effect, but it is checked on every run.

dryRun

Logical; resolve and check the run, report the steps, the selected sites and every product it would write or replace, and return without calculating, seeding, creating a directory or writing anything. A contract or an input the real run would reject fails here the same way. With ts selected the MCE demands and the heights are left unchecked, because the shear table that fixes them is a product of that run.

Value

NULL, invisibly. Called for the products it writes.

Details

Every product is written under path.products, the directory newmark owns. ts writes the global ShearTable.Rds there, creating that directory when it is absent. dn writes DnTable.Rds, DnDraws.Rds and PGATable.csv under <path.products>/<ID.gmdp>/<siteID>/, plus the global DnTable.Rds and DnPlotTable.Rds. kmax reads those draws and PGA tables and writes the per-site and global kmaxTable.Rds. The hazard directories are only read: MCETable.Rds from path.data, and the UHSRock.Rds of every selected site from <path.uhs>/<ID.gmdp>/<siteID>/, which is also where the sites are discovered. dn and kmax read back the ShearTable.Rds of path.products. An input that is absent fails naming the file and the step that writes it. Global tables are rebuilt from every site product found under the model directory, selected or not. dn is reproducible: every site and demand is sampled with its own fixed seed.

The contract, the paths and the inputs of every selected step are resolved before the first product is calculated or written, so a key the contract lacks, an input no selected step produces, an unknown site, a selected site the MCE table does not carry or, for kmax, a shear table without heights stops the run with nothing replaced. An input a selected step writes earlier in the same run is not required in advance: with ts,dn the shear table is a product, not a prerequisite.

Project contract

The contract is one JSON object. Its path block and file itself are resolved against root when they are relative; the working directory is never changed. Reading it evaluates no code.

path.products

Directory newmark writes, and the only one it writes: the global tables at its root and the products of each site under <ID.gmdp>/<siteID>/. ts creates it when it is absent, and dn creates the directory of each site it processes. Always required; a contract that does not declare it fails naming it, and no product falls back to the hazard directories.

path.data

Directory of the hazard tables, read only: dn takes MCETable.Rds from it. Always required.

path.uhs

Directory holding <ID.gmdp>/<siteID>/UHSRock.Rds, read only; it is also where the sites are discovered. Required by dn and kmax.

path.calc

JSON of the classical calculation behind the rock spectra. Required by dn, which samples with its job.calculation.truncation_level.

Vref.gmdp, ID.gmdp, TR.gmdp, NS, Mw.gmdp, subduction

The reference velocity, model identifier, return periods, realisations per cell, magnitude and subduction regime. Required by dn and kmax; Vref.gmdp is also required by ts.

DaH.gmdp

Admissible displacements relative to the height, in percent of Hs. Required by kmax, which forms the levels DaH.gmdp times Hs over every height of the shear table, in centimetres (a percent of metres) rounded to six significant digits, and inverts every geometry at that whole set: a geometry's own relative levels are the rows whose Da is signif(DaH.gmdp * Hs, 6) for its Hs. Absolute displacements remain available through fitKmaxProducts(), getKmaxTable() and invertDnDraws().

Dn_weights

Object of displacement model names and numeric weights, such as {"AM88": 1, "BM19": 1}.

uscs, IDm

Object of USCS code arrays indexed by material, and the selected material identifiers. Required by ts.

geometryTable

Optional array of IDg, Hs, b and s row objects. It replaces the range construction below.

Hs, Hs.min, Hs.max, NTS, lo.min, lo.max, s.min, s.max

Range construction of ts: explicit Hs, otherwise NTS (10 when absent) heights between Hs.min and Hs.max, otherwise the default seq(10, 120, by = 10). The lo and s ends are required.

pairs

Optional array of IDg/IDm row objects restricting the geometry by material product of ts.

DN_PARALLEL, DN_WORKERS, KMAX_PARALLEL, KMAX_WORKERS

Optional parallel controls. The flags are logical and default to true; the worker counts are positive integers and default to one less than the detected cores, capped by the work of the step.

Every numeric setting, including the numeric columns of geometryTable, is read as a double: JSON spells a whole number without a decimal point and a parser reports it as an integer, so a project keeps the values it declares. A required key that is absent, a contract that does not exist and a contract that is not one JSON object each fail naming the contract.

Examples

if (FALSE) { # \dontrun{
# Requires a project root holding newmark.json, the hazard inputs it
# declares and the classical calculation JSON; not bundled with the package.
runProcess(root = "path/to/project", steps = c("dn", "kmax"))
} # }