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