TUFLOW FV Get Atmos Cartesian

From TUFLOW FV Wiki
Jump to navigation Jump to search

Introduction

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

Prerequisites

1. IMPORTANT - To download the default model output 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

Activate tfv-workspace.png


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>

GetAtmos cd my atmos.png

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>

GetAtmos change drive.png

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 model output files

GetAtmos.png

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

GetAtmos A -h.png

5. To download CFSR model output, your command must include the optional argument --source CFSR. It is important to note that downloading CFSR data from the data server may take several hours, depending on the data request. It may be best to start just the data request before leaving for the day, so they can run overnight. Note that you may periodically experience connectivity issues if the data server is busy. If this is the case, you may need wait and try again at a later time.

Call the program with your specifications for the required positional arguments, and additional optional arguments as desired. This example shows retrieval of CFSR model output covering Cudgen Creek spanning 12:00 am on 31/12/2022 to 12:00 am on 02/02/2023 (dd/mm/yyyy). Please note that the folder "raw_data" must exist before running. 

  GetAtmos A “2022-12-31 00:00” “2023-02-02 00:00” 153 154 -29 -28 --path raw_data --source CFSR

GetAtmos download data cart.png

GetAtmos download data complete cart.png

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

GetAtmos downloaded files cart.png

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

GetAtmos B -h.png

7. Now submit the merge job to GetAtmos B with the following arguments:

Argument Value Details
in_path raw_data Where our raw download files are from GetAtmos A.
out_path merged_data The directory our merged outputs will be saved.

Note: You will need to create this directory prior to running GetAtmos B.

source CFSR Since we are merging CFSR model output, we will need to include the command "--source CFSR".
reproject 28356 The TUFLOW FV model of Cudgen Creek is in the coordinate reference system MGA94 Zone 56, corresponding to EPSG:28356. This reprojection switch will project the coordinates from latitude and longitude into the specified EPSG system, adding the projected coordinates into two new created variables, x and y. The latitude and longitude variables are retained to enable the boundary conditions to be displayed in the correct location in QGIS.
time_start "2022-12-31 00:00” Trims the merged model output to start at this time (UTC).
time_end “2023-02-02 00:00” Trims the merged model output to end at this time (UTC).
tz 10 An additional time variable local_time will be added to the output NetCDF adding the tz offset (hrs). Note: The variable time will remain in the NetCDF in UTC.
tzl AEST tlz will include additional attribute metadata to the NetCDF local_time variable. If using a time offset, it’s good practice to include the ltz.
file_name CFSR_20230101_20230201_GDA94Z56_AEST.nc Set a custom file name to include the model source, the start and end time, plus the timezone. By being careful with our file naming we can already see some information about what it in the NetCDF.

The command line entry is provided as follows: 

GetAtmos B --in_path raw_data --out_path merged_data --source CFSR --reproject 28356 --time_start "2022-12-31 00:00” --time_end “2023-02-02 00:00” -tz 10 -ltz AEST --file_name CFSR_20230101_20230201_GDA94Z56_AEST.nc

GetAtmos merge data rev cart.png

Please note: It is recommended to add the start, end, coordinate reference system and timezone to your output file name. For example, MyArea_20220201_20220401_GDA94Z56_UTC.nc, indicates that the boundary conditions in this file is available from the 1st of February 2022 to 1st of April 2022, uses the GDA94 Zone 56 coordinate reference system, 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:

GetAtmos xarray netcdf cart.png

This NetCDF file can be viewed in QGIS using the following steps.

1. Open a new blank QGIS instance.

GetAtmos QGIS blank.png

2. Select the Coordinate Reference System (CRS) button in the bottom right toolbar.

GetAtmos CRS button.png

3. Search for the CRS of your TUFLOW FV model. For the Cudgen Creek model, this will be GDA94 MGA zone 56, which corresponds to EPSG:28356. Once you have selected your CRS, select "Apply" and then "OK".

GetAtmos CRS search.png

4. Open the TUFLOW Viewer Plugin and navigate to Load Results > Map Outputs to select the Get Atmos B output NetCDF file.

GetAtmos load results cart.png

GetAtmos QGIS NetCDF cart.png

5. QGIS automatically detects the latitude and longitude variables in the NetCDF, and will display the boundary conditions accordingly. To be viewed in the correct location, the layer therefore needs to be translated. To do this, right click on the layer, select Layer CRS, and set to EPSG: 4326.

GetAtmos set layer CRS.png

6. It is likely that the frame may no longer display the layer. To remedy this, right click on the layer and select “Zoom to Layer(s)”.

GetAtmos zoom to layer.png

7. To verify that the boundary condition is correctly located, we will add a Google Satellite layer by navigating to AusMap > Google Basemaps > Google Satellite. If you do not have the AusMap plugin, you can install it via Plugins > Manage and Install Plugins... .

GetAtmos google satellite.png

We can now see that our boundary condition is located on the east coast of Australia.

GetAtmos QGIS NetCDF aligned cart.png


Once the Get Amost B output NetCDF file is correctly located in QGIS, the TUFLOW Viewer Plugin can then be used to generate a variety of plots for the NetCDF variables. For guidance on plotting in QGIS using the TUFLOW Viewer Plugin, please visit: Viewing 3D TUFLOW FV Results in QGIS - TUFLOW FV Wiki.

Checking TUFLOW FV Boundary Assignment

The QGIS and Python review process presented above (TUFLOW FV Get Atmos Cartesian) 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.

GetAtmos cart outputs.png

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 model output into a single NetCDF file, it also creates an fvc file in the same location.

GetAtmos outputs cart.png

Within this fvc file, you will find that Get Atmos has written your atmospheric boundary conditions for you. By default, Get Atmos will reference the new reprojected x and y variables in the grid definition file, as shown below.

GetAtmos fvc cart.png

These 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.

GetAtmos include command cart.png

Conclusion

This page has provided an example of how to use Get Atmos to construct boundary conditions for a TUFLOW FV model that uses a cartesian coordinate system.

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

Retrieved from "https://fvwiki.tuflow.com/w/index.php?title=TUFLOW_FV_Get_Atmos_Cartesian&oldid=13400"