1. Getting Started

1.1. Install Software

Download the latest software version from github by typing

git clone https://github.com/gaelforget/gcmfaces
git clone https://github.com/gaelforget/MITprof

at the command line or using the github web browser interface. This method allows users to update the software later on and to manage their own, if any, code modifications. Archived frozen versions of the software, which can be cited in publications using permanent digital object identifiers, are also available via zenodo. Additionally, gcmfaces relies on the m_map toolbox for geographic projections (Figure 3.1), which can be downloaded from this webpage (e.g., m_map1.4.tar.gz).

Octave users will want to replace git clone ...faces with git clone -b octave ...faces in the above recipe. They will also need to install and load the Octave statistics, io, and netcdf packages.

Note

MITprof is not generally needed by gcmfaces, but is used in Section 3 and Section 4.

1.2. Obtain Input Data

The gcmfaces toolbox allows users to seamlessly deal with various gridding approaches (e.g., all grids distributed via this FTP server) using compact and generic codes as explained in this user guide. Once a grid has been loaded to memory (see below and Section 2.2), gcmfaces can be used to analyze ocean model solutions and state estimates on that grid (Section 3 and Section 4).

To get started in Section 1.3 and Section 2, it suffices to download nctiles_grid/ (145M) either from this ftp server or from this permanent archive. Section 3 and Section 4 use nctiles_climatology/ (10G) to illustrate higher-level functionalities. One download method, from the command line, is shown in Demo Directory Downloads. Commands reported afterwards assume that downloaded contents are organized as shown in Demo Directories Organization.

The other input data sets shown in Demo Directories Organization (inside of release2/) are not be needed unless user wants to reproduce the full set of plots in [FCH+16]. The contents of profiles/ (7G) and nctiles_remotesensing/ (27G) allow for model-data comparisons, while nctiles_monthly/ (170G) contains monthly time series of ocean variables over 1992-2011. These can be used to reproduce the plots in [FCH+16] via a few function calls as explained at the end of Section 4.

Demo Directory Downloads

setenv FTPv4r2 'ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/'
#export FTPv4r2='ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/'
wget --recursive {$FTPv4r2}/nctiles_grid
wget --recursive {$FTPv4r2}/nctiles_climatology
#wget --recursive {$FTPv4r2}/nctiles_monthly
#wget --recursive {$FTPv4r2}/nctiles_remotesensing
#wget --recursive {$FTPv4r2}/profiles

Demo Directories Organization

gcmfaces/ (Matlab / Octave toolbox)
MITprof/ (Matlab / Octave toolbox)
m_map/ (Matlab / Octave toolbox)
nctiles_grid/ (downloaded data)
release2_climatology/
    nctiles_climatology/ (downloaded data)
    mat/ (created by software)
    tex/ (created by software)
release2/
    nctiles_monthly/ (downloaded data)
    nctiles_remotesensing/ (downloaded data)
    profiles/ (downloaded data)
    mat/ (created by software)
    tex/ (created by software)

1.3. Activate gcmfaces

Once gcmfaces/ and nctiles_grid/ have been placed in a common directory as shown in Demo Directories Organization, open Matlab or Octave from within that directory and type:

%add gcmfaces and MITprof directories to Matlab path:
p = genpath('gcmfaces/'); addpath(p);
%p = genpath('MITprof/'); addpath(p);

%load all grid variables from nctiles_grid/ into mygrid:
grid_load;

%make mygrid accessible in current workspace:
gcmfaces_global;

%display list of grid variables:
disp(mygrid);

%display one gcmfaces variable:
disp(mygrid.XC);