-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathREADME.txt
185 lines (134 loc) · 7.71 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% README for supplemental code associated with the following manuscript:
%
% "Advantages of Bilinear Koopman Realizations for the Modeling and Control of
% Systems with Unknown Dynamics", by Daniel Bruder, Xun Fu, and Ram Vasudevan
%
% Preprint: https://arxiv.org/pdf/2010.09961.pdf
%
% All code written using Matlab 2019a
%
% Author: Daniel Bruder (bruderd@umich.edu, dbruder@seas.harvard.edu)
% Last updated: 2020-11-20
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%% Overview of Project %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
This code can be used to generate models and controllers from data.
It was used to construct linear, bilinear, and nonlinear Koopman model
realizations for a simulated planar 3-link arm system.
The data used to train these models 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:
Classes:
-Arm
Properties: - Parameters associated with simulated planar arm system, e.g.
number of links, mass of links, joint stiffness, etc.
Methods: - Functions for defining equations of motion of system,
functions for simulating system, functions for sensing state
of the system, and functions for animating the system.
-Ksysid
Properties: - Parameters associated with data used for training a model,
e.g. dimension of input, dimension of output, timestep, etc.
Methods: - Contains all functions associated with constructing Koopman
realizations from data.
-Kmpc (constructed from user inputs and instance of Ksysid class)
Properties: - Parameters associated with MPC controller such as length of
planning horizon, input bounds, state bounds, etc.
Methods: - Contains functions for constructing MPC problem matrices
and solving MPC optimization problem.
-Ksim (constructed from instances of Kmpc and Arm classes)
Properties: - Inherited parameters from the Kmpc and Arm class
instances it is constructed from.
Methods: - Function that runs a simulated MPC controller trial.
-Data
Properties: - None
Methods: - Various functions for manipulating data, e.g. chopping
single time-series into multiple trials, merging
multiple time-series into single trial, or converting raw
data into format suitable for the Ksysid class.
Folders:
-dataFiles - Contains data used for training models.
-trajectories - Contains the reference trajectories used in the experiments
from the paper, as well as scripts for generating new
reference trajectories.
-systems - Where instances of system classes (e.g. Arm classes)
can be stored, along with Koopman model realizations
(i.e. instances of Ksysid classes) associated with those
system class instances.
Examples:
-example_sysid.m - Trains linear, bilinear, and nonlinear Koopman model from
data.
-example_control.m- Constructs a linear , bilinear, and nonlinear MPC controller
based on Koopman realizations and simulates controller
performance in a trajectory following task.
Additional Files:
-Ksysid_setup.m - Builds a linear/bilinear/nonlinear Koopman model from data
by constructing an instance of the Ksysid class.
-Kmpc_setup.m - Builds a linear/bilinear/nonlinear MPC controller from a
Koopman model by constructing an instacne of the Kmpc class.
-quadprog_gurobi.m- Needed to solve optimization problems using the Gurobi
Gurobi software (optional).
-partitions.m - Support function for creating sets of polynomial basis
functions.
-auto_remane.m - Helps avoid overwriting old files when saving by appending
numbers to file names.
%%%%%%%%%%%%%%% 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 16-24:
Name: Value:
'model_type' 'linear' , 'bilinear' , 'nonlinear'
'time_type' 'discrete' , 'continuous'
'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,...
'loaded' true , false
'dim_red' true , false
Note that 'lasso' is an L1 regularization term. As implemented, the least-square
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 planar arm data from the paper is
included, called 'arm-3link-markers-noload-50trials_train-10_val-5.mat'.
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_sysid.m
-example_control.m
example_sysid.m will train a linear, bilinear, and nonlinear Koopman model from
the included 'arm-3link-markers-noload-50trials_train-10_val-5.mat' data file,
then generate a plot showing the predictions generated by each model compared to
a single validation trial. You can change the parameters of the model(s)
generated by modifying the Name/Value arguments into Ksysid each time it is
called.
example_control.m will construct a linear, bilinear, and nonlinear MPC
controller based on included model realizations. It will simulate the a
trajectory following task using each controller and plot the results. You can
change the parameters of the MPC controllers by modifying the Name/Value
arguments into Kmpc each time it is called.
%%%%%%%%%%%%%%%%%%%%%%%%%%%% Known Issues %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Issue #1 (2021-05-26): u is actually joint reference angle not joint torques
Input 'u' into Arm system is not joint torques, as described in the
accompanying paper. It is actually joint reference angles with the joint
torques defined as follows: joint_torques = ku * ( u - alpha ),
where ku is a stiffness constant and alpha is the actual joint angles.