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.

Note

Upgrading from previous repository clone (pre-v.0.3.0)

If you have an existing surmise repository clone and are upgrading from previous versions, you should remove the root/surmise folder for any versions on or after v0.3.0. At v0.3.0, we have migrated from a flat layout to a src layout. As a result, all functional surmise codes live under root/src/surmise. The remaining root/surmise folder may cause unintended errors when importing the package (e.g., a wrong version, testing procedures failing, or coverage report not recording).

See Issues #150, #151 for details.

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.

Examples are stored in book/ and are hosted online as a Jupyter book. 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:

@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}
}