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. (Or just run jupyter notebook)

   * 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

Installing Python
-----------------

Assumes you have already fetched Anaconda and have 'conda' in your path.
To make conda-forge the default channel, put this in your $HOME/.condarc:

channels:
  - conda-forge

To make your own Anaconda environment named myenv (or most anything else):

  conda create --name myenv
  conda activate myenv
  conda install -n myenv netCDF4
  conda install scipy
  conda install basemap
  conda install jupyter

If you want high-res coastlines, get:

  conda install -c conda-forge basemap-data-hires

If get this error:

   KeyError: 'PROJ_LIB'

from:

  pyproj_datadir = os.environ['PROJ_LIB']

You need to set the PROJ_LIB environment variable:

  export PROJ_LIB=$CONDA_PREFIX/share/proj

You shouldn't need your own environment if you control the whole system,
but I need to make an environment on the supercomputer since their default
does not include netCDF4 (and more).

Installing Pyroms
-----------------

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.

There has been a change in how Python looks for these things. I now need:

   from pyroms import _iso

which used to be:

   import _iso

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.