15. Dumping Problem Formulation and Data

15.1. Why to use the dump tool?

Along with its MATLAB client, FORCESPRO 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:

Important

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.

15.2. How to use the dump tool?

Dumping a problem consist of two steps:

  1. Dumping the problem formulation: once a new solver has been generated, a formulation struct, the codeoptions struct and optionally the outputs struct need to be stored.

  2. Dumping problem data: for each problem instance, the problem params struct needs to be stored. It is possible to store data of multiple problem instances for the same problem formulation.

15.2.1. Dumping the problem formulation

For dumping the problem formulation, the following three steps need to be taken:

  1. Enabling creation of a formulation dump: This is done by using the option

    codeoptions.dump_formulation = 1;
    
  2. Obtaining the dumped formulation: Calling FORCES_NLP with the before-mentioned code option enabled will make it return a formulation struct as third output argument

    [stages, codeoptions, formulation] = FORCES_NLP( model, codeoptions, outputs );
    
  3. Storing the necessary structs into a file: After calling FORCES_NLP, you should use the following function to store both the formulation and codeoptions struct

    tag = ForcesDumpFormulation( formulation,codeoptions,outputs );
    

The third argument outputs is optional. The function ForcesDumpFormulation 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 _F, e.g. myFORCESsolver_ABC3DEFGHIJ_20200101120000000_F.mat.

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.

15.2.2. Dumping problem data

Assuming your generated FORCESPRO 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 unique tag that has been generated when dumping the problem formulation. The function 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 _P, e.g. myFORCESsolver_ABC3DEFGHIJ_20200101120001000_P.mat.

You may dump as many problem instances as you have disk space available.

15.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_20200101120000000_F.mat and myFORCESsolver_ABC3DEFGHIJ_20200101120001000_P.mat at a location in your MATLAB path):

  1. Re-generate the FORCESPRO solver by loading the formulation mat file 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 outputs is only available if you included it into your dump.

  2. Running the solver with dumped problem data by loading the data mat file 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.

15.3. Limitations

Currently, the dump tool has the following limitations:

  • It is only provided for the MATLAB client of FORCESPRO.

  • It cannot be used if you pass external functions in form of C code.

We aim at overcoming these limitations in a future release.