A Matlab toolbox for analyzing and visualizing NetCDF output files from the Blumberg & Mellor ocean circulation models (ECOM-3D, ECOM-si, POM)

Five steps to using ECOM-viz to visualize POM output:

  1. Buy MATLAB .
  2. Get and build the NetCDF source code .
  3. Get and build the UNIX style (compressed-tar) file or PC style (zip) file of POM source code modified to output NetCDF.
  4. Get the appropriate executable of the MEXCDF NetCDF/Matlab interface for your system.
  5. Get the OMVIZ distribution and run "pomdemo" from within Matlab. Also check out CSLICE , a cool point-and-click Matlab application for visualizing ECOM.CDF or POM.CDF files.

NetCDF output files

The standard output files from the Blumberg & Mellor models (ECOM-3D and POM) are in ASCII and machine-specific binary format. To allow efficient and machine-independent access to the model output, a new subroutine and small modifications to the existing Fortran code have been made to allow writing the output as NetCDF files. The NetCDF files are self-describing, machine-independent binary files that are ideally suited for numerical modeling.

For example, here is the FORTRAN routine for POM that will write the output as NetCDF files. Or if you with, here is a self-contained compressed tar file of POM code that generates an ECOMviz compatible NetCDF output file.

Running ECOM-3D creates two NetCDF files called ecom3d.cdf and tsepic.cdf, while running POM creates one NetCDF file called pom.cdf. Ecom3d.cdf contains full 1D, 2D, and 3D fields of variables averaged over IAVGE time steps, while tsepic.cdf contains time series of variables at EPTS grid locations and averaged over ISKILL time steps. The frequency of output to pom.cdf is the same as for the print file and is controlled by IPRTD1, ISWTCH, and IPRTD2.

For ECOM-3D the variables that are stored in these files is controlled by the presense of a 'Y' instead of a 'N' in the beginning of the run_data file. For POM, the switches are set in the beginning of putcdf.f

The tsepic.cdf file created by ECOM-3D use conventions that allow them to be compatible with PMEL's EPIC analysis and visualization system (in addition to the ECOM-viz system described here). Each dependent variable (temp, salt, u, v, etc.) has 4 dimensions reflecting that earth-related data exists in time and 3-space. The contents of NetCDF files may be examined from the system command line using "ncdump -h" or from Matlab using mexdump.

And here is a ECOM-viz compatible NetCDF output file from Massachusetts Bay , all ready to go. Use load-to-local-disk or shift-click!

Time Convention

Time is stored in the NetCDF files as two one-dimensional variables, time and time2. Time is a long integer variable containing the Julian day using the astronomical convention, but where the day starts at midnight. For example, in this convention, Julian day 2440000 begins at 0000 hours, May 23, 1968. Time2 is a long integer containing the number of milliseconds since midnight on the corresponding Julian day element of time.

In the ECOM-viz Matlab routines time is represented as decimal Julian day, typically called something like jd. Gregorian time is represented by a six-column variable where the columns contain year, month, day, hour, minute and second. Thus [1968 5 23 0 0 0] represents 0000 hours, May 23, 1968. The function gregorian converts Julian time to Gregorian time, while the function julian converts Gregorian to Julian.

Extracting data from NetCDF files

Since Matlab is limited to 2D arrays, many of the ECOM-viz routines return some type of 2D array of values -- slices along the i,j, or k model coordinates or at a fixed depth z.

Viewing Data Extracted from NetCDF files