Timestep Optimization
===========================

The choice of timestep :math:`\Delta t` and relaxation coefficients 
:math:`\lambda_i` comprise the field updater parameters which affect how many 
timesteps are needed to converge or equilibrate an OpenFTS simulation. In some 
cases, a simulation requires specific :math:`\Delta t` and :math:`\lambda_i` 
in order to converge. The choice of :math:`\Delta t` and :math:`\lambda_i` is 
often nontrivial, resulting in many trials and errors to find optimal values.

To help with this, OpenFTS offers timestep optimization through the
TimestepOptimizer class. TimestepOptimizer can efficiently find optimal 
:math:`\Delta t` and :math:`\lambda_i` by searching comprehensively through 
brute force methods or by searching efficiently through Bayesian optimized 
methods. Using TimestepOptimizer has the following general procedure ::

    import openfts
    fts = openfts.OpenFTS()                         # create an OpenFTS object
    ...                                             # edit the OpenFTS object
    optimizer = openfts.TimestepOptimizer(fts)      # create a TimestepOptimizer object
    optimizer.set_search_method(...)                # set the search method
    optimizer.run(...)                              # run TimestepOptimizer
    optimizer.write_results()                       # write results to 'results.json'
    optimizer.plot_results()                        # visualize results

where below is the comprehensive API to interface with TimestepOptimizer 
(generated via sphinx.autodoc).

.. autoclass:: openfts.TimestepOptimizer
    :members:
    :undoc-members:

.. automodule:: manual_search
    :members:
    :undoc-members:

.. automodule:: grid_search
    :members:
    :undoc-members:

.. automodule:: bayes_opt_search
    :members:
    :undoc-members:
    :exclude-members: get_next_lambdas, get_nlambdas, remove_lambdas