def calculate_steepest_descent_across_cell_faces(grid, node_values, *args,
**kwds):
"""Get steepest gradient across the faces of a cell.
This method calculates the gradients in *node_values* across all four
faces of the cell or cells with ID *cell_ids*. Slopes upward from the
cell are reported as positive. If *cell_ids* is not given, calculate
gradients for all cells.
Use the *return_node* keyword to return a tuple, with the first element
being the gradients and the second the node id of the node in the direction
of the minimum gradient, i.e., the steepest descent. Note the gradient
value returned is probably thus negative.
Parameters
----------
grid : RasterModelGrid
Input grid.
node_values : array_like
Values to take gradient of.
cell_ids : array_like, optional
IDs of grid cells to measure gradients.
return_node: boolean, optional
Return node IDs of the node that has the steepest descent.
out : ndarray, optional
Alternative output array in which to place the result. Must
be of the same shape and buffer length as the expected output.
Returns
-------
ndarray :
Calculated gradients to lowest node across cell faces.
Convention: gradients positive UP
Examples
--------
Create a rectilinear grid that is 3 nodes by 3 nodes and so has one cell
centered around node 4.
>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid(3, 3)
>>> values_at_nodes = np.arange(9.)
Calculate gradients across each cell face and choose the gradient to the
lowest node.
>>> grid.calculate_steepest_descent_across_cell_faces(values_at_nodes)
masked_array(data = [-3.],
mask = False,
fill_value = 1e+20)
<BLANKLINE>
The steepest gradient is to node with id 1.
>>> (_, ind) = grid.calculate_steepest_descent_across_cell_faces(
... values_at_nodes, return_node=True)
>>> ind
array([1])
>>> grid = RasterModelGrid(3, 3)
>>> node_values = grid.zeros()
>>> node_values[1] = -1
>>> grid.calculate_steepest_descent_across_cell_faces(node_values, 0)
masked_array(data = [-1.],
mask = False,
fill_value = 1e+20)
<BLANKLINE>
Get both the maximum gradient and the node to which the gradient is
measured.
>>> grid.calculate_steepest_descent_across_cell_faces(node_values, 0,
... return_node=True)
(array([-1.]), array([1]))
"""
return_node = kwds.pop('return_node', False)
cell_ids = make_optional_arg_into_id_array(grid.number_of_cells, *args)
grads = calculate_gradient_across_cell_faces(grid, node_values, cell_ids)
if return_node:
ind = np.argmin(grads, axis=1)
node_ids = grid.get_active_neighbors_at_node()[grid.node_at_cell[cell_ids], ind]
# node_ids = grid.neighbor_nodes[grid.node_at_cell[cell_ids], ind]
if 'out' not in kwds:
out = np.empty(len(cell_ids), dtype=grads.dtype)
out[:] = grads[range(len(cell_ids)), ind]
return (out, node_ids)
# return (out, 3 - ind)
else:
return grads.min(axis=1, **kwds)
def test_scalar_arg():
"""Test with a scalar arg for faces."""
grads = calculate_gradient_across_cell_faces(rmg, values_at_nodes, 0)
assert_array_equal(grads, np.array([[1.0, 5.0, -1.0, -5.0]]))
def test_scalar_arg():
"""Test with a scalar arg for faces."""
grads = calculate_gradient_across_cell_faces(rmg, values_at_nodes, 0)
assert_array_equal(grads, np.array([[1., 5., -1., -5.]]))
def calculate_steepest_descent_across_cell_faces(grid, node_values, *args,
**kwds):
"""Get steepest gradient across the faces of a cell.
This method calculates the gradients in *node_values* across all four
faces of the cell or cells with ID *cell_ids*. Slopes upward from the
cell are reported as positive. If *cell_ids* is not given, calculate
gradients for all cells.
Use the *return_node* keyword to return a tuple, with the first element
being the gradients and the second the node id of the node in the direction
of the minimum gradient, i.e., the steepest descent. Note the gradient
value returned is probably thus negative.
Parameters
----------
grid : RasterModelGrid
Input grid.
node_values : array_like
Values to take gradient of.
cell_ids : array_like, optional
IDs of grid cells to measure gradients.
return_node: boolean, optional
Return node IDs of the node that has the steepest descent.
out : ndarray, optional
Alternative output array in which to place the result. Must
be of the same shape and buffer length as the expected output.
Returns
-------
ndarray :
Calculated gradients to lowest node across cell faces.
Convention: gradients positive UP
Examples
--------
Create a rectilinear grid that is 3 nodes by 3 nodes and so has one cell
centered around node 4.
>>> from landlab import RasterModelGrid
>>> grid = RasterModelGrid(3, 3)
>>> values_at_nodes = np.arange(9.)
Calculate gradients across each cell face and choose the gradient to the
lowest node.
>>> grid.calculate_steepest_descent_across_cell_faces(values_at_nodes)
masked_array(data = [-3.],
mask = False,
fill_value = 1e+20)
<BLANKLINE>
The steepest gradient is to node with id 1.
>>> (_, ind) = grid.calculate_steepest_descent_across_cell_faces(
... values_at_nodes, return_node=True)
>>> ind
array([1])
>>> grid = RasterModelGrid(3, 3)
>>> node_values = grid.zeros()
>>> node_values[1] = -1
>>> grid.calculate_steepest_descent_across_cell_faces(node_values, 0)
masked_array(data = [-1.],
mask = False,
fill_value = 1e+20)
<BLANKLINE>
Get both the maximum gradient and the node to which the gradient is
measured.
>>> grid.calculate_steepest_descent_across_cell_faces(node_values, 0,
... return_node=True)
(array([-1.]), array([1]))
"""
return_node = kwds.pop('return_node', False)
cell_ids = make_optional_arg_into_id_array(grid.number_of_cells, *args)
grads = calculate_gradient_across_cell_faces(grid, node_values, cell_ids)
if return_node:
ind = np.argmin(grads, axis=1)
node_ids = grid.get_active_neighbors_at_node()[
grid.node_at_cell[cell_ids], ind]
# node_ids = grid.neighbor_nodes[grid.node_at_cell[cell_ids], ind]
if 'out' not in kwds:
out = np.empty(len(cell_ids), dtype=grads.dtype)
out[:] = grads[range(len(cell_ids)), ind]
return (out, node_ids)
# return (out, 3 - ind)
else:
return grads.min(axis=1, **kwds)
