Developer API

NeuralLyapunov

Build and train neural Lyapunov-function formulations for dynamical systems.

The package exposes composable structures for the candidate Lyapunov function, its minimization condition, and its decrease condition. These components are assembled into symbolic ModelingToolkitBase.PDESystems for use with NeuralPDE. The abstract types and generic functions documented on the developer API page are extension points for packages that provide additional formulations.

phi_to_net(phi, θ[; idx])

Return the network as a function of state alone.

Arguments

• phi: the neural network, represented as phi(x, θ) if the neural network has a single output, or a Vector of the same with one entry per neural network output.
• θ: the parameters of the neural network; If the neural network has multiple outputs, θ[:φ1] should be the parameters of the first neural network output, θ[:φ2] the parameters of the second (if there are multiple), and so on. If the neural network has a single output, θ should be the parameters of the network.
• idx: the neural network outputs to include in the returned function; defaults to all and only applicable when phi isa Vector.

NeuralLyapunovBenchmarkLogger(losses, iterations)

A simple logger for tracking the (full weighted) loss during training using NeuralPDE.

Fields

• losses::Vector{<:Real}: A vector to store the loss values.
• iterations::Vector{<:Integer}: A vector to store the corresponding iteration numbers.

Constructors

• NeuralLyapunovBenchmarkLogger{T1, T2}() where {T1<:Real, T2<:Integer}: Creates an empty logger with specified types for losses and iterations.
• NeuralLyapunovBenchmarkLogger{T}() where {T}: Creates an empty logger with specified type for losses and Int64 for iterations.
• NeuralLyapunovBenchmarkLogger(): Creates an empty logger with Float64 for losses and Int64 for iterations.

AbstractNeuralLyapunovStructure{nc}

Developer interface for a neural Lyapunov-function structure.

The type parameter nc records whether the structure includes a neural-network-dependent control or other contribution to the dynamics. A subtype must implement the following generic functions for every instance:

• get_V: return V(phi, state, fixed_point), where phi is a callable neural network and state is a single state vector.
• get_V̇: return V̇(phi, J_phi, state, dstate_dt, fixed_point), where J_phi evaluates the derivative of phi with respect to state.
• get_network_dim: return the positive number of neural-network outputs used by the structure.

For a subtype of AbstractNeuralLyapunovStructure{true}, also implement get_control_structure, returning control_structure(phi_c, state, fixed_point), and get_control_dim, returning the positive number of outputs consumed by that structure. phi and J_phi must be functions of state alone; implementations must not assume a particular concrete structure type or access its fields from generic code.

The false and true parameter values are part of the dispatch contract. Use AbstractNeuralLyapunovStructure{false} for dynamics of the form f(state, p, t) and AbstractNeuralLyapunovStructure{true} for dynamics of the form f(state, control, p, t).

Example

struct MyStructure <: AbstractNeuralLyapunovStructure{false} end

NeuralLyapunov.get_V(::MyStructure) = (phi, state, fixed_point) -> phi(state)[1]
NeuralLyapunov.get_V̇(::MyStructure) =
    (phi, J_phi, state, dstate_dt, fixed_point) -> sum(J_phi(state)[1, :] .* dstate_dt)
NeuralLyapunov.get_network_dim(::MyStructure) = 1

get_V(str::AbstractNeuralLyapunovStructure)

Return a function V(phi, state, fixed_point) that outputs the value of the Lyapunov function at state.

Arguments

• str: the neural Lyapunov structure being queried.

Returns

A callable accepting a neural network phi, a state vector, and a fixed point. It may return a scalar or an array compatible with the condition and PDESystem constructors.

Extension Rules

Define a method for each concrete subtype. The returned callable must not rely on a specific neural-network implementation.

get_V̇(str::AbstractNeuralLyapunovStructure)

Return a function V̇(phi, J_phi, state, dstate_dt, fixed_point) that outputs the time derivative of the Lyapunov function at state.

Arguments

• str: the neural Lyapunov structure being queried.

Returns

A callable accepting the neural network phi, its state Jacobian J_phi, a state vector, the state derivative dstate_dt, and a fixed point. It may return a scalar or an array compatible with the generated equations.

Extension Rules

Define a method for each concrete subtype. J_phi must be treated as a callable of the state, rather than as a package-specific differentiation object.

neural_controller(str::AbstractNeuralLyapunovStructure)

Return true if str specifies a neural controller (i.e., if str is a subtype of AbstractNeuralLyapunovStructure{true}) and false otherwise.

Arguments

• str: the neural Lyapunov structure to classify.

Returns

true exactly for structures parameterized as AbstractNeuralLyapunovStructure{true} and false for structures parameterized as AbstractNeuralLyapunovStructure{false}.

get_network_dim(str::AbstractNeuralLyapunovStructure)

Return the number of dimensions of the neural network output specified by str.

Arguments

• str: the neural Lyapunov structure being queried.

Returns

A positive Integer equal to the number of neural-network outputs consumed by get_V and get_V̇.

get_control_dim(str::AbstractNeuralLyapunovStructure{true})

Return the control dimension specified by str.

Arguments

• str: an AbstractNeuralLyapunovStructure{true} instance.

Returns

A positive Integer equal to the number of neural-network outputs passed through get_control_structure.

get_control_structure(str::AbstractNeuralLyapunovStructure{true})

Return the control structure specified by str.

Arguments

• str: an AbstractNeuralLyapunovStructure{true} instance.

Returns

A callable control_structure(phi_c, state, fixed_point) that transforms the control-output portion of the neural network into the input expected by the dynamics.

Extension Rules

This method is required only for AbstractNeuralLyapunovStructure{true}. It must preserve the callable signature so that add_policy_search and get_policy can use the result without knowing the concrete subtype.