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.

These options can be passed as CLI flags to oasislmf model run or set in the run configuration / analysis settings JSON (same names, with underscores). See Building and Running Models for the base run command.

Select gulmc as the ground-up engine¶

Turn on the full Monte-Carlo Python engine:

oasislmf model run --gulmc --number-of-samples 100 -C oasislmf.json

Or in the config JSON:

{
  "gulmc": true,
  "number_of_samples": 100
}

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 --gulmc --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. To ignore them for a run, use the gulmc engine flags:

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

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

Enable disaggregation¶

Split aggregate locations into individual buildings before sampling:

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

See Disaggregation.

Enable coverage dependency¶

Coverage dependency (a dependent coverage’s damage conditioned on a source coverage) activates automatically when its inputs are present — no run flag is needed. You must provide:

coverage_dependency_settings in model_settings.json,
the source_coverage_id column in the correlations input (populated during GUL input generation), and
a conditional_vulnerability static file.

See Coverage dependency (gulmc) for the full configuration and rules.

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 --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 --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):

eve 1 1 | modelpy | gulmc -S 100 -a 0 --random-generator 2 -i - -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.