Grid

Contents

Grid#

class roms_tools.Grid(*, nx: int | None = None, ny: int | None = None, size_x: float | None = None, size_y: float | None = None, center_lon: float | None = None, center_lat: float | None = None, rot: float = 0, N: int | None = None, theta_s: float | None = None, theta_b: float | None = None, hc: float | None = None, topography_source: dict[str, str | Path | list[str | Path]] | None = None, mask_shapefile: str | Path | None = None, close_narrow_channels: bool = False, hmin: float = 5.0, verbose: bool = False, filename: str | Path | None = None)#

A single ROMS grid, used for creating, plotting, and then saving a new ROMS domain grid.

The grid generation consists of four steps:

  1. Creating the horizontal grid

  2. Creating the mask

  3. Generating the topography

  4. Preparing the vertical coordinate system

Parameters:

  • nx (int) – Number of grid points in the x-direction.

  • ny (int) – Number of grid points in the y-direction.

  • size_x (float) – Domain size in the x-direction (in kilometers).

  • size_y (float) – Domain size in the y-direction (in kilometers).

  • center_lon (float) – Longitude of grid center.

  • center_lat (float) – Latitude of grid center.

  • rot (float, optional) – Rotation of grid x-direction from lines of constant latitude, measured in degrees. Positive values represent a counterclockwise rotation. The default is 0, which means that the x-direction of the grid is aligned with lines of constant latitude.

  • topography_source (Dict[str, Union[str, Path]], optional) –

    Dictionary specifying the source of the topography data:

    • ”name” (str): The name of the topography data source (e.g., “SRTM15”).

    • ”path” (Union[str, Path, List[Union[str, Path]]]): The path to the raw data file. Can be a string or a Path object.

    The default is “ETOPO5”, which does not require a path.

  • mask_shapefile (str | Path | None, optional) – Path to a custom shapefile to use to determine the land mask; if None, use NaturalEarth 10m.

  • close_narrow_channels (bool, optional) – Whether to close narrow water channels in the mask after it is generated. The default is False.

  • hmin (float, optional) – The minimum ocean depth (in meters). The default is 5.0.

  • N (int, optional) – The number of vertical levels. The default is 100.

  • theta_s (float, optional) – The surface control parameter. Must satisfy 0 < theta_s <= 10. The default is 5.0.

  • theta_b (float, optional) – The bottom control parameter. Must satisfy 0 < theta_b <= 10. The default is 2.0.

  • hc (float, optional) – The critical depth (in meters). The default is 300.0.

  • verbose (bool, optional) – Indicates whether to print grid generation steps with timing. Defaults to False.

Raises:

ValueError – If you try to create a grid with domain size larger than 25000 km.

Methods

Grid.copy_with_ds(ds)

Return a copy of this Grid with the given Dataset.

Grid.from_yaml(filepath[, verbose])

Create an instance of the class from a YAML file.

Grid.grid_to_dict()

Put all grid parameters into a dictionary.

Grid.plot([lat, lon, with_dim_names, save_path])

Plot the grid with bathymetry.

Grid.plot_vertical_coordinate([s, eta, xi, ...])

Plot the layer depth for a given eta-, xi-, or s-slice.

Grid.save(filepath[, format])

Save the grid information to a NetCDF file.

Grid.to_yaml(filepath)

Export the parameters of the class to a YAML file, including the version of roms-tools.

Grid.update_mask([mask_shapefile, ...])

Update the land mask of the current grid dataset.

Grid.update_topography([topography_source, ...])

Update the grid dataset with processed topography.

Grid.update_vertical_coordinate([N, ...])

Create vertical coordinate variables for the ROMS grid.

Attributes

Grid.N

The number of vertical levels.

Grid.center_lat

Latitude of grid center.

Grid.center_lon

Longitude of grid center.

Grid.close_narrow_channels

Whether to close narrow water channels in the mask.

Grid.filename

An external file to load instead of generating the grid from params

Grid.hc

The critical depth (in meters).

Grid.hmin

The minimum ocean depth (in meters).

Grid.mask_shapefile

Path to a custom shapefile to use to determine the landmask; if None, use NaturalEarth 10m.

Grid.nx

Number of grid points in the x-direction.

Grid.ny

Number of grid points in the y-direction.

Grid.rot

Rotation of grid x-direction from lines of constant latitude, measured in degrees.

Grid.size_x

Domain size in the x-direction (in kilometers).

Grid.size_y

Domain size in the y-direction (in kilometers).

Grid.theta_b

The bottom control parameter.

Grid.theta_s

The surface control parameter.

Grid.topography_source

Dictionary specifying the source of the topography data.

Grid.verbose

Whether to print grid generation steps with timing.

Grid.ds

An xarray Dataset containing post-processed variables ready for input into ROMS.

Grid.straddle

Whether the grid straddles the dateline.
Contents