Tim Mitchell

GRANSO: GRadient-based Algorithm for Non-Smooth Optimization

GRANSO is an optimization package implemented in MATLAB, intended to be efficient for constrained nonsmooth optimization problems, without any special structure or assumptions imposed on the objective or constraint functions. It can handle problems involving functions that are any or all of the following: smooth or nonsmooth, convex or nonconvex, and locally Lipschitz or non-locally Lipschitz. For details on the algorithm underlying GRANSO and citing, see the paper mentioned below.

For a native Python port of GRANSO v1.6.4 also incorporating automatic differentiation, GPU acceleration, tensor variables, and new QP solvers, see PyGRANSO.

How to install GRANSO

1. Download the latest version of GRANSO on GitLab (v1.6.5).
2. The user must have a quadratic program (QP) solver that is callable via The MathWorks quadprog interface (such as quadprog.m from MATLAB's Optimization Toolbox or MOSEK). GRANSO's performance is dependent upon the performance of the available quadprog solver. The user is expected to ensure that it is working correctly.
3. The only installation task is to add the desired location of the extracted GRANSO folder to the search path in MATLAB.
4. To read the GRANSO documentation, enter: help granso
help gransoOptions
help gransoOptionsAdvanced
5. Tutorial demos are included in the examples folder of the GRANSO installation directory. It is highly recommended to both run and read through these codes.

Using GRANSO

• GRANSO's convention is that:
  • the objective function is to be minimized
  • the inequality constraint functions must be less than or equal to zero to be satisfied
  • the equality constraint functions must be equal to zero to be satisfied.

• GRANSO only requires that gradients are provided for the objective and constraint functions, even when these functions may have nondifferentiable points. Gradients should always be numerically assessed with a finite difference utility, such as gradCheck, to ensure that they are correct.
• GRANSO should be initialized at points where the objective and constraint functions are differentiable. If this is difficult to assess, in the absence of other information, it is recommended to initialize GRANSO from randomly generated points (which GRANSO will do automatically if no initial point is provided by the user).

Release History

• Version 1.6.5: minor bug fi for opts.bfgs_damping = 0
• Version 1.6.4: improved line search termination; see opts.step_tol and changelog
• Version 1.6.3: minor bug fix for opts.rel_tol being ignored
• Version 1.6.2: minor bug fix for is_descent not assigned
• Version 1.6.1: minor bug fix for prescaling with unconstrained problems
• Version 1.6: several minor enhancements and fixes
• Version 1.5.2: Minor bug fix for custom halting feature (via opts.halt_log_fn)
• Version 1.5.1: Minor bug fix for regularization feature
• Version 1.5: Improvements for large-scale use and examples/tutorials added
• Version 1.0: Initial public release

Citing

If you publish work that either refers to or makes use of GRANSO, please cite the following paper:

• A BFGS-SQP Method for Nonsmooth, Nonconvex, Constrained Optimization and its Evaluation using Relative Minimization Profiles
  Frank E. Curtis, Tim Mitchell, and Michael L. Overton
  Optimization Methods and Software, 32(1):148–181, 2017.

When referring to this software, please also include which version was used, e.g. GRANSO v1.6.5. Note that granso, in lowercase monospaced font, refers to the routine, not the name of the software package.

License

GRANSO is licensed under the GNU Affero General Public License, version 3.

GRANSO contains two subroutines that are licensed under the GNU General Public License, version 3. These subroutines, which are identified by their GPL v3 license headers, are modified code derived from the HANSO optimization package.