pyviability.libviability module¶

Basic module that contains most of the relevant routines.

class pyviability.libviability.RemovingSetWrapper[source]¶

Bases: set

RemovingSetWrapper removes elements on iteration.

Note: Usually used internally only.

When iterating over RemovingSetWrapper, the iterated element is removed. This manages basically which points are still needed to iterate over in the viability algorithm.

pyviability.libviability.backscaling_grid(grid, scaling_vector, offset)[source]¶: Scale a grid back( after computation) from [0, 1]^dim to the original state space.

pyviability.libviability.generate_grid(boundaries, n0, grid_type='orthogonal', periodicity=[], verbosity=True)[source]¶

Generate a grid, that is already normalized to [0, 1]^dimension.

Note: This function also sets globally MAX_NEIGHBOR_DISTANCE, BOUNDS_EPSILON, STEPSIZE, ALL_NEIGHBORS_DISTANCE. So if you don’t use this function, you need to set it yourself by hand. Later, this will be circumvented by using proper OO-programming.

Parameters:

Parameters:	boundaries (array-like) – shape (dim, 2), give the boundaries (min and max) for each dimension of the mode system n0 (non-negative int) – total number of points that the grid should have grid_type (str, default: "orthogonal") – specify the grid_type to be created. experimental, only use if your know what you do periodicity (array-like, default: []) – specify if there is an peridicity given (to avoid overlapping points) verbosity (bool, default: True) – specify the verbosity
Returns:	(grid, scaling_vectors, offset, x_step) with grid: the actual rescaled grid scaling_vectors, offset : parameters to scale the grid back to the original size x_step : stepsize of the grid
Return type:	tuple

boundaries (array-like) – shape (dim, 2), give the boundaries (min and max) for each dimension of the mode system
n0 (non-negative int) – total number of points that the grid should have
grid_type (str, default: "orthogonal") – specify the grid_type to be created. experimental, only use if your know what you do
periodicity (array-like, default: []) – specify if there is an peridicity given (to avoid overlapping points)
verbosity (bool, default: True) – specify the verbosity

Returns:

(grid, scaling_vectors, offset, x_step) with

grid: the actual rescaled grid

scaling_vectors, offset : parameters to scale the grid back to the original size

x_step : stepsize of the grid

Return type:

tuple

pyviability.libviability.get_global_status()[source]¶: Return the current Status of a computation.

pyviability.libviability.get_neighbor_indices_via_cKD(index, neighbor_list=[])[source]¶: extend ‘neighbor_list’ by all neighbors that are closer than STEPSIZE + BOUNDS_EPSILON

pyviability.libviability.make_run_function(rhs, ordered_params, offset, scaling_vector, returning='linear', use_numba=True, nb_nopython=True, rescaling_epsilon=1e-06)[source]¶

Create a run-function from a right-hand side of an ordinary differential equation.

The run-function takes a starting point and a time and returns a trajectory that follows the corresponding ODE. It basically provides the step from a generic ODE to a map that gives the next point. The reason the return value is actually a trajectory and not just the next point is simply future compatibility.

Note: This function automatically rescales the RHS to work on [0, 1]^dim and homogenizes the time (see https://arxiv.org/abs/1706.04542).

Parameters:	rhs (callable) – Function that representes the RHS of the ODE. The first two arguments should be the point x in state space and the time t. The following arguments should be parameters that are need to be given, if necessary. ordered_params (tuple) – The parameters needed for rhs. offset (array-like) – output from grid rescaling, see generate_grid scaling_vector (array-like) – output from grid rescaling, see generate_grid returning (str, default : "linear") – only change of you know what you do use_numa (bool, default : True) – Should numba be used? nb_nb_nopython (bool, default : True,) – If numba is used, force nopython-mode? rescaling_rescaling_epsilon (float, default : 1e-6) – When homogenizing the time, which epsilong value should be used. see https://arxiv.org/abs/1706.04542
Returns:	The corresponding run-function.
Return type:	callable

pyviability.libviability.plot_areas(coords, states)[source]¶: plot the current states in the viability calculation as areas

pyviability.libviability.plot_points(coords, states, markersize=15, plot_unset=False)[source]¶: plot the current states in the viability calculation as points

pyviability.libviability.pre_calculation_hook_kdtree(coordinates, states, is_sunny=None, periodicity=None, grid_type=None, out_of_bounds=True)[source]¶

Do all prepratory stuff for a viability computation.

Note: Usually used internally only.

This function creates the KDTREE, makes a variety of variables globally accessible.

pyviability.libviability.print_evaluation(states, print_empty_regions=True, print_unknown=True)[source]¶: Print an Evaluation of the results of an TSM-Computation.

pyviability.libviability.printv(*args, verbosity=1, date_behind=False, **kwargs)[source]¶: Print the output depending on the given verbosity.

pyviability.libviability.scaled_to_one_sunny(is_sunny, offset, scaling_vector)[source]¶: Scale the is_sunny function so it operates on [0, 1]^dim.

pyviability.libviability.set_global_status(*args, print_verbosity=None)[source]¶: Setting the global Status of a Computation so it can be read out in case of Errors.

pyviability.libviability.state_evaluation_kdtree(traj)[source]¶

Get the closest point to the end of the trajectory in the grid using KDTREE.

Note: Used internally during the viability computations.

pyviability.libviability.topology_classification(coordinates, states, default_evols, management_evols, is_sunny, periodic_boundaries=[], compute_eddies=False, pre_calculation_hook=<function pre_calculation_hook_kdtree>, state_evaluation=<function state_evaluation_kdtree>, post_computation_hook=<function reset_initial_states>, grid_type='orthogonal', out_of_bounds=True, remember_paths=False, verbosity=0, stop_when_finished='')[source]¶

Estimate different regions of the state space using viability theory algorithms.

This function computes the Topology of Sustainable Management (TSM) classification of the state space (see [1] for mathematical details).

The first application can be found in [2].

[1] http://www.earth-syst-dynam.net/7/21/2016/esd-7-21-2016.html

[2] https://arxiv.org/abs/1706.04542

Note: A state is an integer referring to a certain region (in the sense of TSM), corresponding as to how they are defined in the header of this file

Parameters:

Parameters:	coordinates (array-like) – Grid used for the computation, shape (n0, dim) where n0 is the total number of points and dim the dimension of the system states (array-like) – associates to each grid point the corresponding state. negative values correspond to preset values given by the user. The results will be saved in here. compute_eddies (bool, default : True) – Should the Eddies be computed as well. As indicated in [2], this may take quite a bit of computational power and is hence switched of generally. pre_pre_calculation_hook (callable, default : pre_pre_calculation_hook_kdtree) – ignore if you don’t know what to do state_evaluation (callable, default : state_evaluation_kdtree) – ignore if you don’t know what to do post_computation_hook (callable, default : reset_initial_states) – ignore if you don’t know what to do grid_type (str, default : "orthogonal") – out_of_bounds (bool, default : True) – Is outside of the grid a undesirable region (in the sense of TSM)? remember_paths (bool, default : False) – Remember the paths that have been used. This is actually more of a hack and should not really be used. verbosity (int, default : 0) – stop_when_finished (str, default : '') – For Debugging only: stop when a certain operation has finished. See TOPOLOGY_STEP_LIST for the list of possible values.

coordinates (array-like) – Grid used for the computation, shape (n0, dim) where n0 is the total number of points and dim the dimension of the system
states (array-like) – associates to each grid point the corresponding state. negative values correspond to preset values given by the user. The results will be saved in here.
compute_eddies (bool, default : True) – Should the Eddies be computed as well. As indicated in [2], this may take quite a bit of computational power and is hence switched of generally.
pre_pre_calculation_hook (callable, default : pre_pre_calculation_hook_kdtree) – ignore if you don’t know what to do
state_evaluation (callable, default : state_evaluation_kdtree) – ignore if you don’t know what to do
post_computation_hook (callable, default : reset_initial_states) – ignore if you don’t know what to do
grid_type (str, default : "orthogonal") –
out_of_bounds (bool, default : True) – Is outside of the grid a undesirable region (in the sense of TSM)?
remember_paths (bool, default : False) – Remember the paths that have been used. This is actually more of a hack and should not really be used.
verbosity (int, default : 0) –
stop_when_finished (str, default : '') – For Debugging only: stop when a certain operation has finished. See TOPOLOGY_STEP_LIST for the list of possible values.