csnlp.wrappers#

A module to provide wrappers to enhance the NLP class’s capabilities.

Motivation#

The standard class csnlp.Nlp provides a way to solve NLP problems; however, it lacks many features that are useful in practice in different fields. For instance, it does not provide a way to scale the problem, in cases where the primal variables have widely different orders of magnitude and convergence is difficult to numerically guarantee. It also does not provide a way to compute the sensitivity of the solution with respect to the problem’s parameters, which is useful in differentiating throught the optimization problems.

To address this, inspired by the approach adopted by the gymnasium package, we provide a way to wrap instances of the basic csnlp.Nlp class with wrapper classes that can add desired features.

Overview#

The basic idea is to create a base class csnlp.wrappers.Wrapper that can be subclassed to implement the desired features. The base class provides the same interface as csnlp.Nlp, so that the user can interact with the wrapped instance in the same way as with the basic NLP instance. We also provide a csnlp.wrappers.NonRetroactiveWrapper, which is a special wrapper that can only wrap instances of csnlp.Nlp before any variable, parameters, etc. is defined.

The following wrappers are provided in this module:

  • csnlp.wrappers.NlpScaling: a wrapper that scales the NLP parameters, variables and expressions automatically (csnlp.scaling provides also classes to inform this wrapper on how to scale the quantities)

  • csnlp.wrappers.NlpSensitivity: a wrapper that computes the sensitivity of the NLP solution with respect to the parameters [4]

  • csnlp.wrappers.Mpc: a wrapper that facilities the creation of MPC optimization problems [6]

  • csnlp.wrappers.ScenarioBasedMpc: a wrapper that facilities the creation of MPC controllers based on the Scenario Approach [7]

  • csnlp.wrappers.MultiScenarioMpc: a wrapper that generalizes the above one to handle MPC controllers that handle multiple dynamics scenarios at once

  • csnlp.wrappers.PwaMpc: a wrapper that facilities the creation of MPC controllers for piecewise affine (PWA) systems [3].

Classes

Mpc(nlp, prediction_horizon[, ...])

A wrapper to easily turn an NLP scheme into an MPC controller.

MultiScenarioMpc(nlp, n_scenarios, ...[, ...])

Multi-scenario model predictive control (MSMPC) wrapper for a csnlp.Nlp scheme.

NlpScaling(nlp, scaler[, warns])

Wraps an instance of csnlp.Nlp to facilitate the scaling of its parameters and/or variables as well as the automatic scaling of expressions (e.g., objective and constraints).

NlpSensitivity(nlp[, target_parameters, ...])

Wraps an instance of csnlp.Nlp to allow to perform symbolical and numerical sensitivity analysis and compute its derivates w.r.t.

NonRetroactiveWrapper(nlp)

Same as Wrapper, but the wrapped NLP instance must have no variable, parameter or objective specified; in other words, the wrapper must wrap the NLP before it gets defined.

PwaMpc(*args, **kwargs)

MPC controller for piecewise affine (PWA) systems.

PwaRegion(A, B, c, S, T)

Stores the matrices defining the i-th region in a piecewise affine system.

ScenarioBasedMpc(nlp, n_scenarios, ...[, ...])

Implementation of the Scenario-based Model Predictive Control [7], here referred to as SCMPC, a well-known stochastic MPC formulation.

Wrapper(nlp)

Wraps an instance of csnlp.Nlp to allow a modular transformation of its methods.