Core components

The core kernel components run the calculation as a stream: events → ground-up loss → insured loss → summary. They are implemented in pytools (the oasislmf.pytools package); the binary stream formats between stages are unchanged from the original ktools design.

Stage	pytools tool	Replaces (deprecated ktools binary)
Event partitioning	evepy	eve
Effective-damageability CDFs	modelpy	getmodel
Ground-up loss	gulpy / gulmc	gulcalc
Financial module (insured loss)	fmpy	fmcalc
Summary aggregation	summarypy	summarycalc

gulpy is the standard ground-up engine (it consumes modelpy’s effective-damage CDF stream). gulmc is the full Monte-Carlo engine: it reads the model data directly (doing the modelpy step internally) and is the default in generated runs.

evepy

evepy reads a list of event ids and emits a partition of them as a binary stream. Events are “shuffled” — assigned to processes cyclically rather than in contiguous blocks — so the workload is evened out when large events are clustered in the id range.

Output stream — a simple list of event_ids (4-byte integers).

Parameters

• process_number total_processes (positional, required) — this process’s partition and the total number of partitions.

• -i, --input_file — input events file (default input/events.bin).

• -o, --output_file — output file (default stdout).

• -n, --no_shuffle — keep input ordering (distribute in blocks).

• -r, --randomise — randomise with a Fisher-Yates shuffle.

Usage

evepy <p> <N> -o events.bin
evepy <p> <N> | modelpy | gulpy -S100 -a1

Example

evepy 1 2 -o events1_2.bin           # partition 1 of 2, shuffled
evepy 1 2 -n -o events1_2.bin        # unshuffled
evepy 1 1 | gulmc -S100 -a0          # full Monte-Carlo pipeline

Internal data — input/events.bin (a list of 4-byte event ids).

modelpy

modelpy (the getmodel step) generates a stream of effective damageability distributions (CDFs). It combines the model’s footprint (hazard intensity distributions) and vulnerability (conditional damage distributions) for the exposures in items, convolving them into an effective damage CDF per areaperil/vulnerability.

Output stream — a CDF stream (stream type 0/1).

Parameters

• -i, --file-in / -o, --file-out — input event stream / output CDF stream.

• -r, --run-dir — run directory (default .).

• --peril-filter — restrict to specific perils.

• --data-server — share model data over TCP sockets (for multi-process runs).

Usage

evepy 1 1 | modelpy | gulpy -S100 -a1 -o gul.bin
modelpy --run-dir . -i events.bin -o cdf.bin

Internal data (relative to the run directory)

• static/footprint.bin, static/footprint.idx

• static/vulnerability.bin

• static/damage_bin_dict.bin

• input/items.bin

Calculation — modelpy filters the footprint for areaperils and the vulnerability for vulnerability ids that appear in items, convolves the intensity and conditional- damage distributions per event/areaperil/vulnerability, and outputs the resulting cumulative distributions (with the damage-bin mean used for interpolation downstream).

gulpy / gulmc

Both compute ground-up loss by Monte-Carlo sampling; they assign the special statistics below to negative sample indices.

• gulpy samples from the effective-damage CDF stream produced by modelpy (the classic getmodel → gulcalc split).

• gulmc is the full Monte-Carlo engine: it reads the model data directly, samples the hazard intensity and then the damage (so it does not need a separate modelpy step), and supports coverage dependency and separate hazard/damage correlation. It is the default engine in generated runs.

Output stream — a loss stream (stream type 2/1).

Parameters (common)

• -S SAMPLE_SIZE — number of samples.

• -a ALLOC_RULE — back-allocation rule (see below; default 0).

• -L LOSS_THRESHOLD — drop losses below the threshold (default 1e-6).

• -i, --file-in / -o, --file-out — input / output.

• --run-dir — run directory (default .).

• --random-generator — 0 Mersenne-Twister, 1 Latin Hypercube, 2 Latin Hypercube on Philox4x32-7 (default 2). See Appendix A: Random numbers.

• --ignore-correlation (and --ignore-haz-correlation for gulmc) — ignore the peril correlation groups.

• gulmc also: --effective-damageability (draw from the effective-damage distribution instead of full MC).

Usage

# full Monte-Carlo (default engine)
evepy 1 1 | gulmc -S100 -a1 | fmpy -a2 > il.bin

# standard engine via modelpy CDFs
evepy 1 1 | modelpy | gulpy -S100 -a1 -o gul.bin

Internal data — static/damage_bin_dict.bin, input/items.bin, input/coverages.bin (plus the model data read via modelpy/directly).

Random sampling — for each item CDF and each sample, a uniform random number is drawn and used to sample a damage factor by interpolation (linear, quadratic, or point- value depending on the damage-bin definitions), which is multiplied by the item TIV. Random numbers are reproducible; the generator is selected with --random-generator (see Appendix A: Random numbers), replacing the ktools -R/-r/-s flags.

Special samples — negative sample indices carry statistics rather than samples:

sidx	description
-1	numerical integration mean
-2	numerical integration standard deviation
-3	impacted exposure
-4	chance of loss
-5	maximum loss

Allocation rule (-a) — how item losses are adjusted when a coverage is hit by multiple perils (total loss to a coverage cannot exceed its TIV):

-a	description
0	pass losses through unadjusted (single-peril models)
1	sum losses, cap to TIV, back-allocate to items in proportion to unadjusted losses
2	keep the maximum sub-peril loss, others zero; back-allocate equally on ties

fmpy

fmpy is the Oasis Financial Module: it applies policy terms and conditions to the ground-up losses, producing insured-loss samples. It reads a loss stream from gulpy/ gulmc (or from another fmpy) and can be chained to apply successive sets of terms (e.g. direct insurance then reinsurance).

Output stream — a loss stream (stream type 2/1).

Parameters

• -a, --allocation-rule — back-allocation rule: 0 none, 1 ground-up basis, 2 prior-level basis (default 0).

• -n, --net-loss — output net losses (input minus calculated) instead of gross.

• -p, --static-path — location of the FM input files (default input/).

• -i, --files-in / -o, --files-out.

• --create-financial-structure-files — pre-build the shared FM structure.

Usage

evepy 1 1 | gulmc -S100 -a1 | fmpy -a2 | summarypy -t il -1 il_summary.bin
fmpy -p ri1 -a2 -n -i gul.bin -o ri1_net.bin        # reinsurance, net losses

Internal data — input/items.bin, input/coverages.bin, input/fm_programme.bin, input/fm_policytc.bin, input/fm_profile.bin (or fm_profile_step.bin), input/fm_xref.bin. For a loss-stream input only the four fm_* files are needed. Use -p to point at a different set (e.g. -p ri1).

Calculation — fmpy passes the loss samples (including the mean, sidx -1, and impacted exposure, sidx -3) through the financial calculation defined by the input files; special samples -2, -4, -5 are dropped. See Financial Module.

summarypy

summarypy aggregates loss samples to a reporting summary level — reducing stream volume, unifying the gulpy/gulmc and fmpy stream shapes for downstream outputs, and producing one or more summary sets in a single pass.

Output stream — a summary stream (stream type 3/1).

Parameters

• -t, --run-type {gul,il,ri} — the input stream type (replaces the ktools -i/-f distinction).

• -i, --files-in — input stream.

• -p, --static-path — location of the summary-xref files.

• -m, --low-memory — reduce downstream memory with index files.

Usage

evepy 1 1 | gulmc -S100 -a1 | summarypy -t gul -1 gul_summary.bin
fmpy -a2 -i gul.bin | summarypy -t il -1 il_summary.bin

Internal data — input/gulsummaryxref.bin (for -t gul) or input/fmsummaryxref.bin (for -t il/-t ri), which map the input identifier to a user-defined summary_id.

Calculation — losses are summed to each summary_id. The mean (sidx -1), impacted exposure (sidx -3) and maximum loss (sidx -5) are summed as normal; the standard deviation (sidx -2) is dropped; the chance of loss (sidx -4, gul input only) is combined by the law of total probability, 1 − Π(1 − Cᵢ) over the items in each summary.

---

See also: Output components · 3. Specification (stream formats). A worked, pytools-correct pipeline walkthrough lives with the example models (OasisModels) and is linked from the aggregated Oasis documentation.