|pounders|
==========
General Description
-------------------
The Practical Optimization Using No Derivatives and Exploiting Recognized
Structure method, better known as |pounders|, solves the optimization
problem

.. math::
    \min_{\psp \in \R^{\np}} \hfun(\Ffun(\psp))

subject to

.. math::
    Low_j \leq \pspcomp{j} \le Upp_j, j=1,...,\np

* where :math:`\Ffun` is a vector-valued, user-provided blackbox ("zeroth-order") function from :math:`\R^{\np}` to :math:`\R^{\nd}`,
* :math:`\hfun` is a smooth function mapping from :math:`\R^{\nd}` to :math:`\R`,
* :math:`Low` is a user-provided boundary constraint that permits values of
  :math:`-\infty` to specify that the problem is unconstrained for the
  associated parameter, and
* :math:`Upp` is a user-provided boundary constraint that permits values of
  :math:`+\infty` to specify that the problem is unconstrained for the
  associated parameter.

Originally, |pounders| was designed to
minimize only "sum of squares" mappings of
blackbox functions, that is, |pounders| solved

.. math::
   \min_{\psp \in \R^{\np}} \left\{f(\psp)=\sum_{i=1}^{\nd} \Ffuncomp{i}(\psp)^2\right\}

subject to

.. math::
    Low_j \le \pspcomp{j} \le Upp_j, j=1,...,\np.

As such, the current implementation of |pounders| generalizes the class of
functions to which |pounders| can be applied.

|pounders| will never attempt to evaluate :math:`\Ffun` outside of the provided bounds, but it is
possible to take advantage of function values at infeasible :math:`\psp` if
these are passed initially through the ``(X_init,F_init)`` entries of ``Prior``.  In each iteration,
|pounders| forms a set of quadratic models interpolating each of the :math:`\np` functions in
:math:`\Ffun` and minimizes a derived scalar-valued model of :math:`f` within an
infinity-norm trust region.

If a user wishes to employ an outer function :math:`\hfun` other than a
sum-of-squares, then the user must specify a custom outer-function :math:`\hfun`
that maps vectors in :math:`\R^{\nd}` to a scalar value.
In that case, users must also provide a "combine
models" function that |pounders| uses to map the linear and quadratic terms from
the quadratic models of :math:`\Ffun` into a single quadratic model.

For more detailed information please refer to :cite:t:`POUNDERS_TAO_2017`.  A
brief description can also be found in :cite:t:`UNEDF0_2010`.

We provide two implementations of |pounders|, namely, `pounders` and `pounders_concurrent`.

Programmatic Interface
----------------------
Status Code
^^^^^^^^^^^
Both |pounders| implementations return a termination criteria flag.  The
interpretation of the value of the flag is identical across both implementations and is defined by:

* 0 - normal termination because norm of :math:`\gradf(\psp)` at final
  :math:`\psp` satisfied user-provided gradient tolerance,
* > 0 - the budget specified in `nf_max` was reached; the value of the flag is the 2-norm of
  :math:`\gradf` at final :math:`\psp`
* -1 - input was fatally incorrect (error message shown)
* -2 - a valid model produced ``X[nf] == X[xk_in]`` or ``(mdec == 0, hF[nf] == hF[xk_in])``
  (this indicates that the TRSP solver failed to find decrease in the model)
* -3 - a ``NaN`` was encountered
* -4 - error in trust-region subproblem solver
* -5 - an attempt at model improvement failed
* -6 - the trust-region radius `delta` has shrunk to`delta_min`, and the model is valid

The programmatic interface is generally maintained identical between both
implementations.  Nevertheless, we provide the interface for each implementation
to provide language-specific descriptions.

Python
^^^^^^
.. autofunction:: ibcdfo.run_pounders
.. autofunction:: ibcdfo.run_pounders_concurrent

|matlab|
^^^^^^^^
.. mat:autofunction:: pounders.m.pounders

General :math:`\hfun` Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following :math:`\hfun` functions are available for immediate use with both
the Python and |matlab| implementations of |pounders|.  While they are presented
through their integration into the Python package, the documentation is valid
for the |matlab| version of these functions, which are located in
``pounders/m/general_h_funs``.

.. autofunction:: ibcdfo.pounders.h_leastsquares
.. autofunction:: ibcdfo.pounders.h_neg_leastsquares
.. autofunction:: ibcdfo.pounders.h_identity
.. autofunction:: ibcdfo.pounders.h_emittance

Parameterized :math:`\hfun` Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|pounders| permits parameterized :math:`\hfun` functions, which it can use
only once users have chosen a single set of parameter values for formulating a
specific :math:`\hfun` function and, therefore, a single related problem.  As an example, the
following routine can be used to create a single ``hfun`` and ``combinemodels``
matched pair for a single set of desired parameter values.  While this routine
is presented through its integration into the Python package, the
documentation is valid for the |matlab| version of these routines, which is
located in ``pounders/m/general_h_funs``.

.. autofunction:: ibcdfo.pounders.create_squared_diff_from_mean_functions