Building Grid Projection Files#
Application Configuration#
The gridspec application supports grid-projections defined from
both netCDF-formatted and GRIB-formatted file attributes. Example
netCDF- and GRIB-derived configurations, respectively, follow.
netCDF Configurations#
gridspec_netcdf: /run/gridspec.tripolar.0p25.nc
angle:
ncfile: /work/ufs_tools/gridspec/0p25/mom6/mom6.grid.0p25.nc
ncxdim: x
ncydim: y
ncvarname: angle_dx
latitude:
ncfile: /work/ufs_tools/gridspec/0p25/mom6/mom6.grid.0p25.nc
ncxdim: nx
ncydim: ny
ncvarname: y
longitude:
ncfile: /work/ufs_tools/gridspec/0p25/mom6/mom6.grid.0p25.nc
ncxdim: nx
ncydim: ny
ncvarname: x
Configuration Variable |
Description |
|---|---|
|
The input grid-projection angle orientation; this is used for
instances of rotating velocity vectors for different grid
projections – namely tripolar type; for instances when the
|
|
The netCDF-formatted file path to contain the computed/defined grid-projection. |
|
The input grid-projection latitude coordinate attributes. |
|
The input grid-projection longitude coordinate attributes. |
The YAML keys for the respective angle, latitude, and
longitude blocks are as follows.
Configuration Variable |
Description |
|---|---|
|
The path to the netCDF-formatted file containing the supergrid for the respective grid-projection. |
|
The netCDF-formatted file variable name for the respective geographical coordinate/attribute. |
|
The zonal-coordinate (i.e., \(x\)) netCDF dimension name. |
|
The meridional-coordinate (i.e., \(y\)) netCDF dimension name. |
Using the a \(1.0^{\circ}\) MOM6 tripolar-projection
supergrid as an example, the netCDF gridspec attributes listed in
the table above may be found as follows.
user@host:$ ncdump -h /work/ufs_tools/gridspec/0p25/mom6/mom6.grid.0p25.nc
netcdf mom6.grid.0p25.nc {
dimensions:
nyp = 641 ;
nxp = 721 ;
ny = 640 ;
nx = 720 ;
string = 255 ;
variables:
char tile(string) ;
double y(nyp, nxp) ;
y:units = "degrees" ;
double x(nyp, nxp) ;
x:units = "degrees" ;
double dy(ny, nxp) ;
dy:units = "meters" ;
double dx(nyp, nx) ;
dx:units = "meters" ;
double area(ny, nx) ;
area:units = "m2" ;
double angle_dx(nyp, nxp) ;
angle_dx:units = "degrees" ;
}
GRIB Configurations#
gridspec_netcdf: /run/gridspec.reglatlon.1p0.nc
grib_file: /path/to/input/grib/file
grib_varname: grib_variable_name
Configuration Variable |
Description |
|---|---|
|
The path to the WMO GRIB-formatted file containing variables defined on a supported grid projection. |
|
The GRIB-formatted variable containing the respective grid projection. |
Note that in the above example that the latitude and longitude
grid-dimension attributes ncxdim and ncydim are set to nx
and ny despite the netCDF-formatted file metadata attributes. This
is due to how the tripolar supergrid is reduced to compute the nominal
resolution gridspec grid.
Launching the Application#
The available gridspec application command-line interface (CLI)
attributes are as follows.
user@host:$ cd scripts
user@host:$ ./compute_gridspec.py --help
2000-01-01 00:00:00 :: INFO :: __main__: Beginning application compute_gridspec.py.
Usage: compute_gridspec.py [-h] [-arakawa_a] [-arakawa_c] [-grib] [-netcdf] [-reglatlon] [-supergrid] [-tripolar] [-wrap_lons] yaml
Gridspec application interface.
Positional Arguments:
yaml YAML-formatted file containing the gridspec application configuration.
Optional Arguments:
-h, --help show this help message and exit
-arakawa_a The source grid-projection is Arakawa-A.
-arakawa_c The source grid-projection is Arakawa-C.
-grib The source grid-projection is derived from GRIB variable attributes.
-netcdf The source grid-projection is derived from a netCDF-formatted file.
-reglatlon The destination grid-projection is a regular latitude/longitude projection.
-supergrid The source grid-projection is a `supergrid` projection.
-tripolar The destination grid-projection is a tripolar grid projection; only supported for Arakawa-C instances.
-wrap_lons Wrap longitude values and normalize as required; only supported for Arakawa-C instances.
Tripolar Grid Projections#
An example application for computing and/or definining the
gridspec attributes for a \(5.0^{\circ}\) Arakawa-C tripolar
grid projection is as follows.
user@host:$ cd scripts
user@host:$ ./compute_gridspec.py --arakawa_c --netcdf --supergrid --tripolar --wrap_lons /ufs_tools/parm/gridspec/gridspec.tripolar.5p0.yaml
2000-01-01 00:00:00 :: INFO :: __main__: Beginning application compute_gridspec.py.
2000-01-01 00:00:00 :: INFO :: utils.schema_interface:
+------------+--------+------------+-----------------+------------------+
| Variable | Type | Optional | Default Value | Assigned Value |
+============+========+============+=================+==================+
| arakawa_a | bool | True | False | False |
| reglatlon | bool | True | False | False |
| wrap_lons | bool | True | False | True |
| grib | bool | True | False | False |
| tripolar | bool | True | False | True |
| supergrid | bool | True | False | True |
| arakawa_c | bool | True | False | True |
+------------+--------+------------+-----------------+------------------+
2000-01-01 00:00:00 :: INFO :: utils.schema_interface: Schema successfully validated.
2000-01-01 00:00:00 :: INFO :: gridspec.write.GridSpecWrite: Writing gridspec output to path /run/gridspec.test.nc.
2000-01-01 00:00:00 :: INFO :: __main__: Completed application compute_gridspec.py.
2000-01-01 00:00:00 :: INFO :: __main__: Total Elapsed Time: 0.08440637588500977 seconds.
user@host:$ /path/to/ncdump -h /run/gridspec.tripolar.5p0.nc
netcdf gridspec.tripolar.5p0 {
dimensions:
nx = 72 ;
nxp = 72 ;
ny = 35 ;
nyp = 35 ;
variables:
double angle(ny, nx) ;
string angle:dims = "ny", "nx" ;
angle:desc = "Grid projection rotation angle; radians." ;
angle:type = "float64" ;
double qlat(ny, nx) ;
string qlat:dims = "ny", "nx" ;
qlat:desc = "Array of q-grid latitudes; degrees north." ;
qlat:type = "float64" ;
double qlon(ny, nx) ;
string qlon:dims = "ny", "nx" ;
qlon:desc = "Array of q-grid longitudes; degrees east." ;
qlon:type = "float64" ;
double tlat(ny, nx) ;
string tlat:dims = "ny", "nx" ;
tlat:desc = "Array of t-grid latitudes; degrees north." ;
tlat:type = "float64" ;
double tlon(ny, nx) ;
string tlon:dims = "ny", "nx" ;
tlon:desc = "Array of t-grid longitudes; degrees east." ;
tlon:type = "float64" ;
double ulat(ny, nx) ;
string ulat:dims = "ny", "nx" ;
ulat:desc = "Array of u-grid latitudes; degrees north." ;
ulat:type = "float64" ;
double ulon(ny, nx) ;
string ulon:dims = "ny", "nx" ;
ulon:desc = "Array of u-grid longitudes; degrees east." ;
ulon:type = "float64" ;
double vlat(ny, nx) ;
string vlat:dims = "ny", "nx" ;
vlat:desc = "Array of v-grid latitudes; degrees north." ;
vlat:type = "float64" ;
double vlon(ny, nx) ;
string vlon:dims = "ny", "nx" ;
vlon:desc = "Array of v-grid longitudes; degrees east." ;
vlon:type = "float64" ;
// global attributes:
:_FillValue = NaN ;
:date = "00:00:00 UTC 01 January 2000" ;
:created = "x0x0x0x0x0x0" ;
:source = "Arakawa-C" ;
:source_supergrid = "True" ;
:source_tripolar = "True" ;
:wrapped_lons = "True" ;
Note that for tripolar Arakawa-C projections nx = nxp and ny =
nyp. The netCDF metadata attributes are as follows.
Metadata Variables(s) |
Description |
|---|---|
|
The grid projection rotation angle; this is used for non-Arakawa-A grids to rotate velocity vectors relative to the center of the respective grid cell; units are degrees. |
|
The geographical coordinates for the respective grid cell vertices; units are degrees. |
|
The geographical coordinates for the respective grid cell centers; these are often referred to as the mass-variable locations; units are degrees. |
|
The geographical coordinates for the zonal velocity components for the respective Arakawa-type grid; units are degrees. |
|
The geographical coordinates for the meridional velocity components for the respective Arakawa-type grid; units are degrees. |
Regular Latitude/Longitude Projections#
An example application for computing and/or definining the
gridspec attributes for a \(1.0^{\circ}\) regular
latitude/longitude (e.g., Gaussian) grid projection is as follows.
user@host:$ cd scripts
user@host:$ ./compute_gridspec.py --reglatlon --grib /ufs_tools/parm/gridspec/gridspec.reglatlon.1p0.yaml
2000-01-01 00:00:00 :: INFO :: __main__: Beginning application compute_gridspec.py.
2000-01-01 00:00:00 :: INFO :: utils.schema_interface:
+------------+--------+------------+-----------------+------------------+
| Variable | Type | Optional | Default Value | Assigned Value |
+============+========+============+=================+==================+
| wrap_lons | bool | True | False | False |
| reglatlon | bool | True | False | True |
| supergrid | bool | True | False | False |
| tripolar | bool | True | False | False |
| arakawa_c | bool | True | False | False |
| arakawa_a | bool | True | False | False |
| grib | bool | True | False | True |
+------------+--------+------------+-----------------+------------------+
2000-01-01 00:00:00 :: INFO :: utils.schema_interface: Schema successfully validated.
2000-01-01 00:00:00 :: INFO :: gridspec.read.GridSpecRead: Parsing GRIB-formatted file path /run/gfs.1p0.pgrb2 and seeking a GRIB record for variable Temperature.
2000-01-01 00:00:00 :: INFO :: gridspec.write.GridSpecWrite: Writing gridspec output to path /run/gridspec.reglatlon.1p0.nc.
user@host:$ /path/to/ncdump -h /run/gridspec.reglatlon.1p0.nc
netcdf gridspec.reglatlon.1p0 {
dimensions:
nx = 360 ;
nxp = 360 ;
ny = 181 ;
nyp = 181 ;
variables:
double angle(ny, nx) ;
string angle:dims = "ny", "nx" ;
angle:desc = "Grid projection rotation angle; radians." ;
angle:type = "float64" ;
double qlat(ny, nx) ;
string qlat:dims = "ny", "nx" ;
qlat:desc = "Array of q-grid latitudes; degrees north." ;
qlat:type = "float64" ;
double qlon(ny, nx) ;
string qlon:dims = "ny", "nx" ;
qlon:desc = "Array of q-grid longitudes; degrees east." ;
qlon:type = "float64" ;
double tlat(ny, nx) ;
string tlat:dims = "ny", "nx" ;
tlat:desc = "Array of t-grid latitudes; degrees north." ;
tlat:type = "float64" ;
double tlon(ny, nx) ;
string tlon:dims = "ny", "nx" ;
tlon:desc = "Array of t-grid longitudes; degrees east." ;
tlon:type = "float64" ;
double ulat(ny, nx) ;
string ulat:dims = "ny", "nx" ;
ulat:desc = "Array of u-grid latitudes; degrees north." ;
ulat:type = "float64" ;
double ulon(ny, nx) ;
string ulon:dims = "ny", "nx" ;
ulon:desc = "Array of u-grid longitudes; degrees east." ;
ulon:type = "float64" ;
double vlat(ny, nx) ;
string vlat:dims = "ny", "nx" ;
vlat:desc = "Array of v-grid latitudes; degrees north." ;
vlat:type = "float64" ;
double vlon(ny, nx) ;
string vlon:dims = "ny", "nx" ;
vlon:desc = "Array of v-grid longitudes; degrees east." ;
vlon:type = "float64" ;
// global attributes:
:_FillValue = NaN ;
:date = "00:00:00 UTC 01 January 2000" ;
:created = "x0x0x0x0x0x0" ;
:source = "Regular Latitude/Longitude" ;
:source_supergrid = "False" ;
:source_tripolar = "False" ;
:wrapped_lons = "False" ;
}