Added documentation

Author: lindonroberts

.gitignore

@@ -1,7 +1,6 @@
 *.pyc
 */__pycache__
 *.egg-info
-docs/_build
 dist/
 venv/
 .eggs/

dfbgn/exit_information.py

@@ -118,7 +118,9 @@ def __str__(self):
             output += "Needed %g objective evaluations\n" % (self.nf)
             if self.nruns > 1:
                 output += "Did a total of %g runs\n" % self.nruns
-            if np.size(self.jacobian) < 200:
+            if self.jacobian is None:
+                output += "No approximate Jacobian available\n"
+            elif np.size(self.jacobian) < 200:
                 output += "Approximate Jacobian = %s\n" % str(self.jacobian)
             else:
                 output += "Not showing approximate Jacobian because it is too long; check self.jacobian\n"

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_build/doctrees/environment.pickle

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: e7e4519aca41910b746d8b9cb3eee0db
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_build/doctrees/index.doctree

@@ -0,0 +1,37 @@
+.. DFBGN documentation master file, created by
+   sphinx-quickstart on Fri Oct 23 17:28:35 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+DFBGN: Derivative-Free Block Gauss-Newton Optimizer for Least-Squares Minimization
+==================================================================================
+
+**Release:** |version|
+
+**Date:** |today|
+
+**Author:** `Lindon Roberts <lindon.roberts@anu.edu.au>`_
+
+DFBGN is a package for finding local solutions to large-scale nonlinear least-squares minimization problems, without requiring any derivatives of the objective. DFBGN stands for Derivative-Free Block Gauss-Newton.
+
+That is, DFBGN solves
+
+.. math::
+
+   \min_{x\in\mathbb{R}^n} \quad  f(x) := \sum_{i=1}^{m}r_{i}(x)^2
+
+If you wish to solve small-scale least-squares problems, you may wish to try `DFO-LS <https://github.com/numericalalgorithmsgroup/dfols>`_. If you are interested in solving general optimization problems (without a least-squares structure), you may wish to try `Py-BOBYQA <https://github.com/numericalalgorithmsgroup/pybobyqa>`_.
+
+DFBGN is released under the GNU General Public License. Please `contact NAG <http://www.nag.com/content/worldwide-contact-information>`_ for alternative licensing.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   install
+   userguide
+
+Acknowledgements
+----------------
+This software was developed under the supervision of `Coralia Cartis <https://www.maths.ox.ac.uk/people/coralia.cartis>`_, 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) in collaboration with the `Numerical Algorithms Group <http://www.nag.com/>`_.
+

docs/_build/doctrees/install.doctree

@@ -0,0 +1,94 @@
+Installing DFBGN
+================
+
+Requirements
+------------
+DFBGN requires the following software to be installed:
+
+* Python 2.7 or Python 3 (http://www.python.org/)
+
+Additionally, the following python packages should be installed (these will be installed automatically if using *pip*, see `Installation using pip`_):
+
+* NumPy 1.11 or higher (http://www.numpy.org/)
+* SciPy 0.18 or higher (http://www.scipy.org/)
+* Pandas 0.17 or higher (http://pandas.pydata.org/)
+
+Installation using pip
+----------------------
+For easy installation, use `pip <http://www.pip-installer.org/>`_ as root:
+
+ .. code-block:: bash
+
+    $ [sudo] pip install dfbgn
+
+or alternatively *easy_install*:
+
+ .. code-block:: bash
+
+    $ [sudo] easy_install dfbgn
+
+If you do not have root privileges or you want to install DFBGN for your private use, you can use:
+
+ .. code-block:: bash
+
+    $ pip install --user dfbgn
+
+which will install DFBGN in your home directory.
+
+Note that if an older install of DFBGN is present on your system you can use:
+
+ .. code-block:: bash
+
+    $ [sudo] pip install --upgrade dfbgn
+
+to upgrade DFBGN to the latest version.
+
+Manual installation
+-------------------
+Alternatively, you can download the source code from `Github <https://github.com/numericalalgorithmsgroup/dfbgn>`_ and unpack as follows:
+
+ .. code-block:: bash
+
+    $ git clone https://github.com/numericalalgorithmsgroup/dfbgn
+    $ cd dfbgn
+
+DFBGN is written in pure Python and requires no compilation. It can be installed using:
+
+ .. code-block:: bash
+
+    $ [sudo] pip install .
+
+If you do not have root privileges or you want to install DFBGN for your private use, you can use:
+
+ .. code-block:: bash
+
+    $ pip install --user .
+
+instead.
+
+To upgrade DFBGN to the latest version, navigate to the top-level directory (i.e. the one containing :code:`setup.py`) and rerun the installation using :code:`pip`, as above:
+
+ .. code-block:: bash
+
+    $ git pull
+    $ [sudo] pip install .  # with admin privileges
+
+Testing
+-------
+If you installed DFBGN manually, you can test your installation by running:
+
+ .. code-block:: bash
+
+    $ python setup.py test
+
+Alternatively, the HTML documentation provides some simple examples of how to run DFBGN.
+
+Uninstallation
+--------------
+If DFBGN was installed using *pip* you can uninstall as follows:
+
+ .. code-block:: bash
+
+    $ [sudo] pip uninstall dfbgn
+
+If DFBGN was installed manually you have to remove the installed files by hand (located in your python site-packages directory).