TUFLOW FV Get Atmos Longitude Latitude Draft

Introduction

This page shows how to use Get Atmos in geographical (longitude and latitude) coordinates. The example downloads the ERA5 atmospheric model output and generates the boundary conditions used by the suite of Coastal Example Models.

Requirements And Downloads

1. IMPORTANT - To download the default data source ERA5 you are required to setup a CDSAPI key via the Copernicus API Webpage.
2. 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.

Workflow

The workflow to run Get Atmos includes the following steps.

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.

Initialise Get Atmos

To activate the required python environment and navigate to the required working directory:

1. Open Anaconda prompt (installed with Miniconda) and activate the TUFLOW FV Python environment with the command:

  conda activate tfv-workspace

2. Navigate to your preferred working directory. In this example, the working directory is set to C:\TUFLOW\Get_Tools\my_atmos.

  cd <directory>

If the working directory is located on another drive switch to that drive using the drive letter and ':' for example to switch from K drive to C drive enter 'C:' as shown below. Then cd to the required working directory.

3. Check that Get Atmos is installed correctly by entering the following command into the command window.

  GetAtmos

Running Get Atmos outputs the overview help information including the available sub-commands.

• GetAtmos A – Downloads the raw atmospheric model output files for a specified time period and spatial extent.
• GetAtmos B – Merges the raw atmospheric files into a single NetCDF file and creates a TUFLOW FV FVC (Boundary Include) file.
• GetAtmos info – Prints more detailed help information about the program and available run options.

Use view more information about a specific sub-command.

4. Run the below command:

  GetAtmos info

This produces:

• A brief description of the tool’s purpose.
• The available data sources and sub-models (for example ECMWF ERA5, NOAA CFSR and BoM BARRA2) and any registration requirements.
• Example usage for downloading or merging datasets.
• Guidance on how to access detailed help for specific sub-commands (using GetAtmos A -h or GetAtmos B -h).

Get Atmos A

Get Atmos A is used to download raw atmospheric model data. This section will:

• Review the available run options.
• Provide an example of running the program.
• Demonstrate a method to review Get Atmos A outputs.

Reviewing Run Options

Prior to downloading any model output review the arguments for Get Atmos A by entering the command:

  GetAtmos A -h

For reference the command is labelled as '1' in the red box of the figure below.

The output shows a number of required positional arguments (red box '2') and run options (red box '3'). Positional arguments are required and must be provided in order: time_start and time_end to define the date range and bbox to define the spatial extent as longitude or latitude bounds. Optional arguments can be included as needed.

Running Get Atmos A

During this step Get Atmos A will be run to download ERA5 model 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 final four arguments are the spatial bounding box 135 143 -19 -7 (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 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 ERA5 files should appear in your specified output directory as shown below.

Reviewing Get Atmos A Outputs

This section is for information only.

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. The example below shows the structure and properties of ERA5_ATMOS_20100401_20100430.nc using Python (which can be installed with the TUFLOW FV Python Toolbox):

Review of the data attributes can be completed to confirm the units for each data variable. The file ERA5_ATMOS_20100401_20100430.nc contains the variables and units below.

Data Variables	Units	Long Name
avg_sdlwrf	W m-2	Time-mean surface downward long-wave radiation flux
avg_sdswrf	W m-2	Time-mean surface downward short-wave radiation flux
avg_tprate	kg m-2 s-1	Time-mean total precipitation rate
u10	m s-1	10 metre U wind component
v10	m s-1	10 metre V wind component
mslp	Pa	Mean sea level pressure
t2m	K	2 metre temperature
d2m	K	2 metre dewpoint temperature

Take note of these units. When generating TUFLOW FV control files in Get Atmos B scale factors and offsets however these are indicative only and require review prior to using on modelling projects.

Get Atmos B

Get Atmos B merges raw atmospheric files output from Get Atmos A into a single NetCDF file compatible with TUFLOW FV. It also creates a TUFLOW FV boundary condition include file. In this section the following concepts are presented.

• Review the available run options.
• Provide an example of running the program.
• Demonstrate methods to review Get Atmos B outputs.

Reviewing Run Options

Prior to downloading any model output review the arguments for Get Atmos B by entering the command:

  GetAtmos B -h

For reference the command is labelled as '1' in the red box of the figure below.

The output describes a number of run options (red box '2') that can be used to customise how atmospheric datasets are merged and exported.\

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.

Example 1 - Input And Output Directories

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

  GetAtmos B -i raw_data -o output_data

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

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.

Example 2 - Timezone Options And Filename Output

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 -tz 10 -ltz AEST -f GoC_ERA5_20100301_20100531_AEST.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).
-tz	10	This helps when working in a local timezone rather than Coordinated Universal Time (UTC). 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.
-ltz	AEST	This command should be used in combination with -tz. It adds timezone attribute metadata to the NetCDF local_time variable.
-f	GoC_ERA5_20100301_20100531_AEST.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 check that the timezone commands and custom filepath are as expected (red box '2' below).

If the program has run as expected there should be two new files GoC_ERA5_20100301_20100531_AEST.nc and GoC_ERA5_20100301_20100531_AEST.fvc within the output_data directory as shown below.

Reviewing Get Atmos B NetCDF Output

The NetCDF produced by Get Atmos B can be opened with programs or viewers that support NetCDF4. Two examples are presented as follows.

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

Example 1 - QGIS TUFLOW Viewer

NetCDFs produced by Get Atmos B can be directly opened in QGIS using the TUFLOW Viewer Plugin as described in the Load Map Outputs wiki page. The below image shows the map output for air temperature.

The TUFLOW Viewer Plugin can also be used to generate a variety of timeseries cross sectional and longitudinal plots. The below figure shows creation of a timeseries plot of mean sea level pressure.

Example 2 - Python

Reviewing NetCDF contents with Python allows the user to access more detailed information on the file contents and attributes than what is available in QGIS.

This example shows the contents of the merged file using Python and Xarray (which can be installed using the TUFLOW FV Python Toolbox).

Python attributes can be used to extract key information such as data units which are summarised in the table below..

Data Variables	Units
avg_sdlwrf	W m**-2
avg_sdswrf	W m**-2
avg_tprate	kg m**-2 s**-1
u10	m s-1
v10	m s-1
mslp	Pa
t2m	K
relhum	%

TUFLOW FV Boundary Include File

Open the file GoC_ERA5_20100301_20100531_AEST.fvc in a text editor such as Notepad ++.

Get Atmos has automatically written the atmospheric boundary conditions required 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 that required review as follows.

• 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 as shown in the table below.

TUFLOW FV Boundary Type	ERA5 Units (@December 2025)	TUFLOW FV Units	Conversion
LW_RAD_GRID	W m-2	W m-2	N/A
SW_RAD_GRID	W m-2	W m-2	N/A
PRECIP_GRID	kg m-2 s-1	m day-1	BC Scale == 86.4 ! Conversion: [kg m-2 s-1] to [m day-1]
W10_GRID	m s-1	m s-1	N/A
MSLP_GRID	Pa	hPa	BC Scale == 0.01 ! Conversion: pascal [Pa] to hectopascal [hPa]
AIR_TEMP_GRID	K	°C	BC Offset == -273.15 ! Conversion: kelvin [K] to degrees Celsius [°C]
REL_HUM_GRID	N/A**	%	N/A

***Relative humidity (relhum) is internally calculated in Atmos B as ERA5 does not provide 2 m relative humidity directly in its outputs. Relative humidity is derived from the ERA5 2 m temperature (t2m) and 2 m dewpoint temperature (d2m) downloaded in Get Atmos A. For further information refer to _custom_conversions.py for the dewpt_to_relhum function within the TUFLOW FV Python Toolbox Data Package or contact support@tuflow.com.

! TUFLOW FV FVC File for Atmospheric Dataset
! Written by TUFLOW FV `tfv-get-tools`

! This control file has been prepared using the TUFLOW FV Get Tools (tfv-get-tools),
! a free set of Python tools designed to assist with the download and formatting of
! boundary condition data from global model sources such as ERA5 and CFSR for use in TUFLOW FV.
! These external model datasets are subject to change over time and are provided 'as is'.
! Users are responsible for reviewing and, where possible, verifying these inputs against
! observational data before use in any modelling application.

! Source: ERA5
! Info: https://cds.climate.copernicus.eu/datasets/reanalysis-era5-single-levels

! NetCDF time datum: AEST
! NetCDF start time: 2010-03-01 10:00
! NetCDF end time: 2010-06-01 09:00


! Coordinate system EPSG: 4326
! Coordinate system name: WGS 84
! NetCDF x-limits: 135.0000, 143.0000
! NetCDF y-limits: -19.0000, -7.0000

Grid Definition File == output_data/GoC_ERA5_20100301_20100531_AEST.nc
  Grid Definition Variables == longitude, latitude
  Grid Definition Label == atmos
End Grid

BC == LW_RAD_GRID, atmos, output_data/GoC_ERA5_20100301_20100531_AEST.nc
  BC Header == local_time, avg_sdlwrf
  BC Update dt == 3600.
  BC Time Units == hours
  BC Reference Time == 01/01/1990 00:00
  BC Default == NaN
End BC

BC == SW_RAD_GRID, atmos, output_data/GoC_ERA5_20100301_20100531_AEST.nc
  BC Header == local_time, avg_sdswrf
  BC Update dt == 3600.
  BC Time Units == hours
  BC Reference Time == 01/01/1990 00:00
  BC Default == NaN
End BC

BC == PRECIP_GRID, atmos, output_data/GoC_ERA5_20100301_20100531_AEST.nc
  BC Header == local_time, avg_tprate
  BC Scale == 86.4 ! Conversion: [kg m-2 s-1] to [m day-1]
  BC Update dt == 3600.
  BC Time Units == hours
  BC Reference Time == 01/01/1990 00:00
  BC Default == NaN
End BC

BC == MSLP_GRID, atmos, output_data/GoC_ERA5_20100301_20100531_AEST.nc
  BC Header == local_time, mslp
  BC Scale == 0.01 ! Conversion: pascal [Pa] to hectopascal [hPa]
  BC Update dt == 3600.
  BC Time Units == hours
  BC Reference Time == 01/01/1990 00:00
  BC Default == NaN
End BC

BC == REL_HUM_GRID, atmos, output_data/GoC_ERA5_20100301_20100531_AEST.nc
  BC Header == local_time, relhum
  BC Update dt == 3600.
  BC Time Units == hours
  BC Reference Time == 01/01/1990 00:00
  BC Default == NaN
End BC

BC == AIR_TEMP_GRID, atmos, output_data/GoC_ERA5_20100301_20100531_AEST.nc
  BC Header == local_time, t2m
  BC Offset == -273.15 ! Conversion: kelvin [K] to degrees Celsius [°C]
  BC Update dt == 3600.
  BC Time Units == hours
  BC Reference Time == 01/01/1990 00:00
  BC Default == NaN
End BC

BC == W10_GRID, atmos, output_data/GoC_ERA5_20100301_20100531_AEST.nc
  BC Header == local_time, u10, v10
  BC Update dt == 3600.
  BC Time Units == hours
  BC Reference Time == 01/01/1990 00:00
  BC Default == NaN
End BC

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_ERA5_20100301_20100531_AEST.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. TThis 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 developed from the ERA5 global atmospheric model for a TUFLOW FV model in geographic (longitude and latitude) coordinates.

For more information on the Get Atmos tool including alternatively models and coordinate systems 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.