This PR introduces gulmc, a new tool that uses a "full Monte Carlo" approach for ground up losses calculation that, instead of drawing loss samples from the 'effective damageability' probability distribution (as done by calling eve | modelpy | gulpy), it first draws a sample of the hazard intensity, and then draws a sample of the damage from the vulnerability function corresponding to the hazard intensity sample.

Introducing gulmc, full Monte Carlo loss calculation engine

This PR introduces gulmc, a new tool that uses a "full Monte Carlo" approach for ground up losses calculation that, instead of drawing loss samples from the 'effective damageability' probability distribution (as done by calling eve | modelpy | gulpy), it first draws a sample of the hazard intensity, and then draws a sample of the damage from the vulnerability function corresponding to the hazard intensity sample.

Comparing gulpy and gulmc output

gulmc runs the same algorithm of eve | modelpy | gulpy, i.e., it runs the 'effective damageability' calculation mode, with the same command line arguments. For example, to run a model with 1000 samples, alloc rule 1, and streaming the binary output to the output.bin file, can be done with:

eve 1 1 | modelpy | gulpy -S1000 -a1 -o output.bin

or

eve 1 1 | gulmc -S1000 -a1 -o output.bin

Hazard uncertainty treatment

If the hazard intensity in the fooprint has no uncertainty, i.e.:

event_id,areaperil_id,intensity_bin_id,probability
1,4,1,1
[...]

then gulpy and gulmc produce the same outputs. However, if the hazard intensity has a probability distribution, e.g.:

event_id,areaperil_id,intensity_bin_id,probability
1,4,1,2.0000000298e-01
1,4,2,6.0000002384e-01
1,4,3,2.0000000298e-01
[...]

then, by default, gulmc runs the full Monte Carlo sampling of the hazard intensity, and then of damage. In order to reproduce the same results that gulpy produces can be achieved by using the --effective-damageability flag:

eve 1 1 | gulmc -S1000 -a1 -o output.bin --effective-damageability

On the usage of modelpy and eve with gulmc

Due to internal refactoring, gulmc now incorporates the functionality performed by modelpy, therefore modelpy should not be used in a pipe with gulmc:

eve 1 1 | modelpy | gulpy -S1000 -a1 -o output.bin        # wrong usage, won't work
eve 1 1 | gulpy -S1000 -a1 -o output.bin                  # correct usage

Note: both gulpy and gulmc can read the events stream from binary file, i.e., without the need of eve, with:

 gulmc -i input/events.bin -S1000 -a1 -o output.bin

Printing the random values used for sampling

Since we now sample in two dimensions (hazard intensity and damage), the -d flag is revamped to output both random values used for sampling. While gulpy -d printed the random values used to sample the effective damageability distribution, in gulmc:

gulmc -d1 [...]   # prints the random values used for the hazard intensity sampling
gulmc -d2 [...]   # prints the random values used for the damage sampling

Note: if the --effective-damageability flag is used, only -d2 is valid since there is no sampling of the hazard intensity, and the random value printed are those used for the effective damageability sampling.

Note: if -d1 or -d2 are passed, the only valid alloc_rule value is 0. This is because, when printing the random values, back-allocation is not meaningful. alloc_rule=0 is the default value or it can be set with -a0. If a value other than 0 is passed to -a, an error will be thrown.

Testing suite

This PR introduces:

• a minimal toy model in tests/assets/test_model_1/ that can be used to run unit tests on various functionality in the repository. A more detailed description of the content of the model can be found at tests/assets/test_model_1/README.md.
• a suite of 192 quantitative tests for the gulmc output for combinations of input parameters (alloc rule, correlation, etc.). Binary files with the expected outputs are stored at tests/assets/test_model_1/expected/.
• a suite of 48 quantitative tests for the gulpy output for combinations of input parameters.
• tests checking that ValueErrors in gulmc are raised when expected.