Application Examples¶

Standard processes used to analyse and visualise model data have been supplied as executable python script files which are controlled by passing an ASCII Run File and/or parameters at the command line. The applications have been designed to allow processing automation through python scripting. The batch processing scripts are written for the linux operating system, and can be run in the background using the linux nohup function. The spawning of multiple processes on windows is not as straightforward due to its single-user architecture. A method for running multiple processes on windows has not yet been developed.

The applications provided are summarised in Table 2.

Table 2 : Standard processing scripts.¶
Application	Purpose	Input
otm_extract_by_location.py	Extract timeseries of model data from specified locations from multiple output files	run type, run file
otm_extract_transect.py	Extract timeseries of model data along a linear transect from multiple output files	run file
otm_model_vector_fields.py	Extract 2D model fields derived from data	results path, results file, number of cores, set number
otm_batch_model_vector_fields.py	Batch process to extract 2D model fields a file using multiple cores	results path, results file, number of cores
otm_merge_model_vector_fields.py	Merge batch extracted 2D field data into a single file	extract data path, search string
otm_gen_circ_frames.py	Generate timeseries of single timestep files of 2D circulation for processing and animation	results path, results file, number of cores, set number
otm_batch_gen_circ_frames.py	Batch process to generate a timeseries of 2D circulation files from a results file	results path, results file, number of cores
otm_CoastalDistance.py	Calculate the shortest distance of each model mesh node from a hard boundary	mesh file
merge_ocmw_extracts.py	Merge multiple daily file data extracts into a single file	extract data path, search string, data type (ADCP , Model), output file

All application scripts start with the interpreter shebang line #!/usr/bin/env python3 so that the scripts can be run directly from the command line without invoking python. The scripts must have executable permissions set (this can be done on linux using the chmod command). Windows does not interpret the shebang line, so you need to invoke python to run the applications.

All of the applipcations are setup so that you can get command line help to indicate what input parameters are required, for example:

$ ./otm_extract_by_location.py -h
USAGE: ./otm_extract_by_location.py -r <runtype> -f <fname>
$

The Run Files that are passed to applications are text files that are interpreted by a basic text parser. There are a standard set of parser fields that can be used to generate the Run Files and that the parser uses to extract the input parameters. The parser fields are listed in Table 3. The parser is currently case sensitive and the format used to set a field value is

Field Name = Field Value

where there link between Field Name and Field Value is an equals sign with a single space on either side. The inclusion of extra spaces may lead to errors. The intention is to improve the parser to be less strict on the format and case. There are also some restrictions on the order data are entered into the run files. In particular, where a list of values (e.g. location coordinates) are entered this list must be immediately preceeded by a field defining the number of entites. Other fields can be entered in any order because the parser simply checks the field name and converts the parameter to the required data type and saves it in the corresponding parser data field. Examples of input files will be given with the descriptions of the applications.

Table 3 : Standard parser fields used in run files.¶
Parser Field String	Purpose
Data Path	String defining full path to data to be processed
Output Path	String defining the full path to where results are to be written
Output File	String giving the filename for output results
Search String	A sub-string that is used to select files to be processed
Start Date	A date of first day to process as a string with the format dd-mmm-yyyy, e.g. 15-Mar-2023
Number of Days	The number of days of data to process
Location CRS	Coordinate reference system for the location coordinates passed
Number of Locations	The number of geospatial locations to extract data for
Number of Nodes	The number of nodes to extract data for
Number of Vertices	The number of vertices in a polygon
Run String	String identifying a specific model run
Title String	String describing data that is added to the global attributes for the data generated
Start Point	Transect start point in the form [x, y] where x and y are the coordinates
End Point	Transect end point in the form [x, y] where x and y are the coordinates
Transect Sampling	The distance between points along a transect in metres

Extract timeseries of Open Telemac-Mascaret data by location¶

The extraction of timeseries of data at specific locations within the model domain is required for model cal/val and for targeted analysis. The script otm_extract_by_location.py is used to extract data from a proprietary format Open Telemac-Mascaret selafin results file for a set of mesh nodes identified by node number, at specified geo-spatial locations identified by geo-spatial coordinates, or for all nodes within a user-defined polygon defined by a set of vertices. There are two input parameters to the script:

Run Type: This defined type of extraction to run. Options are:
- loc = geospatial locations
- nod = nodes
- pol = polygon
Filename: The path and name to the Run File that defines the extraction.

The form of the output depends on the type of extraction requested. Extraction by geo-spatial location will generated separated files for each location which are identified by a string passed in the Run File. Extraction by nodes or polygon produces a single file with the data for all nodes extracted and a list of corresponding node ids that can be used to interpret the data.

This application assumes that the model data are stored using the standardised directory structure described in the Overview section. The model data are assumed to be in the \Model\RESULTS directory, and the extracted data will be written to the \Model\EXTRACT directory.

Two example Run Files are provided, shown in Listing 1 and Listing 2. The first example in Listing 1 extracts data at a geo-spatial location defined by UTM easting and northing coordinates. All of the soi_hr_msl_04 model files generated for the year 2023 are selected by the search string. Not text wildcards can be used in the search string. Only files with data from 15 March 2023 onwards are used and 30 days of data are extracted. The tag TideGauge is added to teh output file names to identify the data location. If multiple points are requested, each location must have a unique tag to separate the files written. Tags must not include spaces or characters not allowed in filenames.

Listing 1 soi_port_askaig_tidegauge_extract_runfile.txt¶

Data Path = D:/Models/soi_hr_msl_04/RESULTS
Search String = soi_hr_msl_04_2023*2D
Start Date = 15-Mar-2023
Number of Days = 30
Locations CRS = EPSG:32630
Number of Locations = 1
305711.0 6193556.0 TideGauge

The second example given in Listing 2 demonstrates how to extract data for all mesh nodes within a polygon. In this case data are extracted from the soi_hr_msl_04 model for 7 days starting from 7 Septenber 2023. The polygon vertices are entered as coordinate pairs of easting and northing. When the polygon is constructed the first and last points are automatically connected by the geometry functions. The polygon must not include any crossing lines or closed loops.

Listing 2 soi_polygon_extract_runfile.txt¶

Data Path = D:/Models/soi_hr_msl_04/RESULTS
Search String = soi_hr_msl_04_2023*2D
Start Date = 07-Sep-2023
Number of Days = 7
Locations CRS = EPSG:32630
Number of Vertices = 9
303216.69097382 6203165.14294004
306193.253476856 6206737.01794368
310162.003480904 6206141.70544308
311154.190981916 6203760.45544065
313733.878484547 6187488.58042405
315321.378486166 6182329.20541879
313535.440984345 6177963.58041434
309169.815979892 6176376.08041272
302026.065972605 6189274.51792587

Extract timeseries of Open Telemac-Mascaret data along a transect¶

The script otm_extract_transect.py is used to extract data along a linear transect with a user-defined along-transect sample spacing. Model data are interpolated from the nodes surrounding a given transect location onto the point using Barycentric weighted interpolation. Data are stored in order from the start point to the end point of the defined transect, and velocity data are provided in geo-coordinates and in the along- and across-transect directions.

Listing 3 is an example Run File for extracting timeseries data along a transect.

Listing 3 soi_across_channel_transect_runfile.txt¶

Data Path = D:/Models/soi_hr_msl_04/RESULTS
Output Path = D:/Models/soi_hr_msl_04/EXTRACT
Run String = soi_hr_msl_04_20230319
Output File = soi_hr_msl_04_20230319_across_transect.mat
Title String = Sound of Islay across channel transect of simulated flow
Position CRS = EPSG:32630
Start Point = [305377.00,6195392.00]
End Point = [306457.00,6195581.00]
Transect Sampling = 10.0

In this example, we are extracting an across-channel transect with the defined start and end points, with an along-transect spacing of 10.0m from the soi_hr_msl_04 model. The individual results file being processed is defined by the parameter Run String, where the suffix _2D.slf or _3D.slf is added internally to extract both the 2D and 3D field data at the transect locations.

Extract timeseries of Open Telemac-Mascaret 2D vector field data¶

The script otm_model_vector_fields.py is used to extract surface elevation and depth-averaged velocity gradient fields and the 2D vorticity field based on the depth-averaged velocity. These data are used for dynamical analysis and visualisation. The gradients and vorticity are calculated at the mesh node locations.