phlearn.control

The control subpackage implements PID and MPC controllers for pseudo-Hamiltonian systems and pseudo-Hamiltonian neural networks.

Controller classes

Reference classes

Reference

ConstantReference

StepReference

PoissonStepReference

FixedReference

class phlearn.control.CasadiFCNN(layers=())

Bases: object

Casadi-implementation of a fully-connected neural network. The class takes in a specification of a neural network model and implements the specification as a Casadi function.

Parameters
layerslist of dicts

List of dictionaries where each entry describes a layer of the neural network as returned by the “get_pytorch_model_architecture” function.

Methods

create_forward

get_parameters

set_weights_and_biases

test_correct_output
create_forward(*args)
get_parameters()
set_weights_and_biases(params, source='pytorch')
test_correct_output(gt_model, n=10)
class phlearn.control.CasadiPseudoHamiltonianSystem(S, dH, u, R=None, F=None)

Bases: object

Casadi implementation of the pseudo-Hamiltonian framework, modeling a system of the form:

dx/dt = (S - R)*grad(H) + F(x, t)

where S is the skew-symmetric interconnection matrix, R is a diagonal positive semi-definite damping/dissipation matrix, H is the Hamiltonian of the system, F is the external interaction and x is the system state. The system dimension is denoted by nstates.

Methods

create_forward
create_forward()
class phlearn.control.PIDController(control_forces_filter, gains, references, input_bounds=None)

Bases: PseudoHamiltonianController

This class implements a proportional-integral-derivative (PID) controller. The PID controller is a SISO controller, but several PIDs can be configured to run in parallel, up to one per state of the system.

Parameters
control_forces_filter(nstates, nstates) or (nstates,) ndarray

A binary ndarray where 1 signifies that the corresponding state has a control input in its derivative right-hand-side.

gainsdict

Dictionary where the key is the index of the state that the PID controls, and the value is anotherdictionary of the form {“p”: proportional gain, “i”: integral gain”, “d”:derivative gain}. Missing gains are assumed to be zero.

referencesdict of references

Dictionary where the key is the index of the state that the PID controls, and the value is a Reference object for that PID controller.

input_boundsdict

Dictionary where the key is the index of the state that the PID controls, and the value is a two-element list where the first element gives a lower bound for the control input and the second element gives an upper bound.

Methods

reset()

Function called before starting control of a new trajectory.

set_reference(references)

Function used to change the Reference objects specified during instantiation.
reset()

Function called before starting control of a new trajectory. Resets the controllers’ internal state, as well as any reference objects.

set_reference(references)

Function used to change the Reference objects specified during instantiation.

Parameters
referencesdict of references

Dictionary of reference name as keys and Reference object as values.

class phlearn.control.PseudoHamiltonianController(control_forces_filter)

Bases: object

Abstract base class for controllers of pseudo-Hamiltonian systems of the form:

dx/dt = (S - R)*grad[H(x)] + F(x, t) + u(x, t)

where this class implements u(x, t), i.e. known and controlled external ports. Implementations of controllers must subclass this class and implement all of its methods.

Parameters
control_forces_filter(nstates, nstates) or (nstates,) ndarray

A binary ndarray where 1 signifies that the corresponding state has a control input in its derivative right-hand-side.

Methods

__call__(x[, t])

Control inputs are computed by calling the controller with a system state, and optionally with system time for controllers that depend on time (e.g.

reset()

Function called before starting control of a new trajectory.

set_reference(references)

Function used to change the Reference objects specified during instantiation.
reset()

Function called before starting control of a new trajectory. Resets the controllers’ internal state, as well as any reference objects.

set_reference(references)

Function used to change the Reference objects specified during instantiation.

Parameters
referencesdict of references

Dictionary of reference name as keys and Reference object as values.

class phlearn.control.PseudoHamiltonianMPC(control_forces_filter, S=None, dH=None, H=None, F=None, R=None, baseline=None, state_names=None, control_names=None, references=None, model_callback=None, p_callback=None, tvp_callback=None)

Bases: PseudoHamiltonianController

This class implements a model predictive controller (MPC) that solves an optimal control problem to decide control inputs, where the model is formulated as a pseudo-Hamiltonian system:

dx/dt = (S - R) * grad[H(x)] + F(x, t) + u(x, t)

or if the baseline argument is provided:

dx/dt = Baseline(x, t) + u(x, t)

Each component of the model can be provided as either a python function or as a pytorch neural network (NN). Note that for any component implemented as a python function mist use only operations that are compatible with casadi variable types.

The MPC is based on the do-mpc python toolbox, see its documentation for configuration options and behaviour (do-mpc.com).

Parameters
control_forces_filtermatrix

A binary matrix of (nstates, nstates) or vector of (nstates) where 1 signifies that the corresponding state has a control input in its derivative right-hand-side.

Smatrix, default None

(nstates, nstates) ndarray. nstates if inferred from this.

dHcallable, default None

Function/NN computing the gradient of the Hamiltonian. Takes one argument (state). Accepts an ndarray both of size (nstates,) and of size (nsamples, nstates), and returns either an ndarray of size (nstates,) or an ndarray of size (nsamples, nstates), correspondingly.

Hcallable, default None

Function/NN computing the Hamiltonian of the system. Takes one argument (state,). Accepts ndarrays both of size (nstates,) and of size (nsamples, nstates), and returns either a scalar or an ndarray of size (nstates,), correspondingly.

Rmatrix or array, default None

(nstates, nstates) ndarray or (N,) ndarray of diagonal elements or NN

Fcallable, default None

Function/NN computing external ports taking two arguments (state and time), which can be both an ndarray of size (nstates,) + a scalar, and an ndarray of size (nsamples, nstates) + an ndarray of size (nstates,). Returns either an ndarray of size (nstates,) or an ndarray of size (nsamples, nstates), correspondingly.

baselinecallable, default None

Alternative model formulation

state_nameslist, default None

List of length (nstates) where each entry sets the name of the model state variables such that states can be referenced by these names.

control_nameslist, default None

List of size (ncontrols) where each entry sets the name of the model control input variables such that inputs can be referenced by these names.

referencesdict, default None

Dictionary with reference names as keys and Reference as values. Note that all references must be specified using this argument on object instantiation as they must be added as variables to the model.

model_callbackcallable, default None

Callback function for the end of model creation taking the model as argument, and returns the modified model. Can be used to add additional variables to the model.

p_callbackcallable, default None

Callback function calles before computing the MPC solution (get_input) where values for additional parameters must be set by user. Takes as argument the parameter object and the current model time, and must return the modified parameter object.

tvp_callbackcallable, default None

Callback function called before computing the MPC solution (get_input) where values for additional time-varying parameter must be set by user. Takes as argument the time-varying-parameter object and the current model time, and must return the modified time-varying-parameter object object.

Methods

reset()

Function called before starting control of a new trajectory.

set_reference(references)

Function used to change the Reference objects specified during instantiation.

setup(setup_callback)

Function to finalize MPC creation.
reset()

Function called before starting control of a new trajectory. Resets the MPC state, and the reference object.

set_reference(references)

Function used to change the Reference objects specified during instantiation. Note that only existing references can be updated using this function.

Parameters
referencesdict

Dictionary of reference name as keys and Reference object as values.

setup(setup_callback)

Function to finalize MPC creation. Must be called prior to use of the MPC for getting control inputs. Note that the objective must be set by the user. Other MPC options such as constraints and optimization horizon can also be configured here through the setup_callback argument.

Parameters
setup_callbackcallable

Function for user to finalize the MPC configuration. Takes as argument the MPC object, and returns the modified mpc object. Note that set_objective must be called by user on the mpc object.