What is PINS

PINS is the acronym for PINS Is Not a Solver and is a collection of libraries and programs mainly developed to symbolically formulate and numerically solve Optimal Control Problems (OCPs).

Indeed, PINS allows users to formulate other engineering problems in addition to OCPs such as forward numerical integration of dynamical systems and steady and stability analysis among others.

Once the problem is properly defined, the toolkit automatically generates the symbolic equations, the related|CPP| code and the auxiliary files to compile and simulate the dynamical system and/or solve the desired problem.

Additionally, PINS allows expert users to customise and extend the code in many ways, such as modifying/extending the C++ code, link to custom C functions, C++ classes or extending/modifying the embedded ruby scripts or use the genereted code in their own application (e.g. Non Linear Model Predictive Control applications).

PINS is made of three main parts:

  • XOptima, which is a Maple package that formulates and generates the C++ code both for Optimal Control Problems (OCPs) using an indirect variational method and for steady state analysis and forward integration of ODE-DAE dynamical systems (DS). The generated C++ code can be compiled as stand alone program or as a callable library ready to be used in custom code for different purposes (including real time applications).

  • Mechatronix, which is a collection of C++ libraries of classes that includes Non Linear solvers, Boundary Value Problem Solvers, ODE-DAE solvers, and utility classes such as vehicle components (e.g. tyre models, etc), 2D-3D road model, splines and Mruby and Lua interfaces (Matlab/Simulink is foreseen).

  • pins, which is a command line program that provides numerous utility functions, and also allows to control the building (i.e. compilation/linking) solution of an OCP or DS problem via scripts, even in an interactive way. This is implemented using the embedded Ruby language.

XOptima was mainly designed to formulate Optimal Control Problems with Pontryagin Maximum (Minimum) Principle and numerically solve it exploiting the special structure of the resulting Boundary Value Problem.

XOptima fully makes the most of the advantages of symbolic modelling of dynamical systems and automatic optimised C++ code generation including the necessary symbolic Jacobians. These features, along with a robust and fast NonLinear System Solver, custom designed penalty functions, let users quickly formulate and efficiently solve complex Optimal Control Problems (including real time applications).

Indeed the Mechatronix relies on Maple for the problem formulation via the XOptima package but the compiled problem is independent from Maple. The user might still use the C++ libraries and PINS without Maple but it will loose the benefit of the automatic problem setup and code generation. Consequently the user still has to provide the symbolic equations and their jacobians coded in C++.

The pins command is a multi-language interpreter used for dealing with - C++ code generated by the XOptima module in Maple. The main language provided by PINS is Ruby, although the interpreter itself is MRuby, which is an embedded, simplified, and faster version of it. The syntax is compatible to Ruby 1.9, although the interpreter has some notable difference, including the lack of support for Ruby gems (libraries).

The powerful mechanism of PINS is enabled by the fact that the dynamic library generated by XOptima also includes C entry points that allow the MRuby interpreter to dynamically load the compiled library at runtime (via dlopen). This works regardless of the platform.

Note though that, if the Ruby scripts are portable amongst different platforms, the compiled dynamic libraries are not, and you will need to recompile the source code for each platform. The code generated by Maple and XOptima, though, can be moved to a different platform and recompiled without editing.

The pins command also embeds a Lua interpreter. This allows the user to also write data files in Lua, although that interpreter currently does not offer the same functionalities as the Ruby one.

Problems solvable with PINS

In a nutshell, PINS was designed to solve optimal control problems and the analysis of dynamical systems. Here only a short description of the main features is given. A deeper insight on the specific topics can be found in the next chapters.

The family of OC problems is very abstract but is applied since the Sixties. Well known fields of those computational methods are automotive, chemistry, aeronautics and space, financial/portfolio optimization, just to itemize some.

Recently it has been applied to biotechnology in the study of gene mutation. There are three ways to approach an OCP, the direct method, in which the OCP is first discretised and then optimised, the indirect method, where the philosophy is to first optimise and then discretise, the method of dynamic programming (DPP). The direct methods make use of NonLinear Programming (NLP), the direct methods take advantage of the calculus of variations and the theorem of Pontryagin, the DPP methods are based on Bellman’s theory and on the iterative dynamic programming, see Figure:

../_images/diagramma_indirect.png

The main subdivision of numerical methods for optimal control problems.

PINS and in particular XOptima are based on an indirect method, therefore the final problem to solve is a (multipoint) Boundary Value Problem (BVP).

The working flow

In the next chapter, a walk through for the set up of both OCPs and DSs is provided, here the abstract working flow is given. The idea behind PINS is to exploit the power of a symbolic engine, a computer algebra system (CAS for short) to specify the equations of the problem and to perform the necessary exact symbolic manipulations.

The CAS adopted by PINS is Maple. It is used by XOptima as an example, this happens when solving an OCP. The user has to provide the functional and the dynamic system with the various constraints, then XOptima computes (exactly when possible, otherwise numerically) the optimal control law, generates the equations of the costate (adjoint variables), computes the derivatives of the necessary functions. The importance of having the derivatives is clear when looking at the numerical solution of the problem, the higher is the information provided to the nonlinear solver, the better is the convergence, at least in theory. In this phase is also possible for the user to specify external custom function: in XOptima there will be only the instantiation, the implementation is supplied by the user in an external C++ file.

After the complete definition of the problem, XOptima generates an optimised C++ code that will be linked with the C++ library Mechatronix that provides the BVP Solvers and auxiliary classes (e.g. 2D-3D road class, Spline classes, etc.).

At this point, the generated the C++ code needs to be compiled and run, although this can be done by the user, with a bit of knowledge, the task is accomplished by pins, the interpreter. It is a Ruby-based interface for all these little (repetitive) operations. It allows also the post processing of the results (which are stored in a text file) and other automatised instructions.

It is interesting to notice that the numeric data of the problem constraint, like initial/final conditions, tolerances on the penalty functions, the activation or deactivation of parameters are stored in an editable text file, which allows the user to modify his problem without regenerating the whole project in XOptima and even without recompiling the C++ code. It suffices to just rerun pins.

Other features are the possibility to interface the optimised C++ code with other software, for example run a PINS project from Matlab via a mex file.