Creating a grid

Creating a grid#

Mask#

The land–sea mask is generated by comparing the grid’s latitude and longitude coordinates with a coastline dataset provided as a shapefile.

Mask Shapefile#

The coastline dataset is supplied through the mask_shapefile parameter when creating the grid object.

If no shapefile is provided, ROMS-Tools automatically falls back to the Natural Earth 1:10m coastline dataset (used in the example above). The label 1:10m refers to a map scale of 1:10,000,000, which corresponds to an effective spatial resolution of approximately 1–5 km.

To improve the accuracy of the land–sea mask, especially for fjords, narrow straits, and other complex coastal geometries, we next explore several resolutions of the GSHHG coastline dataset.

GSHHG provides five resolutions:

f (full): original highest-detail dataset
h (high): ~80% reduction in detail and file size
i (intermediate): another ~80% reduction
l (low): another ~80% reduction
c (crude): another ~80% reduction

Higher-resolution versions offer more accurate coastlines but require substantially more memory when generating the mask. In the following, we therefore profile the memory usage.

[3]:

%load_ext memory_profiler

We will compare the masks derived from Natural Earth and GSHHG for a ROMS grid representing Hvalfjörður fjord in Iceland at 50 m horizontal resolution.

[4]:

iceland_fjord_kwargs = {
    "nx": 800,
    "ny": 400,
    "size_x": 40,
    "size_y": 20,
    "center_lon": -21.76,
    "center_lat": 64.325,
    "rot": 0,
    "topography_source": {
        "name": "SRTM15",
        "path": "/anvil/projects/x-ees250129/Datasets/SRTM15/SRTM15_V2.6.nc"
    },
    "N": 40
}

First, we create a land-sea mask using the default Natural Earth coastline (i.e., withouth specifying a mask_shapefile).

[5]:

%%time
%%memit

fjord_grid_natural_earth = Grid(**iceland_fjord_kwargs, verbose=True)

2026-04-01 13:22:00 - INFO - === Creating the horizontal grid ===
2026-04-01 13:22:00 - INFO - Total time: 0.421 seconds
2026-04-01 13:22:00 - INFO - ================================================================================================
2026-04-01 13:22:00 - INFO - === Making the mask ===
2026-04-01 13:22:01 - INFO - Inferring the mask from coastlines: 0.413 seconds
2026-04-01 13:22:01 - INFO - Filling enclosed basins with land: 0.002 seconds
2026-04-01 13:22:01 - INFO - Total time: 0.417 seconds
2026-04-01 13:22:01 - INFO - ================================================================================================
2026-04-01 13:22:01 - INFO - === Generating the topography using SRTM15 data and hmin = 5.0 meters ===
2026-04-01 13:22:01 - INFO - Reading the topography data: 0.013 seconds
2026-04-01 13:22:01 - INFO - Regridding the topography: 0.015 seconds
2026-04-01 13:22:01 - INFO - Domain-wide topography smoothing: 0.029 seconds
2026-04-01 13:22:02 - INFO - Local topography smoothing: 0.739 seconds
2026-04-01 13:22:02 - INFO - Total time: 0.809 seconds
2026-04-01 13:22:02 - INFO - ================================================================================================
2026-04-01 13:22:02 - INFO - === Preparing the vertical coordinate system using N = 40, theta_s = 5.0, theta_b = 2.0, hc = 300.0 ===
2026-04-01 13:22:02 - INFO - Total time: 0.003 seconds
2026-04-01 13:22:02 - INFO - ================================================================================================

peak memory: 705.34 MiB, increment: 89.58 MiB
CPU times: user 1.72 s, sys: 121 ms, total: 1.84 s
Wall time: 1.94 s

Mask creation was very fast (< 1 second), and the total memory footprint of the grid generation was small (< 1 GB). However, the next plot shows that the Natural Earth coastline provides only a coarse representation of Hvalfjörður, resulting in an overly smooth and poorly resolved shoreline.

[6]:

fjord_grid_natural_earth.plot()

Next, we explore the high-resolution (h) version of the GSHHG dataset to generate the land–sea mask.

[7]:

%%time
%%memit

fjord_grid_gshhg_h = Grid(
    **iceland_fjord_kwargs,
    mask_shapefile="/anvil/projects/x-ees250129/Datasets/GSHHS/gshhg-shp-2.3.7/GSHHS_shp/h/GSHHS_h_L1.shp",
    verbose=True
)

2026-04-01 13:22:12 - INFO - === Creating the horizontal grid ===
2026-04-01 13:22:12 - INFO - Total time: 0.434 seconds
2026-04-01 13:22:12 - INFO - ================================================================================================
2026-04-01 13:22:12 - INFO - === Making the mask ===
2026-04-01 13:22:28 - INFO - Inferring the mask from coastlines: 15.794 seconds
2026-04-01 13:22:28 - INFO - Filling enclosed basins with land: 0.003 seconds
2026-04-01 13:22:28 - INFO - Total time: 15.842 seconds
2026-04-01 13:22:28 - INFO - ================================================================================================
2026-04-01 13:22:28 - INFO - === Generating the topography using SRTM15 data and hmin = 5.0 meters ===
2026-04-01 13:22:28 - INFO - Reading the topography data: 0.015 seconds
2026-04-01 13:22:28 - INFO - Regridding the topography: 0.015 seconds
2026-04-01 13:22:28 - INFO - Domain-wide topography smoothing: 0.034 seconds
2026-04-01 13:22:29 - INFO - Local topography smoothing: 0.752 seconds
2026-04-01 13:22:29 - INFO - Total time: 0.828 seconds
2026-04-01 13:22:29 - INFO - ================================================================================================
2026-04-01 13:22:29 - INFO - === Preparing the vertical coordinate system using N = 40, theta_s = 5.0, theta_b = 2.0, hc = 300.0 ===
2026-04-01 13:22:29 - INFO - Total time: 0.003 seconds
2026-04-01 13:22:29 - INFO - ================================================================================================

peak memory: 45282.23 MiB, increment: 44587.82 MiB
CPU times: user 13.4 s, sys: 3.62 s, total: 17.1 s
Wall time: 17.4 s

Creating the mask now took about 15 seconds, and the overall memory footprint of the grid increased to roughly 45 GB: relatively high. The coastlines are better resolved than with Natural Earth, though still somewhat angular due to the data reduction applied in this GSHHG resolution.

[21]:

fjord_grid_gshhg_h.plot()

Finally, we use the full-resolution GSHHG dataset to generate the land–sea mask.

[8]:

%%time
%%memit

fjord_grid_gshhg_f = Grid(
    **iceland_fjord_kwargs,
    mask_shapefile="/anvil/projects/x-ees250129/Datasets/GSHHS/gshhg-shp-2.3.7/GSHHS_shp/f/GSHHS_f_L1.shp",
    verbose=True
)

2026-04-01 13:22:37 - INFO - === Creating the horizontal grid ===
2026-04-01 13:22:37 - INFO - Total time: 0.437 seconds
2026-04-01 13:22:37 - INFO - ================================================================================================
2026-04-01 13:22:37 - INFO - === Making the mask ===
2026-04-01 13:22:57 - INFO - Inferring the mask from coastlines: 19.963 seconds
2026-04-01 13:22:57 - INFO - Filling enclosed basins with land: 0.002 seconds
2026-04-01 13:22:57 - INFO - Total time: 20.017 seconds
2026-04-01 13:22:57 - INFO - ================================================================================================
2026-04-01 13:22:57 - INFO - === Generating the topography using SRTM15 data and hmin = 5.0 meters ===
2026-04-01 13:22:57 - INFO - Reading the topography data: 0.018 seconds
2026-04-01 13:22:57 - INFO - Regridding the topography: 0.015 seconds
2026-04-01 13:22:57 - INFO - Domain-wide topography smoothing: 0.031 seconds
2026-04-01 13:22:58 - INFO - Local topography smoothing: 0.765 seconds
2026-04-01 13:22:58 - INFO - Total time: 0.842 seconds
2026-04-01 13:22:58 - INFO - ================================================================================================
2026-04-01 13:22:58 - INFO - === Preparing the vertical coordinate system using N = 40, theta_s = 5.0, theta_b = 2.0, hc = 300.0 ===
2026-04-01 13:22:58 - INFO - Total time: 0.003 seconds
2026-04-01 13:22:58 - INFO - ================================================================================================

peak memory: 56353.35 MiB, increment: 55625.62 MiB
CPU times: user 16.7 s, sys: 4.55 s, total: 21.2 s
Wall time: 21.6 s

Creating the mask now took about 20 seconds, and the grid’s memory footprint increased to roughly 55 GB: even higher. However, the coastline is captured in much greater detail using the full-resolution GSHHG data.

[23]:

fjord_grid_gshhg_f.plot()

Note

For very large grids with many points, using the full-resolution GSHHG dataset may exceed available memory. You may need to experiment to find the optimal coastline resolution. For most applications, the Natural Earth coastlines may provide a sufficiently accurate representation.

Closing narrow channels#

When creating a grid, you have the option to set close_narrow_channels to True. This functionality cleans up the land-sea mask by removing narrow 1-pixel wide passages. This is particularly useful when working with high-resolution coastline datasets that may create unrealistic narrow channels that could cause instabilities in ROMS.

The method performs one main operation:

Closes narrow 1-pixel channels: Iteratively removes 1-pixel wide land passages in both north-south and east-west directions. After closing, the velocity masks (mask_u and mask_v) are automatically updated to reflect the changes in mask_rho and any lakes/holes in the mask generated by closing narrow passages are filled subsequently.

Let’s create two grids and look at the difference to demonstrate the functionality. We’ll use a grid with a relatively high resolution to show how narrow passages can be problematic.

[9]:

# Create a fine-scale grid for demonstration

# Create common grid kwargs for both grids
kwargs = {
    "nx": 512,
    "ny": 512,
    "size_x": 102.4,
    "size_y": 102.4,
    "center_lon": -22.3,
    "center_lat": 64.39,
    "rot": 0,
    "mask_shapefile": "/anvil/projects/x-ees250129/Datasets/GSHHS/gshhg-shp-2.3.7/GSHHS_shp/f/GSHHS_f_L1.shp",
    "topography_source" :{
        "name": "EMOD",
        "path": "/anvil/projects/x-ees250129/Datasets/EMODnet_C2.nc"
    },
    "N": 60, # number of vertical layers
    "verbose": True
}

# Set close_narrow_channels to False
narrow_channel_false_grid = Grid(
    **kwargs,
    close_narrow_channels=False # this is the default
)

# Set close_narrow_channels to True
narrow_channel_true_grid = Grid(
    **kwargs,
    close_narrow_channels=True
)

# Plot without closed channels
narrow_channel_false_grid.plot()

2026-04-01 13:23:16 - INFO - === Creating the horizontal grid ===
2026-04-01 13:23:16 - INFO - Total time: 0.326 seconds
2026-04-01 13:23:16 - INFO - ================================================================================================
2026-04-01 13:23:16 - INFO - === Making the mask ===
2026-04-01 13:23:31 - INFO - Inferring the mask from coastlines: 14.484 seconds
2026-04-01 13:23:31 - INFO - Filling enclosed basins with land: 0.011 seconds
2026-04-01 13:23:31 - INFO - Total time: 14.543 seconds
2026-04-01 13:23:31 - INFO - ================================================================================================
2026-04-01 13:23:31 - INFO - === Generating the topography using EMOD data and hmin = 5.0 meters ===
2026-04-01 13:23:32 - INFO - Reading the topography data: 1.111 seconds
2026-04-01 13:23:38 - INFO - Regridding the topography: 0.027 seconds
2026-04-01 13:23:38 - INFO - Domain-wide topography smoothing: 0.027 seconds
2026-04-01 13:23:39 - INFO - Local topography smoothing: 0.345 seconds
2026-04-01 13:23:39 - INFO - Total time: 7.893 seconds
2026-04-01 13:23:39 - INFO - ================================================================================================
2026-04-01 13:23:39 - INFO - === Preparing the vertical coordinate system using N = 60, theta_s = 5.0, theta_b = 2.0, hc = 300.0 ===
2026-04-01 13:23:39 - INFO - Total time: 0.003 seconds
2026-04-01 13:23:39 - INFO - ================================================================================================
2026-04-01 13:23:39 - INFO - === Creating the horizontal grid ===
2026-04-01 13:23:39 - INFO - Total time: 0.321 seconds
2026-04-01 13:23:39 - INFO - ================================================================================================
2026-04-01 13:23:39 - INFO - === Making the mask ===
2026-04-01 13:23:53 - INFO - Inferring the mask from coastlines: 14.352 seconds
2026-04-01 13:23:53 - INFO - Closing narrow channels: 0.024 seconds
2026-04-01 13:23:53 - INFO - Filling enclosed basins with land: 0.005 seconds
2026-04-01 13:23:53 - INFO - Total time: 14.435 seconds
2026-04-01 13:23:53 - INFO - ================================================================================================
2026-04-01 13:23:53 - INFO - === Generating the topography using EMOD data and hmin = 5.0 meters ===
2026-04-01 13:23:54 - INFO - Reading the topography data: 0.360 seconds
2026-04-01 13:24:00 - INFO - Regridding the topography: 0.028 seconds
2026-04-01 13:24:00 - INFO - Domain-wide topography smoothing: 0.027 seconds
2026-04-01 13:24:00 - INFO - Local topography smoothing: 0.347 seconds
2026-04-01 13:24:00 - INFO - Total time: 6.533 seconds
2026-04-01 13:24:00 - INFO - ================================================================================================
2026-04-01 13:24:00 - INFO - === Preparing the vertical coordinate system using N = 60, theta_s = 5.0, theta_b = 2.0, hc = 300.0 ===
2026-04-01 13:24:00 - INFO - Total time: 0.003 seconds
2026-04-01 13:24:00 - INFO - ================================================================================================

Now, let’s look at the difference between the two plots.

[10]:

from roms_tools.plot import plot

# Plot the difference (areas that were changed)
mask_diff = narrow_channel_false_grid.ds.mask_rho - narrow_channel_true_grid.ds.mask_rho
plot(mask_diff, grid_ds=narrow_channel_true_grid.ds, apply_mask=False)

The plot above shows where the mask was modified. Red areas indicate where water was converted to land.

Updating the mask#

If you want to update the land–sea mask while keeping the existing horizontal grid, topography, and vertical coordinate system, you can skip Steps I, III, and IV. This can be easily done using the .update_mask method.

Here, we update the grid created at the beginning of this notebook (using the Natural Earth coastlines) with a mask derived from the GSHHG dataset.

[ ]:

%%time
%%memit

grid.update_mask(
    mask_shapefile="/anvil/projects/x-ees250129/Datasets/GSHHS/gshhg-shp-2.3.7/GSHHS_shp/f/GSHHS_f_L1.shp",
    close_narrow_channels=True,
    verbose=True
  )

The new shapefile is now also recorded in the grid attributes.

[11]:

grid

[11]:

Grid(nx=250, ny=250, size_x=2500, size_y=2500, center_lon=-15, center_lat=65, rot=-30, N=100, theta_s=5.0, theta_b=2.0, hc=300.0, topography_source={'name': 'SRTM15', 'path': '/anvil/projects/x-ees250129/Datasets/SRTM15/SRTM15_V2.6.nc'}, close_narrow_channels=False, hmin=5.0, verbose=True, straddle=True)

[12]:

grid.plot()

Let’s save a copy of the mask before updating the grid again to switch back to the Natural Earth–derived mask.

[29]:

nordic_mask_gshhg = grid.ds.mask_rho.copy()

We now switch back to the Natural Earth–derived mask.

[30]:

grid.update_mask(
    verbose=True
)

2026-02-08 11:59:51 - INFO - === Deriving the mask from coastlines ===
2026-02-08 11:59:51 - INFO - Total time: 0.196 seconds
2026-02-08 11:59:51 - INFO - ================================================================================================

[31]:

grid

[31]:

Grid(nx=250, ny=250, size_x=2500, size_y=2500, center_lon=-15, center_lat=65, rot=-30, N=100, theta_s=5.0, theta_b=2.0, hc=300.0, topography_source={'name': 'SRTM15', 'path': '/anvil/projects/x-ees250129/Datasets/SRTM15/SRTM15_V2.6.nc'}, close_narrow_channels=False, hmin=5.0, verbose=True, straddle=True)

[32]:

nordic_mask_natural_earth = grid.ds.mask_rho.copy()

The next plot shows the difference between the two masks.

[33]:

from roms_tools.plot import plot
plot(nordic_mask_gshhg - nordic_mask_natural_earth, grid_ds=grid.ds, apply_mask=False)

The red and yellow dots along the coastline show where the two coastline datasets produce different land-sea masks and where narrow channels were closed.

Topography#

Here you can find an overview of the steps involved in the topography generation. In the following, we will illustrate how these concepts work in practice.

Topography source data#

The grid object includes a parameter called topography_source. If this parameter is not specified, it defaults to using the ETOPO5 topography data. The ETOPO5 data is downloaded internally, so the user does not need to provide a filename.

The ETOPO5 data has a horizontal resolution of 5 arc-minutes (or 1/12th of a degree). This horizontal resolution may be sufficient for coarser-resolution grids, but for finer-resolution grids we might want to use the finer-resolution topography product SRTM15. SRTM15 has a horizontal resolution of 15 arc-seconds (or 1/240th of a degree).

Let’s compare the topographies that are generated from ETOPO5 versus SRTM15 data for a ROMS grid surrounding Iceland.

[34]:

iceland_kwargs = {
    "size_x": 800,
    "size_y": 800,
    "center_lon": -19,
    "center_lat": 65,
    "rot": 20,
}

First, we generate two “coarse-resolution” grids with a horizontal resolution of 800km/100 = 8km: one regridded from the ETOPO5 data and the other from the SRTM15 data.

[35]:

%%time

coarse_grid_ETOPO5 = Grid(nx=100, ny=100, **iceland_kwargs, verbose=False)

CPU times: user 1.36 s, sys: 9.94 ms, total: 1.37 s
Wall time: 1.38 s

[36]:

%%time

coarse_grid_SRTM15 = Grid(
    nx=100,
    ny=100,
    topography_source={
        "name": "SRTM15",
        "path": "/anvil/projects/x-ees250129/Datasets/SRTM15/SRTM15_V2.6.nc",
    },
    **iceland_kwargs,
    verbose=False
)

CPU times: user 1.58 s, sys: 46.8 ms, total: 1.62 s
Wall time: 1.63 s

Comparing the timings above, we can see that generating the topographies took a similar amount of time and was quick overall. Next, let’s compare the generated topography fields.

[37]:

coarse_grid_ETOPO5.plot()

[38]:

coarse_grid_SRTM15.plot()

Comparing the figures above, we don’t see significant differences in the generated topography fields. The grid is simply too coarse to fully utilize the high-resolution SRTM15 data! To observe more noticeable differences, we need to use a finer resolution grid.

Let’s do that! Next, we generate two fine-resolution grids with a horizontal resolution of 800km/5000 = 0.16km: one regridded from the ETOPO5 data and the other from the SRTM15 data.

[39]:

%%time

fine_grid = Grid(nx=5000, ny=5000, **iceland_kwargs, verbose=True)

2026-02-08 11:59:56 - INFO - === Creating the horizontal grid ===
2026-02-08 12:00:32 - INFO - Total time: 36.619 seconds
2026-02-08 12:00:32 - INFO - ================================================================================================
2026-02-08 12:00:33 - INFO - === Deriving the mask from coastlines ===
2026-02-08 12:01:05 - INFO - Total time: 32.618 seconds
2026-02-08 12:01:05 - INFO - ================================================================================================
2026-02-08 12:01:06 - INFO - === Generating the topography using ETOPO5 data and hmin = 5.0 meters ===
2026-02-08 12:01:06 - INFO - Reading the topography data: 0.026 seconds
2026-02-08 12:01:07 - INFO - Regridding the topography: 0.861 seconds
2026-02-08 12:01:11 - INFO - Domain-wide topography smoothing: 4.141 seconds
2026-02-08 12:02:32 - INFO - Local topography smoothing: 80.996 seconds
2026-02-08 12:02:32 - INFO - Total time: 86.150 seconds
2026-02-08 12:02:32 - INFO - ================================================================================================
2026-02-08 12:02:32 - INFO - === Preparing the vertical coordinate system using N = 100, theta_s = 5.0, theta_b = 2.0, hc = 300.0 ===
2026-02-08 12:02:32 - INFO - Total time: 0.003 seconds
2026-02-08 12:02:32 - INFO - ================================================================================================

CPU times: user 2min 13s, sys: 21.9 s, total: 2min 35s
Wall time: 2min 36s

[40]:

%%time

fine_grid_SRTM15 = Grid(
    nx=5000,
    ny=5000,
    topography_source={
        "name": "SRTM15",
        "path": "/anvil/projects/x-ees250129/Datasets/SRTM15/SRTM15_V2.6.nc",
    },
    **iceland_kwargs,
    verbose=True
)

2026-02-08 12:02:32 - INFO - === Creating the horizontal grid ===
2026-02-08 12:03:07 - INFO - Total time: 35.193 seconds
2026-02-08 12:03:07 - INFO - ================================================================================================
2026-02-08 12:03:07 - INFO - === Deriving the mask from coastlines ===
2026-02-08 12:03:40 - INFO - Total time: 32.596 seconds
2026-02-08 12:03:40 - INFO - ================================================================================================
2026-02-08 12:03:41 - INFO - === Generating the topography using SRTM15 data and hmin = 5.0 meters ===
2026-02-08 12:03:41 - INFO - Reading the topography data: 0.012 seconds
2026-02-08 12:03:42 - INFO - Regridding the topography: 1.384 seconds
2026-02-08 12:03:47 - INFO - Domain-wide topography smoothing: 4.398 seconds
2026-02-08 12:05:25 - INFO - Local topography smoothing: 97.790 seconds
2026-02-08 12:05:25 - INFO - Total time: 103.867 seconds
2026-02-08 12:05:25 - INFO - ================================================================================================
2026-02-08 12:05:25 - INFO - === Preparing the vertical coordinate system using N = 100, theta_s = 5.0, theta_b = 2.0, hc = 300.0 ===
2026-02-08 12:05:25 - INFO - Total time: 0.003 seconds
2026-02-08 12:05:25 - INFO - ================================================================================================

CPU times: user 2min 33s, sys: 18 s, total: 2min 51s
Wall time: 2min 52s

The grid and topography generation process took longer this time, but the durations for both cases were quite similar.

Note that most of the time was spent during the local smoothing phase in both cases. The goal of this smoothing is to ensure that the local steepness ratio does not exceed the threshold of 0.2. Because the topography data contains a lot of details for such a fine-resolution grid, the local smoothing required many iterations for smoothing.

Let’s take a look at the generated topography fields.

[41]:

fine_grid.plot()  # grid with ETOPO5 topography

[42]:

fine_grid_SRTM15.plot()  # grid with SRTM15 topography

The two figures above reveal differences: the topography generated with the SRTM15 data shows a lot more detail. If we moved to an even finer resolution, these differences would become even more pronounced.

The minimal ocean depth `hmin`#

The default for hmin is 5 meters. In the above examples, we did not specify the (optional) hmin parameter, so it was set to the default value.

[43]:

fine_grid.hmin

[43]:

5.0

Let’s confirm that the minimum ocean depth is indeed at least 5 meters.

[44]:

fine_grid.ds["h"].min()

[44]:

<xarray.DataArray 'h' ()> Size: 8B
array(5.)

We can define a grid with a different hmin.

[45]:

%%time

fine_grid_with_larger_hmin = Grid(
    nx=5000,
    ny=5000,
    **iceland_kwargs,
    verbose=True,
    hmin=10.0,  # Minimum ocean depth in meters (default: 5.0)
)

2026-02-08 12:06:35 - INFO - === Creating the horizontal grid ===
2026-02-08 12:07:12 - INFO - Total time: 36.270 seconds
2026-02-08 12:07:12 - INFO - ================================================================================================
2026-02-08 12:07:12 - INFO - === Deriving the mask from coastlines ===
2026-02-08 12:07:45 - INFO - Total time: 33.180 seconds
2026-02-08 12:07:45 - INFO - ================================================================================================
2026-02-08 12:07:46 - INFO - === Generating the topography using ETOPO5 data and hmin = 10.0 meters ===
2026-02-08 12:07:46 - INFO - Reading the topography data: 0.026 seconds
2026-02-08 12:07:47 - INFO - Regridding the topography: 0.865 seconds
2026-02-08 12:07:51 - INFO - Domain-wide topography smoothing: 4.311 seconds
2026-02-08 12:08:30 - INFO - Local topography smoothing: 38.933 seconds
2026-02-08 12:08:30 - INFO - Total time: 44.240 seconds
2026-02-08 12:08:30 - INFO - ================================================================================================
2026-02-08 12:08:30 - INFO - === Preparing the vertical coordinate system using N = 100, theta_s = 5.0, theta_b = 2.0, hc = 300.0 ===
2026-02-08 12:08:30 - INFO - Total time: 0.003 seconds
2026-02-08 12:08:30 - INFO - ================================================================================================

CPU times: user 1min 40s, sys: 13.3 s, total: 1min 54s
Wall time: 1min 54s

[46]:

fine_grid_with_larger_hmin.ds["h"].min()

[46]:

<xarray.DataArray 'h' ()> Size: 8B
array(10.)

Updating topography and `hmin`#

When working with a grid that has a large number of grid points, such as nx = ny = 5000 in the example above, Steps I and II (creating the horizontal grid and land mask) can be quite time-consuming: it took about 40 + 30 = 70 seconds! If you simply want to repeat Step III, which involves updating the topography and/or hmin, but you would like to keep the same horizontal grid and mask, you can skip Steps I, II, and IV. This can be easily achieved using the .update_topography method. In the next cell, we take our fine resolution grid with ETOPO5 topography, and update it with SRTM15 topography and a larger hmin of 10 meters.

[47]:

%%time

fine_grid.update_topography(
    hmin=10.0,
    topography_source={
        "name": "SRTM15",
        "path": "/anvil/projects/x-ees250129/Datasets/SRTM15/SRTM15_V2.6.nc",
    },
    verbose=True,
)

2026-02-08 12:08:30 - INFO - === Generating the topography using SRTM15 data and hmin = 10.0 meters ===
2026-02-08 12:08:30 - INFO - Reading the topography data: 0.020 seconds
2026-02-08 12:08:32 - INFO - Regridding the topography: 1.412 seconds
2026-02-08 12:08:36 - INFO - Domain-wide topography smoothing: 4.301 seconds
2026-02-08 12:09:35 - INFO - Local topography smoothing: 58.472 seconds
2026-02-08 12:09:35 - INFO - Total time: 64.526 seconds
2026-02-08 12:09:35 - INFO - ================================================================================================

CPU times: user 53.2 s, sys: 11.2 s, total: 1min 4s
Wall time: 1min 4s

From the printed output, you can see that Steps I, II, and IV were skipped as desired. The following confirms that the topography_source and hmin were indeed updated.

[48]:

fine_grid

[48]:

Grid(nx=5000, ny=5000, size_x=800, size_y=800, center_lon=-19, center_lat=65, rot=20, N=100, theta_s=5.0, theta_b=2.0, hc=300.0, topography_source={'name': 'SRTM15', 'path': '/anvil/projects/x-ees250129/Datasets/SRTM15/SRTM15_V2.6.nc'}, close_narrow_channels=False, hmin=10.0, verbose=True, straddle=False)

Creating a grid

Contents

Creating a grid#

The Grid object#

Saving as NetCDF or YAML file#

Creating a grid from an existing NetCDF or YAML file#

Mask#

Mask Shapefile#

Closing narrow channels#

Updating the mask#

Topography#

Topography source data#

The minimal ocean depth `hmin`#

Updating topography and `hmin`#

The vertical coordinate system#

Plotting the vertical coordinate system#

Vertical coordinate system parameters#

Critical depth#

Surface and bottom control parameters#

Updating the vertical coordinate system#

Creating a grid

Contents

Creating a grid#

The Grid object#

Saving as NetCDF or YAML file#

Creating a grid from an existing NetCDF or YAML file#

Mask#

Mask Shapefile#

Closing narrow channels#

Updating the mask#

Topography#

Topography source data#

The minimal ocean depth hmin#

Updating topography and hmin#

The vertical coordinate system#

Plotting the vertical coordinate system#

Vertical coordinate system parameters#

Critical depth#

Surface and bottom control parameters#

Updating the vertical coordinate system#

The minimal ocean depth `hmin`#

Updating topography and `hmin`#