ROMS-tools

Overview

A suite of python tools for setting up a ROMS simulation.

Note these tools are for the Center for Earth Systems Research Group at UCLA's version of ROMS.

Installation instructions

Install via pip

pip install roms-tools

Check the installation has worked by running the tests (you will need to also install pytest to run these)

pytest

Dependencies required are xarray and netcdf4, plus matplotlib and cartopy for visualising grids.

ROMS-tools should run on any platform that can install the above dependencies.

Usage instructions

To set up all the input files for a new ROMS simulation from scratch, follow these steps in order.

Step 1: Make Grid

The first step is choosing the domain size, location, and resolution. Do this by creating an instance of the Grid class:

from roms_tools import Grid

grid = Grid(
    nx=100,          # number of points in the x-direction (not including 2 boundary cells on either end)
    ny=100,          # number of points in the y-direction (not including 2 boundary cells on either end)
    size_x=1800,     # size of the domain in the x-direction (in km)
    size_y=2400,     # size of the domain in the y-direction (in km)
    center_lon=-21,  # longitude of the center of the domain
    center_lat=61,   # latitude of the center of the domain
    rot=20,          # rotation of the grid's x-direction from lines of constant longitude, with positive values being a counter-clockwise rotation
)

To visualize the grid we have just created, use the .plot method:

grid.plot()

To see the values of the grid variables you can examine the xarray.Dataset object returned by the .ds property

grid.ds

<xarray.Dataset>
Dimensions:    (eta_rho: 3, xi_rho: 3, one: 1)
Dimensions without coordinates: eta_rho, xi_rho, one
Data variables:
    angle      (eta_rho, xi_rho) float64 0.0 0.0 0.0 -1.46e-16 ... 0.0 0.0 0.0
    f0         (eta_rho, xi_rho) float64 4.565e-06 4.565e-06 ... -4.565e-06
    pn         (eta_rho, xi_rho) float64 5e-06 5e-06 5e-06 ... 5e-06 5e-06 5e-06
    lon_rho    (eta_rho, xi_rho) float64 339.1 340.0 340.9 ... 339.1 340.0 340.9
    lat_rho    (eta_rho, xi_rho) float64 1.799 1.799 1.799 ... -1.799 -1.799
    spherical  (one) <U1 'T'
    tra_lon    (one) int64 -20
    tra_lat    (one) int64 0
    rotate     (one) int64 0
Attributes:
    Title:    ROMS grid. Settings: nx: 1 ny: 1  xsize: 0.1 ysize: 0.1 rotate:...
    Date:     2023-11-20
    Type:     ROMS grid produced by roms-tools

Once we are happy with our grid, we can save it as a netCDF file via the .save method:

grid.save('grids/my_new_roms_grid.nc')

The basic grid domain is now ready for use by ROMS.

Steps 2-7:

Coming soon!

Feedback and contributions

If you find a bug, have a feature suggestion, or any other kind of feedback, please start a Discussion.

We also accept contributions in the form of Pull Requests.

See also

• ROMS source code
• C-Star