%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% README for supplemental code associated with the following manuscript:
% "Data-Driven Control of Soft Robots Using Koopman Operator Theory", by
% Daniel Bruder, Xun Fu, R. Brent Gillespie, C. David Remy, and Ram Vasudevan.
%
% All code written using Matlab 2019a
%
% Author: Daniel Bruder (bruderd@umich.edu)
% Last updated: 2019-11-25
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%



%%%%%%%%%%%%%%%%%%%%%%%%%%% Overview of Project %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

This code was used to generate models and controllers for a soft robot from
data. This data is included, and example scripts are provided for recreating
these models and controllers on your machine.

This code can also be used to generate models and controllers for other systems
based on your own data.

Below are the names and descriptions of some of the included contents:

Folders:
-dataFiles        - Contains data used for training models.
-ref-trajectories - Contains the reference trajectories used in the experiments
                    from the paper.
-systems          - Where saved models can be stored

Files:
-example_KMPC.m   - Trains linear Koopman model from data, builds an MPC
                    controller, and runs a simulation of the controller.
-example_KNMPC.m  - Trains a nonliner Koopman model from data, builds an NMPC
                    controller, computes open-loop inputs and runs a simulation.
-ksysid_setup.m   - Builds a linear/nonlinear Koopman model from data.
-kmpc_setup.m     - Builds a linear MPC controller from a Koopman model
-ksysid.m         - Class containing all functions related to sysid
-kmpc.m           - Class containing all functions related to linear MPC




%%%%%%%%%%%%%%% How to construct a Koopman model from data %%%%%%%%%%%%%%%%%%%%%

Step 0:-------------------------------------------------------------------------
Before running 'ksysid_setup.m' you can customize the model by changing the
Name-Value pair input arguments into ksysid, found on lines 28-34:

Name:                       Value:
'model_type'                'linear', 'nonlinear'
'obs_type'                  'poly', 'fourier' , 'gaussian' , 'hermite' ,
                            'fourier-sparser'
'obs_degree'                1,2,3,4,...
'snapshots'                 1,2,3,4,..., Inf
'lasso'                     [0 , Inf]
'delays'                    0,1,2,3,4,...

Note that 'lasso' is an L1 regularization term. In the paper, the L1 penalty
term is called \lambda. Based on the way the regularization is implemented,
'lasso' is actually  1 / (\lambda), i.e. the least-squares solution is given for
'lasso' = Inf, not 0.

You can train several models at once for different values of 'lasso' by
setting its value to a vector. For example if I set it to [1 2 3]. It will train
3 separate models with 'lasso' equal to 1, 2, and 3 respectively.

Step 1:-------------------------------------------------------------------------
Run 'ksysid_setup.m'. You will be prompted to choose a datafile from the
'dataFiles' folder. A file containing the soft robot data from the paper is
included, called 'softrobot_train-13_val-4'. Then a model will be generated.

Step 2:-------------------------------------------------------------------------
Comparison plots between the generated model and validation data will be
generated, and a dialog box will appear asking if you would like to save the
model. Answering yes will save the ksysid class as a file in 'systems/fromData',
otherwise it will just exist in the Matlab Workspace.

You can always save you model later by running the following from the command
line:
>> ksysid.save_class()

The model matrices/functions are containted in ksysid.model, for a single model,
or ksysid.candidates if you generated multiple models by setting 'lasso' equal
to a vector in Step 0.




%%%%%%%%%%%%%%%%%%%%%%%%%%%% Running Examples %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Two example files are included:
-example_KMPC.m
-example_KNMPC.m

Each of these files will train a Koopman model, construct a controller, and
simulate the response of that controller in following a reference trajectory.

You can change the parameters of the model generated by modifying the arguments
into ksysid, but do not modify the 'model_type' argument.

Note that to run perform nonlinear MPC in example_KNMPC, GPOPS-II optimal
control software is required. It can be purchased at
http://www.gpops2.com/Purchase/Purchase.html