Skip to content

Commit 667b232

Browse files
committed
Changed doc theme, added setup for github pages
1 parent 88668c2 commit 667b232

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

55 files changed

+17496
-6
lines changed

docs/.nojekyll

Whitespace-only changes.

docs/Makefile

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ SPHINXOPTS =
66
SPHINXBUILD = python3 -msphinx
77
SPHINXPROJ = DFO-GN
88
SOURCEDIR = .
9-
BUILDDIR = _build
9+
BUILDDIR = build
1010

1111
# Put it first so that "make" without argument is like "make help".
1212
help:

docs/build/html/.buildinfo

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Sphinx build info version 1
2+
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
3+
config: 323aea43a5449895fd1471c6a55fc908
4+
tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/build/html/.nojekyll

Whitespace-only changes.
29.2 KB
Loading
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
Version History
2+
===============
3+
This section lists the different versions of DFO-GN and the updates between them.
4+
5+
Version 0.1 (13 Sep 2017)
6+
-------------------------
7+
* Initial version of DFO-GN
8+
9+
Version 0.2 (20 Feb 2018)
10+
-------------------------
11+
* Minor bug fix to trust region subproblem solver (the output :code:`crvmin` is calculated correctly) - this has minimal impact on the performance of DFO-GN.
12+
13+
Version 1.0 (17 Jul 2018)
14+
-------------------------
15+
* Bug fix for installation when dependencies not installed, added requirements.txt - no changes to the DFO-GN algorithm.
16+
Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
.. DFO-GN documentation master file, created by
2+
sphinx-quickstart on Thu Aug 3 16:29:21 2017.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
DFO-GN: A Derivative-Free Gauss-Newton Solver
7+
=============================================
8+
9+
**Release:** |version|
10+
11+
**Date:** |today|
12+
13+
**Author:** `Lindon Roberts <[email protected]>`_ (Mathematical Institute, University of Oxford)
14+
15+
DFO-GN is a Python package for finding local solutions to **nonlinear least-squares minimization problems (with optional bound constraints)**, without requiring any derivatives of the objective. DFO-GN stands for Derivative-Free Optimization using Gauss-Newton, and is applicable to problems such as
16+
17+
* Parameter estimation/data fitting;
18+
* Solving systems of nonlinear equations (including under- and over-determined systems); and
19+
* Inverse problems, including data assimilation.
20+
21+
DFO-GN is a *derivative-free* algorithm, meaning it does not require any information about the derivative of the objective, nor does it attempt to estimate such information (e.g. by using finite differencing). This means that it is **particularly useful for solving noisy problems**; i.e. where evaluating the objective function several times for the same input may give different results.
22+
23+
Mathematically, DFO-GN solves
24+
25+
.. math::
26+
27+
\min_{x\in\mathbb{R}^n} &\quad f(x) := \sum_{i=1}^{m}r_{i}(x)^2 \\
28+
\text{s.t.} &\quad a \leq x \leq b
29+
30+
where the functions :math:`r_i(x)` may be nonlinear and even nonconvex. Full details of the DFO-GN algorithm are given in our paper: `A Derivative-Free Gauss-Newton Method <https://arxiv.org/abs/1710.11005>`_, C. Cartis and L. Roberts, submitted (2017).
31+
32+
DFO-GN is released under the open source GNU General Public License, a copy of which can be found in LICENSE.txt. Please `contact NAG <http://www.nag.com/content/worldwide-contact-information>`_ for alternative licensing. It is compatible with both Python 2 and Python 3.
33+
34+
Note: we have released a newer package, called DFO-LS, which is an upgrade of DFO-GN to improve its flexibility and robustness to noisy problems. See `here <https://github.com/numericalalgorithmsgroup/dfols>`_ for details.
35+
36+
If you have any questions or suggestsions about the code, or have used DFO-GN for an interesting application, we would very much like to hear from you: please contact `Lindon Roberts <[email protected]>`_ (`alternative email <[email protected]>`_).
37+
38+
.. toctree::
39+
:maxdepth: 2
40+
:caption: Contents:
41+
42+
info
43+
install
44+
userguide
45+
history
46+
47+
Acknowledgements
48+
----------------
49+
This software was developed under the supervision of `Coralia Cartis <https://www.maths.ox.ac.uk/people/coralia.cartis>`_ (Mathematical Institute, University of Oxford), and was supported by the EPSRC Centre For Doctoral Training in `Industrially Focused Mathematical Modelling <https://www.maths.ox.ac.uk/study-here/postgraduate-study/industrially-focused-mathematical-modelling-epsrc-cdt>`_ (EP/L015803/1) at the University of Oxford's Mathematical Institute, in collaboration with the `Numerical Algorithms Group <http://www.nag.com/>`_.
50+
51+
DFO-GN was developed using techniques from DFBOLS (`Zhang, Conn & Scheinberg, 2010 <https://doi.org/10.1137/09075531X>`_) and BOBYQA (`Powell, 2009 <http://mat.uc.pt/~zhang/software.html>`_).
52+
The structure of this documentation is from `oBB <http://pythonhosted.org/oBB/>`_ by Jari Fowkes.
53+

docs/build/html/_sources/info.rst.txt

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
Overview
2+
========
3+
4+
When to use DFO-GN
5+
------------------
6+
DFO-GN is designed to solve the nonlinear least-squares minimization problem (with optional bound constraints)
7+
8+
.. math::
9+
10+
\min_{x\in\mathbb{R}^n} &\quad f(x) := \sum_{i=1}^{m}r_{i}(x)^2 \\
11+
\text{s.t.} &\quad a \leq x \leq b
12+
13+
We call :math:`f(x)` the objective function and :math:`r_i(x)` the residual functions (or simply residuals).
14+
15+
DFO-GN is a *derivative-free* optimization algorithm, which means it does not require the user to provide the derivatives of :math:`f(x)` or :math:`r_i(x)`, nor does it attempt to estimate them internally (by using finite differencing, for instance).
16+
17+
There are two main situations when using a derivative-free algorithm (such as DFO-GN) is preferable to a derivative-based algorithm (which is the vast majority of least-squares solvers).
18+
19+
If **the residuals are noisy**, then calculating or even estimating their derivatives may be impossible (or at least very inaccurate). By noisy, we mean that if we evaluate :math:`r_i(x)` multiple times at the same value of :math:`x`, we get different results. This may happen when a Monte Carlo simulation is used, for instance, or :math:`r_i(x)` involves performing a physical experiment.
20+
21+
If **the residuals are expensive to evaluate**, then estimating derivatives (which requires :math:`n` evaluations of each :math:`r_i(x)` for every point of interest :math:`x`) may be prohibitively expensive. Derivative-free methods are designed to solve the problem with the fewest number of evaluations of the objective as possible.
22+
23+
**However, if you have provide (or a solver can estimate) derivatives** of :math:`r_i(x)`, then it is probably a good idea to use one of the many derivative-based solvers (such as `one from the SciPy library <https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.least_squares.html>`_).
24+
25+
Parameter Fitting
26+
-----------------
27+
A very common problem in many quantitative disciplines is fitting parameters to observed data. Typically, this means that we have developed a model for some proccess, which takes a vector of (known) inputs :math:`\mathrm{obs}\in\mathbb{R}^N` and some model parameters :math:`x=(x_1, \ldots, x_n)\in\mathbb{R}^n`, and computes a (predicted) quantity of interest :math:`y\in\mathbb{R}`:
28+
29+
.. math::
30+
31+
y = \mathrm{model}(\mathrm{obs}, x)
32+
33+
For this model to be useful, we need to determine a suitable choice for the parameters :math:`x`, which typically cannot be directly observed. A common way of doing this is to calibrate from observed relationships.
34+
35+
Suppose we have some observations of the input-to-output relationship. That is, we have data
36+
37+
.. math::
38+
39+
(\mathrm{obs}_1, y_1), \ldots, (\mathrm{obs}_m, y_m)
40+
41+
Then, we try to find the parameters :math:`x` which produce the best possible fit to these observations by minimizing the sum-of-squares of the prediction errors:
42+
43+
.. math::
44+
45+
\min_{x\in\mathbb{R}^n} \quad f(x) := \sum_{i=1}^{m}(y_i - \mathrm{model}(\mathrm{obs}_i, x))^2
46+
47+
which is in the least-squares form required by DFO-GN.
48+
49+
As described above, DFO-GN is a particularly good choice for parameter fitting when the model has noise (e.g. Monte Carlo simulation) or is expensive to evaluate.
50+
51+
Solving Nonlinear Systems of Equations
52+
--------------------------------------
53+
Suppose we wish to solve the system of nonlinear equations: find :math:`x\in\mathbb{R}^n` satisfying
54+
55+
.. math::
56+
57+
r_1(x) &= 0 \\
58+
r_2(x) &= 0 \\
59+
&\vdots \\
60+
r_m(x) &= 0
61+
62+
Such problems can have no solutions, one solution, or many solutions (possibly infinitely many). Often, but certainly not always, the number of solutions depends on whether there are more equations or unknowns: if :math:`m<n` we say the system is underdetermined (and there are often multiple solutions), if :math:`m=n` we say the system is square (and there is often only one solution), and if :math:`m>n` we say the system is overdetermined (and there are often no solutions).
63+
64+
This is not always true -- there is no solution to the underdetermined system when :math:`m=1` and :math:`n=2` and we choose :math:`r_1(x)=\sin(x_1+x_2)-2`, for example.
65+
Similarly, if we take :math:`n=1` and :math:`r_i(x)=i (x-1)(x-2)`, we can make :math:`m` as large as we like while keeping :math:`x=1` and :math:`x=2` as solutions (to the overdetermined system).
66+
67+
If no solution exists, it makes sense to instead search for an :math:`x` which approximately satisfies each equation. A common way to do this is to minimize the sum-of-squares of the left-hand-sides:
68+
69+
.. math::
70+
71+
\min_{x\in\mathbb{R}^n} \quad f(x) := \sum_{i=1}^{m}r_i(x)^2
72+
73+
which is the form required by DFO-GN.
74+
75+
If a solution does exist, then this formulation will also find this (where we will get :math:`f=0` at the solution).
76+
77+
**Which solution?** DFO-GN, and most similar software, will only find one solution to a set of nonlinear equations. Which one it finds is very difficult to predict, and depends very strongly on the point where the solver is started from. Often it finds the closest solution, but there are no guarantees this will be the case. If you need to find all/multiple solutions for your problem, consider techniques such as `deflation <http://www.sciencedirect.com/science/article/pii/0022247X83900550>`_.
78+
79+
Details of the DFO-GN Algorithm
80+
-------------------------------
81+
DFO-GN is a type of *trust-region* method, a common category of optimization algorithms for nonconvex problems. Given a current estimate of the solution :math:`x_k`, we compute a model which approximates the objective :math:`m_k(s)\approx f(x_k+s)` (for small steps :math:`s`), and maintain a value :math:`\Delta_k>0` (called the *trust region radius*) which measures the size of :math:`s` for which the approximation is good.
82+
83+
At each step, we compute a trial step :math:`s_k` designed to make our approximation :math:`m_k(s)` small (this task is called the *trust region subproblem*). We evaluate the objective at this new point, and if this provided a good decrease in the objective, we take the step (:math:`x_{k+1}=x_k+s_k`), otherwise we stay put (:math:`x_{k+1}=x_k`). Based on this information, we choose a new value :math:`\Delta_{k+1}`, and repeat the process.
84+
85+
In DFO-GN, we construct our approximation :math:`m_k(s)` by interpolating a linear approximation for each residual :math:`r_i(x)` at several points close to :math:`x_k`. To make sure our interpolated model is accurate, we need to regularly check that the points are well-spaced, and move them if they aren't (i.e. improve the geometry of our interpolation points).
86+
87+
A complete description of the DFO-GN algorithm is given in our paper [CR2017]_.
88+
89+
References
90+
----------
91+
92+
.. [CR2017]
93+
Cartis, C. and Roberts, L., `A Derivative-Free Gauss-Newton Method <https://arxiv.org/abs/1710.11005>`_, submitted (2017).
94+
Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
Installing DFO-GN
2+
=================
3+
4+
Requirements
5+
------------
6+
DFO-GN requires the following software to be installed:
7+
8+
* `Python 2.7 or Python 3 <http://www.python.org/>`_
9+
10+
Additionally, the following python packages should be installed (these will be installed automatically if using `pip <http://www.pip-installer.org/>`_, see `Installation using pip`_):
11+
12+
* `NumPy 1.11 or higher <http://www.numpy.org/>`_
13+
* `SciPy 0.18 or higher <http://www.scipy.org/>`_
14+
15+
16+
Installation using pip
17+
----------------------
18+
For easy installation, use `pip <http://www.pip-installer.org/>`_ as root:
19+
20+
.. code-block:: bash
21+
22+
$ [sudo] pip install --pre dfogn
23+
24+
If you do not have root privileges or you want to install DFO-GN for your private use, you can use:
25+
26+
.. code-block:: bash
27+
28+
$ pip install --pre --user dfogn
29+
30+
which will install DFO-GN in your home directory.
31+
32+
Note that if an older install of DFO-GN is present on your system you can use:
33+
34+
.. code-block:: bash
35+
36+
$ [sudo] pip install --pre --upgrade dfogn
37+
38+
to upgrade DFO-GN to the latest version.
39+
40+
Manual installation
41+
-------------------
42+
The source code for DFO-GN is `available on Github <https://https://github.com/numericalalgorithmsgroup/dfogn>`_:
43+
44+
.. code-block:: bash
45+
46+
$ git clone https://github.com/numericalalgorithmsgroup/dfogn
47+
$ cd dfogn
48+
49+
or through the `Python Package Index <https://pypi.python.org/pypi/dfogn>`_:
50+
51+
.. code-block:: bash
52+
53+
$ wget http://pypi.python.org/packages/source/d/dfogn/dfogn-X.X.tar.gz
54+
$ tar -xzvf dfogn-X.X.tar.gz
55+
$ cd dfogn-X.X
56+
57+
DFO-GN is written in pure Python and requires no compilation. It can be installed using:
58+
59+
.. code-block:: bash
60+
61+
$ [sudo] pip install --pre .
62+
63+
If you do not have root privileges or you want to install DFO-GN for your private use, you can use:
64+
65+
.. code-block:: bash
66+
67+
$ pip install --pre --user .
68+
69+
instead.
70+
71+
Testing
72+
-------
73+
If you installed DFO-GN manually, you can test your installation by running:
74+
75+
.. code-block:: bash
76+
77+
$ python setup.py test
78+
79+
Uninstallation
80+
--------------
81+
If DFO-GN was installed using `pip <http://www.pip-installer.org/>`_ you can uninstall as follows:
82+
83+
.. code-block:: bash
84+
85+
$ [sudo] pip uninstall dfogn
86+
87+
If DFO-GN was installed manually you have to remove the installed files by hand (located in your python site-packages directory).
88+
89+

0 commit comments

Comments
 (0)