Data files for:
Performance Bounds and Suboptimal Policies for Multi-Period Investment
by Stephen Boyd, Mark T. Mueller, Brendan O'Donoghue, Yang Wang

REQUIREMENTS
-----------------------------------------------------------------------------
To run the code you will need:

- MATLAB (version 6.5 or later)
- CVX:      A MATLAB toolbox for convex optimization (for solving the SDPs).
            Available at: http://cvxr.com/cvx/
- CVXGEN:   Used to generate the QP solvers for trading policy implementation.
            You won't need to install this. The required code for implementing
            the policy has already been generated, and is included in this
            package. If you'd like to try out code generation yourself you 
            can request a license at: http://cvxgen.com/
- MEMORY:   The SDPs that need to be solved for the approximate value functions
            are quite large, machines with less than 8GB of RAM may run out of 
            memory.
            For those without sufficient memory we have included the data.mat
            file which contains the output of the solve_sdp.m files.
-----------------------------------------------------------------------------

FILES
-----------------------------------------------------------------------------
top level directory:

    - README: this file
    - clean: script to clean subdirectories of data / mex files
    - data_gen.m: generates problem data using method described in paper
	- run_all.m: cleans directories, then runs all examples with both ADP and
	  MPC policies
	- leverage_limit/: files for leverage limit example
    - long_only/: files for long-only example
    - quadratic/: files for quadratic example
    - sector_neutral/: files for sector_neutral example
    - unconstrained/: files for unconstrained example

subdirectories 'leverage_limit', 'long_only', 'sector_neutral', 'unconstrained', 
'quadratic' each contain:

	- ADP/: subdirectory containing files related to the ADP policy
	- MPC/: subdirectory containing files related to the MPC policy
	- run.m: runs entire example

	subsubdirectory 'MPC' contains:

		- cvxgen/: subdirectory containing C source for policy implementation
    	- make_solver.m: makes the cvxgen solver
    	- run_mpc.m: runs monte-carlo to estimate performance of MPC policy

	subsubdirectory 'ADP' in 'leverage_limit', 'long_only', 'sector_neutral', 'unconstrained' contains:

    	- cvxgen/: subdirectory containing C source for policy implementation
    	- cvxgen_prob: cvxgen problem description used to generate solver
    	- data.mat: contains coefficients for pre-computed approx. value functions
    	- gen_plots.m: generates plots
    	- make_solver.m: makes the cvxgen solver
    	- run_montecarlo.m: runs monte-carlo to estimate performance of ADP policy
    	- run_perturbations.m: runs robustness analysis
    	- run_sims.m: runs only monte-carlo and perturbation simulations
    	- solve_sdp.m: solves sdp to find approximate value functions and bound

	subsubdirectory 'ADP' in 'quadratic' contains:
    
		- data.mat: contains coefficients for pre-computed value functions
    	- gen_plots.m: generates plots
    	- quadratic_bell_rec.m: runs bellman recursion to find value functions
    	- run_montecarlo.m: runs monte-carlo to verify optimal cost
    	- run_perturbations.m: runs robustness analysis
    	- run_sims.m: runs only monte-carlo and perturbation simulations
-----------------------------------------------------------------------------

RUNNING THE CODE
-----------------------------------------------------------------------------
there are several ways to run the example code.

to run the code for all examples, open MATLAB in the top level directory and 
at the command prompt type

>> run_all

this will run all the examples and generate data files and plots in the 
subdirectories corresponding to each example. depending on your system, this 
may take around 15-20 hours in total, to compute the value functions and run
monte-carlo analysis for both ADP and MPC policies.

alternatively, you can run each example separately, cd into the subdirectory
corresponding to the example, open MATLAB and at the command prompt type

>> run

this will run both the MPC and ADP policies by calling
run_adp.m and run_mpc.m in the respective subdirectories

alternatively the ADP and MPC policies can be evaluated separately, open
MATLAB, cd into the relevant subdirectory and at the prompt type

>> run_mpc

or

>> run_adp

in the ADP case this will compute the approximate value functions (calling
solve_sdp.m or quadratic_bell_rec.m in the quadratic case), run monte-carlo
simulations to estimate policy performance (calling run_montecarlo.m), run
perturbation analysis (calling run_perturbations.m), and finally generate plots
(gen_plots.m). depending on your system, each example will take 3-5 hours to
run.

instead of running the whole example for the ADP policy, you can run only the
monte carlo and perturbation simulations. this skips solving the SDP, and loads
the coefficients of the approximate value functions (and other relevant problem
data), directly from the data file data.mat. cd into the subdirectory
corresponding to the example, open MATLAB, cd into the ADP subdirectory and at
the command prompt type

>> run_sims

finally, you can run each .m file separately. the first time you run the ADP
policy in this way you must do it in the order in run_adp.m. 
-----------------------------------------------------------------------------

OUTPUT
-----------------------------------------------------------------------------
after an example has been run, several data files CVXGEN solver files will be 
produced in each subdirectory. you will find

in 'ADP' subdirectories:
    - csolve.mexXXX: CVXGEN solver mex file (XXX depends on your architecture)
    - csolve.m: CVXGEN solver info file
    - bump_data.mat: contains results of perturbation analysis
    - data.mat: contains coefficients of approximate value functions
    - MC_data.mat: contains results of monte-carlo simulations
    - traces.eps: plots of sample trajectories
	- hist.eps: histogram of MC simulations total net costs

in 'MPC' subdirectories:
	- csolve.mexXXX: CVXGEN solver mex file (XXX depends on your architecture)
    - csolve.m: CVXGEN solver info file
    - MPC_data.mat: contains results of monte-carlo simulations

-----------------------------------------------------------------------------

