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.

shared_tools¶

Shared functions¶

Time scaling functions¶

Utilities¶

Table of Contents

Previous topic

Next topic

This Page