shared_tools

Todo

add paragraph description of the module

The tools are defined in pyDeltaRCM.shared_tools.

Shared functions

This module defines several functions that are used throughout the model, and so are organized here for convenience.

pyDeltaRCM.shared_tools.get_random_uniform(limit)

Get a random number from the uniform distribution.

Get a random number from the uniform distribution, defined over the interval [0, limit], where limit is an input parameter (often 1).

Hint

Function returns only a single float. Wrap the call in a simple for loop to get many random numbers.

Parameters

limit (float) – Upper limit to distribution to draw from.

Returns

Float value from the random number generator in the interval defined.

Return type

float

Examples

>>> get_random_uniform(1)
0.5488135039273248

>>> get_random_uniform(0.1)
0.07151893663724194
pyDeltaRCM.shared_tools.get_start_indices(inlet, inlet_weights, num_starts)

Get start indices.

Todo

Description needed. Where is it used?

pyDeltaRCM.shared_tools.get_steps(new_cells, iwalk, jwalk)

Find the values giving the next step.

Todo

Description needed. Where is it used?

pyDeltaRCM.shared_tools.random_pick(prob)

Pick number from weighted array.

Randomly pick a number weighted by array probabilities (len 9) Return the index of the selected weight in array probs Takes a numpy array that is the precalculated probability around the cell flattened to 1D.

Examples

Todo

Examples needed (pull from tests?).

pyDeltaRCM.shared_tools.custom_unravel(i, shape)

Unravel indexes for 2D array.

This is a jitted function, equivalent to the numpy implementation of unravel_index, but configured to accept only a single integer as the index to unravel.

Parameters
  • i (int) – Integer index to unravel.

  • shape (tuple of int) – Two element tuple of integers indicating the shape of the two-dimensional array from which i will be unravelled.

Returns

  • x (int) – x index of i into array of shape shape.

  • y (int) – y index of i into array of shape shape.

Examples

>>> _shape = (100, 200)  # e.g., delta.eta.shape

>>> np.unravel_index(5124, _shape)
(25, 124)

>>> custom_unravel(5124, _shape)
(25, 124)
pyDeltaRCM.shared_tools.custom_ravel(tup, shape)

Ravel indexes for 2D array.

This is a jitted function, equivalent to the numpy implementation of ravel_multi_index, but configured to accept only a single tuple as the index to ravel, and only works for two-dimensional array.

Parameters
  • tup (tuple of int) – Two element tuple with the x and y index into an array of shape shape to ravel.

  • shape (tuple of int) – Two element tuple of integers indicating the shape of the two-dimensional array from which tup will be ravelled.

Returns

i – Ravelled integer index into array of shape shape.

Return type

int

Examples

>>> _shape = (100, 200)  # e.g., delta.eta.shape

>>> np.ravel_multi_index((25, 124), _shape)
5124

>>> custom_ravel((25, 124), _shape)
5124
pyDeltaRCM.shared_tools.custom_pad(arr)

Pad an array.

This is a jitted function, equivalent to the numpy implementation of pad with certain optional parameters:

np.pad(arr, 1, 'edge')

In pyDeltaRCM model fields (e.g., depth) are frequently padded to enable straightforward slicing of the neighbors of a given cell; i.e., padding guarantees that all cells will have 9 neighbors.

Parameters

arr (ndarray) – Array to pad.

Returns

pad – Padded array.

Return type

ndarray

Examples

Consider a model domain of size (4, 8)

>>> arr = np.arange(32).reshape(4, 8)

>>> np_pad = np.pad(arr, 1, 'edge')
>>> cust_pad = custom_pad(arr)
>>> np.all(np_pad == cust_pad)
True
>>> cust_pad.shape
(6, 10)

which enables all elements of the original (4, 8) array to be safely sliced:

>>> for i in range(4):
...     for j in range(8):
...         slc = cust_pad[i:i+3, j:j+3]

>>> slc.shape  # will always be a (3, 3) 9-cell neighborhood
(3, 3)
pyDeltaRCM.shared_tools.get_weight_sfc_int(stage, stage_nbrs, qx, qy, ivec, jvec, distances)

Determine random walk weight surfaces.

Determines the surfaces for weighting the random walks based on the stage and discharge fields.

Todo

Expand description. Where is it used? Include an example? Equations? Link to Hydrodyanmics doc?

pyDeltaRCM.shared_tools.custom_yaml_loader()

A custom YAML loader to handle scientific notation.

We are waiting for upstream fix here:

https://github.com/yaml/pyyaml/pull/174

Returns

loader

Return type

pyyaml.Loader with custom resolver

Examples

The custom loader can be used as:

>>> loader = pyDeltaRCM.shared_tools.custom_yaml_loader()

>>> a_file = open('/path/to/file.yaml', mode='r')
>>> yaml_as_dict = yaml.load(a_file, Loader=loader)

Time scaling functions

Scaling of real-world time and model time is an important topic covered in detail in Time in pyDeltaRCM. Several functions are defined here which can help with scaling between model and real-world time.

pyDeltaRCM.shared_tools.scale_model_time(time, If=1, units='seconds')

Scale the model time to “real” time.

Model time is executed as assumed flooding conditions, and executed at the per-second level, with a multi-second timestep. This model design implicitly assumes that the delta is always receiving a large volume of sediment and water at the inlet. This is unrealistic, given that rivers flood only during a small portion of the year, and this is when morphodynamic activity is largest. See Time in pyDeltaRCM for a complete description of this assumption, and how to work with the assumption in configuring the model.

Using this assumption, it is possible to scale up model time to “real” time, by assuming an intermittency factor. This intermittency factor is the fraction of unit-time that a river is assumed to be flooding.

t_r = \dfrac{t}{I_f \cdot S_f}

where t is the model time (time), t_r is the “real” scaled time, I_f is the intermittency factor, and S_f is the scale factor to convert base units of seconds to units specified as an input argument. Note that this function uses _scale_factor internally for this conversion.

Parameters
  • time (float) – The model time, in seconds.

  • If (float, optional) – Intermittency factor, fraction of time represented by morphodynamic activity. Should be in interval (0, 1]. Defaults to 1 if not provided, i.e., no scaling is performed.

  • units (str, optional) – The units to convert the scaled time to. Default is to return the scaled time in seconds (seconds), but optionally supply argument days or years for unit conversion.

Returns

scaled – Scaled time, in units, assuming the intermittency factor If.

Return type

float

Raises

ValueError – if the value for intermittency is not 0 < If <= 1.

pyDeltaRCM.shared_tools._scale_factor(If, units)

Scaling factor between model time and “real” time.

The scaling factor relates the model time to a real worl time, by the assumed intermittency factor and the user-specified units for output.

Parameters
  • If (float) – Intermittency factor, fraction of time represented by morphodynamic activity. Must be in interval (0, 1].

  • units (str) – The units to convert the scaled time to. Must be a string in [‘seconds’, ‘days’, ‘years’].

Utilities

Additionally, functions defined in pyDeltaRCM.shared_tools manage the random state of the model, and help with documentation and version management.

pyDeltaRCM.shared_tools.set_random_seed(_seed)

Set the random seed from an integer.

Set the seed of the random number generator with a single integer. Importantly, this function will affect the state of the numba random number generator, rather than the numpy generator.

This function is called during model intialization, but is not called during loading a model from checkpoint (load_checkpoint()) where the random number generator state is configured via the set_random_state() function.

Important

This function is preferred to setting the random seed directly. If you are working with model subclassing, interacting with the numpy random number generator directly will lead to a model that is not reproducible!

Internally, the method is simply the below line; however it is crucial this happens inside a jitted function, in order to affect the state of the numba random number generator seed.

np.random.seed(_seed)
Parameters

_seed (int) – Integer to use as the random number generator seed. Should be in interval [0, 2^32].

pyDeltaRCM.shared_tools.get_random_state()

Get the random state as a tuple.

Get the random state from a tuple in the form returned by numba._helperlib.rnd_get_state(). This tuple contains the necessary information for resuming a checkpoint from the exact same random number generator state.

Important

You probably do not need to use this function. Be sure you know exactly how you are affecting the random number generator state before using this function, or you are likely to create a model that cannot be peproduced.

See also set_random_seed().

Returns

state – Random number generator state as a tuple.

Return type

tuple

pyDeltaRCM.shared_tools.set_random_state(_state_tuple)

Set the random state from a tuple.

Set the random state from a tuple in the form returned by numba._helperlib.rnd_get_state().

Important

You probably do not need to use this function. Be sure you know exactly how you are affecting the random number generator state before using this function, or you are likely to create a model that cannot be peproduced.

See also set_random_seed().

Parameters

state (tuple) – Random number generator state as a tuple.

pyDeltaRCM.shared_tools._docs_temp_directory()

Helper for creating and tearing down models in documentation.

This function should be used as a context manager, to create a DeltaModel with a temporary folder as output, rather than anywhere in the project structure.

Examples

>>> with _docs_temp_directory() as output_dir:
...     delta = pyDeltaRCM.DeltaModel(out_dir=output_dir)
pyDeltaRCM.shared_tools._get_version()

Extract version from file.

Extract version number from single file, and make it availabe everywhere. This function is used to make sure that when the version number is incremented in the pyDeltaRCM._version module, it is properly updated throughout documentation and version-controlled release.

Note

You probably don’t need to use this function.

Returns

ver_str – Version number, as a string.

Return type

str

Examples

>>> pyDeltaRCM.shared_tools._get_version()