Merge pull request #12 from denehoffman/documentation

Documentation and other small updates

.justfile

@@ -2,4 +2,17 @@ default:
   just --list
 
 develop:
-  maturin develop -r --uv --strip
+  CARGO_INCREMENTAL=true maturin develop -r --uv --strip
+
+builddocs:
+  CARGO_INCREMENTAL=true maturin build -r --strip
+  uv pip install ./target/wheels/*
+  make -C docs clean
+  make -C docs html
+
+makedocs:
+  make -C docs clean
+  make -C docs html
+
+odoc:
+  firefox ./docs/build/html/index.html

.readthedocs.yaml

@@ -0,0 +1,19 @@
+# .readthedocs.yaml
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/source/conf.py
+
+formats:
+   - pdf
+
+python:
+   install:
+   - requirements: docs/requirements.txt

Cargo.toml

@@ -29,12 +29,17 @@ auto_ops = "0.3.0"
 rand = "0.8.5"
 rand_chacha = "0.3.1"
 rayon = { version = "1.10.0", optional = true }
-pyo3 = { version = "0.22.5", optional = true, features = ["num-complex"] }
+pyo3 = { version = "0.22.5", optional = true, features = [
+  "num-complex",
+  "abi3-py37",
+] }
 numpy = { version = "0.22.0", optional = true, features = ["nalgebra"] }
-ganesh = "0.12.2"
-thiserror = "1.0.64"
+ganesh = "0.13.0"
+thiserror = "2.0.0"
 shellexpand = "3.1.0"
 accurate = "0.4.1"
+serde = "1.0.214"
+serde-pickle = "1.1.1"
 
 [dev-dependencies]
 approx = "0.5.1"

README.md

@@ -21,10 +21,13 @@
     <img alt="Crates.io Version" src="https://img.shields.io/crates/v/laddu?style=for-the-badge&logo=rust&logoColor=red&color=red"></a>
   <a href="https://docs.rs/laddu" alt="Laddu documentation on docs.rs">
     <img alt="docs.rs" src="https://img.shields.io/docsrs/laddu?style=for-the-badge&logo=rust&logoColor=red"></a>
+  <a href="https://https://laddu.readthedocs.io/en/latest/" alt="Laddu documentation readthedocs.io">
+    <img alt="Read the Docs" src="https://img.shields.io/readthedocs/laddu?style=for-the-badge&logo=readthedocs&logoColor=%238CA1AF&label=Python%20Documentation"></a>
   <a href="https://app.codecov.io/github/denehoffman/laddu/tree/main/" alt="Codecov coverage report">
     <img alt="Codecov" src="https://img.shields.io/codecov/c/github/denehoffman/laddu?style=for-the-badge&logo=codecov"></a>
   <a href="https://pypi.org/project/laddu/" alt="View project on PyPI">
   <img alt="PyPI - Version" src="https://img.shields.io/pypi/v/laddu?style=for-the-badge&logo=python&logoColor=yellow&labelColor=blue"></a>
+  <a href="https://codspeed.io/denehoffman/laddu"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fcodspeed.io%2Fbadge.json&style=for-the-badge" alt="CodSpeed Badge"/></a>
 </p>
 
 `laddu` (/ˈlʌduː/) is a library for analysis of particle physics data. It is intended to be a simple and efficient alternative to some of the [other tools](#alternatives) out there. `laddu` is written in Rust with bindings to Python via [`PyO3`](https://github.com/PyO3/pyo3) and [`maturin`](https://github.com/PyO3/maturin) and is the spiritual successor to [`rustitude`](https://github.com/denehoffman/rustitude), one of my first Rust projects. The goal of this project is to allow users to perform complex amplitude analyses (like partial-wave analyses) without complex code or configuration files.
@@ -245,9 +248,9 @@ The data format for `laddu` is a bit different from some of the alternatives lik
 | `p4_0_Px`    | `Float32` | Beam Momentum (x-component) |
 | `p4_0_Py`    | `Float32` | Beam Momentum (y-component) |
 | `p4_0_Pz`    | `Float32` | Beam Momentum (z-component) |
-| `eps_0_Px`    | `Float32` | Beam Polarization (x-component) |
-| `eps_0_Py`    | `Float32` | Beam Polarization (y-component) |
-| `eps_0_Pz`    | `Float32` | Beam Polarization (z-component) |
+| `eps_0_x`    | `Float32` | Beam Polarization (x-component) |
+| `eps_0_y`    | `Float32` | Beam Polarization (y-component) |
+| `eps_0_z`    | `Float32` | Beam Polarization (z-component) |
 | `p4_1_E`    | `Float32` | Recoil Proton Energy    |
 | `p4_1_Px`    | `Float32` | Recoil Proton Momentum (x-component) |
 | `p4_1_Py`    | `Float32` | Recoil Proton Momentum (y-component) |

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,3 @@
+laddu
+sphinx==8.1.3
+sphinx-rtd-theme==3.0.1

docs/source/conf.py

@@ -0,0 +1,37 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import laddu
+
+project = "laddu"
+copyright = "2024, Nathaniel Dene Hoffman"
+author = "Nathaniel Dene Hoffman"
+release = laddu.__version__
+version = release
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.napoleon"]
+
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+}
+
+autodoc_member_order = "groupwise"
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]

docs/source/index.rst

@@ -0,0 +1,13 @@
+laddu
+=====
+
+``laddu`` is an library for analyzing particle physics data. It is written in Rust with bindings to Python which are documented here.
+
+Right now, this page just documents the basic Python API of the library, but the plan is to eventually write a tutorial here for general use. See the `GitHub Repository <https://github.com/denehoffman/laddu>`_ for more details.
+
+.. toctree::
+   :caption: API Reference
+   :maxdepth: 1
+   :name: sec-api
+
+   modules/index

docs/source/modules/index.rst

@@ -0,0 +1,10 @@
+Submodules
+==========
+
+.. toctree::
+   :maxdepth: 1
+
+   laddu/amplitudes/index
+   laddu/data
+   laddu/likelihoods
+   laddu/utils/index

docs/source/modules/laddu/amplitudes/breit_wigner.rst

@@ -0,0 +1,6 @@
+Breit-Wigner
+============
+
+.. automodule:: laddu.amplitudes.breit_wigner
+   :members:
+   :undoc-members:

docs/source/modules/laddu/amplitudes/common.rst

@@ -0,0 +1,6 @@
+Common
+======
+
+.. automodule:: laddu.amplitudes.common
+   :members:
+   :undoc-members:

docs/source/modules/laddu/amplitudes/index.rst

@@ -0,0 +1,17 @@
+Amplitudes
+==========
+
+.. automodule:: laddu.amplitudes
+   :members:
+   :undoc-members:
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Amplitudes:
+
+   common
+   ylm
+   zlm
+   breit_wigner
+   kmatrix

docs/source/modules/laddu/amplitudes/kmatrix.rst

@@ -0,0 +1,6 @@
+K-Matrix
+========
+
+.. automodule:: laddu.amplitudes.kmatrix
+   :members:
+   :undoc-members:

docs/source/modules/laddu/amplitudes/ylm.rst

@@ -0,0 +1,6 @@
+Ylm
+===
+
+.. automodule:: laddu.amplitudes.ylm
+   :members:
+   :undoc-members:

docs/source/modules/laddu/amplitudes/zlm.rst

@@ -0,0 +1,6 @@
+Zlm
+===
+
+.. automodule:: laddu.amplitudes.zlm
+   :members:
+   :undoc-members:

docs/source/modules/laddu/data.rst

@@ -0,0 +1,6 @@
+Data
+====
+
+.. automodule:: laddu.data
+   :members:
+   :undoc-members:

docs/source/modules/laddu/likelihoods.rst

@@ -0,0 +1,6 @@
+Likelihoods
+===========
+
+.. automodule:: laddu.likelihoods
+   :members:
+   :undoc-members:

docs/source/modules/laddu/utils/index.rst

@@ -0,0 +1,9 @@
+Utilities
+=========
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Utility Modules:
+
+   vectors
+   variables

docs/source/modules/laddu/utils/variables.rst

@@ -0,0 +1,6 @@
+Variables
+=========
+
+.. automodule:: laddu.utils.variables
+   :members:
+   :undoc-members:

docs/source/modules/laddu/utils/vectors.rst

@@ -0,0 +1,6 @@
+Vectors
+=======
+
+.. automodule:: laddu.utils.vectors
+   :members:
+   :undoc-members:

pyproject.toml

@@ -25,6 +25,7 @@ amptools-to-laddu = "laddu:convert.run"
 
 [project.optional-dependencies]
 tests = ["pytest"]
+docs = ["sphinx", "sphinx-rtd-theme"]
 
 [tool.maturin]
 python-source = "python"

python/laddu/convert.py

@@ -125,8 +125,8 @@ def run():
     output_file = args["<output_file>"]
     tree_name = args["--tree"]
     pol_in_beam = args["--pol-in-beam"]
-    pol_angle = float(args["--pol-angle"]) * np.pi / 180
-    pol_magnitude = float(args["--pol-magnitude"])
+    pol_angle = float(args["--pol-angle"]) * np.pi / 180 if args["--pol-angle"] else None
+    pol_magnitude = float(args["--pol-magnitude"]) if args["--pol-magnitude"] else None
     num_entries = int(args["-n"]) if args["-n"] else None
 
     convert_from_amptools(

python/laddu/likelihoods/__init__.pyi

@@ -1,4 +1,5 @@
-from typing import Literal, Sequence
+from collections.abc import Sequence
+from typing import Literal
 
 import numpy as np
 import numpy.typing as npt
@@ -74,6 +75,10 @@ class Status:
     n_f_evals: int
     n_g_evals: int
 
+    def save_as(self, path: str): ...
+    @staticmethod
+    def load(path: str) -> Status: ...
+
 class Bound:
     lower: float
     upper: float

python/laddu/utils/vectors/__init__.pyi

@@ -0,0 +1,39 @@
+import numpy as np
+import numpy.typing as npt
+
+class Vector3:
+    mag: float
+    mag2: float
+    costheta: float
+    theta: float
+    phi: float
+    unit: Vector3
+    px: float
+    py: float
+    pz: float
+    def __init__(self, px: float, py: float, pz: float): ...
+    def __add__(self, other: Vector3) -> Vector3: ...
+    def dot(self, other: Vector3) -> float: ...
+    def cross(self, other: Vector3) -> Vector3: ...
+    def to_numpy(self) -> npt.NDArray[np.float64]: ...
+
+class Vector4:
+    mag: float
+    mag2: float
+    vec3: Vector3
+    e: float
+    px: float
+    py: float
+    pz: float
+    momentum: Vector3
+    gamma: float
+    beta: Vector3
+    m: float
+    m2: float
+    def __init__(self, e: float, px: float, py: float, pz: float): ...
+    def __add__(self, other: Vector4) -> Vector4: ...
+    def boost(self, beta: Vector3) -> Vector4: ...
+    def boost_along(self, other: Vector4) -> Vector4: ...
+    def to_numpy(self) -> npt.NDArray[np.float64]: ...
+    @staticmethod
+    def from_momentum(momentum: Vector3, mass: float) -> Vector4: ...