Loading the ECCOv4 native model grid parameters

Objectives

Introduce two methods of loading the ECCOv4 native model grid parameters.

Introduction

The ECCOv4 model grid parameters are provided as a single NetCDF file. The file you have may look a little different than the one shown here because we have been working hard at improving how what exactly goes into our NetCDF files.

This tutorial document is current as of Sep 2019 with the ECCOv4 NetCDF grid files provided in the following directories:

https://ecco.jpl.nasa.gov/drive/files/Version4/Release3_alt (po.daac drive, recommended)

https://web.corral.tacc.utexas.edu/OceanProjects/ECCO/ECCOv4/Release3_alt/ (mirror at U. Texas, Austin)

Two methods to load the ECCOv4 model grid parameter NetCDF file

Because the ECCOv4 model grid parameter data is provided in a single file you can use the open_dataset routine from xarray to open it.

Alternatively, our subroutine load_ecco_grid_nc allows you to (optionally) specify a subset of vertical levels or a subset of tiles to load.

We’ll show both methods. Let’s start with open_dataset.

First set up your environment.

[1]:
import numpy as np
import xarray as xr
import sys
import matplotlib.pyplot as plt
%matplotlib inline
[2]:
## Import the ecco_v4_py library into Python
## =========================================

## -- If ecco_v4_py is not installed in your local Python library,
##    tell Python where to find it.  For example, if your ecco_v4_py
##    files are in /Users/ifenty/ECCOv4-py/ecco_v4_py, then use:

sys.path.append('/home/ifenty/ECCOv4-py')
import ecco_v4_py as ecco
[3]:
## Set top-level file directory for the ECCO NetCDF files
## =================================================================

## -- If files are on a local machine, use something like
# base_dir = '/Users/ifenty/'
base_dir = '/home/ifenty/ECCOv4-release/'

## define a high-level directory for ECCO fields
ECCO_dir = base_dir + '/Release3_alt/'

Method 1: Loading the model grid parameters using load_ecco_grid_nc

Method 2 is super simple, just use open_dataset:

[4]:
grid_dir = ECCO_dir + 'nctiles_grid/'

## load the grid
grid = xr.open_dataset(grid_dir + 'ECCOv4r3_grid.nc')
grid
[4]:
<xarray.Dataset>
Dimensions:    (i: 90, i_g: 90, j: 90, j_g: 90, k: 50, k_l: 50, k_p1: 51, k_u: 50, tile: 13)
Coordinates:
  * i          (i) int64 0 1 2 3 4 5 6 7 8 9 ... 80 81 82 83 84 85 86 87 88 89
  * i_g        (i_g) int64 0 1 2 3 4 5 6 7 8 9 ... 80 81 82 83 84 85 86 87 88 89
  * j          (j) int64 0 1 2 3 4 5 6 7 8 9 ... 80 81 82 83 84 85 86 87 88 89
  * j_g        (j_g) int64 0 1 2 3 4 5 6 7 8 9 ... 80 81 82 83 84 85 86 87 88 89
  * k          (k) int64 0 1 2 3 4 5 6 7 8 9 ... 40 41 42 43 44 45 46 47 48 49
  * k_u        (k_u) int64 0 1 2 3 4 5 6 7 8 9 ... 40 41 42 43 44 45 46 47 48 49
  * k_l        (k_l) int64 0 1 2 3 4 5 6 7 8 9 ... 40 41 42 43 44 45 46 47 48 49
  * k_p1       (k_p1) int64 0 1 2 3 4 5 6 7 8 9 ... 42 43 44 45 46 47 48 49 50
  * tile       (tile) int64 0 1 2 3 4 5 6 7 8 9 10 11 12
    XC         (tile, j, i) float32 ...
    YC         (tile, j, i) float32 ...
    XG         (tile, j_g, i_g) float32 ...
    YG         (tile, j_g, i_g) float32 ...
    CS         (tile, j, i) float32 ...
    SN         (tile, j, i) float32 ...
    Z          (k) float32 ...
    Zp1        (k_p1) float32 ...
    Zu         (k_u) float32 ...
    Zl         (k_l) float32 ...
    rA         (tile, j, i) float32 ...
    dxG        (tile, j_g, i) float32 ...
    dyG        (tile, j, i_g) float32 ...
    Depth      (tile, j, i) float32 ...
    rAz        (tile, j_g, i_g) float32 ...
    dxC        (tile, j, i_g) float32 ...
    dyC        (tile, j_g, i) float32 ...
    rAw        (tile, j, i_g) float32 ...
    rAs        (tile, j_g, i) float32 ...
    drC        (k_p1) float32 ...
    drF        (k) float32 ...
    PHrefC     (k) float32 ...
    PHrefF     (k_p1) float32 ...
    hFacC      (k, tile, j, i) float32 ...
    hFacW      (k, tile, j, i_g) float32 ...
    hFacS      (k, tile, j_g, i) float32 ...
    maskC      (k, tile, j, i) bool ...
    maskW      (k, tile, j, i_g) bool ...
    maskS      (k, tile, j_g, i) bool ...
    maskCtrlW  (k, tile, j, i_g) bool ...
    maskCtrlS  (k, tile, j_g, i) bool ...
    maskCtrlC  (k, tile, j, i) bool ...
Data variables:
    *empty*
Attributes:
    Conventions:  CF-1.6
    title:        netCDF wrapper of MITgcm MDS binary data
    source:       MITgcm
    history:      Created by calling `open_mdsdataset(extra_metadata=None, ll...

Let’s plot two of the model grid parameter fields hFacC (tracer cell thickness factor) and rA (grid cell surface area)

First we plot hFac:

[5]:
ecco.plot_tiles(grid.hFacC.sel(k=0), show_colorbar=True, cmap='gray');
_images/ECCO_v4_Loading_the_ECCOv4_native_model_grid_parameters_8_0.png
[6]:
ecco.plot_tiles(grid.rA, show_colorbar=True);
'Model grid cell surface area [m^2]'
[6]:
'Model grid cell surface area [m^2]'
_images/ECCO_v4_Loading_the_ECCOv4_native_model_grid_parameters_9_1.png

Method 2: Loading the model grid parameters using load_ecco_grid_nc

A more advanced routine, load_ecco_grid_nc, allows you to load only a subset of tiles and vertical levels. If no optional parameters are given, the entire grid object is loaded, just like open_dataset

[7]:
grid_dir = ECCO_dir + 'nctiles_grid'

grid = ecco.load_ecco_grid_nc(grid_dir, 'ECCOv4r3_grid.nc')
grid
[7]:
<xarray.Dataset>
Dimensions:    (i: 90, i_g: 90, j: 90, j_g: 90, k: 50, k_l: 50, k_p1: 51, k_u: 50, tile: 13)
Coordinates:
  * i          (i) int64 0 1 2 3 4 5 6 7 8 9 ... 80 81 82 83 84 85 86 87 88 89
  * i_g        (i_g) int64 0 1 2 3 4 5 6 7 8 9 ... 80 81 82 83 84 85 86 87 88 89
  * j          (j) int64 0 1 2 3 4 5 6 7 8 9 ... 80 81 82 83 84 85 86 87 88 89
  * j_g        (j_g) int64 0 1 2 3 4 5 6 7 8 9 ... 80 81 82 83 84 85 86 87 88 89
  * k          (k) int64 0 1 2 3 4 5 6 7 8 9 ... 40 41 42 43 44 45 46 47 48 49
  * k_u        (k_u) int64 0 1 2 3 4 5 6 7 8 9 ... 40 41 42 43 44 45 46 47 48 49
  * k_l        (k_l) int64 0 1 2 3 4 5 6 7 8 9 ... 40 41 42 43 44 45 46 47 48 49
  * k_p1       (k_p1) int64 0 1 2 3 4 5 6 7 8 9 ... 42 43 44 45 46 47 48 49 50
  * tile       (tile) int64 0 1 2 3 4 5 6 7 8 9 10 11 12
    XC         (tile, j, i) float32 -111.60647 -111.303 ... -111.86579
    YC         (tile, j, i) float32 -88.24259 -88.382515 ... -88.07871 -88.10267
    XG         (tile, j_g, i_g) float32 -115.0 -115.0 ... -102.928925 -108.95171
    YG         (tile, j_g, i_g) float32 -88.17569 -88.31587 ... -88.02409
    CS         (tile, j, i) float32 0.06157813 0.06675376 ... -0.9983638
    SN         (tile, j, i) float32 -0.99810225 -0.9977695 ... -0.057182025
    Z          (k) float32 -5.0 -15.0 -25.0 -35.0 ... -5039.25 -5461.25 -5906.25
    Zp1        (k_p1) float32 0.0 -10.0 -20.0 -30.0 ... -5244.5 -5678.0 -6134.5
    Zu         (k_u) float32 -10.0 -20.0 -30.0 -40.0 ... -5244.5 -5678.0 -6134.5
    Zl         (k_l) float32 0.0 -10.0 -20.0 -30.0 ... -4834.0 -5244.5 -5678.0
    rA         (tile, j, i) float32 362256450.0 363300960.0 ... 361119100.0
    dxG        (tile, j_g, i) float32 15584.907 15589.316 ... 23142.107
    dyG        (tile, j, i_g) float32 23210.262 23273.26 ... 15595.26 15583.685
    Depth      (tile, j, i) float32 0.0 0.0 0.0 0.0 0.0 ... 0.0 0.0 0.0 0.0 0.0
    rAz        (tile, j_g, i_g) float32 179944260.0 180486990.0 ... 364150620.0
    dxC        (tile, j, i_g) float32 15583.418 15588.104 ... 23406.256
    dyC        (tile, j_g, i) float32 11563.718 11593.785 ... 15578.138
    rAw        (tile, j, i_g) float32 361699460.0 362790240.0 ... 364760350.0
    rAs        (tile, j_g, i) float32 179944260.0 180486990.0 ... 364150620.0
    drC        (k_p1) float32 5.0 10.0 10.0 10.0 ... 399.0 422.0 445.0 228.25
    drF        (k) float32 10.0 10.0 10.0 10.0 10.0 ... 387.5 410.5 433.5 456.5
    PHrefC     (k) float32 49.05 147.15 245.25 ... 49435.043 53574.863 57940.312
    PHrefF     (k_p1) float32 0.0 98.1 196.2 ... 51448.547 55701.18 60179.445
    hFacC      (k, tile, j, i) float32 0.0 0.0 0.0 0.0 0.0 ... 0.0 0.0 0.0 0.0
    hFacW      (k, tile, j, i_g) float32 0.0 0.0 0.0 0.0 0.0 ... 0.0 0.0 0.0 0.0
    hFacS      (k, tile, j_g, i) float32 0.0 0.0 0.0 0.0 0.0 ... 0.0 0.0 0.0 0.0
    maskC      (k, tile, j, i) bool False False False ... False False False
    maskW      (k, tile, j, i_g) bool False False False ... False False False
    maskS      (k, tile, j_g, i) bool False False False ... False False False
    maskCtrlW  (k, tile, j, i_g) bool False False False ... False False False
    maskCtrlS  (k, tile, j_g, i) bool False False False ... False False False
    maskCtrlC  (k, tile, j, i) bool False False False ... False False False
Data variables:
    *empty*
Attributes:
    Conventions:              CF-1.6
    geospatial_lat_max:       90.0
    geospatial_lat_min:       -90.0
    geospatial_lon_max:       180.0
    geospatial_lon_min:       -179.99919
    geospatial_vertical_max:  -5.0
    geospatial_vertical_min:  -5906.25
    history:                  Created by calling `open_mdsdataset(extra_metad...
    nx:                       90
    ny:                       90
    nz:                       50
    source:                   MITgcm
    title:                    netCDF wrapper of MITgcm MDS binary data

Alternatively we can load just a subset of tiles and vertical levels.

[8]:
grid_subset = ecco.load_ecco_grid_nc(grid_dir, 'ECCOv4r3_grid.nc', tiles_to_load = [1, 10, 12], k_subset=[0,1,2,3])
grid_subset
[8]:
<xarray.Dataset>
Dimensions:    (i: 90, i_g: 90, j: 90, j_g: 90, k: 4, k_l: 4, k_p1: 4, k_u: 4, tile: 3)
Coordinates:
  * i          (i) int64 0 1 2 3 4 5 6 7 8 9 ... 80 81 82 83 84 85 86 87 88 89
  * i_g        (i_g) int64 0 1 2 3 4 5 6 7 8 9 ... 80 81 82 83 84 85 86 87 88 89
  * j          (j) int64 0 1 2 3 4 5 6 7 8 9 ... 80 81 82 83 84 85 86 87 88 89
  * j_g        (j_g) int64 0 1 2 3 4 5 6 7 8 9 ... 80 81 82 83 84 85 86 87 88 89
  * k          (k) int64 0 1 2 3
  * k_u        (k_u) int64 0 1 2 3
  * k_l        (k_l) int64 0 1 2 3
  * k_p1       (k_p1) int64 0 1 2 3
  * tile       (tile) int64 1 10 12
    XC         (tile, j, i) float32 -37.5 -36.5 -35.5 ... -105.58465 -111.86579
    YC         (tile, j, i) float32 -56.73891 -56.73891 ... -88.07871 -88.10267
    XG         (tile, j_g, i_g) float32 -38.0 -37.0 ... -102.928925 -108.95171
    YG         (tile, j_g, i_g) float32 -57.005695 -57.005695 ... -88.02409
    CS         (tile, j, i) float32 1.0 1.0 1.0 ... -0.98536175 -0.9983638
    SN         (tile, j, i) float32 -0.0 6.52406e-15 ... -0.1704766 -0.057182025
    Z          (k) float32 -5.0 -15.0 -25.0 -35.0
    Zp1        (k_p1) float32 0.0 -10.0 -20.0 -30.0
    Zu         (k_u) float32 -10.0 -20.0 -30.0 -40.0
    Zl         (k_l) float32 0.0 -10.0 -20.0 -30.0
    rA         (tile, j, i) float32 3624512000.0 3624512000.0 ... 361119100.0
    dxG        (tile, j_g, i) float32 60542.324 60542.324 ... 23142.107
    dyG        (tile, j, i_g) float32 59441.125 59441.125 ... 15595.26 15583.685
    Depth      (tile, j, i) float32 3284.1084 3485.7 3485.7 ... 0.0 0.0 0.0
    rAz        (tile, j_g, i_g) float32 3584245000.0 ... 364150620.0
    dxC        (tile, j, i_g) float32 60975.85 60975.85 ... 23865.428 23406.256
    dyC        (tile, j_g, i) float32 59201.66 59201.66 ... 15585.765 15578.138
    rAw        (tile, j, i_g) float32 3624512000.0 3624512000.0 ... 364760350.0
    rAs        (tile, j_g, i) float32 3584245000.0 3584245000.0 ... 364150620.0
    drC        (k_p1) float32 5.0 10.0 10.0 10.0
    drF        (k) float32 10.0 10.0 10.0 10.0
    PHrefC     (k) float32 49.05 147.15 245.25 343.35
    PHrefF     (k_p1) float32 0.0 98.1 196.2 294.3
    hFacC      (k, tile, j, i) float32 1.0 1.0 1.0 1.0 1.0 ... 0.0 0.0 0.0 0.0
    hFacW      (k, tile, j, i_g) float32 1.0 1.0 1.0 1.0 1.0 ... 0.0 0.0 0.0 0.0
    hFacS      (k, tile, j_g, i) float32 1.0 1.0 1.0 1.0 1.0 ... 0.0 0.0 0.0 0.0
    maskC      (k, tile, j, i) bool True True True True ... False False False
    maskW      (k, tile, j, i_g) bool True True True True ... False False False
    maskS      (k, tile, j_g, i) bool True True True True ... False False False
    maskCtrlW  (k, tile, j, i_g) bool True True True True ... False False False
    maskCtrlS  (k, tile, j_g, i) bool True True True True ... False False False
    maskCtrlC  (k, tile, j, i) bool True True True True ... False False False
Data variables:
    *empty*
Attributes:
    Conventions:              CF-1.6
    geospatial_lat_max:       72.043434
    geospatial_lat_min:       -88.02409
    geospatial_lon_max:       51.0
    geospatial_lon_min:       -128.0
    geospatial_vertical_max:  -5.0
    geospatial_vertical_min:  -35.0
    history:                  Created by calling `open_mdsdataset(extra_metad...
    nx:                       90
    ny:                       90
    nz:                       4
    source:                   MITgcm
    title:                    netCDF wrapper of MITgcm MDS binary data

notice that grid_subset only has 3 tiles (9,10, 11) and 4 depth levels (0, 1, 2, 3), as expected.

Let’s plot hFacC and rA again

[9]:
ecco.plot_tiles(grid_subset.hFacC.sel(k=0), show_colorbar=True, cmap='gray');
'Model grid cell surface area [m^2] in tiles 1, 10, and 12 '
[9]:
'Model grid cell surface area [m^2] in tiles 1, 10, and 12 '
_images/ECCO_v4_Loading_the_ECCOv4_native_model_grid_parameters_15_1.png

Notice that 10 of the 13 tiles are blank because they were not loaded.

[10]:
ecco.plot_tiles(grid_subset.rA, show_colorbar=True);
'Model grid cell surface area [m^2]'
[10]:
'Model grid cell surface area [m^2]'
_images/ECCO_v4_Loading_the_ECCOv4_native_model_grid_parameters_17_1.png

Summary

Now you know two ways to load the ECCOv4 grid parameter file!