TUFLOW FV Get Atmos BARRA

From TUFLOW FV Wiki
Jump to navigation Jump to search

Introduction

This page shows how to use Get Atmos in geographical (longitude and latitude) coordinates. The example downloads the BARRA2 atmospheric model produced the Bureau of Meteorology's BARRA Reanalysis. The Get Atmos tool is configured to use the latest generation of the Bureau of Meteorology's BARRA Reanalysis, BARRA2. Users who need access to the earlier BARRA dataset can find it here.

Requirements And Downloads

Install Miniconda and setup a development environment by following the steps within TUFLOW FV Python Environment. If you already have a version TUFLOW FV Python Environment pre February 2026 visit the Get Tools installation and update page before proceeding. If unsure check your version of the TUFLOW FV Python Environment here.

Prerequisites

Review the download and post processing steps for longitude latitude and cartesian TUFLOW FV models. The steps for BARRA2 are analogous with changes only to the -s source and addition of the -m model arguments when running Get Atmos A and Get Atmos B.

BARRA2 Sub-Domains

To download BARRA2 data your command should include the optional argument -s BARRA2 and -m X. Where X represents your choice of the following sub-domains:

  • R2 (12 km resolution over Australia, New Zealand and the maritime continent) for the period 1979-01-01 to present day.
  • C2 (4.4 km resolution over Australia) for the period 1979-01-01 to present day.

This example demonstrates how to use Get Atmos to download BARRA2 data for the R2 sub-domain.

Workflow

The workflow to run Get Atmos includes the following steps. This tutorial provides an example of sourcing BARRA2 sub-domain R2.

  1. Initialise Get Atmos to activate the required python environment and navigate to the required working directory.
  2. Run Get Atmos A to download the datasets in their original raw format. This is conducted for a user specified spatial coordinate bounding box and time period.
  3. Run Get Atmos B to merge the data ready for direct reading by TUFLOW FV.

This page is a guided example running first Get Atmos A and then Get Atmos B via commands to the Command-Line Interface (CLI). An alternative workflow using a Python Application Programming Interface (API) is also available.

Get Atmos

Initialise Get Atmos

To activate the required python environment and navigate to the required working directory refer to the steps outlined in Initialise Get Atmos within the TUFLOW FV Get Atmos Longitude Latitude tutorial.

Running Get Atmos A

During this step Get Atmos A will be run to download BARRA2 model sub-domain R2 output for the Gulf of Carpentaria a region in the north east of Australia.

  • The first two arguments are time_start 01/03/2010 and time_end 01/05/2010 (dd/mm/yyyy).
  • The -p path switch followed by the output directory specify where raw model output will be saved. The directory name is user defined and in this example set to raw_data. This directory must be manually created prior to running the tool. If the path argument is omitted data is saved to the current working directory.
  • The -s source switch followed by the desired source model. In this example BARRA2 is specifiecied. Depending on the size of the data request the download may take several hours. It can be useful to start the request before leaving for the day so it 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.
  • The -m model switch followed by the desired model. In this example the R2 sub-domain is specified. Refer to Available BARRA data for more information on BARRA2 sub-domains.
  • The final four arguments are the spatial bounding box 153 154 -29 -28 (xmin xmax ymin ymax) which select the region of data to download. The bounding box must always be the final four arguments.

Enter the commands below ensuing the raw_data folder exists in the current working directory: 

 GetAtmos A 2010-03-01 2010-05-01 -p raw_data -s BARRA2 -m R2 135 143 -19 -7

A confirmation list of the request will be provided. If happy with the request details type Y and hit Enter to confirm the request. To abort type n.

Once complete review the download summary and confirm that files were downloaded successfully.

The downloaded BARRA2 files should appear in your specified output directory.

Prior to merging it is recommended to review the raw downloaded datasets to ensure there are no spatial gaps or corrupted files. It is also good practice to review the attributes of the raw data files as data providers may change variable names, units or conventions without notice. Always confirm that the dataset matches expected units and variable names before use. Raw files are saved in NetCDF format and can be opened with viewers that support NetCDF4. An example on reviewing Get Atmos A outputs is shown in the TUFLOW FV Get Atmos Longitude Latitude-Reviewing Get Atmos A Outputs, where Python (included with the TUFLOW FV Python Toolbox) is used to view the file structure and properties.

Running Get Atmos B

This section demonstrates how to run Get Atmos B and provides examples on using optional command line arguments to customise the merge program.

Run Get Atmos B with the following arguments (labelled as '1' beside the red box below) and ensure the output_data folder exists. Each argument is described in the table below. 

  GetAtmos B -i raw_data -o output_data -s BARRA2 -m R2 -f GoC_BARRA2_R2_20100301_20100531_UTC.nc
Argument Value Details
-i raw_data Directory where raw download files have been saved from Get Atmos A.
-o output_data The directory where merged outputs and TUFLOW FV .fvc boundary condition file will be saved (the directory must pre-exist).
-s BARRA2 Since we are merging BARRA2 model output we will need to include the command "-s BARRA".
-m R2 In Get Atmos the default sub-domain for BARRA2 is R2. However, for the purpose of demonstration we will still specify the command "-m R2".
-f GoC_BARRA2_R2_20100301_20100531_UTC.nc The -f argument is an optional argument used to specify the filename for the merged output. It is recommended to use this feature to include the start, end, and timezone to the 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 working with differing combinations of boundary conditions for a project model.

As the program is running the information within the red box labelled '2' should appear in the command window. Monitor the progress messages to verify that the merge completed successfully.

Review the contents of the output_data directory. It should contain a single merged NetCDF dataset and TUFLOW FV include .fvc file.

Get Atmos B Output: NetCDF

The NetCDF produced by Get Atmos B can be opened with programs or viewers that support NetCDF4. The following two examples are presented in TUFLOW FV Get Atmos Longitude Latitude-Reviewing Get Atmos B NetCDF:

  1. Using the TUFLOW Viewer Plugin for QGIS.
  2. Using Python and the Xarray library.

Get Atmos B Output: TUFLOW FV FVC

The FVC file produced by Get Atmos has automatically written the atmospheric boundary conditions that can be used by TUFLOW FV and should be ready to run 'as is' with some precautions. There are several default scaling and unit-conversion factors that are applied. Open GoC_BARRA2_R2_20100301_20100531_UTC.fvc in a text editor such as Notepad ++.

Within the .fvc file note that:

  • Precipitation: converted from kg m−2 s−1 to m day−1
  • MSLP: converted from Pascals (Pa) to hectopascals (hPa)
  • Temperature: an offset and scaling are applied to convert from Kelvin (K) to degrees Celsius (°C)

It is a requirement that the user review these scale factors and offsets to ensure they are accurate prior to completing project modelling. Data providers can change data formats or units without notice and it may be necessary to manually adjust the scale factors or offsets to ensure that boundary data is applied in the units required. Atmospheric models differ in the variables they supply; some may not include all parameters required. Always check that the dataset contains the variables your model needs.

Including Boundary Conditions

The .fvc file generated by Get Atmos B can be incorporated into a TUFLOW FV simulation by using an include statement as follows. 

! BOUNDARY CONDITIONS
! Atmospheric
Include == ..\bc_dbase\GoC_BARRA2_R2_20100301_20100531_UTC.fvc ! Include file for atmospheric boundary conditions

To check that variables have been correctly read into TUFLOW FV it is recommended to run TUFLOW FV with the meteorological output parameters (as per the example below). 

Output == NetCDF ! Output block, NetCDF output format
  Output Parameters == h, v, d, Air_temp, Evap, LW_rad, SW_rad, MSLP, PRECIP, rel_hum, W10 ! Water level, velocity, water depth, and atmospheric outputs 
  Output Interval == 900. ! Results will be saved every 900 seconds (15mins) of simulation time
End Output

Python API

The Get Tools can be run using a Python API. This enables automation and easy integration into larger workflows and reproducible dataset preparation. Making it ideal for repeatable or scripted simulations. For more information visit the TFV Get Tools git lab repository.

Archive Dataset

If using Get Atmos downloaded prior to February 2026 please refer to the Get Atmos Archive page.

Conclusion

This page provides examples of how to run and review Get Atmos outputs. Boundary condition data is derived from the BAARA2 regional atmospheric reanalysis model for Australia and applied to a TUFLOW FV model in geographical (longitude–latitude) coordinates.

For more information on the Get Atmos tool, please return to TUFLOW FV Get Atmos. If you have any further queries, feedback or requests for new functionality please feel free to get in contact with support@tuflow.com.

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