Welcome to gcmfaces’ documentation!

Here, you will learn about the gcmfaces toolbox that provides a generic treatment of gridded Earth variables in Matlab and Octave.

The gcmfaces toolbox handles gridded Earth variables as sets of connected arrays. This object-oriented approach allows users to write generic, compact analysis codes that readily become applicable to a wide variety of grids (e.g., those in Figure 1). gcmfaces notably allows for analysis of MITgcm output on any of its familiar grids. It was originally developed as part the ECCO version 4 framework along with the companion MITprof toolbox that handles unevenly distributed in-situ ocean observations [FCH+15].

This user manual provides an installation guide for gcmfaces and MITprof (Section 1), a documentation of the basic gcmfaces features (Section 2), and an overview of higher-level gcmfaces functionalities for mapping, transport, etc. operations (Section 3 and Section 4).

Sample grids


Figure 1 Four approaches to gridding the Earth which are all commonly used in numerical models. Top left: lat-lon grid; mapping the Earth to a single rectangular array (face). Top right: cube-sphere grid; mapping the earth to the six faces of a cube. Bottom right: lat-lon-cap, LLC, grid (five faces). Bottom left: quadripolar grid (four faces). In this depiction, faces are color-coded, only grid line subsets are shown, and gaps are introduced between faces to highlight the defining characteristics of each grid.

Indices and tables