Events

Breaches

from threedi_api_client.openapi.models import Breach

Create

Create a breach during a given simulation. The potential_breach parameter refers to the id of a potential location associated with the threedimodel. A list of these locations can be retrieved at the uri /threedimodels/{id}/potentialbreaches/

POST /simulations/{simulation_pk}/events/breaches/

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

with ThreediApi() as api_client:
    api_client: V3Api

    breach = Breach(
        potential_breach=9554,
        duration_till_max_depth=100,
        initial_width=15,
        offset=0
    )

    api_client.simulations_events_breaches_create(<simulation_id>, breach)

Parameter	Type	Description
duration_till_max_depth	integer	describes the time it takes until the deepest point of the breach is reached. [seconds]
maximum_breach_depth	number	specifies the maximum depth of the breach relative to the top of the levee [meters]
initial_width	number	initial width of the breach [meters]
discharge_coefficient_positive	number	dimensionless parameters to deal with behaviour of energy loss around a breach.
discharge_coefficient_negative	number	dimensionless parameters to deal with behaviour of energy loss around a breach

from openapi_client.models import Breach

breach = Breach(
    potential_breach=9554,
    duration_till_max_depth=100,
    initial_width=15,
    offset=0
)

See simulate a breach for a complete example.

Rain

Raster

NetCDF

POST /simulations/{simulation_pk}/events/rain/rasters/netcdf/

NetCDF4 files can serve as a rain datasource.

Tip

Check out the NetCDF4 raster format specification to make sure the file can be processed correctly.

Warning

NetCDF3 files are not supported.

Parameter	Type	Description
filename	string	name of the file that you want to upload

If the request was successful the response body will contain a put_url, e.g.

{
  "filename": "string",
  "put_url": "string"
}

Upload the file to the put_url, for example using curl

curl -X PUT "put_url_here_between_quotes" -T /full_path_to/filename.nc

Once uploaded, the file is automatically validated by a background worker. The validation status is posted to the file resource linked to the netcdf resource in the API together with meta information like timesteps. The status of the validation process can be checked via /simulations/{simulation_pk}/events/rain/rasters/netcdf/{id}

If the validation status of the file (linked to the netcdf resource) is 'processed', the NetCDF is ready to be used by the simulation.

Structure Controls

Table

POST /simulations/{simulation_pk}/events/structure-control/table/

A table structure control can used to apply a certain action like increasing the pump capacity of a pump station, based on the measured values of one or more locations.

Action Types

Type	Structures	Description
set_crest_level	weir, orifice	change the crest level for the given structure
set_discharge_coefficients	weir, orifice, culvert, channel, pipe	change discharge coefficients for the given structure
set_pump_capacity [m3/s]	weir, orifice	change the capacity for the given pump station

Action Values

The action table consists of one or more value pairs (threshold, action_value)

To close/open or partially close/open a structure using the set_discharge_coefficients type the values must contain three values. For example [[1.2, 0.5, 0.7]], where

• 1.2 is the threshold value
• 0.5 the action value for the left flow direction
• 0.7 action value for the right flow direction

Constraints

Action values for set_discharge_coefficients type must be > 0.

For the operators > and >= threshold values must be ascending, for the operators < and <= they must be descending.

In most cases the measure location will be of type v2_connection_node. For this location type, only the variables s1 and vol1 apply. If your measure location, however, is of any other type the variable must either be q or u1.

For both the target structure as well as for the measure location it is allowed to use a grid id as input directly. In this case we will check if the structure type associated with the given id matches with the grid administration data.

Nonetheless, we encourage you to use the structure id (that is the id of the structure in the model sqlite database) as input data. We will look up the corresponding grid id for you. If the validation holds, the state of the resource will be updated from processing to valid. Using the structure id will enable you to re-use the structure control resource after a model revision as a grid id will most likely change with every new grid generation.

Timed

POST /simulations/{simulation_pk}/events/structure-control/timed/

A timed structure control can be used to apply a certain action like increasing the pump capacity of a pump station at a given time stamp of the simulation.

Boundary conditions

POST /simulations/{simulation_pk}/events/boundaryconditions/file/

The boundary-conditions allow you to override and provide new timeseries for the 1D and 2D boundary-conditions defined in the threedimodel.

Parameter	Type	Description
filename	string	The name of the file that you want to upload. The format of the filename should be filename.extension, e.g. my_boundaries.json. Every leading and trailing spaces will be removed. Other spaces are converted to underscores and anything that is not an alphanumeric, dash, underscore, or dot will be removed as well.

python

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

with ThreediApi() as api_client:
    api_client: V3Api

    response = api_client.simulations_events_boundaryconditions_file_create(
        simulation_pk=<simulation_id>,
        data={'filename': 'my_boundaries.json'}
    )

curl

curl --request POST
     --header "Authorization: Bearer <your token here>
     --header  "accept: application/json"
     --data "filename=my_boundaries.json"
     https://api.3di.live/v3/simulations/{simulation_pk}/events/boundaryconditions/file/

If the request was successful the response body will contain a put_url:

{
  "filename": "my_boundaries.json",
  "put_url": "string"
}

Now use the put_url to actually upload the boundary-conditions file:

python

import requests

boundary_file = Path("/full_path_to/boundary_file.json")
with open(boundary_file, 'rb') as f:
    requests.put(response.put_url, data=f)

curl

curl  --upload-file /full_path_to/boundary_file.json
      "response_put_url_between_quotes"

Once the file has been uploaded it's content will be validated. If the validation succeeds the Fileboundaryconditions.state obviously will be valid, and invalid otherwise. The Fileboundaryconditions.state_detail field in the latter case provides more information about the underlying error(s).

Boundary conditions file format

The uploaded file should be a JSON-file containing an array of timeseries. The valid content of such a file could look like this:

[
    {
        "id": 1,   # sqlite boundary_1d table id
        "type": "1D",  # "1D" for 1d boundaries
        "interpolate": false,
        "values": [
            [0, 0.5],
            [500, 0,8],
            [1000, 0]
        ]
    },
    {
        "id": 1,  # sqlite boundary_2d table id
        "type": "2D", # "2D" for 2d boundaries
        "interpolate": false,
        "values": [
            [0, 0,3],
            [400, 0.1]
        ]
    },
    {
        "id": 2,
        "type": "2D",
        "interpolate": false,
        "values": [
            [0, -2.4],
            [1300, 0,3],
            [3000, 1.2],
            [3600, 0]
        ]
    }
]

Constraints

Boundary-conditions need to be added before initializing/starting the simulation and cannot be changed once the simulation is initialized.

For each defined boundary-condition in the threedimodel, a new timeseries needs to be defined.

You can only have a single boundary-conditions-file per simulation.