dorado.lagrangian_walker

Core functions to handle the Lagrangian random walk movement of the particles.

Project Homepage: https://github.com/passaH2O/dorado

dorado.lagrangian_walker.big_sliding_window(raster)

Creates 3D array organizing local neighbors at every index

Returns a raster of shape (L,W,9) which organizes (along the third dimension) all of the neighbors in the original raster at a given index, in the order [NW, N, NE, W, 0, E, SW, S, SE]. Outputs are ordered to match np.ravel(), so it functions similarly to a loop applying ravel to the elements around each index. For example, the neighboring values in raster indexed at (i,j) are raster(i-1:i+2, j-1:j+2).ravel(). These 9 values have been mapped to big_ravel(i,j,:) for ease of computations. Helper function for make_weight.

Inputs :

rasterndarray

2D array of values (e.g. stage, qx)

Outputs :

big_ravelndarray

3D array which sorts the D8 neighbors at index (i,j) in raster into the 3rd dimension at (i,j,:)

dorado.lagrangian_walker.calc_travel_times(Particles, new_cell, ind, new_ind, dist)

Calculate travel time for particle to get to the new location.

Function to calculate the travel time for the particle to get from the current location to the new location. Calculated by taking the inverse of the velocity at the old and new locations.

Inputs :

Particlesdorado.particle_track.Particles

A dorado.particle_track.Particles object

new_cellint

Integer 1-8 indicating new location in D-8 way

indtuple

Tuple (x,y) of the current location

new_indtuple

Tuple (x,y) of the new location

distfloat

Distance between current (old) and new particle location

Outputs :

trav_timefloat

Travel time it takes the particle to get from the current location to the new proposed location using the inverse of the average velocity

dorado.lagrangian_walker.calculate_new_ind(ind, new_cell, iwalk, jwalk)

Add new cell location (1-8 value) to the previous index.

Inputs :

indtuple

Tuple (x,y) of old particle location

new_cellint

Integer 1-8 indicating new cell location relative to the old one in a D-8 sense

iwalkndarray

A D8 array with the positive and negative x directions

jwalkndarray

A D8 array with the positive and negative y directions

Outputs :

new_indtuple

tuple (x,y) of the new particle location

dorado.lagrangian_walker.check_for_boundary(new_inds, current_inds, cell_type)

Ensure new location is not a boundary cell.

Function to make sure particle is not exiting the boundary with the proposed new location.

Inputs :

new_indslist

List [] of tuples (x,y) of new indices

current_indslist

List [] of tuples (x,y) of old indices

cell_typenumpy.ndarray

Array of the different types of cells in the domain where 2 = land, 1 = channel, 0 = ocean, and -1 = edge. If not explicitly defined then the values are estimated based on the depth array and the defined dry_depth

Outputs :

new_indslist

list [] of tuples (x,y) of new indices where any proposed indices outside of the domain have been replaced by the old indices so those particles will not travel this iteration

dorado.lagrangian_walker.clear_borders(tiled_array)

Set to zero all the edge elements of a vertical stack of 2D arrays. Helper function for make_weight.

Inputs :

tiled_arrayndarray

3D array repeating raster (e.g. stage, qx) 9 times along the third axis

Outputs :

tiled_arrayndarray

The same 3D array as the input, but with the borders in the first and second dimension set to 0.

dorado.lagrangian_walker.get_weight(Particles, ind)

Choose new cell location given an initial location.

Function to randomly choose 1 of the surrounding 8 cells around the current index using the routing weights from make_weight.

Inputs :

Particlesdorado.particle_track.Particles

A dorado.particle_track.Particles object

indtuple

Tuple (x,y) with the current location indices

Outputs :

new_cellint

New location given as a value between 1 and 8 (inclusive)

dorado.lagrangian_walker.make_weight(Particles)

Create the weighting array for particle routing

Function to compute the routing weights at each index, which gets stored inside the dorado.particle_track.Particles object for use when routing. Called when the object gets instantiated.

Inputs :

Particlesdorado.particle_track.Particles

A dorado.particle_track.Particles object

Outputs :

Updates the weights array inside the dorado.particle_track.Particles object

dorado.lagrangian_walker.particle_stepper(Particles, current_inds, travel_times)

Step particles a single iteration.

Inputs :

Particles: dorado.particle_track.Particles

A dorado.particle_track.Particles object.

current_indslist

List of tuples of the current particle (x,y) locations in space

travel_timeslist

List of initial travel times for the particles

Outputs :

new_indslist

List of the new particle locations after the single iteration

travel_timeslist

List of the travel times associated with the particle movements

dorado.lagrangian_walker.random(size=None)

Return random floats in the half-open interval [0.0, 1.0). Alias for random_sample to ease forward-porting to the new random API.

dorado.lagrangian_walker.random_pick(probs)

Pick value from weighted probability array.

Randomly pick a number weighted by array probs (len 8) Return the index of the selected weight in array probs

Inputs :

probslist

8 values indicating the probability (weight) associated with the surrounding cells for the random walk

Outputs :

idxint

1-8 value chosen randomly based on the weighted probabilities

dorado.lagrangian_walker.random_pick_seed(choices, probs=None)

Randomly pick a number from array of choices.

Inputs :

choicesndarray

Array of possible values to draw from

probsndarray

Optional, can add weighted probabilities to draw

Outputs :

choices[idx]int

The randomly chosen value

dorado.lagrangian_walker.steep_descent(probs)

Choose value with greatest probability, no longer random.

Pick the array value with the greatest probability, no longer a stochastic process, instead just choosing the steepest descent

Inputs :

probsfloat

8 values indicating probability (weight) associated with the surrounding cells

Outputs :

idxint

1-8 value chosen by greatest probs

dorado.lagrangian_walker.step_update(new_cell, distances, dx)

Get distance to new particle location.

Function to check new location is some distance away from old one, also provides way to track the travel distance of the particles

Inputs :

new_cellint

Integer 1-8 indicating new location in D-8 way

distancesndarray

D8 distances between cells

dxfloat

Length along one square cell face

Outputs :

distfloat

Distance between current (old) and new particle location

dorado.lagrangian_walker.tile_domain_array(raster)

Repeat a large 2D array 9 times along the third axis. Helper function for make_weight.

Inputs :

rasterndarray

2D array of values (e.g. stage, qx)

Outputs :

tiled_arrayndarray

3D array repeating raster 9 times

dorado.lagrangian_walker.tile_local_array(local_array, L, W)

Take a local array [[NW, N, NE], [W, 0, E], [SW, S, SE]] and repeat it into an array of shape (L,W,9), where L, W are the shape of the domain, and the original elements are ordered along the third axis. Helper function for make_weight.

Inputs :

local_arrayndarray

2D array of represnting the D8 neighbors around some index (e.g. ivec, jvec)

Lint

Length of the domain

Wint

Width of the domain

Outputs :

tiled_arrayndarray

3D array repeating local_array.ravel() LxW times