Merge pull request #91 from zfit/tfpwacomp

enh: add tf-pwa connection

.gitignore

@@ -103,3 +103,5 @@ venv.bak/
 # mypy
 .mypy_cache/
 /.idea/sonarlint/*
+/tests/tfpwa/data/
+/src/zfit_physics/_version.py

.pre-commit-config.yaml

@@ -26,6 +26,16 @@ repos:
 #      - id: docformatter
 #        args: [ -r, --in-place, --wrap-descriptions, '120', --wrap-summaries, '120', -- ]
 
+  - repo: local
+    hooks:
+      - id: doc arg replacer
+        name: docarg
+        entry: utils/api/replace_argdocs.py
+        language: python
+        always_run: true
+        additional_dependencies: [ pyyaml ]
+
+
   - repo: https://github.com/pre-commit/pygrep-hooks
     rev: v1.10.0
     hooks:

CHANGELOG.rst

@@ -7,6 +7,7 @@ Develop
 
 Major Features and Improvements
 -------------------------------
+- `TF-PWA <https://tf-pwa.readthedocs.io/en/latest/>`_ support for loss functions. Minimizer can directly minimize the loss function of a model.
 
 Breaking changes
 ------------------

docs/api/static/zfit_physics.pdf.rst

@@ -1,5 +1,5 @@
-pdf
-===
+PDFs
+=======================
 
 .. automodule:: zfit_physics.pdf
     :members:

docs/api/static/zfit_physics.tfpwa.rst

@@ -0,0 +1,44 @@
+TF-PWA
+=======================
+
+TFPWA is a generic software package intended for Partial Wave Analysis (PWA). It can be connected with zfit,
+currently by providing a loss function that can be minimized by a zfit minimizer.
+
+Import the module with:
+
+.. code-block:: python
+
+    import zfit_physics.tfpwa as ztfpwa
+
+This will enable that :py:function:~`tfpwa.model.FCN` can be used as a loss function in zfit minimizers as
+
+.. code-block:: python
+
+    minimizer.minimize(loss=fcn)
+
+More explicitly, the loss function can be created with
+
+.. code-block:: python
+
+    nll = ztfpwa.loss.nll_from_fcn(fcn)
+
+which optionally takes already created :py:class:~`zfit.core.interfaces.ZfitParameter` as arguments.
+
+
+Variables
+++++++++++++
+
+
+.. automodule:: zfit_physics.tfpwa.variables
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Loss
+++++++++++++
+
+.. automodule:: zfit_physics.tfpwa.loss
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/conf.py

@@ -22,6 +22,8 @@
 import sys
 from pathlib import Path
 
+import yaml
+
 sys.path.insert(0, str(Path("..").resolve()))
 
 import zfit_physics
@@ -68,7 +70,7 @@
     "sphinx_copybutton",
     "sphinxcontrib.youtube",
     "sphinx_panels",
-    "seed_intersphinx_mapping",
+    # "seed_intersphinx_mapping",
     "myst_nb",
     "sphinx_togglebutton",
 ]
@@ -115,6 +117,27 @@
 }
 autodoc_inherit_docstrings = False
 
+
+# add whitespaces to the internal commands. Maybe move to preprocessing?
+project_dir = Path(__file__).parents[1]
+rst_epilog = """
+.. |wzw| unicode:: U+200B
+   :trim:
+
+"""
+# ..  replace:: |wzw|
+#
+# .. |@docend| replace:: |wzw|
+# """
+with Path(project_dir / "utils/api/argdocs.yaml").open() as replfile:
+    replacements = yaml.load(replfile, Loader=yaml.Loader)
+for replacement_key in replacements:
+    rst_epilog += f"""
+.. |@doc:{replacement_key}| replace:: |wzw|
+
+.. |@docend:{replacement_key}| replace:: |wzw|
+"""
+
 # -- autosummary settings ---------------------------------------------
 
 autosummary_generate = True

docs/index.rst

@@ -23,3 +23,11 @@ PDF documentation
     :maxdepth: 2
 
     api/static/zfit_physics.pdf
+
+Extensions
+----------
+
+.. toctree::
+    :maxdepth: 1
+
+    api/static/zfit_physics.tfpwa.rst

pyproject.toml

@@ -36,6 +36,18 @@ dependencies = ["zfit>=0.20"]
 dynamic = ["version"]
 
 [project.optional-dependencies]
+
+tfpwa = ["tfpwa@git+https://github.com/jiangyi15/tf-pwa"]
+
+all = ["zfit-physics[tfpwa]"]
+test = [
+    "pytest",
+    "pytest-cov",
+    "pytest-rerunfailures",
+    "pytest-xdist",
+    "zfit-physics[all]",
+    "contextlib_chdir",  # backport of chdir from Python 3.11
+]
 dev = [
     "bumpversion>=0.5.3",
     "coverage>=4.5.1",
@@ -46,11 +58,7 @@ dev = [
     "pip>=9.0.1",
     "pre-commit",
     "pydata-sphinx-theme>=0.9", # new dark theme configuration
-    "pytest>=3.4.2",
-    "pytest-cov",
-    "pytest-rerunfailures>=6",
-    "pytest-runner>=2.11.1",
-    "pytest-xdist",
+    "pyyaml",
     "seed_intersphinx_mapping",
     "setupext-janitor",
     "Sphinx>=3.5.4",
@@ -65,6 +73,7 @@ dev = [
     "twine>=1.10.0",
     "watchdog>=0.8.3",
     "wheel>=0.29.0",
+    "zfit-physics[test]",
 ]
 
 [project.urls]
@@ -74,16 +83,11 @@ Repository = "https://github.com/zfit/zfit-physics"
 Discussions = "https://github.com/zfit/zfit-physics/discussions"
 Changelog = "https://github.com/zfit/zfit-physics/blob/main/CHANGELOG.rst"
 
-
-
-
-
-
-
-
 [tool.hatch]
 version.source = "vcs"
 build.hooks.vcs.version-file = "src/zfit_physics/_version.py"
+metadata.allow-direct-references = true
+
 
 [tool.pytest.ini_options]
 minversion = "6.0"

src/zfit_physics/__init__.py

@@ -6,7 +6,7 @@
 
 __license__ = "BSD 3-Clause"
 __copyright__ = "Copyright 2019, zfit"
-__status__ = "Pre-alpha"
+__status__ = "Beta"
 
 __author__ = "zfit"
 __maintainer__ = "zfit"
@@ -18,6 +18,6 @@
     # TODO(release): add more, Anton etc
 ]
 
-__all__ = ["pdf"]
+__all__ = ["pdf", "unstable"]
 
 from . import pdf, unstable

src/zfit_physics/models/pdf_argus.py

@@ -81,6 +81,16 @@ def __init__(
                The default space is used for example in the sample method: if no
                sampling limits are given, the default space is used.
 
+               If the observables are binned and the model is unbinned, the
+               model will be a binned model, by wrapping the model in a
+               :py:class:`~zfit.pdf.BinnedFromUnbinnedPDF`, equivalent to
+               calling :py:meth:`~zfit.pdf.BasePDF.to_binned`.
+
+               If the observables are binned and the model is unbinned, the
+               model will be a binned model, by wrapping the model in a
+               :py:class:`~zfit.pdf.BinnedFromUnbinnedPDF`, equivalent to
+               calling :py:meth:`~zfit.pdf.BasePDF.to_binned`.
+
                The observables are not equal to the domain as it does not restrict or
                truncate the model outside this range. |@docend:pdf.init.obs|
             m0: Maximal energetically allowed mass, cutoff
@@ -93,10 +103,13 @@ def __init__(
                ``ext_*`` methods and the ``counts`` (for binned PDFs). |@docend:pdf.init.extended|
             norm: |@doc:pdf.init.norm| Normalization of the PDF.
                By default, this is the same as the default space of the PDF. |@docend:pdf.init.norm|
-            name: |@doc:pdf.init.name| Human-readable name
+            name: |@doc:pdf.init.name| Name of the PDF.
+               Maybe has implications on the serialization and deserialization of the PDF.
+               For a human-readable name, use the label. |@docend:pdf.init.name|
+           label: |@doc:pdf.init.label| Human-readable name
                or label of
-               the PDF for better identification. |@docend:pdf.init.name|
-           label: |@doc:pdf.init.label| Label of the PDF, if None is given, it will be the name. |@docend:pdf.init.label|
+               the PDF for a better description, to be used with plots etc.
+               Has no programmatical functional purpose as identification. |@docend:pdf.init.label|
 
         Returns:
             `tf.Tensor`: the values matching the (broadcasted) shapes of the input

src/zfit_physics/models/pdf_cmsshape.py

@@ -117,6 +117,16 @@ def __init__(
                The default space is used for example in the sample method: if no
                sampling limits are given, the default space is used.
 
+               If the observables are binned and the model is unbinned, the
+               model will be a binned model, by wrapping the model in a
+               :py:class:`~zfit.pdf.BinnedFromUnbinnedPDF`, equivalent to
+               calling :py:meth:`~zfit.pdf.BasePDF.to_binned`.
+
+               If the observables are binned and the model is unbinned, the
+               model will be a binned model, by wrapping the model in a
+               :py:class:`~zfit.pdf.BinnedFromUnbinnedPDF`, equivalent to
+               calling :py:meth:`~zfit.pdf.BasePDF.to_binned`.
+
                The observables are not equal to the domain as it does not restrict or
                truncate the model outside this range. |@docend:pdf.init.obs|
             extended: |@doc:pdf.init.extended| The overall yield of the PDF.
@@ -126,11 +136,13 @@ def __init__(
                ``ext_*`` methods and the ``counts`` (for binned PDFs). |@docend:pdf.init.extended|
             norm: |@doc:pdf.init.norm| Normalization of the PDF.
                By default, this is the same as the default space of the PDF. |@docend:pdf.init.norm|
-            name: |@doc:pdf.init.name| Human-readable name
+            name: |@doc:pdf.init.name| Name of the PDF.
+               Maybe has implications on the serialization and deserialization of the PDF.
+               For a human-readable name, use the label. |@docend:pdf.init.name|
+            label: |@doc:pdf.init.label| Human-readable name
                or label of
-               the PDF for better identification.
-               Has no programmatical functional purpose as identification. |@docend:pdf.init.name|
-            label: |@doc:pdf.init.label| Label of the PDF, if None is given, it will be the name. |@docend:pdf.init.label|
+               the PDF for a better description, to be used with plots etc.
+               Has no programmatical functional purpose as identification. |@docend:pdf.init.label|
         """
         params = {"m": m, "beta": beta, "gamma": gamma}
         super().__init__(obs=obs, params=params, name=name, extended=extended, norm=norm, label=label)

src/zfit_physics/models/pdf_conv.py

@@ -40,6 +40,16 @@ def __init__(
                The default space is used for example in the sample method: if no
                sampling limits are given, the default space is used.
 
+               If the observables are binned and the model is unbinned, the
+               model will be a binned model, by wrapping the model in a
+               :py:class:`~zfit.pdf.BinnedFromUnbinnedPDF`, equivalent to
+               calling :py:meth:`~zfit.pdf.BasePDF.to_binned`.
+
+               If the observables are binned and the model is unbinned, the
+               model will be a binned model, by wrapping the model in a
+               :py:class:`~zfit.pdf.BinnedFromUnbinnedPDF`, equivalent to
+               calling :py:meth:`~zfit.pdf.BasePDF.to_binned`.
+
                The observables are not equal to the domain as it does not restrict or
                truncate the model outside this range. |@docend:pdf.init.obs|
             extended: |@doc:pdf.init.extended| The overall yield of the PDF.
@@ -49,10 +59,13 @@ def __init__(
                ``ext_*`` methods and the ``counts`` (for binned PDFs). |@docend:pdf.init.extended|
             norm: |@doc:pdf.init.norm| Normalization of the PDF.
                By default, this is the same as the default space of the PDF. |@docend:pdf.init.norm|
-            name: |@doc:pdf.init.name| Human-readable name
+            name: |@doc:pdf.init.name| Name of the PDF.
+               Maybe has implications on the serialization and deserialization of the PDF.
+               For a human-readable name, use the label. |@docend:pdf.init.name|
+           label: |@doc:pdf.init.label| Human-readable name
                or label of
-               the PDF for better identification. |@docend:pdf.init.name|
-           label: |@doc:pdf.init.label| Label of the PDF, if None is given, it will be the name. |@docend:pdf.init.label|
+               the PDF for a better description, to be used with plots etc.
+               Has no programmatical functional purpose as identification. |@docend:pdf.init.label|
         """
         super().__init__(obs=obs, pdfs=[func, kernel], params={}, name=name, extended=extended, norm=norm, label=label)
         limits = self._check_input_limits(limits=limits)

src/zfit_physics/models/pdf_cruijff.py

@@ -73,26 +73,38 @@ def __init__(
             sigmar: Right width parameter.
             alphar: Right tail acceleration parameter.
         obs: |@doc:pdf.init.obs| Observables of the
-           model. This will be used as the default space of the PDF and,
-           if not given explicitly, as the normalization range.
+               model. This will be used as the default space of the PDF and,
+               if not given explicitly, as the normalization range.
 
-           The default space is used for example in the sample method: if no
-           sampling limits are given, the default space is used.
+               The default space is used for example in the sample method: if no
+               sampling limits are given, the default space is used.
 
-           The observables are not equal to the domain as it does not restrict or
-           truncate the model outside this range. |@docend:pdf.init.obs|
+               If the observables are binned and the model is unbinned, the
+               model will be a binned model, by wrapping the model in a
+               :py:class:`~zfit.pdf.BinnedFromUnbinnedPDF`, equivalent to
+               calling :py:meth:`~zfit.pdf.BasePDF.to_binned`.
+
+               If the observables are binned and the model is unbinned, the
+               model will be a binned model, by wrapping the model in a
+               :py:class:`~zfit.pdf.BinnedFromUnbinnedPDF`, equivalent to
+               calling :py:meth:`~zfit.pdf.BasePDF.to_binned`.
+
+               The observables are not equal to the domain as it does not restrict or
+               truncate the model outside this range. |@docend:pdf.init.obs|
         extended: |@doc:pdf.init.extended| The overall yield of the PDF.
-           If this is parameter-like, it will be used as the yield,
-           the expected number of events, and the PDF will be extended.
-           An extended PDF has additional functionality, such as the
-           ``ext_*`` methods and the ``counts`` (for binned PDFs). |@docend:pdf.init.extended|
+               If this is parameter-like, it will be used as the yield,
+               the expected number of events, and the PDF will be extended.
+               An extended PDF has additional functionality, such as the
+               ``ext_*`` methods and the ``counts`` (for binned PDFs). |@docend:pdf.init.extended|
         norm: |@doc:pdf.init.norm| Normalization of the PDF.
-           By default, this is the same as the default space of the PDF. |@docend:pdf.init.norm|
-        name: |@doc:pdf.init.name| Human-readable name
-           or label of
-           the PDF for better identification.
-           Has no programmatical functional purpose as identification. |@docend:pdf.init.name|
-        label: |@doc:pdf.init.label| A human readable label to identify the PDF. |@docend:pdf.init.label|
+               By default, this is the same as the default space of the PDF. |@docend:pdf.init.norm|
+        name: |@doc:pdf.init.name| Name of the PDF.
+               Maybe has implications on the serialization and deserialization of the PDF.
+               For a human-readable name, use the label. |@docend:pdf.init.name|
+        label: |@doc:pdf.init.label| Human-readable name
+               or label of
+               the PDF for a better description, to be used with plots etc.
+               Has no programmatical functional purpose as identification. |@docend:pdf.init.label|
         """
         params = {"mu": mu, "sigmal": sigmal, "alphal": alphal, "sigmar": sigmar, "alphar": alphar}
         super().__init__(obs=obs, params=params, extended=extended, norm=norm, name=name, label=label)