diff --git a/local_optimization/BXNL/Readme.md b/local_optimization/BXNL/Readme.md index 12e31d7..640ad4d 100644 --- a/local_optimization/BXNL/Readme.md +++ b/local_optimization/BXNL/Readme.md @@ -1,10 +1,13 @@ -[![NAG](https://raw.githubusercontent.com/numericalalgorithmsgroup/NAGPythonExamples/master/nag_logo.png)](https://www.nag.co.uk) +[![NAG Logo](../../nag_logo.png)](https://www.nag.com) # Nonlinear Least-Squares Trust-Region Method (BXNL) +[[`handle_solve_bxnl`](https://www.nag.co.uk/numeric/py/nagdoc_latest/naginterfaces.library.opt.html#naginterfaces.library.opt.handle_solve_bxnl) | [`e04ggf`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04ggf.html) | +[`e04ggc`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/clhtml/e04/e04ggc.html) ] + Data fitting and calibrating parameters of complex numerical models is one of the most common problems found in numerous industries such as physics, space exploration, simulations, engineering, amongs many others. -[NAG](https://www.nag.co.uk/) introduces to the [NAG Library at Mark 27.1](https://www.nag.co.uk/content/nag-library) a novel [nonlinear least-square](https://en.wikipedia.org/wiki/Non-linear_least_squares) [trust-region solver](https://en.wikipedia.org/wiki/Trust_region) for unconstrained or bound-constrained fitting problems, [`handle_solve_bxnl`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/clhtml/e04/e04ggc.html) ([`e04gg`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04ggf.html)). It offers a significant variety of algorithms and regularisation techniques. +[NAG](https://www.nag.co.uk/) introduces to the [NAG Library at Mark 27.1](https://www.nag.co.uk/content/nag-library) a novel [nonlinear least-square](https://en.wikipedia.org/wiki/Non-linear_least_squares) [trust-region solver](https://en.wikipedia.org/wiki/Trust_region) for unconstrained or bound-constrained fitting problems, [`handle_solve_bxnl`](https://www.nag.co.uk/numeric/py/nagdoc_latest/naginterfaces.library.opt.html#naginterfaces.library.opt.handle_solve_bxnl) ([`e04gg`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04ggf.html)). It offers a significant variety of algorithms and regularisation techniques. The solver [`e04gg`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04ggf.html) is aimed at small to medium sized fitting problems (up to 1000s of parameters) bound-constrained nonlinear least-squares problems and is also part of the [NAG Optimization Modelling Suite](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04intro.html#optsuite) common handle interface. It offers clarity and consistency of the interface of the solvers within the suite, making it trivial to switch among compatible solvers. @@ -25,7 +28,7 @@ Figure 1 shows an illustrative simple problem of data fitting ([Jupyter Notebook # More Info 1. [BXNL information leaflet](https://www.nag.com/content/faster-data-fitting-solver) 2. [BXNL in the NAG Library for Python](https://www.nag.co.uk/numeric/py/nagdoc_latest/naginterfaces.library.opt.html#naginterfaces.library.opt.handle_solve_bxnl) - 3. [BXNL documentation page](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04ggf.html) [[Python example](https://www.nag.co.uk/numeric/py/nagdoc_latest/naginterfaces.library.opt.html#naginterfaces.library.examples.opt.handle_disable_ex.main), [C example](https://www.nag.co.uk/numeric/nl/nagdoc_latest/clhtml/e04/e04ggc.html#example), [Fortran example](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04ggf.html#example)] + 3. Examples [[Python example](https://www.nag.co.uk/numeric/py/nagdoc_latest/naginterfaces.library.opt.html#naginterfaces.library.examples.opt.handle_disable_ex.main), [C example](https://www.nag.co.uk/numeric/nl/nagdoc_latest/clhtml/e04/e04ggc.html#example), [Fortran example](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04ggf.html#example)] # Unfolding Nuclear Track Data @@ -96,4 +99,10 @@ represent less functions and gradients calls. * Adachi S, Iwata S, Nakatsukasa Y, and Takeda A (2015) _Solving the trust region subproblem by a generalized eigenvalue problem_. Technical report, METR 2015-14. Mathematical Engineering, The University of Tokyo https://www.keisu.t.u-tokyo.ac.jp/data/2015/METR15-14.pdf * Conn A R, Gould N I M and Toint Ph L (2000) _Trust Region Methods_. SIAM, Philadephia + + +# Obtaining the NAG Library for Python + + * Instructions on [how to install the NAG Library for Python](../Readme.md#install) + * Instructions on [how to run the Jupyter notebooks in the Repository](../Readme.md#jupyter) diff --git a/local_optimization/DFO/Readme.md b/local_optimization/DFO/Readme.md new file mode 100644 index 0000000..9460b19 --- /dev/null +++ b/local_optimization/DFO/Readme.md @@ -0,0 +1,89 @@ +[![NAG Logo](../../nag_logo.png)](https://www.nag.com) + +# Derivative-Free Optimization ([DFO](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/e04/e04intro.html#derivatives)) + +[DFO](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/e04/e04intro.html#derivatives) solvers are aimed at optimizing _black box_ models and can handle either [calibration (nonlinear least squares)](https://en.wikipedia.org/wiki/Non-linear_least_squares) problems (DFLS) +or [problems with a generic objective function](https://en.wikipedia.org/wiki/Nonlinear_programming) (DFNO). + +* Calibration: DFLS (Derivative Nonlinear least squares) +[[`handle_solve_dfls`](https://www.nag.co.uk/numeric/py/nagdoc_latest/naginterfaces.library.opt.html#naginterfaces.library.opt.handle_solve_dfls) | +[`e04fff`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04fff.html) | +[`e04ffc`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/clhtml/e04/e04ffc.html) ] + + * DFNO (Derivative-Free Nonlinear Optimization) + [[`handle_solve_dfno`](https://www.nag.co.uk/numeric/py/nagdoc_latest/naginterfaces.library.opt.html#naginterfaces.library.opt.handle_solve_dfno) | + [`e04jdf`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04jdf.html) | +[`e04jdc`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/clhtml/e04/e04jdc.html) ] + + +Optimizing complex numerical models is one of the most common problems found in the industry (finance, multi-physics simulations, +engineering, etc.). To solve these optimization problems with a standard optimization algorithm such as +[Gauss–Newton](https://en.wikipedia.org/wiki/Gauss%E2%80%93Newton_algorithm) (for +problems with a nonlinear least squares structure) or +[CG](https://en.wikipedia.org/wiki/Conjugate_gradient_method) (for unstructured nonlinear objective) requires good estimates +of the model's derivatives. +If exact derivatives are easy to compute then using derivative-based methods is preferable. However, explicitly writing the derivatives +or applying [AD methods](https://www.nag.com/content/algorithmic-differentiation-software) might be impossible if the model is a black box. +The alternative, estimating derivatives via [finite differences](https://en.wikipedia.org/wiki/Finite_difference#Relation_with_derivatives), +can quickly become impractical or too computationally expensive. Under these circumstances, an attractive optimization solver that does not +require the user to provide any derivatives is the model-based DFO solver. + +NAG's model-based [DFO](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/e04/e04intro.html#derivatives) [solvers for DFLS and DFNO]() present a number of attractive features: + + * Proved resilient to noise, + * The least-square solver is able to start making progress with as few as two objective evaluations, + * Integrated to the [NAG Optimization Modeling Suite (NOMS)](https://www.nag.com/numeric/nl/nagdoc_latest/clhtml/e04/e04intro.html#optsuite) with simple interfaces for the solvers and related routines, + * Optional reverse communication interface. + +![2 steps of DFO algorithm](animation.gif) + +**Figure 1.** Animation showing 2 iterations of a model-based DFO algorithm [`handle_solve_dfls`](https://www.nag.co.uk/numeric/py/nagdoc_latest/naginterfaces.library.opt.html#naginterfaces.library.opt.handle_solve_dfls). + + +## Poster + + + + +
A 2019 poster discussing NAG's DFO/DFLS functionality +is available on the NAG website. +DFO Poster thumbnail
+ +## Example + +The Jupyter notebook showcases the optimization of noisy problems where the objective function is not deterministic. +The example discuses and illustrates the advantages of using a DFO solver instead of a derivative-based solver using +finite difference estimations for the gradient. + + * [Noisy problem notebook.](DFO_noisy.ipynb) + +## More information + + * [Informative Leaflet](https://www.nag.com/content/derivative-free-optimization-dfo) + + * Blog post from the OptCorner [The price of derivatives - Derivative-free Optimization](https://www.nag.com/blog/optcorner-price-derivatives-derivative-free-optimization) + + * [DFO/DFLS in the NAG Library for Python](https://www.nag.co.uk/numeric/py/nagdoc_latest/naginterfaces.library.opt.html#naginterfaces.library.opt.handle_solve_dfls) + + * Examples [ [Python example](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.library.opt.html#naginterfaces.library.examples.opt.handle_solve_dfls_ex.main) | [C example](https://www.nag.co.uk/numeric/nl/nagdoc_latest/clhtml/e04/e04ffc.html#example) | [Fortran 90 example](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04fff.html#example) ] + + * [DFO/DFNO in the NAG Library for Python](https://www.nag.co.uk/numeric/py/nagdoc_latest/naginterfaces.library.opt.html#naginterfaces.library.opt.handle_solve_dfno) + + * Examples [ [Python example](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.library.opt.html#naginterfaces.library.examples.opt.handle_solve_dfno_ex.main) | [C example](https://www.nag.co.uk/numeric/nl/nagdoc_latest/clhtml/e04/e04jdc.html#example) | [Fortran 90 example](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04jdf.html#example) ] + + +## References + +* C. Cartis, J. Fiala, B. Marteau, and L. Roberts (2019) _Improving the Flexibility and robustness of + model-based derivative-free optimization solvers_. ACM Transactions On Numerical Software. +* C. Cartis and L. Roberts (2017) _A derivative-free Gauss–Newton method_. Mathematical Programming Computation. +* Powell M. J. D. (2009) _The BOBYQA algorithm for bound constrained optimization without derivatives_. Report DAMTP 2009/NA06 University of Cambridge. + + + +# Obtaining the NAG Library for Python + + * Instructions on [how to install the NAG Library for Python](../Readme.md#install) + * Instructions on [how to run the Jupyter notebooks in the Repository](../Readme.md#jupyter) + diff --git a/local_optimization/DFO/animation.gif b/local_optimization/DFO/animation.gif new file mode 100644 index 0000000..80c75da Binary files /dev/null and b/local_optimization/DFO/animation.gif differ diff --git a/local_optimization/FOAS/README.md b/local_optimization/FOAS/README.md index b1f592b..fbceeba 100644 --- a/local_optimization/FOAS/README.md +++ b/local_optimization/FOAS/README.md @@ -1,6 +1,8 @@ -[![NAG](https://raw.githubusercontent.com/numericalalgorithmsgroup/NAGPythonExamples/master/nag_logo.png)](https://www.nag.co.uk) +[![NAG Logo](../../nag_logo.png)](https://www.nag.com) -# First-order active-set method (FOAS) [`handle_solve_bounds_foas (e04kf)`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04kff.html) +# First-order active-set method (FOAS) +[[`handle_solve_bounds_foas`](https://www.nag.co.uk/numeric/py/nagdoc_latest/naginterfaces.library.opt.html#naginterfaces.library.opt.handle_solve_bounds_foas) | [`e04kff`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04kff.html) | +[`e04kfc`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/clhtml/e04/e04kfc.html) ] Implementations of first-order methods not only are ubiquitous and have a widespread use, they have also demonstrated to endure the challenges of ever-growing problems sizes imposed by the industry. Most notable are applications in statistics, e.g. parameter calibration for log-linear models, conditional random fields (L2-regularisation) or logistic multi-class regression, amongs many other. First-order methods and the Conjugate Gradient method inparticular have been a research subject for well over 50 years and continue to be improved. @@ -17,13 +19,13 @@ The following example illustrates the simple usage of FOAS to solve the bound-co **Figure 1.** 2D Rosenbrock function, (left) the minimum is shown as a yellow dot at x=(1,1). On the right a bound constrained version showing with a purple dotted line a path towards the constrained solution point on the border. -# More information +## More information 1. [FOAS information page](https://www.nag.com/content/limited-memory-nonlinear-conjugate-gradient-solver) 2. [FOAS in the NAG Library for Python](https://www.nag.co.uk/numeric/py/nagdoc_latest/naginterfaces.library.opt.html#naginterfaces.library.opt.handle_solve_bounds_foas) 3. [FOAS documentation page](https://www.nag.co.uk/numeric/nl/nagdoc_latest/clhtml/e04/e04kfc.html) [ [C](https://www.nag.co.uk/numeric/nl/nagdoc_latest/clhtml/e04/e04kfc.html) | [Fortran](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04kff.html) ] 4. Examples [ [Python example](https://www.nag.co.uk/numeric/py/nagdoc_latest/naginterfaces.library.opt.html#naginterfaces.library.examples.opt.handle_solve_bounds_foas_ex.main) | [C example](https://www.nag.co.uk/numeric/nl/nagdoc_latest/clhtml/e04/e04kfc.html#example) | [Fortran example](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04kff.html#example) ] -# A modern replacement for NAG solver [`uncon_conjgrd_comp` (`e04dg`)](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04dgf.html) +## A modern replacement for NAG solver [`uncon_conjgrd_comp` (`e04dg`)](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04dgf.html) One of the main design objectives for `handle_solve_bounds_foas` (`e04kf`) was to provide a modern and attractive replacement for the CG solver `e04dg` introduced in Mark 12. While this solver was targeted for unconstrained NLPs, `e04kf` has been extended with an active-set method in order to solve bound-constrained NLPs. More recent and modern methods have been incorporated into `e04kf` making it much faster than `e04dg`. The following Figure 2 reports performance profiles over 114 unconstrained NLP CUTEst problems for both solvers `e04kf` and `e04dg`. Contrasting the three plots, it is evident that the new solver is more efficient in time (40% faster) and in general terms is less expensive: requires less function and gradient evaluations. @@ -36,15 +38,16 @@ More recent and modern methods have been incorporated into `e04kf` making it muc **Figure 2.** Performance profiles comparing solvers `e04kf` and `e04dg`. In the time plot on the left, higher line indicates faster solver. For the center and right plots higher line represent less functions (NF) or gradients (NG) calls. For all three plots it can be seen that `e04kf` is 40% faster in time and requires less function and gradient calls. -# Migrating from [`uncon_conjgrd_comp (e04dg)`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04dgf.html) (Mark 26.x) to [`handle_solve_bounds_foas (e04kf)`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04kff.html) (Mark 27+) +## Migrating from Marks 25 and 26 to Mark 27 -Notes and comments on migrating your code to the new FOAS solver: +Notes and comments on migrating your code from [`uncon_conjgrd_comp (e04dg)`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04dgf.html) to the new FOAS solver [`handle_solve_bounds_foas`](https://www.nag.co.uk/numeric/py/nagdoc_latest/naginterfaces.library.opt.html#naginterfaces.library.opt.handle_solve_bounds_foas) ([`e04kff`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04kff.html), +[`e04kfc`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/clhtml/e04/e04kfc.html)): * [Python](migration/migration_e04dg_e04kf.ipynb) * [Fortran 90](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/genint/replace.html#e04dgf) * [C](https://www.nag.com/numeric/nl/nagdoc_latest/clhtml/genint/replace.html#e04dgc) -# Beale's function +## Beale's function This example compares the steps taken by FOAS and L-BFGS-B 3.0 to find the solution point to [Beale's function](https://en.wikipedia.org/wiki/Test_functions_for_optimization). It is a classic nonconvex test function used to benchmark nonlinear optimization solvers. Both solvers are used to find a minimum to the function and are started at the same initial point (2, 2). The following figure shows an animation of the steps taken by each solver to find a minimum to the function. @@ -54,7 +57,7 @@ It illustrates the agressive steps taken by the [Conjugate Gradient method](http **Figure 3.** Contour plots for Beale's function (thin blue lines), and the steps taken by FOAS (red) and L-BFGS-B 3.0 (blue) to find the minimum of Beale's funtion at (3, 0.5) marked with a magenta star. It can be seen that FOAS by the 8th step provides a reasonable approximation to the solution point while L-BFGS-B is still relatively far from it. -# References +## References * Hager W W and Zhang H (2005) _A New Conjugate Gradient Method with Guaranteed Descent and an Efficient Line Search_. SIAM J. Optim. 16(1) 170–192 * Hager W W and Zhang H (2006a) _Algorithm 851: CG DESCENT, a Conjugate Gradient Method with Guaranteed Descent_. ACM Trans. Math. Software 32(1) 113–137 @@ -64,4 +67,8 @@ It illustrates the agressive steps taken by the [Conjugate Gradient method](http +# Obtaining the NAG Library for Python + + * Instructions on [how to install the NAG Library for Python](../Readme.md#install) + * Instructions on [how to run the Jupyter notebooks in the Repository](../Readme.md#jupyter) diff --git a/local_optimization/Modelling/Readme.md b/local_optimization/Modelling/Readme.md new file mode 100644 index 0000000..2c5ddc1 --- /dev/null +++ b/local_optimization/Modelling/Readme.md @@ -0,0 +1,52 @@ +[![NAG Logo](../../nag_logo.png)](https://www.nag.com) + +# Modelling Optimization Problems + +In this folder you will find notebook examples, tips and tricks related to modeling optimization problems. + +* **Christmas Special** [How to decorate your Christmas tree (Notebook)](christmas_demo.ipynb) + or view the [Blog-post](https://www.nag.com/blog/optcorner-christmas-edition). + + + + + +
+Xmas Tree PlotSee how optimization can help to decorate a Christmas tree...
+ + +* **Demo** [Linear Programming (LP)](LP_demo.ipynb). + + Tiny and Cute LP problem... +* **Demo** [Nonlinear calibration (data fitting)](handle_disable_ex.ipynb). + + + + + +
+Data fitting PlotThis demo shows useful features of the NAG Optimization Modelling Suite (NOMS) in a Nonlinear Least-squares problem.
+ + +* **Demo** [Production Planning](production_planning.ipynb). + + Optimal production planning showcasing features of the [NAG Optimization Modelling Suite (NOMS)](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/e04/e04intro.html#optsuite). + +# Useful Links +* [Background to Optimization Methods](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/e04/e04intro.html#algorithms) +* [Nag Blog](https://www.nag.com/content/nag-blog) + + + + + +# Obtaining the NAG Library for Python + + * Instructions on [how to install the NAG Library for Python](../Readme.md#install) + * Instructions on [how to run the Jupyter notebooks in the Repository](../Readme.md#jupyter) diff --git a/local_optimization/Notebooks/Readme.md b/local_optimization/Notebooks/Readme.md new file mode 100644 index 0000000..9850f1e --- /dev/null +++ b/local_optimization/Notebooks/Readme.md @@ -0,0 +1,15 @@ +[![NAG Logo](../../nag_logo.png)](https://www.nag.com) + +# Local Optimization Jupyter notebooks + + * [Example on minimizing the generalized Rosenbrock function](bounds_quasi_func_easy.ipynb) + using [bounds_quasi_func_easy](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.library.opt.bounds_quasi_func_easy.html). + + + + + +# Obtaining the NAG Library for Python + + * Instructions on [how to install the NAG Library for Python](../Readme.md#install) + * Instructions on [how to run the Jupyter notebooks in the Repository](../Readme.md#jupyter) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index db535ce..407cf8c 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -1,13 +1,211 @@ ![NAG Logo](../nag_logo.png) -# Local Optimization +# Content -# Content +* [How to install the NAG Library for Python](#install) +* [How to run the Jupyter notebook examples](#jupyter) +* [Useful links](#links) + +### Repository * [Second Order Cone Programming (SOCP)](./SOCP/) -* [First order active set CG (FOAS)](./FOAS) +* [First order active set CG (FOAS)](./FOAS/) * [Nonlinear Least-Squares (BXNL)](./BXNL) * [Semi-Definite Programming (SDP)](./SDP/) -* [Minimizing the generalized Rosenbrock function using bound constrained optimization](./bounds_quasi_func_easy.ipynb) -* [Linear Programming Demo](./LP_demo.ipynb) -* [Model-based derivative free optimization](./DFO_noisy.ipynb) +* [Derivative-Free Optimization (DFO)](./DFO/) +* [Tips and Tricks in modelling](./Modelling/) +* [Assortment of example notebooks](./Notebooks) ![Jupyter](https://img.shields.io/badge/NAG-Work in progress-yellow) + + +# How to install the NAG Library for Python + +In this section we illustrate how to install the NAG Library for Python, request a Trial Licence and make sure the Library is working. Details and further information regarding the installation can be found [here](https://www.nag.com/numeric/py/nagdoc_latest/readme.html#installation). + +**Note** Before starting make sure you have access to a host that has Python 3 (3.4 or more recent). + +### Step 1. Downloading and installing +Installing the NAG Library is done using the `pip` package manager, fire-up a terminal and create a Python 3 virtual environment where to install and test the NAG Library +```{bash} +guest@nag-37:~$ python3 -m venv nag3 +guest@nag-37:~$ . nag3/bin/activate +(nag3) guest@nag-37:~$ +``` +Now use `pip` to install the NAG Library for Python +```{bash} +(nag3) guest@nag-37:~$ python -m pip install --extra-index-url https://www.nag.com/downloads/py/naginterfaces_nag naginterfaces +``` +or if you prefer the version of the package that relies on Intel MKL for optimized linear algebra routines, then use +```{bash} +(nag3) guest@nag-37:~$ python -m pip install --extra-index-url https://www.nag.com/downloads/py/naginterfaces_mkl naginterfaces +``` + +The output should be similar to +```{bash} +Collecting naginterfaces + Downloading https://www.nag.com/downloads/py/naginterfaces_nag/naginterfaces/naginterfaces-27.1.0.0-py2.py3-none-linux_x86_64.whl (55.8MB) + 100% |████████████████████████████████| 55.8MB 21kB/s +Collecting numpy>=1.15 (from naginterfaces) + Downloading https://files.pythonhosted.org/packages/45/b2/6c7545bb7a38754d63048c7696804a0d947328125d81bf12beaa692c3ae3/numpy-1.19.5-cp36-cp36m-manylinux1_x86_64.whl (13.4MB) + 100% |████████████████████████████████| 13.4MB 70kB/s +Installing collected packages: numpy, naginterfaces +Successfully installed naginterfaces-27.1.0.0 numpy-1.19.5 +``` +The output indicates that the installation was successful. + +### Step 2. Getting a trial licence +The next step is to get the licensing info (**product code** and **KUSARI ID**) and use it to request a licence. From the same virtual terminal, try +```{bash} +(nag3) guest@nag-37:~$ python -m naginterfaces.kusari +``` +The output should be similar to +``` +The NAG Library for Python on this platform uses +underlying Library NLL6I271VL. +This Library has been installed as part of the package +and it requires a valid licence key. +No such key could be validated: +the key may not have been installed correctly or +it may have expired. +The Kusari licence-check utility reports the following: +User: guest +Directory: /home/guest +NAG_KUSARI_FILE="" +File /home/guest/nag.key does not exist +------------------------------------------------------------------------------- +Error: Licence not found; this product requires a key for NLL6I271VL +The above information has been generated on machine nag-37 +For information on how to obtain a licence, please see +https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.kusari.html +KUSARI ID = "ADLXt-adEclJLmvnxlrU2sseteZoo,RopA-Ld" +``` +The **two** important bits are the + + 1. **product code** shown as **`underlying Library NLL6I271VL.`** which identifies the licence to request, and + + 2. **KUSARI ID** shown as **`KUSARI ID = "ADLXt-adEclJLmvnxlrU2sseteZoo,RopA-Ld"`** which identifies the host you are running the library on. + + **Note** that the **product code** and **KUSARI ID** can be different from the previous example. + + With these, you are set to [contact NAG and request a trial licence](https://www.nag.com/content/software-trials?product=NAG%20Library). + + The trial licence is a plain text chunk similar to + ``` + NLL6I271V TRIAL 2021/01/27 "RverXn0Pc-Ib?ctdgF=Wpis2j7I" + ``` + Save or copy the text into the file `/home/guest/nag.key`. + + The final step is to make sure the licence is valid and the library is working as expected. + +### Step 3. Testing the NAG Library +The last step is to make sure the licence was correctly stored and that the NAG Library is working correctly. From the same virtual terminal re-run the Kusari licence module +```{bash} +(nag3) guest@nag-37:~$ python -m naginterfaces.kusari +``` +This time the output should be similar to +``` +Licence available; the required NLL6I271VL licence key for this product is valid +TRIAL licence, 27 days remaining (licence from file) +``` +Now let's try a more interesting example ([list of optimization examples](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.library.opt.html#examples)) + +This command runs the example for the [FOAS (First-Order Active set method) solver and minimizes the Rosenbrock 2D function](./FOAS). +``` +(nag3) guest@nag-37:~$ python -m naginterfaces.library.examples.opt.handle_solve_bounds_foas_ex +``` +Should generate an outputsimilar to +```{bash} +Trying: + main() +Expecting: + naginterfaces.library.opt.handle_solve_bounds_foas Python Example Results. + Minimizing a bound-constrained Rosenbrock problem. + E04KF, First order method for bound-constrained problems +... + Status: converged, an optimal solution was found + Value of the objective 4.00000E-02 + ... +ok +``` +indicating that the example was successfully executed. The source code can be found [here](https://www.nag.com/numeric/py/nagdoc_latest/_modules/naginterfaces/library/examples/opt/handle_solve_bounds_foas_ex.html#main). + +### Running more examples + +To display the full list of example source files on disk, but not run them, execute +``` +python -m naginterfaces.library.examples --locate +``` +All examples may be executed sequentially by running +``` +python -m naginterfaces.library.examples +``` +Run `python -m naginterfaces.library.examples --help` to see any additional usage. + + + +# How to run the Jupyter notebook examples + +This section briefly illustrates how to setup a host in order to open and run the [Jupyter notebooks](https://jupyter.org/) provided in this repository. +Before running the notebooks make sure the [NAG Library is installed and working](#install). Before starting, it is advised to read [Jupyter's installation page](https://jupyter.org/install.html). + + + + +### Installing Jupyter notebook +To install Jupyter, launch a terminal and activate the virtual environment used to install the NAG Library for Python +```{bash} +guest@nag-37:~$ . nag3/bin/activate +(nag3) guest@nag-37:~$ pip install notebook matplotlib +Collecting notebook + Downloading https://files.pythonhosted.org/packages/74/19/50cd38acf22e33370d01fef764355f1e3517f6e12b4fceb8d434ece4f8fd/notebook-6.2.0-py3-none-any.whl (9.5MB) + 100% |████████████████████████████████| 9.5MB 115kB/s +Collecting argon2-cffi (from notebook) +... +Successfully installed jupyter-client-6.1.11 jupyterlab-pygments-0.1.2 ... wcwidth-0.2.5 +``` +This indicates that Jupyter and matplotlib were successfully installed. The next section shows how to start the notebok interface and open an example. + +### Running the notebook examples +To run an example, grab a copy of the notebook of interest and start up the notebook interface. +For example, download the [Rosenbrock 2D optimization example](./FOAS/rosenbrock2d.ipynb) notebook `rosenbrock2d.ipynb` into the current directory +```{bash} +(nag3) guest@nag-37:~$ curl -O https://raw.githubusercontent.com/numericalalgorithmsgroup/NAGPythonExamples/master/local_optimization/FOAS/rosenbrock2d.ipynb + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed +100 61961 100 61961 0 0 382k 0 --:--:-- --:--:-- --:--:-- 382k +``` +and now open it using `jupyter-notebook` +```{bash} +(nag3) guest@nag-37:~$ jupyter-notebook rosenbrock2d.ipynb +[I 12:24:07.336 NotebookApp] Serving notebooks from local directory: /home/guest +[I 12:24:07.336 NotebookApp] Jupyter Notebook 6.2.0 is running at: +[I 12:24:07.336 NotebookApp] http://localhost:8888/?token=f1836a06799a92f25ef9966439bf3491b2f0960dcb51806d +... +``` +This command will fire-up your web browser and open the `rosenbrock2d.ipynb` notebook, the window should be similar to + + +![Notebook screenshot](images/screenshot.png) + + + + + + + +# Useful links + +* [NAG Library for Python Documentation](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.library.opt.html) +* [NAG Library Optimization (Chapter E04) Introduction](https://www.nag.com/numeric/nl/nagdoc_latest/clhtml/e04/e04intro.html) +* [Optimization Index](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/indexes/optimization.html) +* [Decision Tree for selecting the right optimization solver](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/e04/e04intro.html#dtree) +* [Request a trial licence](https://www.nag.com/content/software-trials?product=NAG%20Library) +* [Kusari licence module Documentation](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.kusari.html#kusari) + + +**[Back to Top](#top)** + diff --git a/local_optimization/SDP/Readme.md b/local_optimization/SDP/Readme.md index 01a6c1e..f41b68e 100644 --- a/local_optimization/SDP/Readme.md +++ b/local_optimization/SDP/Readme.md @@ -1,7 +1,20 @@ +[![NAG Logo](../../nag_logo.png)](https://www.nag.com) + # Semi-Definite Programming (SDP) +[[`handle_solve_pennon`](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.library.opt.handle_solve_pennon.html#naginterfaces.library.opt.handle_solve_pennon) | [`e04svf`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/flhtml/e04/e04svf.html) | +[`e04svc`](https://www.nag.co.uk/numeric/nl/nagdoc_latest/clhtml/e04/e04svc.html) ] + + Linear semidefinite programming can be viewed as a generalization of linear programming. While keeping many good properties of LP (such as the duality theory and solvability in polynomial time), SDP introduces a new highly nonlinear type of constraint – matrix inequality. It is an inequality on the eigenvalues of a matrix which depends on the decision variables. Typically, the matrix inequality is written in the form to request all eigenvalues of the matrix to be non-negative, thus the matrix is to be positive semidefinite * [Matrix completion using Semi-Definite Programming (SDP)](./matrix_completion.ipynb) * [Nearest correlation matrix using Semi-Definite Programming (SDP)](./NCM_SDP.ipynb) * [Compute the Lovasz number of a graph using Semi-Definite Programming (SDP)](./theta_optimization.ipynb) + + + +# Obtaining the NAG Library for Python + + * Instructions on [how to install the NAG Library for Python](../Readme.md#install) + * Instructions on [how to run the Jupyter notebooks in the Repository](../Readme.md#jupyter) diff --git a/local_optimization/SOCP/Readme.md b/local_optimization/SOCP/Readme.md index 382ce52..ad6cddd 100644 --- a/local_optimization/SOCP/Readme.md +++ b/local_optimization/SOCP/Readme.md @@ -1,3 +1,5 @@ +[![NAG Logo](../../nag_logo.png)](https://www.nag.com) + # Second Order Cone Programming [Second Order Cone Programming (SOCP)](https://en.wikipedia.org/wiki/Second-order_cone_programming) is convex optimization which extends linear programming (LP) with second-order (Lorentz or the ice cream) cones. Search region of the solution is the intersection of an affine @@ -50,15 +52,18 @@ A mean-variance model with probability constraint using randomly generated data. * [robust_lp.ipynb](./robust_lp.ipynb) Jupyter Notebook * [robust_lp.html](./static/robust_lp.html) Static html version -# Data +## Data * [stock_price.pkl](./data/stock_price.pkl) - pickled data file contains daily prices of 30 stocks in DJIA from March 2018 to March 2019. It is used to estimate out-of-sample expected return and covariance matrix. * [djia_close_price.csv](./data/djia_close_price.csv) - CSV version of daily prices of 30 stocks in DJIA from March 2018 to March 2019. -# Poster +## Poster A 2019 poster discussing NAG's SOCP functionality is [available on the NAG website](https://www.nag.com/market/posters/socp.pdf) # Obtaining the NAG Library for Python -Instructions for how to download, install and license the NAG Library for Python can be found at https://github.com/numericalalgorithmsgroup/NAGPythonExamples#nag-library-for-python-installation + * Instructions on [how to install the NAG Library for Python](../Readme.md#install) + * Instructions on [how to run the Jupyter notebooks in the Repository](../Readme.md#jupyter) + + diff --git a/local_optimization/SOCP/simple_SOCP.ipynb b/local_optimization/SOCP/simple_SOCP.ipynb index 42b5fe0..d652874 100644 --- a/local_optimization/SOCP/simple_SOCP.ipynb +++ b/local_optimization/SOCP/simple_SOCP.ipynb @@ -1,5 +1,16 @@ { "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Installing the NAG library and running this notebook\n", + "\n", + "This notebook depends on the NAG library for Python to run. Please read the instructions in the [Readme.md](https://github.com/numericalalgorithmsgroup/NAGPythonExamples/blob/master/local_optimization/Readme.md#install) file to download, install and obtain a licence for the library.\n", + "\n", + "Instruction on how to run the notebook can be found [here](https://github.com/numericalalgorithmsgroup/NAGPythonExamples/blob/master/local_optimization/Readme.md#jupyter)." + ] + }, { "cell_type": "markdown", "metadata": {}, diff --git a/local_optimization/images/nlls.png b/local_optimization/images/nlls.png new file mode 100644 index 0000000..3639624 Binary files /dev/null and b/local_optimization/images/nlls.png differ diff --git a/local_optimization/images/screenshot.png b/local_optimization/images/screenshot.png new file mode 100644 index 0000000..fc4d241 Binary files /dev/null and b/local_optimization/images/screenshot.png differ diff --git a/local_optimization/images/xmas_tree.png b/local_optimization/images/xmas_tree.png new file mode 100644 index 0000000..e4088ec Binary files /dev/null and b/local_optimization/images/xmas_tree.png differ