Compute ground-up losses with gulmc¶

Task recipes for running ground-up loss (GUL) calculations with the full Monte-Carlo engine, gulmc (oasislmf.pytools.gulmc). For the why behind these options see the Explanation pages; for the full option list see Options for the JSON Configuration File and verbose.

Most of these are flags on oasislmf model run, and can equally be set in the run configuration JSON passed with -C (same name, with underscores). Two things are not: the sample count lives in the analysis settings JSON, and the correlation switches exist only on the gulmc component itself — both noted where they come up below. See Building and Running Models for the base run command.

The ground-up engine (gulmc is the default)¶

gulmc, the full Monte-Carlo Python engine, is the default — no flag is needed to select it. The sample count is set in the analysis settings file, not on the command line:

{
  "number_of_samples": 100
}

oasislmf model run --analysis-settings-json analysis_settings.json -C oasislmf.json

There is no --number-of-samples flag. If the key is absent, the run falls back to model_default_samples from the model settings, and fails if that is missing too.

To opt out and fall back to the CDF-based gulpy engine, pass --gulmc False (config "gulmc": false).

Choose the random number generator¶

--gul-random-generator (config gul_random_generator) selects the sampler:

Value	Generator
`0`	Mersenne-Twister
`1`	Latin Hypercube
`2`	Latin Hypercube on Philox4x32-7 (default)

oasislmf model run --gul-random-generator 1 -C oasislmf.json

See Sampling Methodology for what these do.

Enable / disable correlation¶

Damage and hazard correlation are driven by the peril correlation groups in the model’s correlations input — they are active by default when that data is present. They can be switched off only when invoking gulmc directly, as in the kernel pipeline below:

--ignore-correlation — ignore damage correlation groups
--ignore-haz-correlation — ignore hazard correlation groups

Neither is available on oasislmf model run, and neither is read from the run configuration or analysis settings.

See Correlation for the model-data setup and the difference between damage and hazard correlation.

Disaggregation¶

Disaggregation — splitting aggregate locations into individual buildings before sampling — is on by default. To turn it off:

oasislmf model run --do-disaggregation False -C oasislmf.json

See Disaggregation.

Speed up large runs¶

Effective damageability — draw from the effective damage distribution instead of full Monte-Carlo (faster, different sampling semantics):
```
oasislmf model run --gulmc-effective-damageability -C oasislmf.json
```
Vulnerability cache — size (MB) of the in-memory vulnerability-CDF cache (--gulmc-vuln-cache-size, config gulmc_vuln_cache_size, default 200):
```
oasislmf model run --gulmc-vuln-cache-size 500 -C oasislmf.json
```

Run gulmc directly in a kernel pipeline¶

For low-level runs, gulmc reads an event stream and writes a GUL stream, like the other kernel components (see Core components):

evepy 1 1 | gulmc -S 100 -a 0 --random-generator 2 -o gulmc.bin

Key gulmc flags: -S sample size, -a back-allocation rule, -L loss threshold, --random-generator, --effective-damageability, --ignore-correlation / --ignore-haz-correlation, --vuln-cache-size, --peril-filter. Run gulmc --help for the complete list.