Algorithm Development
=====================

PyBNF was designed with extensibility in mind.  As a result, all of the algorithms implemented here subclass the
Algorithm class found in :ref:`alg_module`.

Implementation
--------------
A new algorithm can be written by creating a class that subclasses the Algorithm class and
registering it with the ``@register_fit_type`` decorator (from ``pybnf.registry``), which
names the ``fit_type`` / ``job_type`` code(s) that select it, its family (``optimizer``,
``sampler``, or ``checker``), a display name, and its config schema (see `Adding configuration
options`_)::

    from pybnf.registry import register_fit_type

    @register_fit_type('newalg', family='optimizer', display_name='My Algorithm',
                       schema=NewAlgorithmConfig)
    class NewAlgorithm(Algorithm):
        def __init__(self, config, **kwargs):
            super(NewAlgorithm, self).__init__(config)
            # Other setup that may involve additional arguments

        def my_custom_function(self):
            # User defined support function
            ...

The new algorithm requires defining three methods, with the first being the ``__init__`` constructor method.  This
method will likely take a Configuration object as its first argument.  The other two required methods that must be
implemented are the ``start_run`` and ``got_result`` methods.

The ``start_run`` method is called at the start of the fitting run. It must return a list of PSet instances, as the first batch of parameter sets
to be evaluated. The Algorithm superclass functions ``random_pset`` and ``random_latin_hypercube_psets`` may be useful::

    def start_run(self):
        return self.random_latin_hypercube_psets(self.population_size)

The ``got_result`` method is called each time an evaluation of a PSet is completed on a worker. It takes a Result instance 
as an argument and returns either a list of new PSet instances for
another round of parameter set evaluations, or the string "STOP" to terminate the fitting run.  Note that an empty list
is valid if the algorithm requires synchronization (and thus must wait for all jobs in the current iteration to
finish). For example::

    def got_result(self, res):
        if self.satisfies_stop_condition(res):
            return "STOP"  # Terminates algorithm

        self.current_iter_results.append(res)
        if self.ready_for_next_iter:  # Synchronization check
            new_psets = []
            for r in self.current_iter_results:
                new_psets.append(self.generate_new_pset(r))
            return new_psets
        else:
            return []  # Waiting for synchronization


Four additional support methods in the Algorithm superclass may optionally be overridden, depending on the details of the new algorithm, 
such that the new algorithm is compatible with all features of PyBNF. 

    * ``add_iterations(self,n)`` is required to support adding extra iterations with the ``-r`` flag. This method should add ``n`` iterations to the algorithm's maximum iteration count. The superclass implementation simply adds ``n`` to the attribute ``self.max_iterations``. You should override the method if your algorithm tracks iteration count in a different way. 
    * ``reset(self, bootstrap)`` is required to support bootstrapping. This method should call the superclass method, and then reset the state of the algorithm so that another fitting replicate can be run. 
    * ``get_backup_every(self)`` helps choose when to save a backup of the algorithm. This method should return an integer telling after how many individual simulations we should back up the algorithm. The superclass implementation uses a formula that should work in most cases, but you can override this depending on details of your algorithm. 
    * ``cleanup(self)`` is used to clean up after an error. This method is called just before PyBNF exits due to an error or keyboard interrupt, and may be used to save any useful files before exiting. 



Adding configuration options
----------------------------

An algorithm's user-settable options live in a **Pydantic config schema** — a class
subclassing ``PyBNFConfigModel`` (or a family base such as ``MCMCFamilyConfig``), co-located
with the algorithm class and wired to the fit type through the ``schema=`` argument of
``@register_fit_type``. The schema is the single source of truth for the method's option
names, types, and defaults; each fit's effective config is narrowed to the global keys plus
its own schema's keys, so a method only ever sees the options it reads::

    from pybnf.config_schema import PyBNFConfigModel

    class NewAlgorithmConfig(PyBNFConfigModel):
        my_option: float = 1.0          # a new key, with its type and default
        my_count: int = 10

A new numeric key must also be listed in the appropriate token-type list in ``pybnf.parse``
(for example ``numkeys_int`` or ``numkeys_float``) so the configuration parser reads and
coerces its value. The parser uses the ``pyparsing`` module; a key with a more elaborate
grammar than a single scalar adds a parse rule there as well.

Pull requests
-------------

To have new algorithms added into the PyBNF software suite, submit a pull request to the main branch at
`<https://github.com/lanl/PyBNF>`_