# osc

**Repository Path**: fengchuanmayun/osc

## Basic Information

- **Project Name**: osc
- **Description**: C package performing operator splitting for control
- **Primary Language**: C
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-03-22
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

OSC: Operator Splitting for Control
===========================================================
A C package for solving optimal control problems quickly.

based on:  
[A Splitting Method for Optimal Control](http://www.stanford.edu/~boyd/papers/oper_splt_ctrl.html)  
by Brendan O'Donoghue, George Stathopoulos and Stephen Boyd  

===========================================================
Solves:
    
    minimize \sum_{t=0}^T \phi_t(x_t,u_t) + \psi_t(x_t,u_t) 
    subject to  x_{t+1} = A_t x_t + B_t u_t +c_t, t=0, ... , T-1

    over x_t, u_t t = 0, ... , T

where `phi_t` terms are quadratic  
and `psi_t` terms are arbitrary, supplied by the user in the form of a proximal operator

Quickstart:
to compile all the simulations, in this directory type:

    make

then to run a particular (e.g. box) example type:

    cd box
    ./osc.out

or 

    cd box
    ./warm_start.out

osc.out runs the algorithm from a cold-start just once  
warm_start.out performs NUM_WARM warm-start simulations

to remove compiled objects and binaries type  
in oper_splt_code/ directory:

    make clean

==========================================================
the code fore examples presented in the paper are in  
the following directories:

box/ : box constrained quadratic optimal control  
finance/ : multi-period portfolio optimization  
rob_est/ : robust state estimation  
sup_ch/ : supply chain management  

==========================================================
the binaries can take additional arguments, e.g.:

    ./osc.out data_KKT data_prox

the first argument must be the main data file (see below)  
the second argument must be the prox data file  

if no arguments are supplied the binaries use the default  
data files: data_KKT data_prox  

==========================================================
This directory consists of the following files:

    osc.c, osc.h:  
			code to perform cold start OSC  
    cholesky.c, cholesky.h:  
			code required to perform the factorization and  
			solve steps	    
    warm_start.c: 
            code that performs the warm-start sumulations  
    Makefile  
    README

==========================================================
This directory consists of the following subdirectories:

AMD  
LDL  
UFconfig  

These contain routines written by Tim Davis et al., these
are required to factorize the KKT matrix and solve the
linear system.  
NOTE: these directories have been reduced to save space.
You can obtain the full versions [here](http://www.cise.ufl.edu/research/sparse/SuiteSparse/)

box  
finance  
rob_est  
sup_ch  

These are the directories that contain the examples as
described in the paper.

==========================================================
The example subdirectories consist of the following files:

    prox.c, prox.h
			these files describe how the prox step for that
			particular example is carried out
    gen_data.m
			a MATLAB script that generates data for the example
			and solves the instance using both CVX and a MATLAB
			implementation of OSC (for verification purposes)
    data_KKT
			the main data file as generated by gen_data.m
    data_prox
			the data required for the prox step, as generated
			by gen_data.m
    osc.c, warm_start.c
			exact copies of the same files in the oper_splt_code/ directory

additionally the oper_splt_code/box/ directory contains directories

    cvxgen
			contains the cvxgen code, for comparison purposes
    fast_mpc-0.0.1
			contains the fast MPC code, for comparison purposes

==========================================================
main data file : (default name: data_KKT)

The main data file must be in a particular format, see any 
gen_data.m for an example.  This file contains information 
like the problem dimensions, horizon
length etc.  Most importantly the full KKT matrix must be 
supplied in column compressed format.

prox data file (defualt name: data_prox) is problem specific
it should contain all data required to perform the prox step

==========================================================
prox.c and prox.h are problem specific but they must conform
to the following requirements:

* prox.h:
  - contain definition of prox_data struct, used in main file
  - this should contain all fixed data that the prox function
  requires to perform the prox step

* prox.c:
  - functions to read in the prox data into prox_data struct  
  - functions to perform the prox step  
  - functions to perturb the data (for warm-start)  
  - functions to free memory associated with prox data