13. Dumping Problem Formulation and Data¶
13.1. Why to use the dump tool?¶
Along with its MATLAB client, FORCES PRO provides a tool that allows the user
to dump the formulation and actual data of an optimization problem. This
information allows to exactly reproduce the same solver for a given
formulation and to feed it with exactly the same data to yield exactly the
same results (provided it is run on the very same target hardware).
Problem formulation and data stored in “stand-alone”
mat files, i.e. there is
no need to keep copies of other files that may be used to specify the
formulation (such as the dynamic equations).
The dump tool may be helpful for a couple of use cases such as:
Debugging: a dumped problem allows you to re-run single solver calls without the need to have your full simulation environment up and running.
External support: you may send a dumped problem to whomever is in charge of providing support and it will enable that person to exactly reproduce your issue.
Testing: keeping dumps of problems that performed as expected can be used to run regression tests to ensure they work as expected after future changes.
Note that the dump tool does not merely save your MATLAB structs into a file. Those structs may contain MATLAB function handles referencing external functions. Instead, the dumped formulation already contains C code generated by the automatic differentiation tool. Thus, keep the following in mind:
A dumped problem will contain complete information about the solver that you have setup. In particular, it may be used to reverse-engineer your problem formulation (including dynamic model, objective function, constraints etc.). Thus, only share a dumped problem with persons that have a right to obtain this information.
13.2. How to use the dump tool?¶
Dumping a problem consist of two steps:
Dumping the problem formulation: once a new solver has been generated, a
codeoptionsstruct and optionally the
outputsstruct need to be stored.
Dumping problem data: for each problem instance, the problem
paramsstruct needs to be stored. It is possible to store data of multiple problem instances for the same problem formulation.
13.2.1. Dumping the problem formulation¶
For dumping the problem formulation, the following three steps need to be taken:
Enabling creation of a formulation dump: This is done by using the option
codeoptions.dump_formulation = 1;
Obtaining the dumped formulation: Calling
FORCES_NLPwith the before-mentioned code option enabled will make it return a
formulationstruct as third output argument
[stages, codeoptions, formulation] = FORCES_NLP( model, codeoptions, outputs );
Storing the necessary structs into a file: After calling
FORCES_NLP, you should use the following function to store both the
tag = ForcesDumpFormulation( formulation,codeoptions,outputs );
The third argument
outputs is optional. The function
will create a
mat file in the directory from where it is called containing the
passed information. The filename is automatically chosen and will contain the
name of your solver, a unique tag, a timestamp as well as the suffix
Note that this function returns a
tag that is unique for a given formulation
and code options. It is strongly recommended to use it when also dumping
corresponding problem data.
13.2.2. Dumping problem data¶
Assuming your generated FORCES PRO solver is called
myFORCESsolver and you
are calling it with the following command
[output, exitflag, info] = myFORCESsolver( problem );
then dumping the problem data of any problem instance is as simple as calling
ForcesDumpProblem( problem,tag );
Here, you need to provide both the problem parameter struct as well as the
tag that has been generated when dumping the problem formulation.
ForcesDumpProblem will create a
mat file in the directory
from where it is called containing the passed information. The filename is
automatically chosen and will contain the name of your solver, a unique tag,
a timestamp as well as the suffix
You may dump as many problem instances as you have disk space available.
13.2.3. Running a dumped problem¶
After you have dumped a problem formulation and at least one set of problem data,
you can use those
mat files to exactly reproduce your solver and problem
instances. To do so, you need to perform the following two steps
(where we assume you have stored the two files
myFORCESsolver_ABC3DEFGHIJ_20200101120001000_P.mat at a location in
your MATLAB path):
Re-generate the FORCES PRO solver by loading the formulation
matfile and using its content to call the code generation:
F = load('myFORCESsolver_ABC3DEFGHIJ_20200101120000000_F.mat'); FORCES_NLP( F.formulation,F.codeoptions,F.outputs );
This will re-create the solver MEX function
myFORCESsolver. Note that the third input struct containing the
outputsis only available if you included it into your dump.
Running the solver with dumped problem data by loading the data
matfile and using its content to call the generated solver:
P = load('myFORCESsolver_ABC3DEFGHIJ_20200101120001000_P.mat'); myFORCESsolver( P.problem );
You may repeat this step for as many problem instances as you have dumped.
Currently, the dump tool has the following limitations:
It is only provided for the MATLAB client of FORCES PRO.
It cannot be used if you pass external functions in form of C code.
We aim at overcoming these limitations in a future release.