Metadata-Version: 2.4
Name: surmise
Version: 1.0.0
Summary: A modular interface for surrogate models and tools
Home-page: https://github.com/bandframework/surmise
Author: Matthew Plumlee, Özge Sürer, Stefan M. Wild, Moses Y.-H. Chan, and Jared O'Neal
Author-email: moses.chan@northwestern.edu
Maintainer: Moses Y.-H. Chan
Maintainer-email: moses.chan@northwestern.edu
License: MIT
Project-URL: Source, https://github.com/bandframework/surmise
Project-URL: Documentation, https://surmise.readthedocs.io
Project-URL: Tracker, https://github.com/bandframework/surmise/issues
Keywords: surmise
Classifier: Natural Language :: English
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: numpy>=1.23.2
Requires-Dist: scipy>=1.9.2
Requires-Dist: scikit-learn>=1.2.0
Requires-Dist: dill>=0.3.8
Requires-Dist: pytest
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary


|

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

|

.. 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`` variables in ``setup.py`` for more details.

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

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

 python -m 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 .

.. 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 <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{surmise2026,
     author      = {Matthew Plumlee and \"Ozge S\"urer and Stefan M. Wild and Moses Y-H. Chan and Jared O'Neal},
     title       = {{surmise 1.0.0} Users Manual},
     institution = {NAISE},
     number      = {Version 1.0.0},
     year        = {2026},
     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
.. _`Issues #150`: https://github.com/bandframework/surmise/pull/150
.. _#151: https://github.com/bandframework/surmise/pull/151
.. [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.
