Merge pull request #59 from SpeysideHEP/minuit

Minuit integration

Author: jackaraz

.github/workflows/tests.yml

@@ -3,7 +3,7 @@ name: Tests
 on:
     pull_request:
         branches: ["main", "releases/**"]
-        types: [review_requested, opened]
+        types: [opened, review_requested, ready_for_review, synchronize]
         paths: ["src/**.py", "tests/**.py", "tests.yml"]
     push:
         branches: ["main", "releases/**"]
@@ -32,8 +32,20 @@ jobs:
                   python -m pip install --upgrade pip
                   python -m pip install pytest pytest-cov
                   if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-                  python -m pip install -e .
+                  python -m pip install -e .[iminuit]
             - name: Test with pytest
               run: |
                   python -c 'import spey;spey.about()'
-                  pytest --cov=spey tests/*py #--cov-fail-under 99
+                  pytest --cov --cov-branch --junitxml=junit.xml -o junit_family=legacy --cov-report=xml tests/*py #--cov-fail-under 99
+
+            - name: Upload coverage reports to Codecov
+              uses: codecov/codecov-action@v5
+              with:
+                  token: ${{ secrets.CODECOV_TOKEN }}
+                  slug: SpeysideHEP/spey
+
+            - name: Upload test results to Codecov
+              if: ${{ !cancelled() }}
+              uses: codecov/test-results-action@v1
+              with:
+                  token: ${{ secrets.CODECOV_TOKEN }}

README.md

@@ -14,6 +14,8 @@
 [![GitHub License](https://img.shields.io/github/license/SpeysideHEP/spey?style=plastic)](https://github.com/SpeysideHEP/spey/blob/main/LICENSE)
 
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/spey?style=plastic)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/spey?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/spey)
+[![codecov](https://codecov.io/gh/SpeysideHEP/spey/graph/badge.svg?token=78Q76XFPTF)](https://codecov.io/gh/SpeysideHEP/spey)
 
 ## Outline
 
@@ -38,9 +40,19 @@ python -m pip install --upgrade "git+https://github.com/SpeysideHEP/spey"
 
 **Note that `main` branch may not be the stable version.**
 
+To install a specific branch with pip, use the following command:
+
+```bash
+python -m pip install git+https://github.com/SpeysideHEP/spey@<BRANCH>
+```
+
+**Please be aware that non-released branches are not stable.**
+
 ## What is Spey?
 
-Spey is a plug-in-based statistics tool that aims to collect all likelihood prescriptions under one roof. This provides users with the workspace to freely combine different statistical models and study them through a single interface. In order to achieve a module that can be used both with statistical model prescriptions, which has been proposed in the past and will be used in the future, Spey uses a so-called plug-in system where developers can propose their statistical model prescriptions and allow Spey to use them.
+Spey is a plug-in-based statistics framework designed to be fully backend-agnostic, providing a unified environment where all likelihood prescriptions can be compiled and accessed in one place. This enables users to flexibly combine diverse statistical models and analyse them through a single, coherent interface. In line with the **FAIR principles, ensuring that models are findable, accessible, interoperable, and reusable**, Spey adopts a modular plug-in system allowing developers to contribute statistical model prescriptions in a transparent and future-proof manner, ensuring compatibility with both current and evolving standards.
+
+Finally, the name "Spey" originally comes from the Spey River, a river in the mid-Highlands of Scotland. The area "Speyside" is famous for its smooth whisky.
 
 ### What a plugin provides
 
@@ -51,8 +63,6 @@ A quick intro on the terminology of spey plugins in this section:
 * Depending on the scope of the plugin, you may wish to provide additional (custom) operations and differentiability through various autodif packages such as ``autograd``
   or ``jax``. As long as they are implemented through a set of predefined function names spey can automatically detect and use them within the interface.
 
-Finally, the name "Spey" originally comes from the Spey River, a river in the mid-Highlands of Scotland. The area "Speyside" is famous for its smooth whiskey.
-
 ### Currently available plug-ins
 
 | Accessor                                | Description                                                                  |

docs/api.rst

@@ -20,6 +20,7 @@ Top-Level
     ExpectationType
     register_backend
     AvailableBackends
+    set_optimiser
     get_backend
     get_backend_metadata
     get_backend_bibtex
@@ -44,18 +45,28 @@ Main Classes
 Base Classes
 ------------
 
+Backend Base
+~~~~~~~~~~~~
+
 .. autoclass:: spey.BackendBase
     :members:
     :undoc-members:
 
+Hypothesis Testing Base
+~~~~~~~~~~~~~~~~~~~~~~~
+
 .. autoclass:: spey.base.hypotest_base.HypothesisTestingBase
     :members:
     :undoc-members:
 
+Model Configuration
+~~~~~~~~~~~~~~~~~~~
+
 .. autoclass:: spey.base.model_config.ModelConfig
     :members:
     :undoc-members:
 
+
 Statistical Model Combiner
 --------------------------
 
@@ -142,9 +153,11 @@ Simple PDFs
     simple_pdf.Gaussian
     simple_pdf.MultivariateNormal
 
+Developer Tools
+---------------
 
 Exceptions
-----------
+~~~~~~~~~~
 
 .. currentmodule:: spey.system.exceptions
 
@@ -162,3 +175,15 @@ Exceptions
     CanNotFindRoots
     UnknownComputer
     CombinerNotAvailable
+
+Logging
+~~~~~~~
+
+.. currentmodule:: spey.system.logger
+
+.. autosummary::
+    :toctree: _generated/
+    :nosignatures:
+
+    disable_logging
+    capture_logs

docs/exclusion.md

@@ -73,7 +73,7 @@ The `allow_negative_signal` keyword controls which test statistic is used and re
 
 For complex statistical models, optimizing the likelihood can be challenging and depends on the choice of optimizer. Spey uses SciPy for optimization and fitting tasks. Any additional keyword arguments not explicitly covered in the {func}`~spey.StatisticalModel.exclusion_confidence_level` function description are passed directly to the optimizer, allowing users to customize its behavior through the interface.
 
-Below we compare the exclusion limits computed with each approach. This comparisson uses normal distribution for the likelihood ([`default.normal`](#normal)) background yields are set to $n_b$, uncertainties are shown with $\sigma$ and observations are given with $n$.
+Below we compare the exclusion limits computed with each approach. This comparisson uses normal distribution for the likelihood (`default.normal`) background yields are set to $n_b$, uncertainties are shown with $\sigma$ and observations are given with $n$.
 
 ```{figure} ./figs/comparisson_observed.png
 ---

docs/index.rst

@@ -24,6 +24,24 @@ Welcome to the documentation of Spey
     :alt: Zenodo DOI
     :target: https://zenodo.org/badge/latestdoi/549515208
 
+.. raw:: html
+
+    <a href="https://pepy.tech/projects/spey"><img src="https://static.pepy.tech/personalized-badge/spey?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads" alt="PyPI Downloads"></a>
+
+What is Spey?
+-------------
+
+Spey is a plug-in-based statistics framework designed to unify all likelihood models under a single, **backend-agnostic interface**. Its aim is to offer a common workspace where users can freely combine, analyse, and interpret statistical models built on entirely different backends. By standardising how likelihoods are accessed and evaluated, Spey facilitates seamless statistical inference across frameworks that would otherwise remain isolated.
+
+At the core of Spey’s design lies a dedication to the `FAIR principles <https://www.nature.com/articles/sdata201618>`_, **ensuring that statistical models and tools are Findable, Accessible, Interoperable, and Reusable**. Spey only requires one key component from any model: the ability to compute the log-probability. Given this, it can carry out the full range of statistical tasks, including but not limited to fitting, calculating exclusion limits, computing :math:`\chi^2`, and running samplers, without being dependent on any specific backend.
+
+This interoperability is made possible through Spey’s modular plug-in architecture. Developers can contribute their own statistical model prescriptions without modifying the Spey codebase. By publishing an independent Spey plug-in, following the guidelines detailed in the documentation, your model becomes automatically discoverable and usable by any Spey installation. The framework also provides built-in citation tools via metadata, ensuring contributors receive proper credit for their plug-ins.
+
+With its flexible architecture, FAIR-driven approach, and emphasis on long-term sustainability, Spey provides a contemporary ecosystem for statistical inference that connects communities and tools across high-energy physics and beyond.
+
+Finally, the name "Spey" originally comes from the Spey River, a river in the mid-Highlands of Scotland. The area "Speyside" is famous for its smooth whisky.
+
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:

docs/outreach.rst

@@ -10,18 +10,21 @@ Talks
    * - Date
      - Event
      - Location
-   * - June 18, 2024
+   * - Nov 25, 2025
+     - `MC&I XPAG Meeting <https://indico.cern.ch/event/1614906/>`_
+     - CERN
+   * - Jun 18, 2024
      - `Reinterpretation & OpenMAPP mini-workshop <https://indico.cern.ch/event/1420197/contributions/5988218/>`_
      - LPSC Grenoble, FR
-   * - February 15, 2024
+   * - Feb 15, 2024
      - `Electroweak and Beyond the Standard Model Physics at the EIC <https://www.int.washington.edu/program/schedule/24-87W>`_
      - INT, University of Washington, USA
-   * - December 5, 2023
+   * - Dec 5, 2023
      - `pyhf Users and Developers Workshop 2023 <https://indico.cern.ch/event/1294577/contributions/5685097/>`_
      - CERN
-   * - October 12, 2023
+   * - Oct 12, 2023
      - `PyHEP 2023 - "Python in HEP" Users Workshop <https://indico.cern.ch/event/1252095/contributions/5592415/>`_
      - Online
-   * - August 30, 2023
+   * - Aug 30, 2023
      - `8th workshop on (Re)interpretation of the LHC results for new physics <https://conference.ippp.dur.ac.uk/event/1178/contributions/6436/>`_
      - University of Durham, UK

docs/quick_start.rst

@@ -24,6 +24,14 @@ Python >=3.8 is required. spey heavily relies on `numpy <https://numpy.org/doc/s
 which are all packaged during the installation with the necessary versions. Note that some
 versions may be restricted due to numeric stability and validation.
 
+To install spey with `iminuit <https://scikit-hep.org/iminuit/>`_, use
+
+.. code-block:: bash
+
+    >>> pip install spey[iminuit]
+
+and iminuit functionality can be activated by :func:`~spey.set_optimiser` function.
+
 What is Spey?
 -------------
 

docs/releases/changelog-v0.2.md

@@ -10,6 +10,9 @@ Specific upgrades for the latest release can be found [here](https://github.com/
 * Add plug-in registry that does not require creating an entire package.
   ([#60](https://github.com/SpeysideHEP/spey/pull/60))
 
+* Iminuit is available to be used for optimisation as alternative to scipy.
+  ([#59](https://github.com/SpeysideHEP/spey/pull/59))
+
 ## Improvements
 
 * Autograd has been upgraded to v1.7 which supports numpy 2.0
@@ -30,6 +33,9 @@ Specific upgrades for the latest release can be found [here](https://github.com/
 * Enable compatibility for Python 3.13, and the deprecation of `pkg_resources` has been addressed.
   ([#56](https://github.com/SpeysideHEP/spey/pull/56))
 
+* Multivariate Normal distribution now supports callable covariance matrix function.
+  ([#59](https://github.com/SpeysideHEP/spey/pull/59))
+
 ## Bug Fixes
 
 * Control mechanism added in case of infinite determinant in covariance matrix.

setup.py

@@ -65,5 +65,6 @@
     ],
     extras_require={
         "dev": ["pytest>=7.1.2", "pytest-cov>=3.0.0", "twine>=3.7.1", "wheel>=0.37.1"],
+        "iminuit": ["iminuit>=2.22.0"],
     },
 )

src/spey/__init__.py

@@ -5,6 +5,7 @@
 import textwrap
 from functools import lru_cache
 from importlib.metadata import EntryPoint, entry_points
+from importlib.util import find_spec
 from typing import Any, Callable, Dict, Iterable, List, Literal, Optional, Union
 
 from semantic_version import SimpleSpec, Version
@@ -459,6 +460,43 @@ def log_once(msg: str, log_type: Literal["warning", "error", "info", "debug"]) -
     }.get(log_type, log.info)(msg)
 
 
+def set_optimiser(name: str) -> None:
+    """
+    Set optimiser for fitting interface.
+
+    Alternatively, optimiser can be set through terminal via
+
+    .. code:: bash
+
+        >>> export SPEY_OPTIMISER=<name>
+
+    spey will automatically track ``SPEY_OPTIMISER`` settings.
+
+    .. versionadded:: 0.2.6
+
+    Args:
+        name (``str``): name of the optimiser, ``scipy`` or ``minuit``.
+    """
+    log.debug(
+        "Currently optimiser is set to: `%s`", os.environ.get("SPEY_OPTIMISER", "scipy")
+    )
+    if name in ["minuit", "iminuit"]:
+        if find_spec("iminuit") is not None:
+            os.environ["SPEY_OPTIMISER"] = "minuit"
+            log.debug("Optimiser set to minuit.")
+        else:
+            log.error("iminuit package is not available.")
+    elif name == "scipy":
+        os.environ["SPEY_OPTIMISER"] = "scipy"
+        log.debug("Optimiser set to scipy.")
+    else:
+        log.error(
+            "Unknown optimiser: %s. The optimiser is set to %s",
+            name,
+            os.environ.get("SPEY_OPTIMISER", "scipy"),
+        )
+
+
 if int(os.environ.get("SPEY_LOGLEVEL", -1)) >= 0:
     set_log_level(int(os.environ.get("SPEY_LOGLEVEL")))