Package: trustregion
This package provides Python routines for solving the trust-region subproblem from nonlinear, nonconvex optimization. For more details on trust-region methods, see the book: A. R. Conn, N. I. M. Gould and Ph. L. Toint (2000), Trust-Region Methods, MPS-SIAM Series on Optimization.The trust-region subproblem we solve ismin_{s in R^n}  g^T s + 0.5 s^T H s, subject to ||s||_2 <= delta (and sl <= s <= su)Quick install$sudoapt-getinstallgfortran$pipinstall--usernumpy$pipinstall--usertrustregionFor more details, see below. Note that NumPy must be installed first, as it is used to compile the Fortran-linked modules.InterfaceThe Python packagetrustregionprovides one routine,solve, with interface:importtrustregions=trustregion.solve(g,H,delta,sl=None,su=None,verbose_output=False)s,gnew,crvmin=trustregion.solve(g,H,delta,sl=None,su=None,verbose_output=True)where the inputs areg, the gradient of the objective (as a 1D NumPy array)H, the symmetric Hessian matrix of the objective (as a 2D square NumPy array) - this can beNoneif the model is lineardelta, the trust-region radius (non-negative float)sl, the lower bounds on the step (as a 1D NumPy array) - this can beNoneif not present, butslandsumust either be bothNoneor both setsu, the upper bounds on the step (as a 1D NumPy array) - this can beNoneif not present, butslandsumust either be bothNoneor both setverbose_output, a flag indicating which outputs to return.The outputs are:s, an approximate minimizer of the subproblem (as a 1D NumPy array)gnew, the gradient of the objective at the solutions(i.e.gnew = g + H.dot(s))crvmin, a float giving information about the curvature of the problem. Ifsis on the trust-region boundary (given bydelta), thencrvmin=0. Ifsis constrained in all directions by the box constraints, thencrvmin=-1. Otherwise,crvmin>0is the smallest curvature seen in the Hessian.Example UsageExamples for the use oftrustregion.solvecan be found in theexamplesdirectory on Github.Algorithmstrustregionimplements three different methods for solving the subproblem, based on the problem class (in Fortran 90, wrapped to Python):trslin.f90solves the linear objective case (whereH=NoneorH=0), using Algorithm B.1 from: L. Roberts (2019),Derivative-Free Algorithms for Nonlinear Optimisation Problems, PhD Thesis, University of Oxford.trsapp.f90solves the quadratic case without box constraints. It is a minor modification of the routine of the same name inNEWUOA[M. J. D. Powell (2004),The NEWUOA software for unconstrained optimization without derivatives, technical report DAMTP 2004/NA05, University of Cambridge].trsbox.f90solves the quadratic case with box constraints. It is a minor modification of the routine of the same name inBOBYQA[M. J. D. Powell (2009),The BOBYQA algorithm for bound constrained optimization without derivatives, technical report DAMTP 2009/NA06, University of Cambridge].In the linear case, an active-set method is used to solve the resulting convex problem. In the quadratic cases, a modification of the Steihaug-Toint/conjugate gradient method is used. For more details, see the relevant references above.Requirementstrustregionrequires the following software to be installed:Fortran compiler (e.g. gfortran)Python 2.7 or Python 3 (http://www.python.org/)Additionally, the following python packages should be installed (these will be installed automatically if usingpip, seeInstallation using pip):NumPy 1.11 or higher (http://www.numpy.org/)Installation using pipFor easy installation, usepipas root:$[sudo]pipinstallnumpy$[sudo]pipinstalltrustregionNote that NumPy should be installed beforetrustregion, as it is used to compile the Fortran modules.If you do not have root privileges or you want to installtrustregionfor your private use, you can use:$pipinstall--usernumpy$pipinstall--usertrustregionwhich will installtrustregionin your home directory.Note that if an older install oftrustregionis present on your system you can use:$[sudo]pipinstall--upgradetrustregionto upgradetrustregionto the latest version.Manual installationAlternatively, you can download the source code fromGithuband unpack as follows:$gitclonehttps://github.com/lindonroberts/trust-region$cdtrust-regionTo upgradetrustregionto the latest version, navigate to the top-level directory (i.e. the one containingsetup.py) and rerun the installation usingpip, as above:$gitpull$[sudo]pipinstall.# with admin privilegesTestingIf you installedtrustregionmanually, you can test your installation by running:$pythonsetup.pytestAlternatively, the documentation provides some simple examples of how to runtrustregion.UninstallationIftrustregionwas installed usingpipyou can uninstall as follows:$[sudo]pipuninstalltrustregionIftrustregionwas installed manually you have to remove the installed files by hand (located in your python site-packages directory).BugsPlease report any bugs using GitHub’s issue tracker.LicenseThis algorithm is released under the GNU GPL license.