.. _sec:faq: FAQ === Frequently Asked Questions about :code:`pyhf` and its use. Questions --------- Where can I ask questions about ``pyhf`` use? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you have a question about the use of ``pyhf`` not covered in the `documentation `__, please ask a question on the `GitHub Discussions `__. If you believe you have found a bug in ``pyhf``, please report it in the `GitHub Issues `__. How can I get updates on ``pyhf``? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you're interested in getting updates from the ``pyhf`` dev team and release announcements you can join the |pyhf-announcements mailing list|_. .. |pyhf-announcements mailing list| replace:: ``pyhf-announcements`` mailing list .. _pyhf-announcements mailing list: https://groups.google.com/group/pyhf-announcements/subscribe Is it possible to set the backend from the CLI? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Yes. Use the :code:`--backend` option for :code:`pyhf cls` to specify a tensor backend. The default backend is NumPy. For more information see :code:`pyhf cls --help`. I installed an old ``pyhf`` release from PyPI, why am I getting an error from a dependency? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For old releases of ``pyhf`` that are not actively supported anymore you might need to manually constrain the **upper bound** of a dependency. We work hard to make sure that ``pyhf`` is well maintained so that it installs correctly "out of the box" and have tested all of ``pyhf``'s core dependencies to determine hard lower bounds for compatible dependency releases. However, as ``pyhf`` is |Henry Python library blog|_ we can only define lower bounds for its core dependencies, as defining upper bounds would make decisions for users on what versions of libraries they can use in Python applications they build with ``pyhf`` --- |Hynek SemVer blog|_. If ``pyhf`` were to define upper bounds we could create situations in which ``pyhf`` and other libraries defined in an environment file (i.e., ``requirements.txt``) could have directly conflicting dependencies that would result in ``pip`` failing to be able to install ``pyhf``. To give an explicit example, |jsonschema GitHub Discussion 995|_ resulted in a ``KeyError`` if used with ``pyhf`` ``v0.6.3`` or older. This problem was fixed (c.f. Pull Request :pr:`1979`) in the next release with ``pyhf`` ``v0.7.0``, but the intermediate solution for users was to install an older version of ``jsonschema`` that was still compatible with the ``pyhf`` release they were using: .. code-block:: # requirements.txt pyhf==0.6.3 jsonschema<4.15.0 .. |Henry Python library blog| replace:: a Python library .. _`Henry Python library blog`: https://iscinumpy.dev/post/app-vs-library/ .. |Hynek SemVer blog| replace:: that would be bad .. _`Hynek SemVer blog`: https://hynek.me/articles/semver-will-not-save-you/ .. |jsonschema GitHub Discussion 995| replace:: breaking changes in ``jsonschema`` ``v4.15.0``'s behavior .. _`jsonschema GitHub Discussion 995`: https://github.com/orgs/python-jsonschema/discussions/995 Does ``pyhf`` support Python 2? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ No. Like the rest of the Python community, as of January 2020 the latest releases of ``pyhf`` no longer support Python 2. The last release of ``pyhf`` that was compatible with Python 2.7 is `v0.3.4 `__, which can be installed with .. code-block:: console python -m pip install pyhf~=0.3 I only have access to Python 2. How can I use ``pyhf``? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It is recommended that ``pyhf`` is used as a standalone step in any analysis, and its environment need not be the same as the rest of the analysis. As Python 2 is not supported it is suggested that you setup a Python 3 runtime on whatever machine you're using. If you're using a cluster, talk with your system administrators to get their help in doing so. If you are unable to get a Python 3 runtime, versioned Docker images of ``pyhf`` are distributed through `Docker Hub `__. Once you have Python 3 installed, see the :ref:`installation` page to get started. I validated my workspace by comparing ``pyhf`` and ``HistFactory``, and while the expected CLs matches, the observed CLs is different. Why is this? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Make sure you're using the right test statistic (:math:`q` or :math:`\tilde{q}`) in both situations. In ``HistFactory``, the asymptotics calculator, for example, will do something more involved for the observed CLs if you choose a different test statistic. I ran validation to compare ``HistFitter`` and ``pyhf``, but they don't match exactly. Why not? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``pyhf`` is validated against ``HistFactory``. ``HistFitter`` makes some particular implementation choices that ``pyhf`` doesn't reproduce. Instead of trying to compare ``pyhf`` and ``HistFitter`` you should try to validate them both against ``HistFactory``. How is ``pyhf`` typeset? ~~~~~~~~~~~~~~~~~~~~~~~~ As you may have guessed from this page, ``pyhf`` is typeset in all lowercase. This is largely historical, as the core developers had just always typed it that way and it seemed a bit too short of a library name to write as ``PyHF``. When typesetting in LaTeX the developers recommend introducing the command .. code-block:: latex \newcommand{\pyhf}{\texttt{pyhf}} If the journal you are publishing in requires you to use ``textsc`` for software names it is okay to instead use .. code-block:: latex \newcommand{\pyhf}{\textsc{pyhf}} Why use Python? ~~~~~~~~~~~~~~~ As of the late 2010's Python is widely considered the lingua franca of machine learning libraries, and is sufficiently high-level and expressive for physicists of various computational skill backgrounds to use. Using Python as the language for development allows for the distribution of the software --- as both source files and binary distributions --- through the Python Package Index (PyPI) and Conda-forge, which significantly lowers the barrier for use as compared to ``C++``. Additionally, a 2017 `DIANA/HEP `_ study :cite:`faq-feickert-diana-fellowship-report` demonstrated the graph structure and automatic differentiation abilities of machine learning frameworks allowed them to be quite effective tools for statistical fits. As the frameworks considered in this study (TensorFlow, PyTorch, MXNet) all provided low-level Python APIs to the libraries this made Python an obvious choice for a common high-level control language. Given all these considerations, Python was chosen as the development language. How did ``pyhf`` get started? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In 2017 Lukas Heinrich was discussing with colleauge Holger Schulz how it would be convenient to share and produce statistical results from LHC experiments if they were able to be created with tools that didn't require the large ``C++`` dependencies and tooling expertise as :math:`\HiFa{}`. Around the same time that Lukas began thinking on these ideas, Matthew Feickert was working on `a DIANA/HEP fellowship `_ with Kyle Cranmer (co-author of :math:`\HiFa{}`) to study if the graph structure and automatic differentiation abilities of machine learning frameworks would allow them to be effective tools for statistical fits. Lukas would give helpful friendly advice on Matthew's project and one night [1]_ over dinner in CERN's R1 cafeteria the two were discussing the idea of implementing :math:`\HiFa{}` in Python using machine learning libraries to drive the computation. Continuing the discussion in Lukas's office, Lukas showed Matthew that the core statistical machinery could be implemented rather succinctly, and that night `proceeded to do so `_ and |dubbed the project pyhf|_. Matthew joined him on the project to begin development and by April 2018 Giordon Stark had learned about the project and began making contributions, quickly becoming `the third core developer `_. The first physics paper to use ``pyhf`` followed closely in October 2018 :cite:`faq-Heinrich:2018nip`, making Lukas and Holger's original conversations a reality. ``pyhf`` was founded on the ideas of open contributions and community software and continues in that mission today as a `Scikit-HEP project `_, with an open invitation for community contributions and new developers. Troubleshooting --------------- - :code:`import pyhf` causes a :code:`Segmentation fault (core dumped)` This is may be the result of a conflict with the NVIDIA drivers that you have installed on your machine. Try uninstalling and completely removing all of them from your machine .. code-block:: console # On Ubuntu/Debian sudo apt-get purge nvidia* and then installing the latest versions. Footnotes ~~~~~~~~~ .. [1] 24 January, 2018 Bibliography ~~~~~~~~~~~~ .. bibliography:: bib/docs.bib bib/use_citations.bib :filter: docname in docnames :style: plain :keyprefix: faq- :labelprefix: faq- .. |dubbed the project pyhf| replace:: dubbed the project ``pyhf`` .. _`dubbed the project pyhf`: https://twitter.com/lukasheinrich_/status/956809112674885632