Metadata-Version: 2.1
Name: aalto-boss
Version: 1.6.2
Summary: Bayesian optimization structure search
Home-page: https://gitlab.com/cest-group/boss
Author: Ville Parkkinen, Henri Paulamaki, Arttu Tolvanen, Ulpu Remes, Nuutti Sten, Emma Lehto, Manuel Kuchelmeister, Tuomas Rossi, Joakim Loefgren, Milica Todorovic, 
Maintainer: The BOSS developers team
Maintainer-email: milica.todorovic@utu.fi
License: Apache License 2.0
Description: BOSS
        =========
        Bayesian Optimization Structure Search (BOSS) is a general-purpose Bayesian Optimization code. It is designed to facilitate machine learning in computational and experimental natural sciences.
        
        For a more detailed description of the code and tutorials, please consult the `user guide <https://cest-group.gitlab.io/boss>`_.
        
        Installation
        ------------
        BOSS is distributed as a PyPI package and can be installed using pip::
        
            python3 -m pip install aalto-boss
        
        We recommend installing BOSS inside a virtual environment (``venv``, ``conda``...). If you are not using virtual environments, we recommend performing a user-installation instead::
        
            python3 -m pip install --user aalto-boss
        
        Basic usage
        -----------
        As an easy example, consider the optimization of a bounded 1D function. BOSS can be run either directly from Python or via a CLI interface, both these approaches are illustrated briefly below. Note that BOSS always minimizes a given function.
        
        Python iterface
        ^^^^^^^^^^^^^^^^^^^^^
        To run BOSS from Python we first define our objective function, by default BOSS expects this function to take a single 2D numpy array as argument (this behaviour can be modified) and return a scalar value. Next, we import the ``BOMain`` object and feed it the function plus any number of BOSS keywords, after which the optimization can be started. Once finished, the optimziation results are returned in a ``BOResults`` object.
        
        .. code-block:: python
        
            """ Using BOSS to solve the minimization problem
            f(x) = sin(x) + 1.5*exp(-(x-4.3)**2) , 0 < x < 7
            """
            import numpy as np
            from boss.bo.bo_main import BOMain
            from boss.pp.pp_main import PPMain
        
            def func(X):
                """ BOSS-compatible definition of the function. """
                x = X[0, 0]
                return np.sin(x) + 1.5*np.exp(-(x - 4.3)**2)
        
            if __name__ == '__main__':
                bo = BOMain(
                    func, 
                    np.array([[0., 7.]]),  # bounds
                    yrange=[-1, 1],
                    kernel='rbf',
                    initpts=5,
                    iterpts=15,
                )
                res = bo.run()
        
                # print global minimum value and location from the last iteration
                print(res.select('mu_glmin', -1), res.select('x_glmin', -1))
        
                # run BOSS post-processing
                # creates a folder "postprocessing" with plots and data
                pp = PPMain(res, pp_models=True, pp_acq_funcs=True)
                pp.run()
        
        
        Command-line iterface
        ^^^^^^^^^^^^^^^^^^^^^
        The CLI is provided by an executable called ``boss``. The user must provide an input file containing a list of BOSS keywords and a separate Python script that defines a function to be optimized. By default, BOSS expects this function to take a single 2D numpy array as argument (this behaviour can be modified) and return a scalar value. Below we define such a function in a Python script, arbitrarily named ``user_function.py``:
        
        .. code-block:: python
        
            """ user_function.py
            This script contains the function definition for the minimization problem
            f(x) = sin(x) + 1.5*exp(-(x-4.3)**2) ,  0 < x < 7
            Note that the bounds are specified in the BOSS input file.
            """
            import numpy as np
        
            def func(X):
                """ BOSS-compatible definition of the function. """
                x = X[0, 0]
                return np.sin(x) + 1.5*np.exp(-(x - 4.3)**2)
        
        
        To minimize this function subject to the constraint *0 < x < 7*, we define a BOSS input file ``boss.in``:
        
        .. code-block:: python
        
            # boss.in
            userfn        user_function.py func
            bounds        0 7
            yrange        -1 1
            kernel        rbf
            initpts       5
            iterpts       15
        
        The optimization (including post-processing) can now be started from the command line:
        
        .. code-block:: bash
        
            $ boss op boss.in
        
        Credits
        -------
        BOSS is under active development in the `Materials Informatics Laboratory` at the University of Turku and the `Computational Electronic Structure Theory (CEST) group <http://cest.aalto.fi/>`_ at Aalto University. Past and present members of development team include
        
        * Ville Parkkinen
        * Henri Paulamäki
        * Arttu Tolvanen
        * Ulpu Remes
        * Nuutti Sten
        * Emma Lehto
        * Tuomas Rossi
        * Manuel Kuchelmeister
        * Joakim Löfgren (maintainer)
        * Milica Todorović (team lead)
        
        If you wish to use BOSS in your research, please cite
        
        | Milica Todorovic, Micheal U. Gutmann, Jukka Corander, and Patrick Rinke
        | *Bayesian inference of atomistic structure in functional materials*
        | npj Comput Mater **5**, 35 (2019)
        | `doi: 10.1038/s41524-019-0175-2 <https://doi.org/10.1038/s41524-019-0175-2>`_
        
        Issues and feature requests
        ---------------------------
        It is strongly encouraged to submit bug reports, questions, and feature requests via the
        `gitlab issue tracker <https://gitlab.com/cest-group/boss/issues>`_.
        The BOSS development team can be contacted by email at milica.todorovic@utu.fi
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
