
|

.. image:: https://badge.fury.io/py/surmise.svg
    :target: https://badge.fury.io/py/surmise

.. image:: https://github.com/bandframework/surmise/actions/workflows/python-installation.yml/badge.svg
    :target: https://github.com/bandframework/surmise/actions/workflows/python-installation.yml

.. image:: https://coveralls.io/repos/github/bandframework/surmise/badge.svg
    :target: https://coveralls.io/github/bandframework/surmise

|

.. image:: https://readthedocs.org/projects/surmise/badge/?version=latest
   :target: https://surmise.readthedocs.io/en/latest/?badge=latest
   :alt: Documentation Status

.. image:: https://github.com/bandframework/surmise/actions/workflows/publish_book.yml/badge.svg?branch=main
    :target: https://github.com/bandframework/surmise/actions/workflows/publish_book.yml

.. image:: https://jupyterbook.org/badge.svg
    :target: https://bandframework.github.io/surmise

|

.. after_badges_rst_tag

===========================
Introduction to surmise
===========================

surmise is a Python package that is designed to provide a surrogate model
interface for calibration, uncertainty quantification, and sensitivity analysis.

Dependencies
~~~~~~~~~~~~

surmise is built with NumPy_, SciPy_, scikit-learn_, dill_, and pytest_.  Please
refer to the [_requires] sections of setup.py for more details.

Installation
~~~~~~~~~~~~

From the command line, surmise can be installed by executing::

 pip install surmise

The list of available .whl files can be found under `PyPI-wheel`_.  If a wheel
file for your preferred platform is not listed, then surmise has to be built
from source.  There is C code in the package that will be compiled for your
setup by `setuptools`_ during this process.  Therefore, a valid C compiler must
be installed beforehand.  In such cases, the installation should be built
automatically from the source distribution in PyPI when installed via pip.
For those who prefer to work from a clone, please execute an
appropriate version of::

 git clone https://github.com/bandframework/surmise/
 cd surmise
 python -m pip install --upgrade pip
 python -m pip install --upgrade setuptools
 python -m pip install build
 python -m build --wheel
 python -m pip install dist/surmise-<version info>.whl

.. note::
    Currently surmise on Windows system is built and tested with MinGW, in order to support the GCC compiler.
    The expectation is that other Windows build environments are compatible as well.

Testing
~~~~~~~

An automated test suite [1]_ is integrated into the package so that users can
directly test their installation by executing::

 $ python
 >>> import surmise
 >>> surmise.__version__
 <version string>
 >>> surmise.test()

The pytest output should indicate clearly if all tests passed or provide
information related to any failures otherwise.

Documentation
~~~~~~~~~~~~~

The user and developer guides are stored in ``docs/`` and are hosted at `Read the Docs <http://surmise.readthedocs.io>`_.

Examples are stored in ``book/`` and are hosted online as a `Jupyter book <https://bandframework.github.io/surmise>`_.
In addition, for a gentle introduction of emulation and calibration using
Gaussian processes, visit `surmise Jupyter notebook`_.

Users and developers that would like to generate the documentation locally are
encouraged to use ``tox``, which automatically creates a dedicated,
fully-functioning virtual environment for the task.  Refer to the online
developer's guide (or ``docs/tox.rst``) for help setting up ``tox`` and using
it to generate documentation.


**Citation:**

- Please use the following to cite surmise in a publication:

.. code-block:: bibtex

   @techreport{surmise2025,
     author      = {Matthew Plumlee and \"Ozge S\"urer and Stefan M. Wild and Moses Y-H. Chan},
     title       = {{surmise 0.4.0} Users Manual},
     institution = {NAISE},
     number      = {Version 0.4.0},
     year        = {2025},
     url         = {https://surmise.readthedocs.io}
   }


.. _NumPy: http://www.numpy.org
.. _pytest: https://pypi.org/project/pytest/
.. _Python: http://www.python.org
.. _SciPy: http://www.scipy.org
.. _Setuptools: https://setuptools.pypa.io
.. _`surmise Jupyter notebook`: https://colab.research.google.com/drive/1f4gKTCLEAGE8r-aMWOoGvY-O6zNqg1qj?usp=drive_link
.. _PyPI-wheel: https://pypi.org/project/surmise/#files
.. _scikit-learn: https://scikit-learn.org/stable/install.html
.. _dill: https://dill.readthedocs.io
.. [1] There are multiple methods in surmise that are not thoroughly tested via the test suite.
       These methods are either under development, or no longer maintained.  The methods
       are offered for use via an expert user mode, but the associated code files are measured
       with 0% coverage.