###########################################################################
                                                                       
 SC_SR1: Shape-changing limited-memory SR1 trust-region algorithms for 
 large-scale optimization problems                                     
                                                                       
                            minimize f(x)                                   
 
 The methods seek a point "norm(grad(x)) = 0", where grad(x) is
 the gradient of the objective f(x).

 johannesbrust@yahoo.com (for correspondence)                                                                       
###########################################################################

 _________________
|                 |
| Getting Started |
|_________________|

Files are organized in 6 folders:

	ALGS/ 		(main algorithms)
	AUXILIARY/ 	(support routines)
	DATA/ 		(data for figures and tables)
	EXPERIMENTS/ 	(examples and experiments)
	EXTERNAL/ 	(third party software)
	FIGS/		(figures)

To try-out two examples navigate inside folder "EXPERIMENTS/".
From within the folder you can run the examples by

	>> example_1

	>> example_2

Similar data like in Tables 1--7 in the manuscript can be generated from
within "EXPERIMENTS/" by running 

	>> driver_EX_tbls_1_to_7

Data of Tables 8 and 9 is generated by running

	>> driver_EX_tbl_8
	>> driver_EX_tbl_9

To rerun any of the 11 experiments from the folders "EX_COMP_FINAL_*" the 
CUTEst (https://github.com/ralna/CUTEst/wiki) test set has to be installed. 
If CUTEst is installed, then the relative path to the CUTEst installation
is to be updated in 

	AUXILIARY/CUTEst_init.m

Without a CUTEst installation, the figures from the manuscript can be plotted 
from within the "AUXILIARY/" folder by calling 
plot_Fig*.m (*=1,2,3,4,5,6,7,8)

Detailed descriptions of the signatures of the algorithms in "ALGS/"
are found in the beginning comments of the respective files and
in the file "Manual.pdf"

 _________________
|                 |
| Installation    |
|_________________|

The sofware has been tested on the computing environments listed at 
the end of this file and runs the examples out-of-the-box, i.e.,
without any needed changes

In general, the main callable functions are in folder "ALGS/", which
depend on "EXTERNAL/". Therefore, typically these folders are added at
the beginning of a program to the search path. For instance, if
the three folders "ALGS/", "EXTERNAL/" and "MY_EXPERIMENTS/" are
in the same directory and a program "MY_EXPERIMENTS/my_scsr1.m" is written 
then the first lines of the file are to ensure that all needed functions are 
on the path, e.g.,

>> addpath(genpath('../ALGS'))
>> addpath(genpath('../EXTERNAL'))

A way to write a new program is to copy one of the example files
and then modify it for one's use case

 _________________
|                 |
| Main function   |
|_________________|

For general smooth unconstrained optimization the main function is 

    %% Inputs (4)
    % x0   (Initial iterate. Can be zeros(n,1) or ones(n,1))
    % func (Objective function, f=func(x))
    % grad (Objective gradient, g=grad(x))
    % pars ([Optional] input struct, can be empty [],{} or
    %       define one of a set of potential values, e.g., pars.print=1)
            
>> [xk1, gk1, fk1, out] = LSR1_SC( x0, func, grad, pars );
            
    % out  (Output struct, e.g., out1.ctime)
    % fk1  (Objective value, fk1=func(xk1))
    % gk1  (Gradient value, gk1=grad(xk1))
    % xk1  (Solution estimate)
    %% Outputs

The initial value x0 can be set to "zeros(n,1)" or "ones(n,1)" if
an appropriate initial iterate is not know. The inputs, "func" and
"grad" are functions and return the objective and gradient values,
i.e., the objective function value at x is "f=func(x)" and the 
gradient at x is "g=grad(x)"

Further callable functions are sc_sr1_infty.m and sc_sr1_2.m,
which are trust-region subproblem solvers to LSR1_SC.m and are described 
in the manual

 _________________
|                 |
| Parameters      |
|_________________|

The struct "pars" enables passing many [optional] parameters to LSR1_SC.
Often it is desirable to print some iteration information, which can
be done by setting "pars.print = 1". All the parameter values have 
defaults, which can be a good combination for initial test runs.
Specific information about the parameters is in the top lines of the 
algorithms and in the manual

The codes have been tested on four different computing environments:

Matlab R2014a, Ubuntu 14.04 LTS, {CUTEst vers. 12, June 2013}
Matlab R2016a, macOS High Sierra, {CUTEst vers. n/a, July 2017}
Matlab R2018b, macOS High Sierra, {CUTEst vers. n/a, July 2017}
Matlab R2022a, macOS Monterey, {CUTEst vers. n/a, July 2017}
	
