% = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = %
%                                                                     %
%                          ACGM Starter Kit                           %
%                                                                     %
% = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = %

Starter code for solving composite optimization problems using
the Accelerated Composite Gradient Method (ACGM). ACGM is a
state-of-the-art first-order scheme applicable to the entire class
of large-scale composite problems.

ACGM was introduced in the following papers:

[FV19] M. I. Florea and S. A. Vorobyov, "An accelerated composite
       gradient method for large-scale composite objective problems,"
       IEEE Trans. Signal Process., vol. 67, pp. 444–459, 2019.

[FV20] M. I. Florea and S. A. Vorobyov,
       "A generalized accelerated composite gradient method:
       Uniting Nesterov's fast gradient method and FISTA,"
       IEEE Trans. Signal Process., vol. 68, pp. 3033-3048, 2020.

Required software:

The code was designed to run on MathWorks MATLAB 8 (R2012b) or later.
The code also runs successfully using GNU Octave 4.2.2 or later,
with the notable exception of the abstract methods in "Problem.m".
These have been commented out to retain compatibility.

Setup:

Unpack the contents to a local directory and set the current folder
in MATLAB or Octave to that directory.

Package contents and usage:

[README.txt]

This documentation file.

[ACGM_demo.m]

The main script file. Contains the following sections:
(1) Optimization problem setup
(2) ACGM parameter setup
(3) ACGM implementation
(4) FISTA implementation (for comparison)
(5) Result display
To run, type "ACGM_demo" in the command window.

This script will to be edited according to your application.
The comments will guide you in the editing process.

[Problem.m]

Base class modeling a composite optimization problem.
This class is inherited by the sample class Problem_L1LR.
You may replace Problem_L1LR with your own custom class, but
the ACGM implementation will only function as long as your custom
class inherits this class and implements the abstract method
oracle functions listed in "Problem.m".

Modifying "Problem.m", except for uncommenting the abstract
methods section, may cause "ACGM_demo.m" to malfunction.

[Problem_L1LR.m]

Sample composite optimization problem class. This class replicates
the simulations involving the l1-regularized logistic regression (L1LR)
experiments presented in [FV20]. This file serves as a starting point
in designing your own class as required by your application.

All properties are optional but your class must implement all the
methods listed in "Problem_L1LR.m", which override the abstract methods
in "Problem.m".

[L1LR.dat]

MATLAB data file containing the structure "data". The fields of the
"data" structure represent a particular instance of the L1LR problem
presented in [FV20].

This file is included for demonstration purposes only.

Support:

Please feel free to send any bug reports, comments, and suggestions to

Mihai I. Florea
mihai.florea@aalto.fi

Disclaimer:

There is ABSOLUTELY NO WARRANTY; not even for MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.
