newmark command-line interface • newmark

The product installer installs the R library and CLI together. Installing only the R package does not install the terminal command. The CLI loads the installed library and operates without the source checkout.

The CLI performs individual calculations through the installed newmark R package. It accepts explicit data and does not require an OpenQuake project folder or access to package source.

newmark --help
newmark --operations
newmark dn-model bm19.json
newmark uhs uhs.json --seed 42 --output result.json

Since CLI 0.2.0, --operations returns JSON from the registry that dispatches the commands: names, public functions and their installed argument names, results and file effects. The six dn-model variants are keyed by IDn. It reads no project and writes no files. --help remains available without loading the R package. The command table below explains the scientific inputs; the maintained registry check verifies its coverage against the dispatcher.

For a direct BM19 calculation, bm19.json contains:

{"IDn":"BM19","ky":0.1,"Ts":0.3,"Sa":0.8,"PGA":0.5,"PGV":80,"Mw":7}

The result contains the model’s existing muLnD, sdLnD and ID fields. BM19 requires Sa at 1.3 × Ts, acceleration in g, Ts in seconds and PGV in cm/s. This command exposes the model parameters; it does not calculate a new quantile report. dn instead takes a spectrum and returns the existing displacement quantiles and mean in cm.

Command	Public function	Required JSON fields
`uhs`	`fitSaF`	`uhs`, `vs30`
`uhs-mixture`	`fitSaFMixture`	`gmm`, `vs30`
`dn`	`fitDnModel`	`uhs`, `ky`, `Ts`, `IDn`
`dn-curve`	`fitDnCurve`	`uhs`, `ky`, `Ts`, `weights`
`kmax`	`invertDnDraws`	`draws`, `Da`, `weights`
`ts`	`fitModel.Ts`	`VSm`, `hs`, `zm`
`dn-model`	`Dn_*`	`IDn` and the selected model’s arguments
`geometry`	`getGeometry`	`hs`, `lo`, `s`
`shear`	`getTs`	`geometryTable`, `uscs`, `IDm`, `Vref`, `p`; optional `pairs`
`dn-products`	`fitDnProducts`	Explicit rock, MCE, shear tables and scientific settings
`kmax-products`	`fitKmaxProducts`	Explicit draws, PGA, shear tables and scientific settings

Tables are JSON arrays of row objects; weights is an object such as {"AM88":1,"BM19":1}. Optional fields use the exact public R argument names and retain the library defaults when omitted. The R reference documents each calculation.

Results are JSON on stdout or in the explicit --output file, which must not already exist. --seed controls one invocation’s random stream. Relative input and output paths use the caller’s working directory. The dn-curve result retains both curve and draws, including PGA.s. uhs-mixture returns analytic components. ts evaluates an explicit velocity profile. shear constructs the geometry/material summaries and their truncated-beam periods. Pass an explicit pairs table with IDg and IDm to evaluate only selected geometry/material combinations; otherwise it forms the complete product. getDnTables() and getKmaxTable() assemble validated reports without reading or writing files.

Project processing

The process verb runs the ts, dn and kmax stages of a project. It loads the installed package and reads only the project’s JSON contract:

newmark process --root /project --steps ts,dn,kmax
newmark process --root /project --steps ts,dn,kmax --dry-run

CONFIG defaults to newmark.json in the root and --root to the current directory. The contract is read, never evaluated: no project file supplies R code. Its path block selects the directories, and every relative path resolves against the root without changing the working directory:

{"path":{"products":"data/newmark","data":"data/hazard/tables",
         "uhs":"data/hazard/uhs","calc":"specs/calcs/S2C1R.json"},
 "Vref.gmdp":760,"TR.gmdp":10000,"NS":300,"Mw.gmdp":8,
 "DaH.gmdp":[0.005,30],"ID.gmdp":"S2C1R","subduction":false,
 "Dn_weights":{"AM88":1,"JB07":1,"BT07":1,"SR08":1,"BM17":1,"BM19":1}}

path.products is the directory newmark writes, and the only one it writes: the global tables at its root, the products of each site under <ID.gmdp>/<siteID>/. ts creates it when absent and writes ShearTable.Rds in it, which dn and kmax read back. A contract that does not declare it fails naming it; no product falls back to the hazard tree. path.data and path.uhs are read only — MCETable.Rds and the rock spectra of hazard, the second also being where the sites are discovered. path.uhs is required by dn and kmax and path.calc by dn. The scientific settings are the geometry/material keys, ID.gmdp, TR.gmdp, Vref.gmdp, Mw.gmdp, NS, subduction, Dn_weights and DaH.gmdp. Dn_weights contains on/off switches; BM17 and BM19 are declared together and the regime selects one. DaH.gmdp declares the admissible displacements relative to the height, in percent of Hs: kmax forms the levels DaH.gmdp times Hs over every height of ShearTable, in centimetres 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. The object verbs kmax and kmax-products, like fitKmaxProducts() and getKmaxTable(), take absolute displacements in centimetres. The calculation JSON supplies its original truncation_level; MCE has no return period or probabilistic truncation. UHS/MCE/AEP production remains with the hazard tools.

For irregular geometry, the contract may provide geometryTable with IDg, Hs, b and s, and pairs with the selected IDg/IDm combinations. Those inputs replace range construction. Displacement and kmax processing retain exactly the pairs in the mean rows of ShearTable, including a single pair.

Every product below is written under path.products. ts writes the global ShearTable.Rds. dn consumes rock spectra and MCETable.Rds and writes DnTable.Rds, DnDraws.Rds and PGATable.csv under <path.products>/<ID.gmdp>/<siteID>/, together with global DnTable.Rds and DnPlotTable.Rds. kmax writes per-site and global kmaxTable.Rds. These selected products are replaced. A --site filter recalculates selected sites; global products include all available validated site products. --model must include the one configured model.

dn fixes one deterministic seed per site, model and return-period demand, including MCE, and reads its parallel controls DN_PARALLEL, DN_WORKERS, KMAX_PARALLEL and KMAX_WORKERS from the contract alone. --seed controls ts and replaces the caller’s random stream, and the message of ts reports the seed it used. The R product helper instead receives explicit seeds or NULL, which consumes the caller’s stream. PGA remains g, Dn/Da cm and Kh the dimensionless kmax/PGA ratio. beyond reports roots outside sampled support without stopping other cells. An input that is absent fails naming the file and the step that writes it.

The contract of the selected steps, its paths and the inputs no selected step produces are checked before the first product is calculated or written, so a key the contract lacks, an absent input, an unknown site or a selected site the MCE table does not carry stops the run with nothing replaced. An input an earlier selected step writes in the same run is not required in advance: with ts,dn the shear table is a product, not a prerequisite. --dry-run (runProcess(dryRun = TRUE)) stops after those checks and reports the steps, the selected sites and every product the run would write or replace, without calculating, seeding, creating a directory or writing anything. The contract keys, with their units and the steps that require them, are listed by newmark --help.

During development, invoke the same entry without installing the CLI:

Rscript --vanilla cli/main.R --help
Rscript --vanilla cli/test.R cli/main.R
Rscript --vanilla cli/testRegistry.R cli/main.R

Installation

From the complete product checkout, the public entries install the library and CLI together. R must already be available; normal CLI commands never install dependencies. On macOS/Linux:

sudo bash install/install.sh
/usr/local/bin/newmark --version

On native Windows, from a non-elevated PowerShell session:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File install\install.ps1
newmark.ps1 --version

Use newmark.ps1 from PowerShell and newmark.cmd from CMD. The CMD launcher called through PowerShell 5.1 can reinterpret literal & in paths. Both native launchers call the same main.R; Rscript must be on PATH. R packages resolve normally, including R_LIBS. On macOS/Linux, the prefix defaults to /usr/local: sudo writes that prefix while every R step runs as the invoking user. Windows installs under %LOCALAPPDATA%\Programs\newmark, with an explicit user-PATH update (-NoPath skips it). macOS/Linux does not modify PATH persistently. --library selects the R library and --prefix the CLI destination; neither is selected silently after a permissions failure.

Rerun the same entry to update an owned installation. Receipt schema 4 records managed files with MD5 hashes; modified or foreign files cause refusal. Removal keeps the R package. On macOS/Linux:

sudo bash install/uninstall.sh

On Windows, use install\uninstall.ps1 with the same -Prefix if a custom destination was used. For inspection without installation, run bash install/install.sh --check or the PowerShell entry with -Check.

This interface does not run OpenQuake or import its exports.