Results

Files💡

List the simulation result files.

GET simulations/{simulation_pk}/results/files

Once your simulation has finished, you probably want to analyse its results (for example using the ThreediToolbox or threedigrid.

See Part III - Download simulation results from our API Examples to learn how to download the files you are interested in.

Results 3Di File💡

Summary

File name: results_3di.nc
Format: NetCDF4
Description: The "raw" 3Di results. Always uploaded if present.

The current output NetCDF4 file consists of all flow variables of the 1D and the 2D mesh. The results file is constructed according to the CF Conventions. That is, the 2D and 1D meshes are split, so each part of the mesh has its own result and mesh variables.

Log files💡

Summary

File name: log_files_sim_{simulation id}.zip
Format: ZIP
Description: A collection of all available log files for the simulation.

`simulation.log`💡

This is the main logging file of the simulation. It tracks initial conditions, changes in forcings, controls and the overall continuation of your simulation.

`flow_summary.log`💡

This file is generated at the end of your simulation. It gives an overview of the total water balance of your simulation. This includes, for example, the cumulative discharges over open boundaries, total infiltrated volume, total amount of rainfall etc. It also includes the water balance of the 0D inflow module (if defined in your threedimodel). Moreover, it informs you about the overall performance including an indication of the maximum and minimum time-step used as well as the size of the possible volume error.

`timestep_reduction.log`💡

Reductions of computational time-step are logged to this file. It contains the timestamps and the locations in the 1D and 2D domain of the most limiting locations. Continuous time-step reductions throughout the simulation are an indication of a faulty time-step setting or problematic schematization choices.

`water_balance.csv`💡

This file keeps track of the overall water balance during your simulation. It uses the same temporal resolution as the results NetCDF file.

`iteration.log`💡

For most simulations this file will be empty. It only contains data if the newton iteration has difficulties converging. The information points out the locations(s) where the problem seems to occur. Keep in mind however, that the cause of the problem may lay somewhere else.

`matrix.log`💡

This file is usually empty after a simulation. It will only be filled if the matrix solvers are having trouble finding a solution. The log information contains a list of locations and a simulation timestamp to help you improve your 3Di schematisation.

Aggregation Results File💡

Summary

File name: aggregate_results_3di.nc
Format: NetCDF4
Description: 3Di aggregation NetCDF4 file. Always uploaded if present.

The results in the results_3di.nc file are snapshots at different time stamps of the simulation. The frequency of the snapshots is defined by the user through the output_time_step parameter, that can be found in the v2_global_setting table. Aggregated results for example, are maximum, minimum or cumulative values of certain variables, like the water depth or flow velocity. If aggregation settings are in place, (through the v2_aggregation_settings table in the threedimodel sqlite), 3Di will keep track of the values required. Another benefit from using the aggregation options is that your results file will be smaller and therefore easier to handle. Also the water balance tool in the Modeller Interface requires certain aggregated results. This is described in the documentation.

Lizard Post-processing💡

3Di users that have access to Lizard can view and play-back stored scenarios.

Tip

The current PostProcessingStatus can be retrieved from
/simulations/{simulation_pk}/results/post_processing/lizard/status/
The history of PostProcessingStatus can be retrieved from
/simulations/{simulation_pk}/results/post_processing/lizard/status/history/

Basic💡

POST /simulations/{simulation_pk}/results/post_processing/lizard/basic/

Only "raw" results like net NetCDF and log files become available through Lizard. Make sure you set the process_basic_results parameter to false in your request payload. With this setting it is not possible to process the arrival time or damage estimation.

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api
from threedi_api_client.openapi.models import BasicPostProcessing


with ThreediApi() as api_client:
    api_client: V3Api

    basic_post_processing = BasicPostProcessing(
        scenario_name="<give me a name>",
        process_basic_results=False,
        result_uuid="<will be filled automatically if not provided>"
    )

    api_client.simulations_results_post_processing_lizard_basic_create(
        <sim_id>, basic_post_processing
    )

Tip

The result_uuid can be a user defined uuid4 string, e.g. for operational models. Like this an existing result in Lizard, like the water depth, will be updated. Defaults to an uuid4 string if not provided.

If you want Lizard to generate water depth rasters based on the simulation results, set the process_basic_results to True. With this setting it is possible to also process the arrival time and/or damage estimation. Besides the raw_results additional WMS layers are available on Lizard.

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api
from threedi-api_client.openapi.models import BasicPostProcessingx

with ThreediApi() as api_client:
    api_client: V3Api

    basic_post_processing = BasicPostProcessing(
        scenario_name="<give me a name>",
        process_basic_results=True,
        result_uuid="<will be filled automayically it not provided>"
    )
    api_client.simulations_results_post_processing_lizard_basic_create(
        <sim_id>, basic_post_processing
    )

Constraints

Three conditions are validated before creating a resource:

The simulation must not already have a BasicPostProcessing resource.
Lizard must not already have been triggered to process this simulation.
The threedimodel of the simulation must have a "raw" DEM file resource linked to it to be able to process basic results.

Arrival💡

POST /simulations/{simulation_pk}/results/post_processing/lizard/arrival/

A arrival time post-processing resource is created with an empty POST.

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api
from threedi_api_client.openapi.models import ArrivalTimePostProcessing

with ThreediApi() as api_client:
    api_client: V3Api

    arrival_time_post_processing = ArrivalTimePostProcessing()

    api_client.s.simulations_results_post_processing_lizard_arrival_create(
        <sim_id>, arrival_time_post_processing
    )

Constraints

Three conditions are validated when creating an resource:

The simulation may not already have an ArrivalTimePostProcessing resource.
The simulation must have a BasicPostProcessing resource with 'process_basic_results'=True.
Lizard may not already have been triggered to process this simulation.

Damage💡

POST /simulations/{simulation_pk}/results/post_processing/lizard/damage/

Study or model area must be within the Netherlands

Please note that estimates of damage caused by inundation or flooding are only available for models that are within the Netherlands. This is because the damage calculation is closely linked to the Dutch waterschadeschatter.nl.

The damages are estimated based on the land-use type, depth of the inundation, month of the year and repair time. The land-use layer is directly derived from Lizard and cannot be specified and therefore changed by means of a damage request. The water depth is derived using the maximum water level and the most recent AHN elevation. This means that the DEM provided in the model will not be used.

Constraints

Three conditions are validated before creating a resource:

The simulation may not already have a DamagePostProcessing resource.
The simulation must have a BasicPostProcessing resource with 'process_basic_results'=True.
Lizard may not already have been triggered to processing this simulation.

Parameter	type	Description
cost_type [required]	string	Choice from [min, avg or max]
flood_month [required]	string	Choice from ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec']
inundation_period [required]	float	Time in hours, must be greater or equal to 1.0.
repair_time_infrastructure [required]	integer	Time in hours, must be between 1 and 240.
repair_time_buildings [required]	integer	Time in hours, must be between 1 and 240.

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api
from threedi_api_client.openapi.models import DamagePostProcessing

with ThreediApi() as api_client:
    api_client: V3Api

    damage = DamagePostProcessing(
        cost_type="min",
        flood_month="sep",
        inundation_period=12.0,
        repair_time_infrastructure=120,
        repair_time_buildings=240
    )

    api_client.simulations_results_post_processing_lizard_damage_create(<sim_id>, damage)

Results

Files💡

Results 3Di File💡

Log files💡

simulation.log💡

flow_summary.log💡

timestep_reduction.log💡

water_balance.csv💡

iteration.log💡

matrix.log💡

Aggregation Results File💡

Lizard Post-processing💡

Basic💡

Arrival💡

Damage💡

`simulation.log`💡

`flow_summary.log`💡

`timestep_reduction.log`💡

`water_balance.csv`💡

`iteration.log`💡

`matrix.log`💡