TUFLOW FV Get Ocean Cartesian DRAFT

Introduction

This page provides an example using Get Ocean to construct boundary conditions for TUFLOW FV models that use projected cartesian (eastings and northings) coordinates. The example will download HYCOM ocean data for a coastal site on the east coast of Australia.

All data is supplied by the HYCOM consortium. Please refer to the HYCOM data acknowledgement and disclaimer.

Prerequisites

Ensure that you have successfully created a TUFLOW FV Python environment by following the instructions within: TUFLOW FV Python Environment.

Downloading and Merging

To use Get Ocean, follow the steps outlined as follows:

1. Open Anaconda Prompt, and activate your TUFLOW FV Python environment with the command:

  conda activate tfv-workspace

2. In this example, we have chosen to work in the “C:\TUFLOW\Get_Tools\my_ocean” directory, however you can select any location you like. Navigate to the directory you wish to work in through the command:

  cd <directory>

Please note: To successfully change your directory location, you must be working out of the same drive that you wish to access. To change drives, enter the command:

  <drive>

3. Enter the following command to see the program setup:

  GetOcean

This command will show the two sub-program options:

A)    GetOcean A Download raw data files

B)    GetOcean B Merge the raw data files

4. Prior to downloading any data we'll first check the arguments by calling program A, and typing “-h” for help:

  GetOcean A -h

5. Form up a command that includes the minimum required positional arguments to now download the data, as per the example below:

  GetOcean A 2022-12-31 2023-02-02 153 154 -29 -28 -p raw_data -pf CudgenCreek_HYCOM -ts 3 

The required positional arguments indicate that HYCOM files will be downloaded for 31/12/2022 to 02/02/2023 (dd/mm/yyyy) for the bounding box (bbox) of 153^oE 154^oE 29^oS 28^oS (Cudgen Creek), for all depth levels. Additional optional arguments have been specified to save the data to the folder "raw_data" (must exist before running), name the files "CudgenCreek_HYCOM_<date>.nc", and download 3-hourly data.

6. Now you wait. Downloading HYCOM can take several hours, particularly if you are collecting 3-hourly increment data.

To save time, you may have up to 2-concurrent connections to the HYCOM server per IP address, so you may run this program twice.  For example, if you are collecting data across two years, you could use two separate conda windows to concurrently download the first and second year.

Be careful that you are not using a shared PC when running this program - you don't want to lock yourself, or others, out of the HYCOM server.

If your download ends prematurely for any reason, you can simply restart the CLI tool and it will detect files that have already been collected, so long as the “—prefix” / “-pf” argument remains the same.

The downloaded HYCOM files should appear in your specified output directory as below.

7. Once your data has finished downloading it can be merged ready for TUFLOW FV using the “GetOcean B” Program. Prior to merging your raw data we'll first check the arguments by calling program B, and typing “-h” for help:

  GetOcean B -h

8. All arguments to this program are optional. By default, the program will try to merge all the files located in the (“./raw”) directory, and will automatically assign an output name, and provide a boundary condition file ready to be directly read in by TUFLOW FV.

This command can be customised to help with reprojection, add a local timezone, or pad nans downwards by depth.

A more complete example is shown below, which takes all the files located in “raw_data” and outputs a merged file called “GoC_HYCOM_20100301_20100501_AEST.nc” into “merged_data”.

This script also adds second time variable local_time that is offset by 10 hrs, and is labelled as "AEST".

  GetOcean B -i raw_data -o merged_data -tz 10 -ltz AEST -n HYCOM_20230101_20230201_GDA94Z56_AEST.nc -rp 28356

Please note: It is highly recommended to add the start, end, and timezone to your output file name. For example, MyArea_20220201_20220401_UTC.nc, indicates that the data in this file is available from the 1st of February, 2022 to 1st of April, 2022 and is in the UTC timezone. If this convention is adhered to, it can save time and reduce errors and confusion when dealing with boundary conditions.

Review Get Ocean Outputs

Get Ocean produces a single NetCDF file which contains the merged downloaded data. Using xarray to inspect this NetCDF, we see it has the structure and properties shown below:

This NetCDF file contains gridded boundary condition data, that is not suitable for viewing in QGIS. We can use the tfv Python module to create a NetCDF file for a single timestep, which we will then be able to inspect in QGIS. The details of this process are provided in Tutorial 3: Working With Gridded Boundary Condition Data. In the example below, we have chosen to create a file for the first timestep of the data.

This new NetCDF file may now be opened in QGIS using the TUFLOW Viewer Plugin to view the data variables as map outputs. In the figure below, the upper plan view shows surface velocity and the bottom image a 3D temperature long section between Point A and Point B. Note the region of cooler water underlaying the warmer surface water between chainages 1 and 3 degrees of longitude. For guidance on plotting in QGIS using the TUFLOW Viewer Plugin, please visit: Viewing 3D TUFLOW FV Results in QGIS.

When Get Ocean merges the downloaded data into a single NetCDF file, it also creates an fvc file in the same location.

Within this fvc file, you will find that Get Ocean has written your open ocean boundary conditions for you. All you need to do is list the open boundary nodestrings and replace “-0.5” with the relevant surface HYCOM mean sea level elevation offset for your study area and time period, as indicated below:

These boundary conditions can then be incorporated into your TUFLOW FV model through an include statement, as shown below. This include statement will reference GoC_HYCOM_AEST.fvc, so that the commands it contains will be read by TUFLOW FV.

Upgrading Get Ocean

Periodically, updates are made to Get Ocean to add new features and fix issues. To learn how to upgrade to the most recent version follow the steps within: Upgrading Get Tools.

Conclusion

For further information on Get Ocean, please visit our GitLab page.

To learn how to use our other Python utilities, please visit our TUFLOW FV Python Toolbox, TUFLOW FV Get Tide and TUFLOW FV Get Atmos pages.

To see how to implement the most common TUFLOW FV model design features, please access our TUFLOW FV Example Models page.

To complete tutorials or learn more tips and tricks, please return to the TUFLOW FV Wiki Mainpage.

If you have any further queries, feedback or requests for new functionality, please feel free to get in contact with support@tuflow.com