Exercise outline
The goal of this exercise is to create a simple hydrological volume model. In the end, it should be possible to run the volume model and inspect some (very simple) spatio-temporal output results.
Create a new model class
Add to the plugin project a new folder named Models. In this folder, create a new class named VolumeModel.cs and adapt the contents as shown below:
using System;
using System.Linq;
using DelftTools.Functions;
using DelftTools.Functions.Generic;
using DelftTools.Hydro;
using DelftTools.Shell.Core.Workflow;
using DelftTools.Shell.Core.Workflow.DataItems;
using NetTopologySuite.Extensions.Coverages;
namespace DeltaShell.Plugins.VolumeModel.Models
{
public class VolumeModel : ModelBase
{
private readonly DrainageBasin basin;
private readonly TimeSeries precipitation;
private readonly FeatureCoverage volume;
/// <summary>
/// Creates a volume model
/// </summary>
public VolumeModel()
{
// Create the input items of the volume model
basin = new DrainageBasin();
precipitation = new TimeSeries { Components = { new Variable<double>("Precipitation") } };
// Create the output item of the volume model
volume = new FeatureCoverage("Output data")
{
IsTimeDependent = true,
Arguments = { new Variable<Catchment>("Catchment") { FixedSize = 0 } },
Components = { new Variable<double>("Volume") },
};
// Wrap fields as input/output data items
DataItems.Add(new DataItem(precipitation, "Precipitation", typeof(TimeSeries), DataItemRole.Input, "PrecipitationTag"));
DataItems.Add(new DataItem(basin, "Basin", typeof(DrainageBasin), DataItemRole.Input, "BasinTag"));
DataItems.Add(new DataItem(volume, "Volume", typeof(FeatureCoverage), DataItemRole.Output, "VolumeTag"));
}
/// <summary>
/// The precipitation time series: P = P(t) [L/T]. Input of the model.
/// </summary>
public TimeSeries Precipitation
{
get { return precipitation; }
}
/// <summary>
/// The drainage basin (set of catchments). Input of the model.
/// </summary>
public DrainageBasin Basin
{
get { return basin; }
}
/// <summary>
/// Time-dependent feature coverage containing the volume of water per catchment: V = V(t, c) [L3/T]. Output of the model.
/// </summary>
public FeatureCoverage Volume
{
get { return volume; }
}
/// <summary>
/// The initialization of model runs
/// </summary>
protected override void OnInitialize()
{
// Clear any previous output
volume.Clear();
// Ensure the coordinate system of the volume output is the same as the catchments input (basin)
volume.CoordinateSystem = basin.CoordinateSystem;
// Ensure at least one catchment and one precipitation value is present
ValidateInputData();
// Initialize the output feature coverage
volume.Features.AddRange(basin.Catchments);
volume.FeatureVariable.FixedSize = basin.Catchments.Count;
volume.FeatureVariable.AddValues(basin.Catchments);
}
/// <summary>
/// The actual calculation during model run
/// </summary>
protected override bool OnExecute()
{
// Loop all times
foreach (var time in precipitation.Time.Values)
{
// Obtain the precipitation value for the current time
var p = (double) precipitation[time];
// Calculate a volume value for every catchment based on catchment area and precipitation value
var volumes = basin.Catchments.Select(c => c.AreaSize * p);
// Add the calculated volume values to the output feature coverage
volume[time] = volumes;
}
return true;
}
private void ValidateInputData()
{
var hasCatchments = basin.Catchments.Any();
var hasPrecipitationData = precipitation.Time.Values.Any();
if (!hasCatchments && !hasPrecipitationData)
{
throw new InvalidOperationException("At least one catchment and one precipitation value should be present");
}
if (!hasCatchments)
{
throw new InvalidOperationException("At least one catchment should be present");
}
if (!hasPrecipitationData)
{
throw new InvalidOperationException("At least one precipitation value should be present");
}
}
}
}
The model class is derived from the ModelBase class in order to automatically implement some basic time dependent modeling logic.
The comments in the code explain the different parts of the model implementation.
The model uses some basic data structures like data items, (feature) coverages and timeseries (functions). A description on the background and usage of these data structures is not part of this tutorial.
Register the model in the application plugin class
Register the model in the application plugin by adding the following code to VolumeModelApplicationPlugin.cs:
public override IEnumerable<ModelInfo> GetModelInfos()
{
yield return new ModelInfo
{
Name = "Volume Model",
Category = "Volume models",
CreateModel = o => new Models.VolumeModel()
};
}
Delta Shell should now be able to create and run volume models.
Exercise results
First of all, download the following WaterML2 XML file: WaterML2_precipitation_data.XML. Also download and unzip the shape files contained in the following archive: Gemeenten.zip. You will use all these data along the exercise.
Next, run the application and start creating a new model item (right click on project | Add | New Model ...). Make sure that the new model is selected in the dialog:
If you now click on OK, a new model item should be added to the project with a structure as shown in the following image:
Try to run the model (right click on the volume model item | Run Model) and check the Messages window. The following error messages will be generated:
As indicated in the error messages, some precipitation and catchment input data must be available in order to successfully run the model.
First, start importing some WaterML2 data on the precipitation time series item (right click the precipitation item | Import...). A file selection dialog automatically pops up. Select the previously downloaded WaterML2 XML file.
After finishing the import, the precipitation item should contain data as shown in the following image (double click the precipitation item in the Project window):
Next, start importing a shape file on the basin item (right click the basin item | Import...). A GIS import wizard automatically pops up. Press on Next to enter the wizard:
Now, you have to specify what type of feature you are going to import and from where. In the drop down menu for Features, select the type Catchments (1). Next, click on the ... button (2) and browse to select the shape file at the location where you have previously unzipped it (3). Once this selection has been made, you need to add the combination of feature type and source file to the import list (4). The list will be updated with the previous selection (5). At this step, you could continue adding more features from other files to the import list. We don't need to do this, so simply continue with the wizard pressing the Next button (6).
You can now map the different properties of the imported GIS data into the model features. Map the Name property to GM_NAAM and continue with the import wizard.
In general, there can be some small differences between the coordinates of different features which are actually located in the same position. The snapping precision specifies the magnitude of this margin. Simply, leave it as default and continue with the wizard.
By clicking on Finish, the wizard will be completed and the import will be started.
After finishing the import, the basin item should contain data as shown in the following image (double click on the basin item in the Project window):
Now, run the model again and notice that, this time, no new error messages have been sent to the Messages window.
Open the volume output (double click the volume item in the Project window and select the Map view) and check that the model results agree with the ones shown in the following image:
In order to inspect time dependent (output) data, open the Time Navigator window and move the slider or click one of the play buttons:
