Pyroms

Welcome to Pyroms!

Pyroms is a collection of tools to process 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.

Pyroms is now hosted on GitHub.com in the ESMG/pyroms repository. This version is on the python3 branch. It requires Python 3.4 or later.

Installation

Pyroms is still a bit rough around the edges, particularly with regard to installation. Recent development has been done in Python environments managed by Conda. However Pyroms itself cannot yet be installed with Conda.

If you are starting from scratch, we recommend that you install
Anaconda or
Miniconda and create a Python 3 environment (as of December 2020, version 3.8 is your best bet) for Pyroms and your other scientific software. You should also consider making conda-forge your default channel. See the conda-forge tips and tricks page.

If you don't want to use Conda, that's fine, but you will have to do more of the work yourself.

Prerequisites

The following are required and are all available from Conda-Forge.

• Python >= 3.4 (Python 3.8 currently recommended for new environments)
• numpy
• scipy
• matplotlib
• basemap
• netcdf4
• cftime
• lpsolve55
• pip

The following is optional: Pyroms can be built and run without it but some of the functionality will be missing.

• scrip, a Python implementation of SCRIP,
  the Spherical Coordinate Remapping and Interpolation Package. This is used by the pyroms
  module. The Python scrip code (a rather old version) is
  bundled in pyroms
  and can be built and installed separately as described below. In future we plan to
  move from the bundled scrip code to a stand-alone package like
  ESMF/ESMPy or
  PySCRIP.

The following is optional and provides high-resolution coastlines for basemap:

• basemap-data-hires

Install from source

To clone a copy of the source and install the pyroms packages, you can use the following commands

# Cd to a convenient directory
$ git clone https://github.com/ESMG/pyroms.git
$ pip install -e pyroms/pyroms
$ pip install -e pyroms/pyroms_toolbox
$ pip install -e pyroms/bathy_smoother

This installs three PIP packages with the names pyroms, pyroms_toolbox and bathy_smoother,
each with an eponymous module.

An editable-mode installation is recommended becauses it means changes you make to your copy of the source code will take effect when you import the modules. If you don't want this you can omit the "-e" option

The "pip install" command runs "python setup.py install" (or "python setup.py develop" with the "-e" switch) in each of the subdirectories listed. The "pip install" form is recommended because it allow easy removal (see below)

The above should work on most Linuces and on OSX with the system gcc and gfortran compilers.
They have also been verified to work in a Conda environment on Windows,
provided you install the
m2w64-gcc and m2w64-gfortran compilers.

Install scrip

If you install as above and try to import the three Pyroms modules without having installed
scrip you will get a warning like this:

$ python
Python 3.8.5 | packaged by conda-forge | (default, Aug 29 2020, 01:22:49)
[GCC 7.5.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import pyroms
WARNING:root: scrip could not be imported. Remapping functions will not be available
>>> import pyroms_toolbox
>>> import bathy_smoother

The scrip module is not available via Conda or any other package repository and we are looking at alternatives. In the meantime, scrip can be built and installed from source as follows

# Start in the directory into which you cloned pyroms and cd to the SCRIP
# source directory
$ cd pyroms/pyroms/external/scrip/source/

# Print the location of the active Conda environment (which is called "python38"
# in this case). The active environment location is used to find the netCDF and
# other libraries.
$ conda info | grep "active env location"
    active env location : /home/hadfield/miniconda3/envs/python38

# Run make to build the scrip Python extension and install it into the Conda
# environment. The makefile calculates a variable called SCRIP_EXT_DIR, into
# which it installs the scrip Python extension. If pyroms has been installed
# in editable (development) mode, set the DEVELOP variable to a non-empty value.
$ export PREFIX=/home/hadfield/miniconda3/envs/python38
$ make DEVELOP=1 PREFIX=$PREFIX install
$ mv -vf scrip*.so ../../../pyroms
‘scrip.cpython-38-x86_64-linux-gnu.so’ -> ‘../../../pyroms/scrip.cpython-38-x86_64-linux-gnu.so’

Removal

To remove the three Pyroms packages you can use the "pip uninstall" command, referring to the packages by their package names

# Run from any directory in the same environment as you installed
# and use the package name
$ pip uninstall pyroms
$ pip uninstall pyroms_toolbox
$ pip uninstall bathy_smoother

If you have built and installed the scrip extension from the makefile as above, you can also uninstall it with the makefile. The PREFIX does not need to be set in this case.

# Start in the directory into which you cloned pyroms and cd to the SCRIP
# source directory
$ cd pyroms/pyroms/external/scrip/source/

# Remove with make.
$ make DEVELOP=1 uninstall

Running Pyroms

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.