surmise 0.4.0

A modular interface for surrogate models and tools

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.

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

[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.