Welcome to PyCNAL!

PyCNAL 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. It has now been converted to
Python 3 and renamed PyCNAL. We're still working on the rough edges.

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

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

   * Python itself, at least 3.0.

   * 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
----------

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

For now,

  cd pycnal_toolbox; python setup.py build --fcompiler=gnu95;
                     python setup.py install --prefix=xxx;
                     cd ..

  cd bathy_smoother; python setup.py build;
                     python setup.py install --prefix=xxx;
                     cd ..
  cd pycnal; check the paths in the install script and see if it runs...
             Maybe cut and paste from it into a bash shell. In particular, 
             if the command "nc-config --fflags" returns something like 
             "nf-config not yet implemented for cmake builds", you must
             edit pycnal/external/scrip/source/makefile so that LIBDIR
             contains the path to the netCDF libraries, INCDIR contains
             the path to the netCDF include files, and LIB contains the
             options for your fortran compiler to include netCDF. 
             
             If you are using Anaconda to manage your python, for a conda
             environment named PyCNAL, and for a username of YOURNAME, compiling with gfortran,
             you can try
             
             LIBDIR = /home/YOURNAME/anaconda3/envs/PyCNAL/lib
             INCDIR = /home/YOURNAME/anaconda3/envs/PyCNAL/include
             LIB  =  -L${LIBDIR} -lnetcdff -Wl,-Bsymbolic-functions -Wl,-z,relro -Wl,-z,now -lnetcdf 
             
             This assumes you have installed the netCDF4 package with conda, and are 
             linking against those libraries. 

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 pycnal got installed and copy all the
.so files:

    cp pycnal/*.so .
    cp pycnal_toolbox/*.so .
    cp bathy_smoother/*.so .

Make sure this site-packages directory is in your PYTHONPATH.

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

Running
-------

We have a gridid.txt file that's pointed to by the PYCNAL_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 pycnal, pycnal_toolbox or
bathy_smoother will generate doxygen files. Edit the .doxygen files to
specify html vs. some other output format.