Rebuild documentation

docs/_build/html/.buildinfo

@@ -1,4 +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: ce4a7ee5f914befb831f556352909169
+config: b31432171e0b7e659b4917e6c7cf980a
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_build/html/_sources/building.rst.txt

@@ -15,7 +15,7 @@ We can check the properties of a specific problem with `problem_properties() <fu
       import pycutest
 
       # Find unconstrained, variable-dimension problems
-      probs = pycutest.find_problems(constraints='U', userN=True)
+      probs = pycutest.find_problems(constraints='unconstrained', userN=True)
       print(sorted(probs)[:5])
 
       # Properties of problem ROSENBR
@@ -28,7 +28,7 @@ Which produces the output:
       # List of unconstrained, variable-dimension problems
       ['ARGLINA', 'ARGLINB', 'ARGLINC', 'ARGTRIGLS', 'ARWHEAD']
       # Properties of problem 'ROSENBR'
-      {'internal': False, 'degree': 2, 'n': 2, 'm': 0, 'objective': 'S', 'origin': 'A', 'constraints': 'U', 'regular': True}
+      {'objective': 'sum of squares', 'constraints': 'unconstrained', 'regular': True, 'degree': 2, 'origin': 'academic', 'internal': False, 'n': 2, 'm': 0}
 
 Full documentation for these functions is given below.
 

docs/_build/html/_sources/contributing.rst.txt

@@ -1,6 +1,49 @@
 Contributing
 ============
 
-We welcome contributions to PyCUTEst, please create a pull request on our `PyCUTEst GitHub repository <https://github.com/jfowkes/pycutest/>`_ where your contribution will be reviewed.
-For instructions on creating pull requests, please see the `GitHub documentation <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`_.
-All pull requests will be automatically tested using GitHub's continuous integration framework.
+Contributing to PyCUTEst
+------------------------
+
+Contributions to PyCUTEst are most welcome.
+
+Reporting Bugs / Feature Suggestions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you find a bug in PyCUTEst, or have a suggestion about how PyCUTEst can be improved, please
+`create a Github issue <https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue>`_.
+It would be helpful if you first check the `existing list of open issues <https://github.com/jfowkes/pycutest/issues>`_
+to see if someone else has reported the same thing - in this case it would be better to comment on the existing issue
+rather than creating a new one.
+
+When reporting a bug, it would be helpful if you could include:
+
+* An informative title and clear description
+* A code snippet showing how the error occurred
+* Any relevant Python output messages
+* Information about your installation (e.g. operating system, Python version/distribution, PyCUTEst version)
+
+Submitting code changes
+^^^^^^^^^^^^^^^^^^^^^^^
+
+We are happy to accept code contributions from the PyCUTEst community.
+If you have made a change (bugfix, new feature, documentation improvement, etc), then please
+`submit a pull request <https://github.com/jfowkes/pycutest/pulls>`_.
+Github has `more information on pull requests <https://docs.github.com/en/pull-requests>`_.
+Please ensure that:
+
+* Your description clearly explains your changes
+* You have updated the documentation in :code:`docs`.
+  We use `Sphinx <https://www.sphinx-doc.org/en/master/>`_ to create our documentation.
+  You will need to install both the Sphinx and sphinx-rtd-theme packages.
+* You have included relevant unit tests in :code:`pycutest/tests`.
+  We use `nose <https://nose.readthedocs.io/en/latest/>`_ to run our unit tests
+  but we do also provide a :code:`tox.ini` for local testing using `tox <https://tox.wiki/en/latest/>`_.
+
+If you are fixing an issue, please reference the issue number in the pull request.
+
+Code of Conduct
+^^^^^^^^^^^^^^^
+We expect everyone in the PyCUTEst community to show respect to each other and behave appropriately at all times.
+Abusive language, harassment and inappropriate/unprofessional language is not acceptable.
+Instances of unacceptable behavior can be reported to the PyCUTEst team
+(`Jari <mailto:jaroslav.fowkes@stfc.ac.uk>`_ and `Lindon <mailto:lindon.roberts@sydney.edu.au>`_).

docs/_build/html/_sources/example.rst.txt

@@ -56,7 +56,7 @@ For this problem, Newton's method finds the unique local and global minimum :cod
 
 Nonlinear least-squares
 -----------------------
-In CUTEst nonlinear least-squares problems are encoded as nonlinear equations which have no objective function defined (as denoted by the :code:`N` in their classification).
+In CUTEst nonlinear least-squares problems are encoded as nonlinear equations which have no objective function defined (as denoted by 'none' in their classification).
 Instead, their residual(s) :code:`r(x)` and Jacobian :code:`J(x)` are accessed using `CUTEstProblem.cons() <methods/pycutest.CUTEstProblem.cons.html>`_.
 Typically you will want to use them as nonlinear least-squares problems, in which case you can construct a standard objective function and gradient as:
 

docs/_build/html/_sources/history.rst.txt

@@ -2,6 +2,13 @@ Version History
 ===============
 This section lists the different versions of PyCUTEst and the updates between them.
 
+Version 1.3 (6 Sep 2022)
+------------------------
+* Use human-readable problem properties (breaking change)
+* Add guidelines for contributors
+* Simplify CUTEst installation
+* Add CUTEst docker install option
+
 Version 1.2 (21 Feb 2022)
 -------------------------
 * Use setuptools instead of distutils

docs/_build/html/_sources/index.rst.txt

@@ -10,7 +10,7 @@ Python interface to the CUTEst optimization test environment
 
 **Release:** |version|
 
-**Date:** 21 February 2022
+**Date:** 6 September 2022
 
 **Author:** `Jaroslav Fowkes <jaroslav.fowkes@maths.ox.ac.uk>`_ and `Lindon Roberts <https://lindonroberts.github.io/>`_
 

docs/_build/html/_sources/install.rst.txt

@@ -8,11 +8,6 @@ PyCUTEst requires the following software to be installed:
 * Python 2.7 or Python 3 (http://www.python.org/)
 * CUTEst (see below)
 
-Additionally, the following python packages should be installed (these will be installed automatically if using *pip*, see `Installing PyCUTEst using pip`_):
-
-* NumPy 1.11 or higher (http://www.numpy.org/)
-* SciPy 0.18 or higher (http://www.scipy.org/)
-
 **Please Note:** Currently PyCUTEst only supports Mac and Linux. For Windows 10 (or later), PyCUTEst can be used through the `Windows Subsystem for Linux <https://docs.microsoft.com/en-us/windows/wsl/>`_, following the Linux installation instructions.
 
 Installing CUTEst
@@ -51,21 +46,8 @@ Now we are ready to install CUTEst in double precision (requires :code:`gfortran
 
  .. code-block:: bash
 
-    $ cd /path/to/cutest/cutest/
-    $ ${ARCHDEFS}/install_optrove
-    Do you wish to install CUTEst (Y/n)? Y
-    Do you require the CUTEst-Matlab interface (y/N)? N
-    Select platform: 6 # PC with generic 64-bit processor
-    Select operating system: 3 # Linux
-    Would you like to review and modify the system commands (y/N)? N
-    Select fortran compiler: 6 # GNU gfortran compiler
-    Would you like to review and modify the fortran compiler settings (y/N)? N
-    Select C compiler: 8 # GCC
-    Would you like to review and modify the C compiler settings (y/N)? N
-    Would you like to compile SIFDecode (Y/n)? Y
-    Would you like to compile CUTEst (Y/n)? Y
-    CUTEst may be compiled in (S)ingle or (D)ouble precision or (B)oth.
-    Which precision do you require for the installed subset (D/s/b) ? D
+    $ source ~/.bashrc # load above environment variables
+    $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/jfowkes/pycutest/master/.install_cutest.sh)"
 
 And CUTEst should run from here. To test that the installation works, issue the commands:
 
@@ -74,7 +56,7 @@ And CUTEst should run from here. To test that the installation works, issue the
     $ cd $SIFDECODE/src ; make -f $SIFDECODE/makefiles/$MYARCH test
     $ cd $CUTEST/src ; make -f $CUTEST/makefiles/$MYARCH test
 
-**Please Note:** *currently PyCUTEst only supports gfortran and uses the default version on your path (as returned by* :code:`gfortran -v` *). Please ensure this is the same version that you install CUTEst with above otherwise you may experience segmentation faults, this should be the case if you select the generic* :code:`GNU gfortran compiler` *as the fortran compiler in the installer above.*
+**Please Note:** *currently PyCUTEst only supports gfortran and uses the default version on your path (as returned by* :code:`gfortran -v` *). Please ensure this is the same version that you install CUTEst with above otherwise you may experience segmentation faults.*
 
 Installing CUTEst on Mac
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -118,24 +100,27 @@ CUTEst can be installed into its own Docker container. Create a file named :code
     ENV MASTSIF /cutest/mastsif/
     ENV CUTEST /cutest/cutest/
     ENV MYARCH "pc64.lnx.gfo"
-    ENTRYPOINT ./archdefs/install_optrove && tail -f /dev/null
+
+    RUN wget https://raw.githubusercontent.com/jfowkes/pycutest/master/.install_cutest.sh
+    RUN chmod +x .install_cutest.sh
+    RUN ./.install_cutest.sh
+
+    ENTRYPOINT tail -f /dev/null
 
 You can then build, launch, and login to the container in the usual way:
 
  .. code-block:: bash
 
-    $ docker build -t cutest .          # build the container
-    $ docker run -dt cutest             # launch the container
-    $ docker exec -it cutest /bin/bash  # login to the container
+    $ docker build -t cutest .               # build the container
+    $ docker run --name mycutest -dt cutest  # launch the container
+    $ docker exec -it mycutest /bin/bash     # login to the container
 
 Please see the `docker docs <https://docs.docker.com/get-started/>`_ for more details on using docker containers.
 
 Installing PyCUTEst
 -------------------
-Note that CUTEst must be installed in order for PyCUTEst to work (see above).
+**Please Note:** *CUTEst must be installed in order for PyCUTEst to work (see* `Installing CUTEst`_ *).*
 
-Installing PyCUTEst using pip
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 For easy installation, use `pip <http://www.pip-installer.org/>`_:
 
  .. code-block:: bash
@@ -164,33 +149,7 @@ And set an environment variable to tell PyCUTEst about this directory, by adding
 
 If you do not set this environment variable, then PyCUTEst will create a cache folder of compiled problems inside your current working directory.
 
-Manual installation of PyCUTEst
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Alternatively, you can download the source code from `Github <https://github.com/jfowkes/pycutest>`_ and unpack as follows:
-
- .. code-block:: bash
-
-    $ git clone https://github.com/jfowkes/pycutest
-    $ cd pycutest
-
-PyCUTEst is written in pure Python and requires no compilation. It can be installed using:
-
- .. code-block:: bash
-
-    $ pip install .
-
-**Please Note:** *don't forget to set up your cache and associated environment variable (see above).*
-
-To upgrade PyCUTEst to the latest version, navigate to the top-level directory (i.e. the one containing :code:`setup.py`) and re-run the installation using :code:`pip`, as above:
-
- .. code-block:: bash
-
-    $ git pull
-    $ pip install .
-
-Uninstallation of PyCUTEst
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-You can uninstall PyCUTEst as follows:
+Note that you can uninstall PyCUTEst as follows:
 
  .. code-block:: bash
 

docs/_build/html/_static/basic.css

@@ -236,16 +236,6 @@ div.body p, div.body dd, div.body li, div.body blockquote {
 a.headerlink {
     visibility: hidden;
 }
-a.brackets:before,
-span.brackets > a:before{
-    content: "[";
-}
-
-a.brackets:after,
-span.brackets > a:after {
-    content: "]";
-}
-
 
 h1:hover > a.headerlink,
 h2:hover > a.headerlink,
@@ -334,11 +324,15 @@ aside.sidebar {
 p.sidebar-title {
     font-weight: bold;
 }
+nav.contents,
+aside.topic,
 div.admonition, div.topic, blockquote {
     clear: left;
 }
 
 /* -- topics ---------------------------------------------------------------- */
+nav.contents,
+aside.topic,
 div.topic {
     border: 1px solid #ccc;
     padding: 7px;
@@ -377,13 +371,17 @@ div.body p.centered {
 
 div.sidebar > :last-child,
 aside.sidebar > :last-child,
+nav.contents > :last-child,
+aside.topic > :last-child,
 div.topic > :last-child,
 div.admonition > :last-child {
     margin-bottom: 0;
 }
 
 div.sidebar::after,
 aside.sidebar::after,
+nav.contents::after,
+aside.topic::after,
 div.topic::after,
 div.admonition::after,
 blockquote::after {
@@ -608,26 +606,6 @@ ol.simple p,
 ul.simple p {
     margin-bottom: 0;
 }
-
-/* Docutils 0.17 and older (footnotes & citations) */
-dl.footnote > dt,
-dl.citation > dt {
-    float: left;
-    margin-right: 0.5em;
-}
-
-dl.footnote > dd,
-dl.citation > dd {
-    margin-bottom: 0em;
-}
-
-dl.footnote > dd:after,
-dl.citation > dd:after {
-    content: "";
-    clear: both;
-}
-
-/* Docutils 0.18+ (footnotes & citations) */
 aside.footnote > span,
 div.citation > span {
     float: left;
@@ -652,8 +630,6 @@ div.citation > p:last-of-type:after {
     clear: both;
 }
 
-/* Footnotes & citations ends */
-
 dl.field-list {
     display: grid;
     grid-template-columns: fit-content(30%) auto;
@@ -666,10 +642,6 @@ dl.field-list > dt {
     padding-right: 5px;
 }
 
-dl.field-list > dt:after {
-    content: ":";
-}
-
 dl.field-list > dd {
     padding-left: 0.5em;
     margin-top: 0em;

docs/_build/html/_static/documentation_options.js

@@ -1,6 +1,6 @@
 var DOCUMENTATION_OPTIONS = {
     URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
-    VERSION: '1.2',
+    VERSION: '1.3',
     LANGUAGE: 'en',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',
@@ -10,5 +10,5 @@ var DOCUMENTATION_OPTIONS = {
     SOURCELINK_SUFFIX: '.txt',
     NAVIGATION_WITH_KEYS: false,
     SHOW_SEARCH_SUMMARY: true,
-    ENABLE_SEARCH_SHORTCUTS: false,
+    ENABLE_SEARCH_SHORTCUTS: true,
 };

docs/_build/html/_static/searchtools.js

@@ -88,7 +88,7 @@ const _displayItem = (item, highlightTerms, searchTerms) => {
   linkEl.href = linkUrl + "?" + params.toString() + anchor;
   linkEl.innerHTML = title;
   if (descr)
-    listItem.appendChild(document.createElement("span")).innerText =
+    listItem.appendChild(document.createElement("span")).innerHTML =
       " (" + descr + ")";
   else if (showSearchSummary)
     fetch(requestUrl)
@@ -155,10 +155,8 @@ const Search = {
   _pulse_status: -1,
 
   htmlToText: (htmlString) => {
-    const htmlElement = document
-      .createRange()
-      .createContextualFragment(htmlString);
-    _removeChildren(htmlElement.querySelectorAll(".headerlink"));
+    const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html');
+    htmlElement.querySelectorAll(".headerlink").forEach((el) => { el.remove() });
     const docContent = htmlElement.querySelector('[role="main"]');
     if (docContent !== undefined) return docContent.textContent;
     console.warn(
@@ -504,21 +502,22 @@ const Search = {
    * latter for highlighting it.
    */
   makeSearchSummary: (htmlText, keywords, highlightWords) => {
-    const text = Search.htmlToText(htmlText).toLowerCase();
+    const text = Search.htmlToText(htmlText);
     if (text === "") return null;
 
+    const textLower = text.toLowerCase();
     const actualStartPosition = [...keywords]
-      .map((k) => text.indexOf(k.toLowerCase()))
+      .map((k) => textLower.indexOf(k.toLowerCase()))
       .filter((i) => i > -1)
       .slice(-1)[0];
     const startWithContext = Math.max(actualStartPosition - 120, 0);
 
     const top = startWithContext === 0 ? "" : "...";
     const tail = startWithContext + 240 < text.length ? "..." : "";
 
-    let summary = document.createElement("div");
+    let summary = document.createElement("p");
     summary.classList.add("context");
-    summary.innerText = top + text.substr(startWithContext, 240).trim() + tail;
+    summary.textContent = top + text.substr(startWithContext, 240).trim() + tail;
 
     highlightWords.forEach((highlightWord) =>
       _highlightText(summary, highlightWord, "highlighted")