The tools are defined in pyDeltaRCM.water_tools.

Public API methods attached to model


water_tools helper functions

Note that these routines are jitted for speed. They generally take a large number of arrays and constants and return a new array(s) to continue with the model progression.

pyDeltaRCM.water_tools._get_weight_at_cell_water(ind, weight_sfc, weight_int, depth_nbrs, ct_nbrs, dry_depth, gamma, theta)
pyDeltaRCM.water_tools._choose_next_directions(inds, water_weights)

Get new cell locations, based on water weights.

Algorithm is to:
  1. loop through each parcel, which is described by a pair in the inds array.

  2. determine the water weights for that location (from water_weights)

  3. choose a new cell based on the probabilities of the weights (using the random_pick function)

  • inds (ndarray) – Current unraveled indices of the parcels. (N,) ndarray containing the unraveled indices.

  • water_weights (ndarray) – Weights of every water cell. (LxW, 9) ndarray, uses unraveled indicies along 0th dimension; 9 cells represent self and 8 neighboring cells.


next_direction – The direction to move towards the new cell for water parcels, relative to the current location. I.e., this is the D8 direction the parcel is going to travel in the next stage, pyDeltaRCM.shared_tools._calculate_new_ind.

Return type


pyDeltaRCM.water_tools._calculate_new_inds(current_inds, new_direction, ravel_walk)

Calculate the new location (current_inds) of parcels.

Use the information of the current parcel (current_inds) in conjunction with the D8 direction the parcel needs to travel (new_direction) to determine the new current_inds of each parcel.

In implementation, we use the flattened ravel_walk array, but the result is identical to unraveling the index, adding iwalk and jwalk to the location and then raveling the index back.

ind_tuple = shared_tools.custom_unravel(ind, domain_shape)
new_ind = (ind_tuple[0] + jwalk[newd],
           ind_tuple[1] + iwalk[newd])
new_inds[p] = shared_tools.custom_ravel(new_ind, domain_shape)
pyDeltaRCM.water_tools._check_for_loops(free_surf_walk_inds, new_inds, _step, L0, CTR, stage_above_SL)

Check for loops in water parcel pathways.

Look for looping random walks. I.e., this function checks for where a parcel will return on its new_inds to somewhere it has already been in free_surf_walk_inds. If the loop is found, the parcel is relocated along the mean transport vector of the parcel, which is computed as the vector from the cell (0, CTR) to the new location in new_inds.

This implementation of loop checking will relocate any parcel that has looped, but only disqualifies a parcel p from contributing to the free surface in _accumulate_free_surf_walks (i.e., looped[p] == 1) if the stage at the looped location is above the sea level in the domain.

  • free_surf_walk_inds – Array recording the walk of parcels. Shape is (:obj:`Np_water, …)`, where the second dimension will depend on the step number, but records each step of the parcel. Each element in the array records the flat index into the domain.

  • new_inds – Array recording the new index for each water parcel, if the step is taken. Shape is (:obj:`Np_water, 1)`, with each element recording the flat index into the domain shape.

  • _step – Step number of water parcels.

  • L0 – Domain shape parameter, number of cells inlet length.

  • CTR – Domain shape parameter, index along inlet wall making the center of the domain. I.e., (0, CTR) is the midpoint across the inlet, along the inlet domain edge.

  • stage_above_SL – Water surface elevation minuns the domain sea level.


  • new_inds – An updated array of parcel indicies, where the index of a parcel has been changed, if and only if, that parcel was looped.

  • looped – A binary integer array indicating whether a parcel was determined to have been looped, and should be disqualified from the free surface computation.

pyDeltaRCM.water_tools._update_dirQfield(qfield, dist, inds, astep, dirstep)

Update unit vector of water flux in x or y.

pyDeltaRCM.water_tools._update_absQfield(qfield, dist, inds, astep, Qp_water, dx)

Update norm of water flux vector.

pyDeltaRCM.water_tools._accumulate_free_surface_walks(free_surf_walk_inds, free_surf_flag, cell_type, uw, ux, uy, depth, dx, u0, h0, H_SL, S0)

Accumulate the free surface by walking parcel paths.

This routine comprises the hydrodynamic physics-based computations.

Algorithm is to:
  1. loop through every parcel’s directed random walk in series.

2. for a parcel’s walk, unravel the indices and determine whether the parcel should contribute to the free surface. Parcels are considered contributors if they have reached the ocean and if they are not looped pathways.

3. then, we begin at the downstream end of the parcel’s walk and iterate up-walk until, determining the Hnew for each location. Downstream of the shoreline-ocean boundary, the water surface elevation is set to the sea level. Upstream of the shoreline-ocean boundary, the water surface is determined according to the land-slope (S0) and the parcel pathway.

  1. repeat from 2, for each parcel.

pyDeltaRCM.water_tools._smooth_free_surface(Hin, cell_type, Nsmooth, Csmooth)

Smooth the free surface.

  • Hin – Stage input to the smoothing (i.e., the old stage).

  • cell_type – Type of each cell.

  • Nsmooth – Number of times to smooth the free surface (i.e., stage)

  • Csmooth – Underrelaxation coefficient for smoothing iterations.