Algorithm Development

PyBNF was designed with extensibility in mind. As a result, all of the algorithms implemented here subclass the Algorithm class found in PyBNF algorithms (pybnf.algorithms).

Implementation

A new algorithm can be written by creating a class that subclasses the Algorithm class:

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

If the new algorithm requires user configuration via the configuration file, new options may be added to the pybnf.parse module. The configuration parser uses the pyparsing module and new grammars for parsing individual lines may be added to the pybnf.parse.parse function based on the key text. Default values for parameters may be added to the Configuration object via its default_config method in the pybnf.config module if desired. Other supporting configuration methods should also be added to the Configuration object if necessary.

Pull requests

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