Welcome to Pyroms!

Pyroms is a collection of tools to help with input and output files
from the Regional Ocean Modeling System (ROMS). It was originally
started by Rob Hetland as a googlecode project, then he morphed it
into octant, also at googlecode. Frederic Castruccio then created a
fork and renamed it back to pyroms. This version is still rather
rough around the edges.

Prerequisites
-------------

Now using Anaconda python to download python 3.x and a bunch of other stuff:

   * Python itself. You will need a version that's at least 3.4.

   * numpy.

   * scipy.

   * matplotlib. This is a plotting package to reproduce the Matlab
     plotting, complete with everything you might not like about
     Matlab plotting. This also contains the gui tools, but it
     depends on an underlying gui package, be that tk, wx, X11, or
     qt. If it can't find any of them, it's time to install one.

   * basemap from matplotlib. These are the map tools for Python,
     complete with etopo2 in the examples directory (user beware).

   * netCDF4 from Jeff Whitaker. This sits on top of the hdf5 and
     netcdf4 libraries.

   * ipython. Fred Castruccio recommends using "ipython --pylab" for
     interactive fun. It preloads both numpy and the matplotlib
     pylab package.

   * natgrid from http://github.com/matplotlib/natgrid for at least
     one of the examples.

Planning to move to ESMF. Download it with:

     conda install --channel https://conda.anaconda.org/conda-forge esmf

We may also add pyngl and pynio from NCAR to this list.
Or jupyter.

Installing
----------

Pyroms is currently in three different packages, pyroms itself,
pyroms_toolbox, and bathy_smoother. We are in the process of creating
setup.py scripts for each, plus an examples directory.

For now,

  cd pyroms_toolbox; python setup.py build
                     python setup.py install --prefix=xxx;
                     cd ..

  cd bathy_smoother; python setup.py build;
                     python setup.py install --prefix=xxx;
                     cd ..
  cd pyroms; check the paths in the install script and see if it runs...
             Maybe cut and paste from it into a bash shell.

I had to hack the scrip makefile for the fortran90 netcdf stuff. The
anaconda netcdf-fortran reports:
    nf-config not yet implemented for cmake builds

A note on the .so files from fortran: They might now end up with names like:

    scrip.cpython-35m-x86_64-linux-gnu.so

It's OK - they'll load as long as they are in your PYTHONPATH. You might
also need libgu.so to be in your LD_LIBRARY_PATH. I'm getting inconsistent
results with where the .so files need to be. Best results for me are if I go
to the site-packages directory where pyroms got installed and copy all the
.so files:

    cp pyroms/*.so .
    cp pyroms_toolbox/*.so .
    cp bathy_smoother/*.so .

Make sure this site-packages directory is in your PYTHONPATH. As for
libgu.so, it went into $DESTDIR/lib, for me $HOME/python/lib - that's
what needs to be in the LD_LIBRARY_PATH.

Also, f2py may or may not be called f2py3, depending. It's listed explicitly
in the scrip makefile and under pyroms_toolbox/pyroms_toolbox/src/makefile.

Running
-------

We have a gridid.txt file that's pointed to by the PYROMS_GRIDID_FILE
environment variable. If you are operating on files containing
sufficient grid information already, you won't need to use this.
An example is provided in the examples directory.


Doxygen
-------

Running "doxygen .doxygen" in any of pyroms, pyroms_toolbox or
bathy_smoother will generate doxygen files. Edit the .doxygen files to
specify html vs. some other output format.