General Configuration

Action Server can be customized by editing the Action.Server.exe.config that lives in the same directory as the program:

  • 32 bits CPU: C:\Program Files\Action Modulers\Action Server
  • 64 bits CPU: C:\Program Files (x86)\Action Modulers\ Action Server

Among other things, this file specifies the database and the directory for plugin's configuration files.


By default, the database and plugin's configuration directory is C:\ProgramData\Action Modulers\<CustomApplicationName>

where CustomApplicationName is "MOHID Studio" if MOHID Studio is installed, or "Action.Server" if not. This option can be customized with:

 <add key="CustomApplicationName" value="MOHID Studio"/>

Start Database

Default database is of Sqlite format, named MOHID Studio.db as specified with the following code block in Action.Server.exe.config file:

     <property name="dialect">NHibernate.Dialect.SQLiteDialect</property>
     <property name="connection.connection_string">Data Source=MOHID Studio.db;Version=3;New=True;</property>
     <property name="connection.driver_class">NHibernate.Driver.SQLite20Driver</property>

Without MOHID Studio installed, a database must be created:

  1. Open command line prompt (start+r, write cmd)
  2. "C:\Program Files (x86)\Action Modulers\Action.Serve.exe" -checkdb
  3. Specify database name according to Action.Server.config
  4. Database should be in C:\ProgramData\Action Modulers\<CustomApplicationName>\Configurations\TestingUrbanWater.db

Running Action Server

Action Server can be run as a Windows service for operational usage, as explained earlier, or as a console program for testing purposes:

  1. Open command line prompt (start+r, write cmd)
  2. "C:\Program Files (x86)\Action Modulers\Action.Serve.exe" -console


Plugins

Installed plugins are present as dll like C:\Program Files (x86)\Action Modulers\Action Server 2015\ActionSoft.Plugins.Server.<PluginName>.dll, where <PluginName> is to be replaced by each plugin name.

Operational Modelling

Operational Modelling plugin allows to operationalize model runs (without human intervention) using user configuration in MOHID Studio.

The service checks what simulations are scheduled to run (based on each operational model crontab) and launches the operational process at a given time. The process will try to get the most recent boundary conditions configured (e.g. meteorological forecast, river measured flow, etc), will run the model and store the results in the database (that make possible to other operational models to use them as boundary conditons).

For further explnation on how to confifure operational modules in MOHID Studio follow Operational Models Configuration

GFS Downloader

GFS Downloader is a service that downloads GFS forecast data at specified times, making them available in MOHID Studio as grid or time series at specified sites. This plugin is also necessary to run WRF Runner plugin.

The corresponding dll name is ActionSoft.Plugins.Server.GfsDownloader.dll.

GFS Downloader can be customized by editing the configuration file C:\ProgramData\Action Modulers\<CostumApplicationName>\Configurations\GfsDownload.config . (Please be aware that this configuration file is case sensitive)

GFSDownload.config.png
Figure 1 : Block of Configuration from file GfsDownload.config.


Where:

CronExpression - Sec Min Days Month Weekday User. Example: "0 30 5/6 * * ?" means "At 30 minutes past the hour, every 6 hours after 05:00, any user" [1]
StorageDirectoryHdf - Directory to store converted HDF5 files as a result of 3D GFS downloaded grib2 files (only needed if Download3D = true)
StorageDirectoryBin - Directory to store converted original 3D grib2 files (needed by WRF model) (only needed if Download3D = true)
SurfaceStorageDirectoryHdf - Directory to store converted HDF5 files as a result of surface GFS downloaded grib2 files (only needed if DownloadSurface = true)
SurfaceStorageDirectoryBin - Directory to store converted original surface grib2 files (needed by WRF model) (only needed if DownloadSurface = true)
ConvertToHDF5 - Flag to convert original files into HDF5
InsertIntoDataBase - Register files in the database
ExtractTimeSeries - Flag to export time series from HDF5 file. Sites are specified in the database and configured with MOHID Studio
TimeOutMinutes - Time (in minutes) after which the download stops waiting for files
ForecastDays - Number of forecast days to download
Download3D - Download full atmosphere (needed to force WRF)
DownloadSurface - Download only surface files
PathToWgribTool - Path to wgrib2 program (include here the absolute path to the WGrib2 executable file)
MaxParallelThreads - Maximum number of simultaneous downloads
DelayHours - hours of delay to start downloading a specific forecast cycle. E.g. DelayHours = 5 means that the download of 06h00 NOAA forecast cycle will only be started after 11h00
ForecastCycles - time (hours) of the GFS forecast cycles to be downloaded (available options: 0, 6, 12, 18)
BinDelete - Flag to delete downloaded GFS binary files stored in the “StorageDirectoryBin” and / or in “SurfaceStorageDirectoryBin” folder(s)
BinDeleteBeforeDays - (only needed If BinDelete = true) delete the downloaded GFS binary files stored in the “StorageDirectoryBin” folder, if they are older than the number of days defined in this keyword. E.g.: <BinDeleteBeforeDays>3</BinDeleteBeforeDays> means that stored files older than 3 days


Each download is retried 5 times by default.

A status.log file is written in the target directory (StorageDirectoryBin\yyyyMMDDHH\status.log) for WRF Runner plugin.

Conversion to HFD5 is for the following variables:

ConvertToHDF5 Variables
GFS Name MOHID Name
TMP:2 m above air temperature
UGRD:10 m above wind velocity X
VGRD:10 m above wind velocity Y
wind modulus
RH:2 m above relative humidity
SOILW:0-0.1 m below ground relative water content (ThetaF)
TCDC:convective cloud layer cloud cover
DSWRF solar radiation

In case the user desires to automatically interpolate GFS model results to other domains, GFSDownloader offers the possibility of executing multiple interpolations, using a configuration block like the following:

GFSDownload.config interpolation.png
Figure 2 : Block of grid interpolations inside configuration from file GfsDownload.config.


Where:

GridInterpolation - block to define one or more grid interpolation domains after GFS download
GridInterpolator - (inside <GridInterpolations> block): Configuration block – one block per domain interpolation
GridDataFile - (inside <GridInterpolator> block): Mesh file to be used for the target interpolation
InterpolationMethod - (inside <GridInterpolator> block): Number (from 0 to 4) linked to the interpolation method to be used. Methods available: 0 - average; 1 – Inverse Weighted Distance; 2 – Triangulation; 3 – Bilinear; 4 - Average in the source file (when the target file has coarser resolution)
StorageDirectory - (inside <GridInterpolator> block): Target Folder to store interpolated file
InsertIntoDatabase - (inside <GridInterpolator> block): flag to insert interpolated file into MohidStudio database
ModelDomainName - (inside <GridInterpolator> block): Name given to the interpolated file

WRF Runner

WRF Runner is a service that runs the regional meteorological model WRF at specified times, making forecasts for a pre-configured domain. Results are available in MOHID Studio as grid or time series at specified sites. This plugin needs GFS Downloader plugin.

The corresponding dll name is ActionSoft.Plugins.Server.WrfRunner.dll.

WRF Runner can be customized by editing the configuration file C:\ProgramData\Action Modulers\<CostumApplicationName>\Configurations\WrfRunner.config. (Please be aware that this configuration file is case sensitive)


WrfRunner.config.png
Figure 3 : Block of Configuration from file WrfRunner.config.


Where:

GfsStorageDirectory - path to GFS original 3D files (grib2 format). It should point to the same folder path as defined in <StorageDirectoryBin> in GFS Downloader plugin.
PathToMpiExec - Path to MPICH2 libraries and executable (full path to MPI execuable file must be defined)
PathToExecutables - Path to WRF pre-compiled executables
CronExpression - Sec Min Days Month Weekday User. Example: "0 30 7/6 * * ?" means "At 30 minutes past the hour, every 6 hours after 07:00, any user" [2]
UseMpi - Flag to run WRF in parallel mode wit MPI
NumberOfCores - Number of parallelized threads
DelayHours - hours of delay to start running a specific forecast cycle. E.g. DelayHours = 5 means that the run of 06h00 forecast cycle will only be started after 11h00
ForecastCycles - time (hours) of the forecast cycles to be run (must be consistent with GFS downloaded cycles)
WorkingDirectory - Path to WRF input files, namelists, etc. If you don't have a WRF model configuration prepared yet, start with an initial WRF model template where the full working directory is already ready. Contact Action Modulers to obtain a template and copy it into the folder. If you want to prepare your own model configuration (with your own model domains), please check below the chapter how to create static grid data for a WRF domain as well as how to configure a new WRF domain for a complete description.
ConvertToHDF5 - Flag to convert original files into HDF5
KeepNetCdfFile - Flag to keep original wrf output file (in netcdf format)
InsertIntoDataBase - Register files in the database
ExtractTimeSeries - Flag to export time series from HDF5 file. Sites are specified in the database and configured with MOHID Studio
StorageDirectory - Directory to store output files
ModelDomainName - Name of domain
ForecastDays - Number of forecast days to download
SpinUpHours - Number of hours to consider as spin-up period (will be removed from final HDF5 file)
GridId - ID of the grid (domain)

HDF grid interpolations can also be defined. This must be defined in a similar way as described above in GFSDownloader (Fig. 2). The <GridInterpolations></GridInterpolations> block must be defined inside each <DomainConfiguration></DomainConfiguration> block.

Each model domain can have child (nested) model domains.In this case, a block <ChildModels></ChildModels> must be included inside domain configuration block (i.e., inside <DomainConfiguration></DomainConfiguration>). Once created the <ChildModels></ChildModels> block, one must define their child model domain configurations with a <WrfModelDomain></WrfModelDomain> block. See next figure for details:

WrfRunner.config childmodels.png
Figure 4 : Block of child models configuration from file WrfRunner.config.

Also, each WRF model domain can also be automatically published online in multiple locations (e.g. ftp sites). In that case, a block <OnlinePublications></OnlinePublications> must be placed close to the model domain configuration (for root domains -> inside <DomainConfiguration></DomainConfiguration> block; for child domains -> inside each <WrfModelDomain></WrfModelDomain> block). Each location for publishing must be defined inside the block <OnlinePublisher></OnlinePublisher>, as shown in the following figure:

WrfRunner.config onlinepublication.png
Figure 5 : Block of online publication configuration from file WrfRunner.config.

Where: URL - URL address used for hosting the publishing
User - Username with permission to publish in the URL defined above
Password - Password with permission to publish in the URL defined above


Create static grid data for a WRF domain

The steps included in this sub-chapter allow to exemplify how to create new static grid data in the context of a WRF domain, based in the structure defined for WRFRunner plugin. You should only proceed with this if you have already successfully run WRFRunner with a WRF configuration template, which can be provided by Action Modulers (please contact us):

1. Download data from the WRF V3 Geographical Static Data Downloads Page - http://www2.mmm.ucar.edu/wrf/users/download/get_sources_wps_geog_V3.html (complete data set -> http://www2.mmm.ucar.edu/wrf/src/wps_files/geog_complete.tar.gz) 2. Download topo_2m data -> http://www2.mmm.ucar.edu/wrf/src/wps_files/topo_2m.tar.bz2 3. Extracted both packages and at the end check if you got the file geog one level above the defined WRF working directory; 4. Change Geogrid.tbl because of the name of a folder: Change “rel_path = default:orogwd_10m/con/” to “rel_path = default:orogwd_10m/_con/” 5. The new definitions about number of WRF domains and their geographical boundaries and number of cells must be changed through namelist.wps

For a more complete description about WRF domain configuration and how to change input files (including namlist.wps), please See how to configure a new WRF domain.

Vessel Tracking

Result & Publishing

WMS Server

WMS stands for Web Map Service and represents a conjunction of standards for requesting map images and in a straightforward way the Action Server WMS Server represents a web service that allows to request an image, a tile of images, feature information and legend of a map for custom layers, date and extent.

For more info follow WMS on OGC

Arquitecture

The web service communicates over Hypertext Transfer Protocol (HTTP) and the WMS specification version is 1.3.0.

The requests are first routed according to type (see below) and then validated (request structure). Depending on the the request type the response output varies (image, geoJson objects, xml, etc.).

Request

WMS specifies a number of different request types and these are available in the service:

  1. GetCapabilities - requests parameters about the WMS (such as map image format and WMS version compatibility) and the available layers (map bounding box, coordinate reference systems, URI of the data and whether the layer is mostly opaque or not)
  2. GetMap - requests a map image. Parameters include: width and height of the map, coordinate reference system, rendering style, image format
  3. GetFeatureInfo - if a layer is marked as 'queryable' then you can request data about a coordinate of the map image.
  4. GetLegendGraphic - requests an image of the map's legend image, giving a visual guide to map elements.

Response

Depending on the request type the response is:

  1. GetCapabilities - a xml with all the WMS service info
  2. GetMap - a map image or a tile of images of the requested layers and extent in the format requested (e.g. png, .jpg, etc)
  3. GetFeatureInfo - geoJson objects of the requested layers that are in the range of the coordinate requested (plus a pixel sensibility for an area).
  4. GetLengednGraphic - the image legend of the request layers in the format requested (e.g. .png, .jog, etc).

Implementations

All the requests can be made on any webbrowser address bar for verification but the powerfull use is trhough operationalization of requests for example in OpenLayers, Leaflet or any other map library.

Examples

These are examples for a Action Server running in Action Modulers headquartes but could be also used for any Action Server install.

In the Web Browser

GetCapabilites

http://wms.actionmodulers.com/wms/wms?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities

It will deliver all the formats and layers available for request in the server

GetMap

http://wms.actionmodulers.com/wms/wms?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetMap&FORMAT=image%2Fpng&TRANSPARENT=true&LAYERS=England_CMEMS_Surface%20%5Bvelocity%5D%2CEngland_CMEMS_Surface%20%5Bvelocity%20modulus%5D&TILED=true&MAP_TYPE=DEF&TIME=2016-08-04T14%3A00%3A00Z&WIDTH=256&HEIGHT=256&CRS=EPSG%3A3857&STYLES=&BBOX=-313086.06785608083%2C6261721.357121639%2C1.1059455573558807e-9%2C6574807.424977721

It will deliver a small tile of a CMEMS result of surface velocity (vectors and modulus in color) for English Channel.

GetLegendGraphic

http://wms.actionmodulers.com/wms/wms?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetLegendGraphic&FORMAT=image%2Fpng&LAYERS=England_CMEMS_Surface%20[velocity],England_CMEMS_Surface%20[velocity%20modulus]&CROP_X=20&CROP_X_LEFT=10&CROP_Y=0&CROP_Y_TOP=0&HEIGHT=150&WIDTH=0&MANTAIN_ASPECT=false&ROTATION=0

It will deliver the legend of the two layers of CMEMS result of surface velocity (vectors and modulus in color).

In OpenLayers

This a WMS layer and source that can be added to the OpenLayers map to show on the web GIS:

GetMap

var wmsLayer = new ol.layer.Tile({
         source:  new ol.source.TileWMS(/** @type {olx.source.TileWMSOptions} */({
               url: 'http://wms.actionmodulers.dtdns.net/wms/wms',
               params:
               {
                   //Comma separated list, case sensitive, no blanks, please
                   'LAYERS': "England_CMEMS_Surface [velocity],England_CMEMS_Surface [velocity modulus]",
                   'TILED': true,
                   'MAP_TYPE': 'DEF',
                   'TIME': ISODateString(new Date()),
               }
               }));
         });

 map.addLayer(wmsLayer);

GetFeatureInfo And to get the info from a given point (e.g. mouse click)

                  var url = wmsLayer.getSource().getGetFeatureInfoUrl(
                             coordinate, viewResolution, viewProjection,
                             {
                                 'INFO_FORMAT': 'text/json',
                                 'QUERY_LAYERS' :  "England_CMEMS_Surface [velocity],England_CMEMS_Surface [velocity modulus]",
                             });

                       $.ajax({
                           url: url,
                           type: 'GET',
                           dataType: "json",
                           contentType: "application/x-www-form-urlencoded; charset=UTF-8",
                       })
                           .success(
                           function (data) {
                               $.each(data.features, function(i, dataElement){
                                    alert(dataElement.properties.LayerName);
                               }
                           })
                           .fail(function (jqXHR, textStatus, errorThrown) {
                               alert("Fail retrieving data");
                           });

Verify that the geojson objects are serialized and is possible to acess the instance properties directly as the features array and for each feature the properties and the LayerName property. See http://geojson.org/ for geoJson format.

In Leaflet
var wmsLayer = L.tileLayer.wms('http://wms.actionmodulers.dtdns.net/wms/wms?', {
   layers: 'England_CMEMS_Surface [velocity],England_CMEMS_Surface [velocity modulus]'
}).addTo(map);

Be aware that WMS handling in Leaflet is quite basic and there’s no GetFeatureInfo support.

Rest API

REST API stands for Representational State Transfer Application Programming Interface and in a straightforward way the Action Server REST API represents a web service that allows to query Action Server database.

For more info follow RESTfull

Arquitecture

The web service communicates over Hypertext Transfer Protocol (HTTP) with the same HTTP verbs (GET, POST, PUT, DELETE, etc.) that web browsers use to retrieve web pages and to send data to remote servers.

The requests are processed asyncronous, routed to their location (the controller and the action, see below) where the query to database is made. Results are serialized to json and sent in the response.

The main classes in database (ModelDomain, Simulation, Monitoring Station, TimeSeries, etc) have already a set of queries pre-defined. New querys can be added in a straightforward way. The service access can be limited with password.

Request

The web servce uses the following notation for requests: "server address"/"controller"/"action"/"parameters"

One example of a server address is "api.actionmodulers,com/api/" but this service can be mounted on any Action Server installation.

The controller is usually associated to a database class (e.g. ModelDomain to handle model domains, Simulation to handle simulations and so on).

The action is the request being made (e.g. taking ModelDomain example GetByDates will try to query model domains existing in database with simulation results in between dates).

The parameters may be optional and are the information needed to perform the request (e.g. start and end date of the request on the above example).

Response

In GET requests the respone is: - a list of json objects (https://en.wikipedia.org/wiki/JSON), that can be empty if no result found, when the result is a database object or instance. - or simply one value or list of values when the result was an operation on objects or instances.

In POST requests the response is just an HTTP status. The POST is used to send information to the server (e.g. run on-demand simulations).

Implementations

Get requests can be made just typing on the browser address bar for verification but the powerfull use is trhough operationalization of requests for example in javascript or jquery AJAX requests (http://api.jquery.com/jquery.ajax/).

Examples

These are examples for a Action Server running in Action Modulers headquartes but could be also used for any Action Server install.

In the Web Browser

GET request on any broswer address bar:

http://api.actionmodulers.com/api/modelDomain/list

This will return a list of all model domains existing in the database without any filter. The format of each result is a json object simplified from the ModelDomain class existing in the database.

With AJAX

Same Get request in a AJAX jquery code, where for each element found is displayed the ModelDomain name:

                       $.ajax({
                           url: api.actionmodulers,com/api/ModelDomain/list,
                           type: 'GET',
                           dataType: "json",
                           contentType: "application/x-www-form-urlencoded; charset=UTF-8",
                       })
                           .success(
                           function (data) {
                               $.each(data, function(i, dataElement){
                                    alert(dataElement.Name);
                               }
                           })
                           .fail(function (jqXHR, textStatus, errorThrown) {
                               alert("Fail retrieving data");
                           });

It can be seen that the AJAX deserializes the result in to javascript objects so the instance properties are available directly (e.g. dataElement.Name and dataElement.ModelType - check the above example to depict ModelDomain structure with ID, Name and ModelType).

MOHID Lagrangian Simulations Examples

Examples of MOHID particle (lagrangian) and polygon (eulerian) results (geometry and values in geoJson format) fetched by simulation ID and instant in REST API:

  1. Get Emission Point : baseApiUrl + "geometry/EmissionPointBySimulation/?&simulationId=" + simulationId
  2. Get Plume Center : baseApiUrl + "geometry/PlumeCenterBySimulation/?&simulationId=" + simulationId
  3. Get Plume Envelope : baseApiUrl + "geometry/PlumeEnvelopeBySimulationAndInstant/?&simulationId=" + simulationId + "&instant=" + instant
  4. Get Particles Property : baseApiUrl + "geometry/ParticlePropertyBySimulationAndInstant/?&propertyName=" + propertyName + "&simulationId=" + simulationId + "&instant=" + instant
  5. Get Polygon Property : baseApiUrl + "geometry/GridPropertyBySimulationAndInstant/?&propertyName=" + propertyName + "&is3D=" + is3D+ "&computeMaximumInColumn=" + computeMaximumInColumn + "&simulationId=" + simulationId + "&instant=" + instant
  6. Send a Simulation to Run : baseApiUrl + "Simulation/PostLagrangian"

baseApiUrl is the server address that can be api.actionmodulers,com/api/ or any other Action Server implementation. The parameters (e.g. simulationId, instant, etc.) are presented here as javascript variables that need to be defined for the request to be valid.

The last example can be processed in a web browser address bar (only GET's) and all the simulation otpions GeneralSettings, SpillSettings, BoundaryConditions and AdvencedSettings need to be sent as a javascript object. Shortlyt this object properties and value type will be addressed here.

Coastal Risk

Coastal Risk - User Guide


References

  1. Cron expression descriptor tool : http://cronexpressiondescriptor.azurewebsites.net.
  2. Cron expression descriptor tool : http://cronexpressiondescriptor.azurewebsites.net.

Links

User Guides

Coastal Risk