Lyapunov

class safe_learning.Lyapunov(discretization, lyapunov_function, dynamics, lipschitz_dynamics, lipschitz_lyapunov, tau, policy, initial_set=None, adaptive=False)

A class for general Lyapunov functions.

Parameters:

discretization : ndarray

A discrete grid on which to evaluate the Lyapunov function.

lyapunov_function : callable or instance of DeterministicFunction

The lyapunov function. Can be called with states and returns the corresponding values of the Lyapunov function.

dynamics : a callable or an instance of Function

The dynamics model. Can be either a deterministic function or something uncertain that includes error bounds.

lipschitz_dynamics : ndarray or float

The Lipschitz constant of the dynamics. Either globally, or locally for each point in the discretization (within a radius given by the discretization constant. This is the closed-loop Lipschitz constant including the policy!

lipschitz_lyapunov : ndarray or float

The Lipschitz constant of the lyapunov function. Either globally, or locally for each point in the discretization (within a radius given by the discretization constant.

tau : float

The discretization constant.

policy : ndarray, optional

The control policy used at each state (Same number of rows as the discretization).

initial_set : ndarray, optional

A boolean array of states that are known to be safe a priori.

adaptive : bool, optional

A boolean determining whether an adaptive discretization is used for stability verification.

Methods

is_safe(self, state)	Return a boolean array that indicates whether the state is safe.
lipschitz_dynamics(self, states)	Return the Lipschitz constant for given states and actions.
lipschitz_lyapunov(self, states)	Return the local Lipschitz constant at a given state.
safety_constraint(self, policy[, …])	Return the safe set for a given policy.
threshold(self, states[, tau])	Return the safety threshold for the Lyapunov condition.
update_safe_set(self[, can_shrink, …])	Compute and update the safe set.
update_values(self)	Update the discretized values when the Lyapunov function changes.
v_decrease_bound(self, states, next_states)	Compute confidence intervals for the decrease along Lyapunov function.
v_decrease_confidence(self, states, next_states)	Compute confidence intervals for the decrease along Lyapunov function.

is_safe(self, state)

Return a boolean array that indicates whether the state is safe.

Parameters:

state : ndarray

Returns:

safe : boolean

Is true if the corresponding state is inside the safe set.

lipschitz_dynamics(self, states)

Return the Lipschitz constant for given states and actions.

Parameters:

states : ndarray or Tensor

Returns:

lipschitz : float, ndarray or Tensor

If lipschitz_dynamics is a callable then returns local Lipschitz constants. Otherwise returns the Lipschitz constant as a scalar.

lipschitz_lyapunov(self, states)

Return the local Lipschitz constant at a given state.

Parameters:

states : ndarray or Tensor

Returns:

lipschitz : float, ndarray or Tensor

If lipschitz_lyapunov is a callable then returns local Lipschitz constants. Otherwise returns the Lipschitz constant as a scalar.

safety_constraint(self, policy, include_initial=True)

Return the safe set for a given policy.

Parameters:

policy : ndarray

The policy used at each discretization point.

include_initial : bool, optional

Whether to include the initial safe set.

Returns:

constraint : ndarray

A boolean array indicating where the safety constraint is fulfilled.

threshold(self, states, tau=None)

Return the safety threshold for the Lyapunov condition.

Parameters:

states : ndarray or Tensor

tau : float or Tensor, optional

Discretization constant to consider.

Returns:

lipschitz : float, ndarray or Tensor

Either the scalar threshold or local thresholds, depending on whether lipschitz_lyapunov and lipschitz_dynamics are local or not.

update_safe_set(self, can_shrink=True, max_refinement=1, safety_factor=1.0, parallel_iterations=1)

Compute and update the safe set.

Parameters:

can_shrink : bool, optional

A boolean determining whether previously safe states other than the initial safe set must be verified again (i.e., can the safe set shrink in volume?)

max_refinement : int, optional

The maximum integer divisor used for adaptive discretization.

safety_factor : float, optional

A multiplicative factor greater than 1 used to conservatively estimate the required adaptive discretization.

parallel_iterations : int, optional

The number of parallel iterations to use for safety verification in the adaptive case. Passed to tf.map_fn.

update_values(self)

Update the discretized values when the Lyapunov function changes.

v_decrease_bound(self, states, next_states)

Compute confidence intervals for the decrease along Lyapunov function.

Parameters:

states : np.array

The states at which to start (could be equal to discretization).

next_states : np.array or tuple

The dynamics evaluated at each point on the discretization. If the dynamics are uncertain then next_states is a tuple with mean and error bounds.

Returns:

upper_bound : np.array

The upper bound on the change in values at each grid point.

v_decrease_confidence(self, states, next_states)

Compute confidence intervals for the decrease along Lyapunov function.

Parameters:

states : np.array

The states at which to start (could be equal to discretization).

next_states : np.array

The dynamics evaluated at each point on the discretization. If the dynamics are uncertain then next_states is a tuple with mean and error bounds.

Returns:

mean : np.array

The expected decrease in values at each grid point.

error_bounds : np.array

The error bounds for the decrease at each grid point