TUFLOW FV Get Ocean
Introduction
This tutorial demonstrates how to run the Get Ocean python command line tool using the TUFLOW FV Python Toolbox. This tool is used to assist with downloading and processing HYCOM ocean data used for TUFLOW FV ocean boundary conditions, including:
- Mean sea level surface anomaly
- 3D ocean currents
- 3D distribution of ocean salinity
- 3D distribution of ocean temperature
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.
Example - Downloading HYCOM Data For The Gulf Of Carpentaria
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 with the minimum required positional arguments to now download the data, as per the example below:
GetOcean A 2010-03-01 2010-05-01 135 143 -19 -7
This will download HYCOM files for 01/03/2010 to 01/05/2010 (dd/mm/yyyy) on a daily time interval (the default time interval) for the bounding box (bbox) of 135oE 143oE 19oS 7oS (Gulf of Carpentaria), for all depth levels.
By default, the files will be downloaded into the same directory from where the tool is being called, and will have the name format: “HYCOM_<date>.nc”
Optional arguments can be supplied to select a subset of z-levels, to put the data files into a sub-directory, to give the files a custom name prefix, or download higher temporal resolution data.
For example, the following command will download only the top 75m of data, save the data to the folder “raw_data” (must exist before running), will name the files “GoC_HYCOM_<date>.nc”, and will download 3-hourly data.
GetOcean A -p raw_data -pf GoC_HYCOM -ts 3 -z 0 75 2010-03-01 2010-05-01 135 143 -19 -7
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 GoC_HYCOM_20100301_20100501_AEST.nc
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