TUFLOW FV Get Atmos Cartesian Draft

Introduction

This page shows how to use Get Atmos in projected cartesian (eastings and northings) coordinates. The example downloads the CFSR atmospheric model output and generates the boundary conditions in TUFLOW FV.

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.

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 CFSR model output for a section of the Australian east coast.

• The first two arguments are time_start 31/12/2022 and time_end 02/02/2023 (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 CFSR is specifiecied. 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 this is the case you may need wait and try again at a later time.
• 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 2022-12-31 2023-02-02 -p raw_data -s CFSR 153 154 -29 -28

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 CFSR 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 CFSR_ATMOS_rh2m_20230201_20230228.nc using Python (which can be installed with the TUFLOW FV Python Toolbox):

CFSR data is downloaded as a single NetCDF file per month per variable. Each file should be checked to confirm the variable units and data continuity. The CFSR data in this example contains the following variables and units.

Data Variables	Units	Long Name
Downward Long-wave raditation	W m-2	Downward long-wave radiation flux (mixed intervals average) at ground or water surface
Downward short-wave raditaiton	W m-2	Downward short-wave radiation flux (mixed intervals average) at ground or water surface
Precipitation rate	kg m-2 s-1	Precipitation rate (mixed intervals average) at ground or water surface
u-component of wind	m s-1	u-component of wind @ Specified height level above ground
v-component of wind	m s-1	v-component of wind @ Specified height level above ground
Pressure reduced to MSL	Pa	Pressure reduced to MSL at mean sea level
Relative humdity	%	Relative humidity at specified height level above ground
Temperature	K	Temperature at specified height level above ground

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 - Reprojecting To EPSG:28356, 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 -s CFSR -rp 28356 -tz 10 -ltz AEST -f CFSR_20230101_20230201_GDA94Z56_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).
-s	CFSR	Since we are merging CFSR model output we will need to include the command "-s CFSR".
-rp	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.
-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.
-tzl	AEST	This command should be used in combination with -tz. It adds timezone attribute metadata to the NetCDF local_time variable.
-f	CFSR_20230101_20230201_GDA94Z56_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, projection and timezone to the output file name. For example, MyArea_20220201_20220401_GDA94Z56_UTC.nc indicates that the model output in this file spans from 1 February 2022 to 1 April 2022, is projected in MGA94 Zone 56 and uses the UTC timezone. Following this naming convention can save time and reduce errors and confusion when working with different 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 he output_data directory. It should contain a single merged NetCDF dataset and TUFLOW FV include .fvc file.

Reviewing Get Atmos B NetCDF Output

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

1. Loading and checking the NetCDF spatial extent in 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. Instruction on installing the TUFLOW Viewer plugin plugin can be found here.

Use the below steps to verify the spatial extent of the NetCDFs produced by Get Atmos B:

1. Open a new blank QGIS instance. Select the Coordinate Reference System (CRS) button in the bottom right toolbar.

2. In Project CRS dialog search for the CRS that the data was reprojected to: GDA94 MGA zone 56 which corresponds to EPSG:28356. Once you have selected your CRS select Apply and then OK.

3. From the TUFLOW Viewer Plugin select Load Results > Map Outputs.

From the dialog navigate to the Get Atmos B output_data folder and open CFSR_20230101_20230201_GDA94Z56_AEST.nc.

4. 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 needs to be translated. To do this right click on the layer then select Layer CRS > Set to EPSG: 4326. 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).

5. To verify that the boundary condition is correctly located add a Google Satellite layer by navigating to AusMap > Basemaps and Imagery > Google Satellite Hybrid. Note if you do not have the AusMap plugin you can install it via Plugins > Manage and Install Plugins....

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

Once the Get Atmos 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 visit Viewing 3D TUFLOW FV Results in QGIS - TUFLOW FV Wiki.

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
dlwrf	W m-2
dswrf	W m-2
prate	kg m-2 s-1
mslp	Pa
relhum	%
t2m	K
u10	m s-1
v10	m s-1

TUFLOW FV Boundary Include File

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

Within the .fvc file note that 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.

• MSLP: converted from Pascals (Pa) to hectopascals (hPa)
• Precipitation: converted from kg m−2 s−1 to m day−1
• 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	CFSR 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
MSLP_GRID	Pa	hPa	BC Scale == 0.01 ! Conversion: pascal [Pa] to hectopascal [hPa]
PRECIP_GRID	kg m-2 s-1	m day-1	BC Scale == 86.4 ! Conversion: [kg m-2 s-1] to [m day-1]
REL_HUM_GRID	%	%	N/A
AIR_TEMP_GRID	K	°C	BC Offset == -273.15 ! Conversion: kelvin [K] to degrees Celsius [°C]
W10_GRID	m s-1	m s-1	N/A

! 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: CFSR
! Info: https://climatedataguide.ucar.edu/climate-data/climate-forecast-system-reanalysis-cfsr

! NetCDF time datum: AEST
! NetCDF start time: 2022-12-01 10:00
! NetCDF end time: 2023-03-01 10:00

! Coordinate system EPSG: 28356
! Coordinate system name: GDA94 / MGA zone 56
! NetCDF x-limits: 519918.7854, 580347.5882
! NetCDF y-limits: 6799855.5485, 6890703.5149

Grid Definition File == output_data/CFSR_20230101_20230201_GDA94Z56_AEST.nc
  Grid Definition Variables == x, y
  Grid Definition Label == atmos
End Grid

BC == LW_RAD_GRID, atmos, output_data/CFSR_20230101_20230201_GDA94Z56_AEST.nc
  BC Header == local_time, dlwrf
  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/CFSR_20230101_20230201_GDA94Z56_AEST.nc
  BC Header == local_time, dswrf
  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/CFSR_20230101_20230201_GDA94Z56_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 == PRECIP_GRID, atmos, output_data/CFSR_20230101_20230201_GDA94Z56_AEST.nc
  BC Header == local_time, prate
  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 == REL_HUM_GRID, atmos, output_data/CFSR_20230101_20230201_GDA94Z56_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/CFSR_20230101_20230201_GDA94Z56_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/CFSR_20230101_20230201_GDA94Z56_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\CFSR_20230101_20230201_GDA94Z56_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. 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 CFSR global atmospheric model and applied to a TUFLOW FV model in projected Cartesian (eastings and northings) 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.