From fe258bea08d8e92b276249cab5170d87f1db3687 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 08:59:48 +0000 Subject: [PATCH 01/57] Update Readme.md Further updates to Kusari --- local_optimization/Readme.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 36c4529..28db8f1 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -52,10 +52,10 @@ or if you have Intel MKL, then use ``` for Intel MKL-enabled NAG Library. -### Step 2. Getting a Trial License +### Step 2. Getting a Trial Licence The next step is to get the licensing info (**product code** and **KUSARI ID**) and request a lincense. From the same virtual terminal ```{bash} -(nag3) andrews@olney:~$ python -m naginterfaces.kusari +(nag3) guest@nag-37:~$ python -m naginterfaces.kusari ``` The output should be similar to ``` @@ -86,7 +86,7 @@ The **two** important bits are the **Note** the **product code** might be different while the **Kusari ID** _will_ be different for your case. - With these, you are set to [contact NAG and request a trial license](https://www.nag.com/content/software-trials?product=NAG%20Library). + 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 ``` @@ -98,7 +98,7 @@ The **two** important bits are the The final step is to make sure the licence is valid and the library is working as expected ### Step 3. Testing the Library -The last step is to make sure the licence was correctly stored and that the library is working correctly. From the same virtual terminal re-run kusary +The last step is to make sure the licence was correctly stored and that the library is working correctly. From the same virtual terminal re-run Kusary licence module ```{bash} (nag3) andrews@olney:~$ python -m naginterfaces.kusari ``` @@ -135,9 +135,9 @@ to see any additional usage. * [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) -* [kurari license module documentation](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.kusari.html#kusari) +* [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) From 261cb1d76a6a6997682d3c077e7d74e5973ec50e Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 09:48:03 +0000 Subject: [PATCH 03/57] Doc anchors --- local_optimization/Readme.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 3fa608c..176387d 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -1,6 +1,6 @@ [![NAG Logo](../nag_logo.png)](https://www.nag.com) -# Local Optimization +# Local Optimization Here you will find a variety of resources (mostly Python notebooks) related to the use of our optimization routines and modelling suite. If you are new to NAG's optimization solvers we highly recomment to read the [E04 chapter](https://www.nag.com/numeric/nl/nagdoc_latest/clhtml/e04/e04intro.html) of the [NAG](https://www.nag.com) Library which is dedicated to local optimization. While if you are new to NAG Library for Python we encourage to review the [Python documentation](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.library.opt.html). @@ -17,13 +17,13 @@ If you are already familiar with NAG's optimization offering and just need to fi red line shows the final solution. (right) Optimization of a wing section: red represent the baseline, center section in yellow shows an overall improvement of 13% while the rightmost section in green/blue shows a further 33% improvement. -# Content +# Content -* [How to install the NAG Library for Python]() -* [How to run the Jupyter Notebooks]() -* [Useful links]() +* [How to install the NAG Library for Python](#install) +* [How to run the Jupyter notebook examples](#jupyter) +* [Useful links](#links) -## Repository +### Repository * [Second Order Cone Programming (SOCP)](./SOCP/) * [First order active set CG (FOAS)](./FOAS/) @@ -32,12 +32,12 @@ shows an overall improvement of 13% while the rightmost section in green/blue sh * [Derivative-Free Optimization (DFO)](./DFO/) * [Tips and Tricks in modelling](./modelling/) -## Examples (Remove) +### Examples (Remove) * [Minimizing the generalized Rosenbrock function using bound constrained optimization](./bounds_quasi_func_easy.ipynb) * move this into modelling [Linear Programming Demo](./LP_demo.ipynb) * move this into DFO [Model-based derivative free optimization](./DFO_noisy.ipynb) -# How to install the NAG Library for Python +# 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). @@ -145,9 +145,9 @@ python -m naginterfaces.library.examples ``` Run `python -m naginterfaces.library.examples --help` to see any additional usage. - +# How to run the Jupyter notebook examples -# Useful links +# 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) @@ -156,6 +156,8 @@ Run `python -m naginterfaces.library.examples --help` to see any additional usag * [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)** From 5fa79ad45ee393223520c4b9a15a0fa1c6029aad Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 09:53:58 +0000 Subject: [PATCH 04/57] Update Readme.md --- local_optimization/Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 176387d..aa3edd2 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -2,7 +2,7 @@ # Local Optimization -Here you will find a variety of resources (mostly Python notebooks) related to the use of our optimization routines and modelling suite. If you are new to NAG's optimization solvers we highly recomment to read the [E04 chapter](https://www.nag.com/numeric/nl/nagdoc_latest/clhtml/e04/e04intro.html) of the [NAG](https://www.nag.com) Library which is dedicated to local optimization. While if you are new to NAG Library for Python we encourage to review the [Python documentation](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.library.opt.html). +Here you will find a variety of resources (mostly Python notebooks) related to the use of our optimization routines and modelling suite. If you are new to NAG's optimization solvers we highly recomment to read the [E04 chapter](https://www.nag.com/numeric/nl/nagdoc_latest/clhtml/e04/e04intro.html) of the [NAG](https://www.nag.com) Library which is dedicated to local optimization. While if you are new to NAG Library for Python we encourage to review the [Python documentation](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.library.opt.html) and read the sections on [How to install the NAG Library for Python](#install) and [How to run the Jupyter notebook examples](#jupyter) on this repository. If you are already familiar with NAG's optimization offering and just need to find the right solver to use for your problem, then we recommend reviewing the [Optimization Index](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/indexes/optimization.html) or the [Decision Tree for selecting the right Optimization solver](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/e04/e04intro.html#dtree). From fc8be91a7a33f93ed20d9bd36bd5b7c256c1f4ec Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 11:22:52 +0000 Subject: [PATCH 05/57] Add badges --- local_optimization/Readme.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index aa3edd2..c7e5cdf 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -147,6 +147,15 @@ Run `python -m naginterfaces.library.examples --help` to see any additional usag # 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 advisable to read [Jupyter's installation guide](). + +You can [view a static render of the notebooks using Jupiter's nbviewer here](https://nbviewer.jupyter.org/github/numericalalgorithmsgroup/NAGPythonExamples/tree/master/local_optimization/) +[![Jupyter](https://img.shields.io/badge/launch-nbviewer-blue?logo=jupyter&logoColor=white)](https://nbviewer.jupyter.org/github/numericalalgorithmsgroup/NAGPythonExamples/tree/master/local_optimization/). +Alternatively, use [Binder](https://mybinder.org/) to view a [render of the notebooks here](https://mybinder.org/v2/gh/numericalalgorithmsgroup/NAGPythonExamples/HEAD) +[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/numericalalgorithmsgroup/NAGPythonExamples/HEAD) + + # Useful links * [NAG Library for Python Documentation](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.library.opt.html) From a109fbf8cb6ab36a67f9d67d2834a954392cf26c Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 11:53:49 +0000 Subject: [PATCH 06/57] Update Readme.md --- local_optimization/Readme.md | 42 +++++++++++++++++++++++++++++++----- 1 file changed, 37 insertions(+), 5 deletions(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index c7e5cdf..aaa4c90 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -145,15 +145,47 @@ 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 advisable to read [Jupyter's installation guide](). +Before running the notebooks make sure the [NAG Library is installed and working](#install). Before starting it is advisable to read [Jupyter's installation page](https://jupyter.org/install.html). + +You can [view a static render of the notebooks using Jupyter's nbviewer here](https://nbviewer.jupyter.org/github/numericalalgorithmsgroup/NAGPythonExamples/tree/master/local_optimization/) +[![Jupyter](https://img.shields.io/badge/launch-nbviewer-blue?logo=jupyter&logoColor=white)](https://nbviewer.jupyter.org/github/numericalalgorithmsgroup/NAGPythonExamples/tree/master/local_optimization/) +or alternatively use [Binder](https://mybinder.org/) to [view them here](https://mybinder.org/v2/gh/numericalalgorithmsgroup/NAGPythonExamples/HEAD) +[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/numericalalgorithmsgroup/NAGPythonExamples/HEAD). + + +### Installing Jupyter +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 +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 was successfully installed. The next section shows how to start the notebok interface and open an example +### Running the notebook examples +Once `pip` finished to install `notebook` all the dependencies, it is time start up the notebook interface +```{bash} +(nag3) guest@nag-37:~$ jupyter-notebook +[I 05:13:44.313 NotebookApp] Serving notebooks from local directory: /home/guest +[I 05:13:44.313 NotebookApp] 0 active kernels +[I 05:13:44.313 NotebookApp] The Jupyter Notebook is running at: http://localhost:8888/ +[I 05:13:44.313 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation). +``` +This command will fire-up your web browser and launch the notebook service. Use the gui interface to open up any of the notebooks provided in this repository + + + + -You can [view a static render of the notebooks using Jupiter's nbviewer here](https://nbviewer.jupyter.org/github/numericalalgorithmsgroup/NAGPythonExamples/tree/master/local_optimization/) -[![Jupyter](https://img.shields.io/badge/launch-nbviewer-blue?logo=jupyter&logoColor=white)](https://nbviewer.jupyter.org/github/numericalalgorithmsgroup/NAGPythonExamples/tree/master/local_optimization/). -Alternatively, use [Binder](https://mybinder.org/) to view a [render of the notebooks here](https://mybinder.org/v2/gh/numericalalgorithmsgroup/NAGPythonExamples/HEAD) -[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/numericalalgorithmsgroup/NAGPythonExamples/HEAD) # Useful links From 7c60eefcacd1ea27b69995451e7d39e7a9b4aba7 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 12:02:53 +0000 Subject: [PATCH 07/57] Update Readme.md --- local_optimization/Readme.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index aaa4c90..3486cb4 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -152,14 +152,14 @@ Run `python -m naginterfaces.library.examples --help` to see any additional usag 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 advisable to read [Jupyter's installation page](https://jupyter.org/install.html). -You can [view a static render of the notebooks using Jupyter's nbviewer here](https://nbviewer.jupyter.org/github/numericalalgorithmsgroup/NAGPythonExamples/tree/master/local_optimization/) + -### Installing Jupyter -To install jupyter, launch a terminal and activate the virtual environment used to install the NAG Library for Python +### 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 From 395fd1792a5e3c5b4aa587f6c9248b2b1097bfda Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 12:03:59 +0000 Subject: [PATCH 08/57] Update Readme.md --- local_optimization/Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 3486cb4..daacaf0 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -172,7 +172,7 @@ Successfully installed jupyter-client-6.1.11 jupyterlab-pygments-0.1.2 ... wcwid ``` This indicates that Jupyter was successfully installed. The next section shows how to start the notebok interface and open an example ### Running the notebook examples -Once `pip` finished to install `notebook` all the dependencies, it is time start up the notebook interface +Once `pip` finished to install `notebook` and all the dependencies, it is time start up the notebook interface ```{bash} (nag3) guest@nag-37:~$ jupyter-notebook [I 05:13:44.313 NotebookApp] Serving notebooks from local directory: /home/guest From 026aed0856a5b37b7f80eaca2cd80fb397aa60d1 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 12:43:54 +0000 Subject: [PATCH 09/57] Update Readme.md --- local_optimization/Readme.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index daacaf0..80f6ede 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -162,7 +162,7 @@ or alternatively use [Binder](https://mybinder.org/) to [view them here](https:/ 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 +(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 @@ -172,15 +172,24 @@ Successfully installed jupyter-client-6.1.11 jupyterlab-pygments-0.1.2 ... wcwid ``` This indicates that Jupyter was successfully installed. The next section shows how to start the notebok interface and open an example ### Running the notebook examples -Once `pip` finished to install `notebook` and all the dependencies, it is time start up the notebook interface +Once `pip` finished to install `notebook` and all the dependencies, it is time to grab a copy of the notebook of interest and start up the notebook interface. +In this example we download the [Rosenbrock 2D optimization example](./FOAS/rosenbrock2d.ipynb) file `rosenbrock2d.ipynb` into the current working directory ```{bash} -(nag3) guest@nag-37:~$ jupyter-notebook -[I 05:13:44.313 NotebookApp] Serving notebooks from local directory: /home/guest -[I 05:13:44.313 NotebookApp] 0 active kernels -[I 05:13:44.313 NotebookApp] The Jupyter Notebook is running at: http://localhost:8888/ -[I 05:13:44.313 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation). +(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 ``` -This command will fire-up your web browser and launch the notebook service. Use the gui interface to open up any of the notebooks provided in this repository +and 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 launch the web gui and open the `rosenbrock2d.ipynb` notebook and should have an output similar to +![Notebook screenshot](Notebooks/screenshot.png) From e52eeecb3335f3797034789d87291b510f123e2f Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 12:44:21 +0000 Subject: [PATCH 10/57] Add files via upload --- local_optimization/Notebooks/screenshot.png | Bin 0 -> 108759 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 local_optimization/Notebooks/screenshot.png diff --git a/local_optimization/Notebooks/screenshot.png b/local_optimization/Notebooks/screenshot.png new file mode 100644 index 0000000000000000000000000000000000000000..fc4d24169bb7454ea7566e342fd30c73c7e8c4b5 GIT binary patch literal 108759 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 z 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 Date: Wed, 27 Jan 2021 12:45:04 +0000 Subject: [PATCH 11/57] Update Readme.md --- local_optimization/Readme.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 80f6ede..9f3e906 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -189,6 +189,8 @@ and open it using `jupyter-notebook` ... ``` This command will fire-up your web browser and launch the web gui and open the `rosenbrock2d.ipynb` notebook and should have an output similar to + + ![Notebook screenshot](Notebooks/screenshot.png) From 64decf9554c9a82c035a713ebac2a2add1b7d6a1 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 14:10:11 +0000 Subject: [PATCH 12/57] Update Readme.md --- local_optimization/Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 9f3e906..12e9ed2 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -188,7 +188,7 @@ and open it using `jupyter-notebook` [I 12:24:07.336 NotebookApp] http://localhost:8888/?token=f1836a06799a92f25ef9966439bf3491b2f0960dcb51806d ... ``` -This command will fire-up your web browser and launch the web gui and open the `rosenbrock2d.ipynb` notebook and should have an output similar to +This command will fire-up your web browser and open the `rosenbrock2d.ipynb` notebook, the window should be similar to ![Notebook screenshot](Notebooks/screenshot.png) From aca6c886168441b18e71867683f6b936fc26c434 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 14:15:17 +0000 Subject: [PATCH 13/57] Update Readme.md --- local_optimization/Readme.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 12e9ed2..7ce9629 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -170,10 +170,10 @@ 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 was successfully installed. The next section shows how to start the notebok interface and open an example +This indicates that Jupyter was successfully installed. The next section shows how to start the notebok interface and open an example. ### Running the notebook examples -Once `pip` finished to install `notebook` and all the dependencies, it is time to grab a copy of the notebook of interest and start up the notebook interface. -In this example we download the [Rosenbrock 2D optimization example](./FOAS/rosenbrock2d.ipynb) file `rosenbrock2d.ipynb` into the current working directory +To run an example, grab a copy of the notebook of interest and start up the notebook interface. +First, in this example we download the [Rosenbrock 2D optimization example](./FOAS/rosenbrock2d.ipynb) file `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 From d0f58b7f0d22135ee6a5addf9a16c74163d3b010 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 14:16:49 +0000 Subject: [PATCH 14/57] Update Readme.md --- local_optimization/Readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 7ce9629..03491f3 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -173,14 +173,14 @@ Successfully installed jupyter-client-6.1.11 jupyterlab-pygments-0.1.2 ... wcwid This indicates that Jupyter was 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. -First, in this example we download the [Rosenbrock 2D optimization example](./FOAS/rosenbrock2d.ipynb) file `rosenbrock2d.ipynb` into the current directory +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 open it using `jupyter-notebook` +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 From 74d52bd39fdc683016b30fc6286c52e62b4848d9 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 14:19:28 +0000 Subject: [PATCH 15/57] Update Readme.md --- local_optimization/Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 03491f3..64eb1c5 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -2,7 +2,7 @@ # Local Optimization -Here you will find a variety of resources (mostly Python notebooks) related to the use of our optimization routines and modelling suite. If you are new to NAG's optimization solvers we highly recomment to read the [E04 chapter](https://www.nag.com/numeric/nl/nagdoc_latest/clhtml/e04/e04intro.html) of the [NAG](https://www.nag.com) Library which is dedicated to local optimization. While if you are new to NAG Library for Python we encourage to review the [Python documentation](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.library.opt.html) and read the sections on [How to install the NAG Library for Python](#install) and [How to run the Jupyter notebook examples](#jupyter) on this repository. +Here you will find a variety of resources (mostly [Jupyter notebooks](https://jupyter.org/)) related to the use of our optimization routines and modelling suite. If you are new to NAG's optimization solvers we highly recomment to read the [E04 chapter](https://www.nag.com/numeric/nl/nagdoc_latest/clhtml/e04/e04intro.html) of the [NAG](https://www.nag.com) Library which is dedicated to local optimization. While if you are new to NAG Library for Python we encourage to review the [Python documentation](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.library.opt.html) and read the sections on [How to install the NAG Library for Python](#install) and [How to run the Jupyter notebook examples](#jupyter) on this repository. If you are already familiar with NAG's optimization offering and just need to find the right solver to use for your problem, then we recommend reviewing the [Optimization Index](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/indexes/optimization.html) or the [Decision Tree for selecting the right Optimization solver](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/e04/e04intro.html#dtree). From 7a55b2ee8591e842b09367ea723cd2e9f6356f75 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 14:20:57 +0000 Subject: [PATCH 16/57] Update Readme.md --- local_optimization/Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 64eb1c5..249a483 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -2,7 +2,7 @@ # Local Optimization -Here you will find a variety of resources (mostly [Jupyter notebooks](https://jupyter.org/)) related to the use of our optimization routines and modelling suite. If you are new to NAG's optimization solvers we highly recomment to read the [E04 chapter](https://www.nag.com/numeric/nl/nagdoc_latest/clhtml/e04/e04intro.html) of the [NAG](https://www.nag.com) Library which is dedicated to local optimization. While if you are new to NAG Library for Python we encourage to review the [Python documentation](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.library.opt.html) and read the sections on [How to install the NAG Library for Python](#install) and [How to run the Jupyter notebook examples](#jupyter) on this repository. +Here you will find a variety of resources (mostly [Jupyter notebooks](https://jupyter.org/)) related to the use of our optimization routines and modelling suite. If you are new to NAG's optimization solvers we highly recomment to read the [E04 chapter](https://www.nag.com/numeric/nl/nagdoc_latest/clhtml/e04/e04intro.html) of the [NAG](https://www.nag.com) Library which is dedicated to local optimization. While if you are new to NAG Library for Python we encourage to review the [NAG Python documentation](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.library.opt.html) and read the sections on [How to install the NAG Library for Python](#install) and [How to run the Jupyter notebook examples](#jupyter) of this `Readme`. If you are already familiar with NAG's optimization offering and just need to find the right solver to use for your problem, then we recommend reviewing the [Optimization Index](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/indexes/optimization.html) or the [Decision Tree for selecting the right Optimization solver](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/e04/e04intro.html#dtree). From 11be5e08c06cb05c0e7a2750a1c5220406ae4007 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 14:26:19 +0000 Subject: [PATCH 17/57] Update Readme.md --- local_optimization/Readme.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 249a483..486d585 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -14,8 +14,9 @@ If you are already familiar with NAG's optimization offering and just need to fi **Figure 1.** Applied optimization examples. (left) DFO nonlinear least-square calibration for the Kowalik and Osborne function, -red line shows the final solution. (right) Optimization of a wing section: red represent the baseline, center section in yellow -shows an overall improvement of 13% while the rightmost section in green/blue shows a further 33% improvement. +red line shows the final solution. (right) Optimization of a wing section struct: red represent the baseline design, center section in yellow +shows a design with an overall improvement of 13% while the rightmost section in green/blue shows design with a further 33% improvement. Improvement metric is +based on weight and strengh of the design. # Content From 5b19d5ce2743401079843752a48691f214a55503 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 14:27:19 +0000 Subject: [PATCH 18/57] Update Readme.md --- local_optimization/Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 486d585..9b615f6 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -16,7 +16,7 @@ If you are already familiar with NAG's optimization offering and just need to fi **Figure 1.** Applied optimization examples. (left) DFO nonlinear least-square calibration for the Kowalik and Osborne function, red line shows the final solution. (right) Optimization of a wing section struct: red represent the baseline design, center section in yellow shows a design with an overall improvement of 13% while the rightmost section in green/blue shows design with a further 33% improvement. Improvement metric is -based on weight and strengh of the design. +based on weight and strengh of the piece. # Content From 10f123e0ba7465e50c7e1796c33e6254b501878b Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 14:29:35 +0000 Subject: [PATCH 19/57] Update Readme.md --- local_optimization/Readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 9b615f6..4f82898 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -42,14 +42,14 @@ based on weight and strengh of the piece. 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). -### Step 1. Downloading and installing (`pip`) +### 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 ``` From f0ae5374166ef0ad456d04201bde78a43707e166 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 14:31:50 +0000 Subject: [PATCH 20/57] Update Readme.md --- local_optimization/Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 4f82898..2d46f55 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -93,7 +93,7 @@ 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 olney.nag.co.uk +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-adEclJLmvnxlrYfsseteZoo,mRLd" From c149ec353667524407b3513eb6a3fac962963603 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 14:32:56 +0000 Subject: [PATCH 21/57] Update Readme.md --- local_optimization/Readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 2d46f55..1bf562f 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -102,9 +102,9 @@ The **two** important bits are the 1. **product code** shown as **`underlying Library NLL6I271VL.`** which identifies the licence to request, and - 2. **Kusary ID** shown as **`KUSARI ID = "ADLXt-adEclJLmvnxlrYfsseteZoo,mRLd"`** which identifies the host you are running the library on. + 2. **KUSARI ID** shown as **`KUSARI ID = "ADLXt-adEclJLmvnxlrYfsseteZoo,mRLd"`** 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. + **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). From aee7d884afc90c5d10c51d9027fb87c86b7b4255 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 14:35:22 +0000 Subject: [PATCH 22/57] Update Readme.md --- local_optimization/Readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 1bf562f..e17737a 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -96,13 +96,13 @@ 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-adEclJLmvnxlrYfsseteZoo,mRLd" +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-adEclJLmvnxlrYfsseteZoo,mRLd"`** which identifies the host you are running the library on. + 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. From e8a532ae785cdda164390ea4a69c891d6d3b0ddb Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 14:39:22 +0000 Subject: [PATCH 23/57] Update Readme.md --- local_optimization/Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index e17737a..7e7c433 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -117,7 +117,7 @@ The **two** important bits are the 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 Kusary licence module +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 ``` From 4410aba3a07f1f4413986717382db606d38190c8 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 14:42:59 +0000 Subject: [PATCH 24/57] Update Readme.md --- local_optimization/Readme.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 7e7c433..aa943c4 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -130,9 +130,23 @@ Now let's try a more interesting example ([list of optimization examples](https: This command runs the example for the [FOAS (First-Order Active set method) solver and minimizes the Rosenbrock 2D function](./FOAS). ``` -python -m naginterfaces.library.examples.opt.handle_solve_bounds_foas_ex +(nag3) guest@nag-37:~$ python -m naginterfaces.library.examples.opt.handle_solve_bounds_foas_ex ``` -The source code of the previous example can be found [here](https://www.nag.com/numeric/py/nagdoc_latest/_modules/naginterfaces/library/examples/opt/handle_solve_bounds_foas_ex.html#main). +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 From b0ea05d0024929acdcaabc83a7ca4effd6f6164d Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 14:44:58 +0000 Subject: [PATCH 25/57] Update Readme.md --- local_optimization/Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index aa943c4..777fb36 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -165,7 +165,7 @@ Run `python -m naginterfaces.library.examples --help` to see any additional usag # 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 advisable to read [Jupyter's installation page](https://jupyter.org/install.html). +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). From 77cc5dd7ae88cf264e2083a087c9aac4947a64b6 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 15:06:16 +0000 Subject: [PATCH 28/57] Update Readme.md --- local_optimization/SOCP/Readme.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/local_optimization/SOCP/Readme.md b/local_optimization/SOCP/Readme.md index 6372a22..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 From a9b3e72e272f285dbf2f9dfcb00bfed2fcaee5be Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 15:16:53 +0000 Subject: [PATCH 29/57] Update README.md Updated Header, Footer and links to Python Lib --- local_optimization/FOAS/README.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) 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) From 031828f9b30b7f617b1c632af65b35b8f1631b17 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 15:29:27 +0000 Subject: [PATCH 30/57] Update Readme.md --- local_optimization/BXNL/Readme.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/local_optimization/BXNL/Readme.md b/local_optimization/BXNL/Readme.md index 12e31d7..bf46583 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. [BXNL Python documentation page](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.library.opt.handle_solve_bxnl.html#naginterfaces.library.opt.handle_solve_bxnl) [[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) From e5a26f12ed8b86b943bf1bf8906ded78a1e7bc4f Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 15:31:40 +0000 Subject: [PATCH 31/57] Update Readme.md --- local_optimization/BXNL/Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/local_optimization/BXNL/Readme.md b/local_optimization/BXNL/Readme.md index bf46583..640ad4d 100644 --- a/local_optimization/BXNL/Readme.md +++ b/local_optimization/BXNL/Readme.md @@ -28,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 Python documentation page](https://www.nag.com/numeric/py/nagdoc_latest/naginterfaces.library.opt.handle_solve_bxnl.html#naginterfaces.library.opt.handle_solve_bxnl) [[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 From db295e3bd8535c82875ae5cf8d902c83517b0eb4 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 15:37:26 +0000 Subject: [PATCH 32/57] Update Readme.md --- local_optimization/SDP/Readme.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) 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) From 64b9ccd8b7ab89ccfc6fcba82bed4e5edf79f484 Mon Sep 17 00:00:00 2001 From: Andrew Sajo Date: Wed, 27 Jan 2021 15:40:47 +0000 Subject: [PATCH 33/57] Moved screenshot to images --- .../{Notebooks => images}/screenshot.png | Bin 1 file changed, 0 insertions(+), 0 deletions(-) rename local_optimization/{Notebooks => images}/screenshot.png (100%) diff --git a/local_optimization/Notebooks/screenshot.png b/local_optimization/images/screenshot.png similarity index 100% rename from local_optimization/Notebooks/screenshot.png rename to local_optimization/images/screenshot.png From 992b2e8b7aeecdedc1a46933b6b7efa12171f591 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 16:37:18 +0000 Subject: [PATCH 34/57] conversion of animation to gif format --- local_optimization/DFO/animation.gif | Bin 0 -> 45917 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 local_optimization/DFO/animation.gif diff --git a/local_optimization/DFO/animation.gif b/local_optimization/DFO/animation.gif new file mode 100644 index 0000000000000000000000000000000000000000..80c75da22f940fd86db1bc1462cdca40b81db3f0 GIT binary patch literal 45917 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 R*Y>8Q{mxW-C*i>V{{UGgr&$01 literal 0 HcmV?d00001 From b556ad430b5e21a0e452339354a634a2d599be9c Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 16:37:57 +0000 Subject: [PATCH 35/57] Create Readme.md --- local_optimization/DFO/Readme.md | 71 ++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 local_optimization/DFO/Readme.md diff --git a/local_optimization/DFO/Readme.md b/local_optimization/DFO/Readme.md new file mode 100644 index 0000000..1d247fe --- /dev/null +++ b/local_optimization/DFO/Readme.md @@ -0,0 +1,71 @@ +[![NAG Logo](../../nag_logo.png)](https://www.nag.com) + +# Derivative-Free Optimization (DFO) + +* Calibration: Derivative Nonlinear least squares (DFLS) +[[`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) ] + + * Derivative-Free Nonlinear Optimization (DFNO) + [[`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) ] + +DFO solvers are aimed at optimizing _black box_ models and can handle either calibration (nonlinear least squares) problems +or problems with a generic objective function. + +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. + + +![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] + * [DFO in the NAG Library for Python] + * 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) ] + +## 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) + From 7415dd08c98f6c4cca0814727f88f3956284770e Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 16:38:27 +0000 Subject: [PATCH 36/57] Update Readme.md --- local_optimization/DFO/Readme.md | 1 + 1 file changed, 1 insertion(+) diff --git a/local_optimization/DFO/Readme.md b/local_optimization/DFO/Readme.md index 1d247fe..66db526 100644 --- a/local_optimization/DFO/Readme.md +++ b/local_optimization/DFO/Readme.md @@ -29,6 +29,7 @@ can quickly become impractical or too computationally expensive. ![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). From 5c3e699c96de0af4ef6396ae369dcf92d4847f9f Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 16:51:43 +0000 Subject: [PATCH 37/57] Update Readme.md --- local_optimization/DFO/Readme.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/local_optimization/DFO/Readme.md b/local_optimization/DFO/Readme.md index 66db526..23d4c54 100644 --- a/local_optimization/DFO/Readme.md +++ b/local_optimization/DFO/Readme.md @@ -52,9 +52,19 @@ finite difference estimations for the gradient. * [Noisy problem notebook.](DFO_noisy.ipynb) ## More information - * [Informative Leaflet] - * [DFO in the NAG Library for Python] - * 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) ] + + * [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 From 2896258b02d83f8dd371e4ccf00ab87b9320accb Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 16:55:03 +0000 Subject: [PATCH 38/57] Update Readme.md --- local_optimization/DFO/Readme.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/local_optimization/DFO/Readme.md b/local_optimization/DFO/Readme.md index 23d4c54..8393dbc 100644 --- a/local_optimization/DFO/Readme.md +++ b/local_optimization/DFO/Readme.md @@ -2,18 +2,19 @@ # Derivative-Free Optimization (DFO) -* Calibration: Derivative Nonlinear least squares (DFLS) +DFO solvers are aimed at optimizing _black box_ models and can handle either calibration (nonlinear least squares) problems (DFLS) +or problems with a generic objective function (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) ] - * Derivative-Free Nonlinear Optimization (DFNO) + * 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) ] -DFO solvers are aimed at optimizing _black box_ models and can handle either calibration (nonlinear least squares) problems -or problems with a generic objective function. 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 From 428316bc4cd345cd4e514c4f2ede62ef6fe63e2f Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 17:00:51 +0000 Subject: [PATCH 39/57] Update Readme.md --- local_optimization/DFO/Readme.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/local_optimization/DFO/Readme.md b/local_optimization/DFO/Readme.md index 8393dbc..c0b168a 100644 --- a/local_optimization/DFO/Readme.md +++ b/local_optimization/DFO/Readme.md @@ -22,12 +22,17 @@ engineering, etc.). To solve these optimization problems with a standard optimiz 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. +NAG's model-based DFO solvers for DFLS and DFNO present a number of attractive features: + + * Proved resilience to noise. + * Solvers are able to start making progress with as few as two objective evaluations; + * Integrated to the NAG Optimization Modeling Suite with simple interfaces for the solvers and related routines; + * Optional reverse communication interface ![2 steps of DFO algorithm](animation.gif) From cd700900f1ac37258269d09148349bd03aa2af66 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 17:01:41 +0000 Subject: [PATCH 40/57] Update Readme.md --- local_optimization/DFO/Readme.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/local_optimization/DFO/Readme.md b/local_optimization/DFO/Readme.md index c0b168a..881dd6b 100644 --- a/local_optimization/DFO/Readme.md +++ b/local_optimization/DFO/Readme.md @@ -29,10 +29,10 @@ can quickly become impractical or too computationally expensive. NAG's model-based DFO solvers for DFLS and DFNO present a number of attractive features: - * Proved resilience to noise. - * Solvers are able to start making progress with as few as two objective evaluations; - * Integrated to the NAG Optimization Modeling Suite with simple interfaces for the solvers and related routines; - * Optional reverse communication interface + * Proved resilience to noise, + * Solvers are able to start making progress with as few as two objective evaluations, + * Integrated to the NAG Optimization Modeling Suite with simple interfaces for the solvers and related routines, + * Optional reverse communication interface. ![2 steps of DFO algorithm](animation.gif) From f57c3e37e22f4df1f27cff2d48c2757eda4ed282 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 17:06:55 +0000 Subject: [PATCH 41/57] Update Readme.md --- local_optimization/Readme.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 72ce261..1f00dd6 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -33,10 +33,8 @@ based on weight and strengh of the piece. * [Derivative-Free Optimization (DFO)](./DFO/) * [Tips and Tricks in modelling](./modelling/) -### Examples (Remove) +### Examples (FIXME: Remove section) * [Minimizing the generalized Rosenbrock function using bound constrained optimization](./bounds_quasi_func_easy.ipynb) -* move this into modelling [Linear Programming Demo](./LP_demo.ipynb) -* move this into DFO [Model-based derivative free optimization](./DFO_noisy.ipynb) # How to install the NAG Library for Python From e9b86354bdecfba1b443ae8c12b9a56cbd854a53 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 17:15:29 +0000 Subject: [PATCH 42/57] Create Readme.md --- local_optimization/Notebooks/Readme.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 local_optimization/Notebooks/Readme.md diff --git a/local_optimization/Notebooks/Readme.md b/local_optimization/Notebooks/Readme.md new file mode 100644 index 0000000..ece2ee9 --- /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) From 7b04211feb6c40a7f389d324848f696ccc077d1d Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 17:17:01 +0000 Subject: [PATCH 43/57] Update Readme.md --- local_optimization/Notebooks/Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/local_optimization/Notebooks/Readme.md b/local_optimization/Notebooks/Readme.md index ece2ee9..9850f1e 100644 --- a/local_optimization/Notebooks/Readme.md +++ b/local_optimization/Notebooks/Readme.md @@ -1,4 +1,4 @@ -[![NAG Logo](../nag_logo.png)](https://www.nag.com) +[![NAG Logo](../../nag_logo.png)](https://www.nag.com) # Local Optimization Jupyter notebooks From 826eba4826c6683b81304bb2337b46295e1c2a9e Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 17:22:23 +0000 Subject: [PATCH 44/57] Update Readme.md --- local_optimization/Readme.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 1f00dd6..85522cb 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -32,6 +32,8 @@ based on weight and strengh of the piece. * [Semi-Definite Programming (SDP)](./SDP/) * [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) + ### Examples (FIXME: Remove section) * [Minimizing the generalized Rosenbrock function using bound constrained optimization](./bounds_quasi_func_easy.ipynb) From f799c0d33a98c8ca8d078f45422ac82769815353 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 17:23:06 +0000 Subject: [PATCH 45/57] Update Readme.md --- local_optimization/Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 85522cb..43259fb 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -31,7 +31,7 @@ based on weight and strengh of the piece. * [Nonlinear Least-Squares (BXNL)](./BXNL) * [Semi-Definite Programming (SDP)](./SDP/) * [Derivative-Free Optimization (DFO)](./DFO/) -* [Tips and Tricks in modelling](./modelling/) +* [Tips and Tricks in modelling](./Modelling/) * [Assortment of example notebooks](./Notebooks) ![Jupyter](https://img.shields.io/badge/NAG-Work in progress-yellow) From 5345296b0f2cca1399d7a818a3f317cec620573f Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 17:23:59 +0000 Subject: [PATCH 46/57] Update Readme.md --- local_optimization/Readme.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 43259fb..333de5c 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -35,9 +35,6 @@ based on weight and strengh of the piece. * [Assortment of example notebooks](./Notebooks) ![Jupyter](https://img.shields.io/badge/NAG-Work in progress-yellow) -### Examples (FIXME: Remove section) -* [Minimizing the generalized Rosenbrock function using bound constrained optimization](./bounds_quasi_func_easy.ipynb) - # 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). From 10e8f3ce2df350f24e0fecfc5d10545fe7474cc4 Mon Sep 17 00:00:00 2001 From: A Date: Wed, 27 Jan 2021 17:27:48 +0000 Subject: [PATCH 47/57] Update Readme.md --- local_optimization/Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 333de5c..7e73dbd 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -206,7 +206,7 @@ and now open it using `jupyter-notebook` This command will fire-up your web browser and open the `rosenbrock2d.ipynb` notebook, the window should be similar to -![Notebook screenshot](Notebooks/screenshot.png) +![Notebook screenshot](images/screenshot.png) From 812cc47cb80b7da26fe0a48dd4a2033f9d0ce745 Mon Sep 17 00:00:00 2001 From: A Date: Thu, 28 Jan 2021 10:15:00 +0000 Subject: [PATCH 48/57] Update Readme.md --- local_optimization/DFO/Readme.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/local_optimization/DFO/Readme.md b/local_optimization/DFO/Readme.md index 881dd6b..1c2ccbb 100644 --- a/local_optimization/DFO/Readme.md +++ b/local_optimization/DFO/Readme.md @@ -25,13 +25,14 @@ 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. +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 solvers for DFLS and DFNO present a number of attractive features: * Proved resilience to noise, * Solvers are able to start making progress with as few as two objective evaluations, - * Integrated to the NAG Optimization Modeling Suite with simple interfaces for the solvers and related routines, + * 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) From c7aa1aa71c8d51618221d93aea128ed5eb7f2822 Mon Sep 17 00:00:00 2001 From: A Date: Thu, 28 Jan 2021 10:29:02 +0000 Subject: [PATCH 49/57] Update Readme.md --- local_optimization/DFO/Readme.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/local_optimization/DFO/Readme.md b/local_optimization/DFO/Readme.md index 1c2ccbb..3191fe6 100644 --- a/local_optimization/DFO/Readme.md +++ b/local_optimization/DFO/Readme.md @@ -1,9 +1,9 @@ [![NAG Logo](../../nag_logo.png)](https://www.nag.com) -# Derivative-Free Optimization (DFO) +# Derivative-Free Optimization ([DFO](https://en.wikipedia.org/wiki/Derivative-free_optimization)) -DFO solvers are aimed at optimizing _black box_ models and can handle either calibration (nonlinear least squares) problems (DFLS) -or problems with a generic objective function (DFNO). +[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) | @@ -28,7 +28,7 @@ The alternative, estimating derivatives via [finite differences](https://en.wiki 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 solvers for DFLS and DFNO present a number of attractive features: +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 resilience to noise, * Solvers are able to start making progress with as few as two objective evaluations, From cdd7cd405588ed628b4d9d450bdea0107368efa6 Mon Sep 17 00:00:00 2001 From: A Date: Thu, 28 Jan 2021 10:29:38 +0000 Subject: [PATCH 50/57] Update Readme.md --- local_optimization/DFO/Readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/local_optimization/DFO/Readme.md b/local_optimization/DFO/Readme.md index 3191fe6..052f135 100644 --- a/local_optimization/DFO/Readme.md +++ b/local_optimization/DFO/Readme.md @@ -1,6 +1,6 @@ [![NAG Logo](../../nag_logo.png)](https://www.nag.com) -# Derivative-Free Optimization ([DFO](https://en.wikipedia.org/wiki/Derivative-free_optimization)) +# 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). From 0a2339a41c77eb8da40d032f533c0327d20025f2 Mon Sep 17 00:00:00 2001 From: A Date: Thu, 28 Jan 2021 11:22:47 +0000 Subject: [PATCH 51/57] Create Readme.md --- local_optimization/Modelling/Readme.md | 37 ++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 local_optimization/Modelling/Readme.md diff --git a/local_optimization/Modelling/Readme.md b/local_optimization/Modelling/Readme.md new file mode 100644 index 0000000..6e7b81a --- /dev/null +++ b/local_optimization/Modelling/Readme.md @@ -0,0 +1,37 @@ +[![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). + + See 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). + + This demo shows useful features of the [NAG Optimization Modelling Suite (NOMS)](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/e04/e04intro.html#optsuite) in [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) From 494b8bf7b64a3f428a79c585e05761c7b597bbce Mon Sep 17 00:00:00 2001 From: A Date: Thu, 28 Jan 2021 11:24:39 +0000 Subject: [PATCH 52/57] Add files via upload --- local_optimization/images/nlls.png | Bin 0 -> 10472 bytes local_optimization/images/xmas_tree.png | Bin 0 -> 8049 bytes 2 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 local_optimization/images/nlls.png create mode 100644 local_optimization/images/xmas_tree.png diff --git a/local_optimization/images/nlls.png b/local_optimization/images/nlls.png new file mode 100644 index 0000000000000000000000000000000000000000..363962432db3ed8d67b05bf2045742d9928049a8 GIT binary patch literal 10472 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 literal 0 HcmV?d00001 diff --git a/local_optimization/images/xmas_tree.png b/local_optimization/images/xmas_tree.png new file mode 100644 index 0000000000000000000000000000000000000000..e4088ec519dc8add7351778a1c4bedae6406f669 GIT binary patch literal 8049 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 literal 0 HcmV?d00001 From f2181f7339b40e57b09c0183f77c4642afea1608 Mon Sep 17 00:00:00 2001 From: A Date: Thu, 28 Jan 2021 11:32:40 +0000 Subject: [PATCH 53/57] Update Readme.md --- local_optimization/Modelling/Readme.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/local_optimization/Modelling/Readme.md b/local_optimization/Modelling/Readme.md index 6e7b81a..6c37235 100644 --- a/local_optimization/Modelling/Readme.md +++ b/local_optimization/Modelling/Readme.md @@ -6,8 +6,13 @@ In this folder you will find notebook examples, tips and tricks related to model * **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). + + + +
See how optimization can help to decorate a Christmas tree... +Xmas Tree Plot
- See how optimization can help to decorate a Christmas tree... * **Demo** [Linear Programming (LP)](LP_demo.ipynb). @@ -15,6 +20,15 @@ In this folder you will find notebook examples, tips and tricks related to model * **Demo** [Nonlinear calibration (data fitting)](handle_disable_ex.ipynb). This demo shows useful features of the [NAG Optimization Modelling Suite (NOMS)](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/e04/e04intro.html#optsuite) in [Nonlinear Least-squares]() problem. + + + + +
This demo shows useful features of the NAG Optimization Modelling Suite (NOMS) in a Nonlinear Least-squares problem. +Data fitting Plot
+ + * **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). From 686cdc694a00cc9d7b29b3b431b680b0cd6f817a Mon Sep 17 00:00:00 2001 From: A Date: Thu, 28 Jan 2021 11:35:49 +0000 Subject: [PATCH 54/57] Update Readme.md --- local_optimization/Modelling/Readme.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/local_optimization/Modelling/Readme.md b/local_optimization/Modelling/Readme.md index 6c37235..25dd503 100644 --- a/local_optimization/Modelling/Readme.md +++ b/local_optimization/Modelling/Readme.md @@ -7,10 +7,12 @@ In this folder you will find notebook examples, tips and tricks related to model * **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). - + +width="100" height="100px" alt="Xmas Tree Plot"/> + +
See how optimization can help to decorate a Christmas tree... Xmas Tree PlotSee how optimization can help to decorate a Christmas tree...
@@ -22,10 +24,12 @@ width="362" height="248px" alt="Xmas Tree Plot"/> This demo shows useful features of the [NAG Optimization Modelling Suite (NOMS)](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/e04/e04intro.html#optsuite) in [Nonlinear Least-squares]() problem. - +width="100" height="80px" alt="Data fitting Plot"/> + + +
This demo shows useful features of the NAG Optimization Modelling Suite (NOMS) in a Nonlinear Least-squares problem. Data fitting PlotThis demo shows useful features of the NAG Optimization Modelling Suite (NOMS) in a Nonlinear Least-squares problem.
From 37bf004216a162a338bd668589f5fccfb288ad62 Mon Sep 17 00:00:00 2001 From: A Date: Thu, 28 Jan 2021 11:36:28 +0000 Subject: [PATCH 55/57] Update Readme.md --- local_optimization/Modelling/Readme.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/local_optimization/Modelling/Readme.md b/local_optimization/Modelling/Readme.md index 25dd503..2c5ddc1 100644 --- a/local_optimization/Modelling/Readme.md +++ b/local_optimization/Modelling/Readme.md @@ -19,10 +19,7 @@ width="100" height="100px" alt="Xmas Tree Plot"/> * **Demo** [Linear Programming (LP)](LP_demo.ipynb). Tiny and Cute LP problem... -* **Demo** [Nonlinear calibration (data fitting)](handle_disable_ex.ipynb). - - This demo shows useful features of the [NAG Optimization Modelling Suite (NOMS)](https://www.nag.com/numeric/nl/nagdoc_latest/flhtml/e04/e04intro.html#optsuite) in [Nonlinear Least-squares]() problem. - +* **Demo** [Nonlinear calibration (data fitting)](handle_disable_ex.ipynb).
Date: Fri, 29 Jan 2021 14:59:18 +0100 Subject: [PATCH 56/57] small edits of the Readmes --- local_optimization/DFO/Readme.md | 4 ++-- local_optimization/Readme.md | 3 +-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/local_optimization/DFO/Readme.md b/local_optimization/DFO/Readme.md index 052f135..9460b19 100644 --- a/local_optimization/DFO/Readme.md +++ b/local_optimization/DFO/Readme.md @@ -30,8 +30,8 @@ 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 resilience to noise, - * Solvers are able to start making progress with as few as two objective evaluations, + * 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. diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 7e73dbd..922a46f 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -52,11 +52,10 @@ 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 have Intel MKL, then use +or if you prefer the version of the package that relies on Intel MKLfor 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 ``` -for Intel MKL-enabled NAG Library. The output should be similar to ```{bash} From f05353cf6c0690383d7e89bf96c2117c9fb791c4 Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 29 Jan 2021 15:29:38 +0100 Subject: [PATCH 57/57] typo and small paragraph in notebook linking to installation instructions --- local_optimization/Readme.md | 2 +- local_optimization/SOCP/simple_SOCP.ipynb | 11 +++++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/local_optimization/Readme.md b/local_optimization/Readme.md index 922a46f..b5d7c1e 100644 --- a/local_optimization/Readme.md +++ b/local_optimization/Readme.md @@ -52,7 +52,7 @@ 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 MKLfor optimized linear algebra routines, then use +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 ``` 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": {},