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 (TBC). 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 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 documentation is stored in docs/ and is hosted at Read the Docs.

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{surmise2024,
  author      = {Matthew Plumlee and \"Ozge S\"urer and Stefan M. Wild and Moses Y-H. Chan},
  title       = {{surmise 0.3.0} Users Manual},
  institution = {NAISE},
  number      = {Version 0.3.0},
  year        = {2024},
  url         = {https://surmise.readthedocs.io}
}

Examples

We provide examples in the examples/ directory to illustrate the basic usage of surmise.

In addition, for a gentle introduction of emulation and calibration using Gaussian processes, visit surmise Jupyter notebook.