TUFLOW FV Get Atmos Longitude Latitude

Introduction

This page provides an example using Get Atmos to construct boundary conditions for TUFLOW FV models that use geographical longitude and latitude coordinates.

The example outlines the procedure used to download the ERA5 atmospheric model output used for boundary conditions within the Coastal Example Models.

Prerequisites

1. IMPORTANT - To download the default data source ERA5, you are required to setup a CDSAPI key. For instructions on how to complete this, please visit the Copernicus API Webpage. You can alternatively download CFSR/CFSv2 or BARRA model output without any additional account setup.

2. Install miniconda and set up the TUFLOW FV Python Environment by following the steps within the TUFLOW FV Python Environment page.

Downloading And Merging

1. Open Anaconda prompt (installed with miniconda), 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_atmos” 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 to command GetAtmos to see the program setup:

  GetAtmos

This command will show the two sub-program options:

A) GetAtmos A Download raw model output files

B) GetAtmos B Merge the raw mode output files

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

  GetAtmos A -h

5. Call the program with your specifications for the required positional arguments, and optional arguments as desired. This example shows retrieval of ERA5 model output covering the Gulf of Carpentaria spanning 12:00 am on 01/03/2010 to 12:00 am on 01/05/2010 (dd/mm/yyyy). Please note that the folder "raw_data" must exist before running.

  GetAtmos A “2010-03-01 00:00” “2010-05-01 00:00” 135 143 -19 -7 --path raw_data

The downloaded ERA5 files should appear in your specified output directory as below:

6. Once all raw model output files are downloaded, we can merge the files into a single NetCDF suitable for direct usage with TUFLOW FV. To see the options for merging, enter the command:

  GetAtmos B -h

7. Now submit the merge job. In this example, we use the command (Note: You need to create the folder "merged_data" before running):

  GetAtmos B --in_path raw_data --out_path merged_data

If you want to work in a local timezone, rather than UTC, the optional extra commands “tz” and “ltz” can be added. If the tz command is entered an additional time variable local_time will be added to the output NetCDF. The variable time will still be included in UTC. If the tlz command additional attribute metadata is added to the NetCDF local_time variable. If using a time offset, it’s good practice to include the ltz to avoid later confusion.

In this example, we will update our command to add both tz and ltz commands, and specify the filename “GoC_ERA5_20100301_20100531_AEST.nc” .

  GetAtmos B --in_path raw_data --out_path merged_data -tz 10 -ltz AEST --file_name GoC_ERA5_20100301_20100531_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 model output 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.

Reviewing Get Atmos Outputs

Get Atmos produces a single NetCDF file that contains the merged downloaded model output. Using Xarray (installed with the TUFLOW FV Python Toolbox) to inspect this NetCDF, we see it has the structure and properties shown below:

This NetCDF file can also be opened in QGIS using the TUFLOW Viewer Plugin to view the model output variables as map outputs. The below image shows the map output for air temperature. For guidance on plotting in QGIS using the TUFLOW Viewer Plugin, please visit: Viewing 3D TUFLOW FV Results in QGIS .

The TUFLOW Viewer Plugin can also be used to generate a variety of plots of the model output variables. The below figure shows creation of a timeseries plot of mean sea level pressure anywhere within the model.

Checking TUFLOW FV Boundary Assignment

Please note: The QGIS and Python review process presented above (Reviewing Get Atmos Outputs) verifies that the longitude and latitude attributes of the NetCDF dataset cover the correct location. To check that the variables have been read into TUFLOW FV correctly, you must run your TUFLOW FV model with the meteorological output parameters (MSLP, W10 etc.) in your NetCDF output block.

You can then review the map outputs using the TUFLOW Viewer in QGIS to determine their location.

TUFLOW FV Boundary Include File

When Get Atmos 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 Atmos has written your atmospheric boundary conditions for you.

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

Conclusion

This page has provided an example of how to use Get Atmos to construct boundary conditions for a TUFLOW FV model that uses longitude and latitude coordinates.

For more information on the Get Atmos tool, please return to TUFLOW FV Get Atmos.