surmise 0.3.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 and scipy, with an optional scikit-learn dependency.

Please refer to the [project] and [project.optional-dependencies] sections of pyproject.toml for details.

Installation

From the command line, use one of the following commands to install surmise:

pip install surmise
pip install surmise[scikit-learn]      # to include scikit-learn in installation
pip install surmise[all]               # to include all optional dependencies

The package scikit-learn is required by specific methods as stated above. These packages can be installed along with surmise via the commands listed.

The list of available .whl files can be found under PyPI-wheel. If a wheel file for your preferred platform is not listed, surmise has to be built from source, which requires extra dependencies:

git clone https://github.com/bandframework/surmise/
cd surmise
python -m pip install --upgrade pip
pip install build Cython
pip install scikit-learn (optional, required by full test suite)
python -m build --wheel
pip install dist/surmise-<version info>.whl

Note

Direct installation of surmise requires Cython to build C executable. On a Windows platform Cython is supported by Microsoft build tools, for which installation is outside pip; see Microsoft build tools for details.

Testing

Testing of surmise can be performed after cloning the repository. The test suite requires the pytest, pytest-cov, and scikit-learn packages to be installed. These packages can be installed via:

pip install pytest pytest-cov scikit-learn

The full test suite can then be run from the tests/ directory of the source distribution by the command:

cd /path/to/surmise/tests/
python -m pytest        # (no coverage report)
python -m pytest --cov  # (with console coverage report)

Access to the test suite with specific testing options are available in the tests directory. To see a complete list of options, run:

./path/to/surmise/tests/run-tests.sh -h

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.