From a7c0d970faaca0f841852e730683f0ba4ca41251 Mon Sep 17 00:00:00 2001 From: Moses Chan Date: Sat, 30 May 2026 09:34:50 -0500 Subject: [PATCH 1/4] correction of inheritance class description. --- docs/howtocalibration.rst | 5 ++--- docs/howtoemulation.rst | 4 ++-- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/howtocalibration.rst b/docs/howtocalibration.rst index 67ac4bfd..ae54f0bb 100644 --- a/docs/howtocalibration.rst +++ b/docs/howtocalibration.rst @@ -5,9 +5,8 @@ In this tutorial, we describe how to include a new calibrator to the surmise's framework. We illustrate this with ``directbayeswoodbury``--a calibrator method located in the directory ``\calibrationmethods``. -In surmise, all calibrator methods inherit from the base class -:py:class:`surmise.calibration.calibrator`. A calibrator class calls the user -input method, and fits the corresponding calibrator. +In surmise, all calibrator methods are automatically discovered from `.py` code files under `src/surmise/calibrationmethods`. +A calibrator class calls the user input method via the filename without extension, e.g., `directbayeswoodbury`, and fits the corresponding calibrator. :py:meth:`surmise.calibration.calibrator.fit` is the main :py:class:`surmise.calibration.calibrator` class methods. It also provides the functionality of updating and manipulating the fitted calibrator by diff --git a/docs/howtoemulation.rst b/docs/howtoemulation.rst index 2e00b02f..103f0b83 100644 --- a/docs/howtoemulation.rst +++ b/docs/howtoemulation.rst @@ -5,8 +5,8 @@ In this tutorial, we describe how to include a new emulator to the surmise's framework. We illustrate this with ``PCGP``--an emulator method located in the directory ``\emulationmethods``. -In surmise, all emulator methods inherit from the base class :py:class:`surmise.emulation.emulator`. -An emulator class calls the user input method, and fits the corresponding +In surmise, all emulator methods are automatically discovered from `.py` code files under `src/surmise/emulationmethods`. +An emulator class calls the user input method by the filename of the respective `.py` file, e.g., `PCGP` for `PCGP.py`, and fits the corresponding emulator. :py:func:`surmise.emulation.emulator.fit` and :py:func:`surmise.emulation.emulator.predict` are the main :py:class:`surmise.emulation.emulator` class methods. It also provides the functionality of updating and manipulating the From 9602492810a5a638de986efcd8f3c58acdf29383 Mon Sep 17 00:00:00 2001 From: Moses Chan Date: Tue, 9 Jun 2026 11:25:47 -0500 Subject: [PATCH 2/4] unify language for code directory, and sampler inheritance --- docs/howtocalibration.rst | 6 ++++-- docs/howtoemulation.rst | 2 +- docs/howtoutilities.rst | 6 ++---- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/howtocalibration.rst b/docs/howtocalibration.rst index ae54f0bb..f929bf04 100644 --- a/docs/howtocalibration.rst +++ b/docs/howtocalibration.rst @@ -5,14 +5,16 @@ In this tutorial, we describe how to include a new calibrator to the surmise's framework. We illustrate this with ``directbayeswoodbury``--a calibrator method located in the directory ``\calibrationmethods``. -In surmise, all calibrator methods are automatically discovered from `.py` code files under `src/surmise/calibrationmethods`. +In surmise, all calibrator methods are automatically discovered from `.py` code files under ``\calibrationmethods``. A calibrator class calls the user input method via the filename without extension, e.g., `directbayeswoodbury`, and fits the corresponding calibrator. :py:meth:`surmise.calibration.calibrator.fit` is the main :py:class:`surmise.calibration.calibrator` class methods. It also provides the functionality of updating and manipulating the fitted calibrator by :py:meth:`surmise.calibration.calibrator.predict` class methods. -In order to use the functionality of the base class :py:class:`surmise.calibration.calibrator`, we categorize the functions to be included in a new emulation method (for example, ``directbayeswoodbury``) into two categories. +In order to use the functionality of the base class :py:class:`surmise.calibration.calibrator`, +we categorize the functions to be included in a new emulation method (for example, ``directbayeswoodbury``) +into two categories. Mandatory functions ++++++++++++++++++++ diff --git a/docs/howtoemulation.rst b/docs/howtoemulation.rst index 103f0b83..5027e701 100644 --- a/docs/howtoemulation.rst +++ b/docs/howtoemulation.rst @@ -5,7 +5,7 @@ In this tutorial, we describe how to include a new emulator to the surmise's framework. We illustrate this with ``PCGP``--an emulator method located in the directory ``\emulationmethods``. -In surmise, all emulator methods are automatically discovered from `.py` code files under `src/surmise/emulationmethods`. +In surmise, all emulator methods are automatically discovered from `.py` code files under ``\emulationmethods``. An emulator class calls the user input method by the filename of the respective `.py` file, e.g., `PCGP` for `PCGP.py`, and fits the corresponding emulator. :py:func:`surmise.emulation.emulator.fit` and :py:func:`surmise.emulation.emulator.predict` are the main :py:class:`surmise.emulation.emulator` class methods. diff --git a/docs/howtoutilities.rst b/docs/howtoutilities.rst index 7f90931f..23c9715a 100644 --- a/docs/howtoutilities.rst +++ b/docs/howtoutilities.rst @@ -5,10 +5,8 @@ In this tutorial, we describe how to include a new utility (specifically, a samp to the surmise's framework. We illustrate this with ``metropolis_hastings``--a well-known sampler located in the directory ``\utilitiesmethods``. -In surmise, all utilities inherit from the base class :py:class:`surmise.utilities.sampler`. -Note that for now, we only have samplers as utilities. Later, we plan to have -different classes (such as :py:class:`surmise.utilities.optimizer`) that can be -used during calibration. +In surmise, all utilities are automatically discovered from `.py` code files under ``\utilitiesmethods``. +Note that for now, we only have samplers as utilities. A sampler takes the function returning the log of the posterior of given theta as an input, and returns a dictionary including a random sample of thetas from the From 78564a91d09195c0cca2c0ca1fbe8213265c7f68 Mon Sep 17 00:00:00 2001 From: Jared O'Neal Date: Wed, 24 Jun 2026 13:08:16 -0500 Subject: [PATCH 3/4] (Issue #154) Try combining first two paragraphs. Add a bit more technical detail as well. --- docs/howtoemulation.rst | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/howtoemulation.rst b/docs/howtoemulation.rst index 5027e701..ec30a85c 100644 --- a/docs/howtoemulation.rst +++ b/docs/howtoemulation.rst @@ -1,13 +1,16 @@ How to include a new emulator ============================================== - -In this tutorial, we describe how to include a new emulator to the surmise's -framework. We illustrate this with ``PCGP``--an emulator method located in the -directory ``\emulationmethods``. - -In surmise, all emulator methods are automatically discovered from `.py` code files under ``\emulationmethods``. -An emulator class calls the user input method by the filename of the respective `.py` file, e.g., `PCGP` for `PCGP.py`, and fits the corresponding -emulator. :py:func:`surmise.emulation.emulator.fit` and :py:func:`surmise.emulation.emulator.predict` +When loaded, the surmise package automatically identifies all available +emulators by locating all ``.py`` codes in the ``emulationmethods`` folder +within its installation [#f1]_. For example, it assumes that the +``emulationmethods/PCGP.py`` file provides the ``PCGP`` emulator, which is the +emulator name that users should provide when choosing a particular emulator to +use for a fit. Therefore, users can integrate their own emulator in surmise by +placing their emulator's Python source code in that same folder. This tutorial +describes how to structure a custom emulator code so that this integration is +successful. + +:py:func:`surmise.emulation.emulator.fit` and :py:func:`surmise.emulation.emulator.predict` are the main :py:class:`surmise.emulation.emulator` class methods. It also provides the functionality of updating and manipulating the fitted emulator by :py:func:`surmise.emulation.emulator.supplement`, @@ -67,3 +70,7 @@ Optional functions ++++++++++++++++++++ ``supplementtheta()`` is an optional function for an emulation method. + +.. rubric:: Footnotes + +.. [#f1] The location of a surmise installation that was installed into a virtual environment, for example, might be ``~/local/venv/my_surmise/lib/python3.14/site-packages/surmise`` or, in Windows, ``TBD`` From 2b410c83527260e9b0dc91e9a1da75865e01d620 Mon Sep 17 00:00:00 2001 From: Moses Chan Date: Thu, 25 Jun 2026 09:53:42 -0500 Subject: [PATCH 4/4] update details of Windows emulationmethods folder --- docs/howtoemulation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/howtoemulation.rst b/docs/howtoemulation.rst index ec30a85c..5651bc12 100644 --- a/docs/howtoemulation.rst +++ b/docs/howtoemulation.rst @@ -73,4 +73,4 @@ Optional functions .. rubric:: Footnotes -.. [#f1] The location of a surmise installation that was installed into a virtual environment, for example, might be ``~/local/venv/my_surmise/lib/python3.14/site-packages/surmise`` or, in Windows, ``TBD`` +.. [#f1] The location of a surmise installation that was installed into a virtual environment, for example, might be ``~/local/venv/my_surmise/lib/python3.14/site-packages/surmise`` or, in Windows, ``~/local/surmise_venv/Lib/site-packages/surmise/emulationmethods``