AmpForm 0.10.2

Release 0.10.2

See all documentation for this version here.

📝 Documentation

Added helicity-vs-canonical basis comparison (#95)

Added a notebook that describes the difference between the helicity basis and canonical basis in the helicity formalism.

🐛 Bug fixes

Required numpy version is limited to v1.20 (#91)

Since NumPy v1.21 it is required to explicitly define __array_ufunc__, both for static typing as for running the code. With the current set-up, __array_ufunc__ is too problematic. Better solution would be #92.

AmpForm 0.10.1

Release 0.10.1

See all documentation for this version here.

💡 New features

Implemented HelicityModel.sum_components (#90)

Import tensorwaves.physics.add_components.

Note that this allows removing the tensorwaves.physics module.

AmpForm 0.10.0

Release 0.10.0

See all documentation for this version here.

⚠️ Interface

AmpForm interface and implementation has been adapted to the new QRules interface (#84)

Adapts the AmpForm interface and implementation to QRules v0.9.0.

Naming has been changed accordingly, most notably that graphs become transitions, edges becomes states, nodes become interactions. Some related interface changes:

• AmpForm's own ReactionInfo (under kinematics) and State (under helicity) have been removed
• TwoBodyKinematicVariableSet:
  • in_edge_inv_mass -> incoming_state_mass
  • out_edge_inv_mass1 -> outgoing_state_mass1
  • out_edge_inv_mass2 -> outgoing_state_mass2
  • There are now also an instance check on its constructor.

AmpForm's helicity module has been split (#87)

Split up the helicity module.

Major change: the generate() method is now called formulate() (97e9ce2)

Related to #61

HelicityModel.generate() has been renamed to HelicityModel.formulate() (#87)

All methods and functions that produce sympy.Exprs are now named 'formulate' instead of 'generate'.

Coefficient names have been changed (#80)

This changes the sum of amplitudes in some cases!

Fixes #73

New notation:

For comparison, there's also 32bb1b6, which also includes helicity, but which results in 8 unique coefficient names:

🔨 Internal maintenance

Test fixtures are now parametrized (#86)

Some improvements to the test set-up.

📝 Documentation

Links to expertsystem replaced with internal links (#82)

Some links in the expertsystem, because intersphinx is a bit too eager.

Intersphinx links can now pinned to specific versions of external API pages (#83)

Added explanation for how to substitute parameters (#88)

First step towards #5. Adds a new page that shows some SymPy tricks to modify the HelicityModel.

Added explanation of how to couple parameters (#89)

Closes #5

AmpForm 0.9.4

Release 0.9.4

See all documentation for this version here.

💡 New features

More phase space factor types available (#81)

⚠️ Interface

phase_space_factor_ac has been renamed to phase_space_factor_analytic (#81)

phase_space_factor does not use ComplexSqrt anymore (#81)

This reverts the phase space factor behaviour to that of version 0.9.2 and prior.

📝 Documentation

Improvements to the analytic-continuation and dynamics pages (#81)

🖱️ Developer Experience

upgrade pinned requirements (#79)

Automated changes by create-pull-request GitHub action

AmpForm 0.9.3

Release 0.9.3

See all documentation for this version here.

💡 New features

Added a new dynamics builder for analytic continuation (#78)

Added a new function create_analytic_breit_wigner to ampform.dynamics.builder that allows setting a relativistic_breit_wigner_with_ff with analytic continuation.

🐛 Bug fixes

Return masses as floats if possible (#76)

Since #75 there is no need to use complex values as input for analytic continuation.

Set relativistic Breit-Wigner with form factor to 0 if 𝑠 below threshold (#77)

A relativistic Breit-Wigner with Blatt-Weisskopf form factor now returns 0 below threshold. See updated docstring.

AmpForm 0.9.2

Release 0.9.2

See all documentation for this version here.

🐛 Bug fixes

More control over complex square roots provided through ComplexSqrt class (#72)

Closes #64

Implements TR-000 and TR-001 by defining a ComplexSqrt class. This allows for custom lambdification for specific expression tree nodes that are a square root.

📝 Documentation

Added tip about jupyter-katex (#74)

The complete amplitude model can only be rendered if jupyterlab-katex is installed. However, since KaTeX is less extensive than MathJax, this is only pointed out as a tip, and jupyterlab-katex is not added to the requirements.

Several improvements to the dynamics and analytic-continuation pages (#75, bb2b4f0, 955be9b)

🖱️ Developer Experience

Auto-close milestone upon release (#70)

Milestones are automatically closed once their matching release is published.

AmpForm 0.9.1

Release 0.9.1

See all documentation for this version here.

⚠️ Interface

Coefficient symbol name has been changed slightly (cdec30b)

The coefficients in canonical amplitudes ended in ";", while the coefficients for helicity amplitudes did not. Furthermore, an additional space has been added behind each intermediate ";" for readability.

🐛 Bug fixes

Function complex_sqrt() has been replaced with sympy.sqrt() to allow lambdified analytic continuation (#58)

The complex_sqrt() function causes problems when being lambdified, because it contains sympy.Piecewise. An attempt was made to replace complex_sqrt() with a class ComplexSqrt that defined specific lambdify methods (#59), but that approach results in too much maintenance work (for instance does not work out of the box with tensorflow).

This PR instead just casts all masses to complex values, so that numpy.sqrt works with negative values, e.g.:

>>> np.sqrt(np.array(-1, dtype=np.complex64))
1j

It's not ideal, but at least allows optimizing models with analytic continuation.

Closes #59

Improve signature of relative_breit_wigner_with_ff (31f5350)

Improve rendering of Clebsch-Gordan coefficient (9d98a3c)

The mini-fix for CG introduced by ComPWA/expertsystem#454 did not work well yet. This fix also removes the intermediate _ClebschGordanLatexFix class by replacing the CG._latex method.

🖱️ 📝 Documentation

Install doc requirements in Google Colab (1e6044f)

AmpForm 0.9.0

Release 0.9.0

Yanked in favor of v0.9.1 due to #58.

Major refactoring and improvements to the dynamics module and documentation.

See all documentation for this version here.

💡 New features

Extracted function for coupled, or "mass-dependent", width (#45)

The running width / coupled width / mass dependent width used in relativisitc_breit_wigner_with_ff is useful to K-matrix and Flatté. It's now exposed as a separate function:

AmpForm now ships with a symplot mini-package (#47)

Previously, the mini-package symplot was only available to the documentation, or as a relative import to notebooks. This did not work well, especially for the notebooks and for Google Colab.

Added phase space factor functions and added visualizations (#51)

Adds the functions phase_space_factor and phase_space_factor_ac, with references. The functions are, however, not yet implemented into the dynamic lineshapes.

Implement analytic continuation (#52 and #56)

Implemented phase_space_factor that was introduced by #51 into the coupled_width. The 'default' phase_space_factor has been adapted so that it can handle negative square roots.

Note: the overall lineshape of amplitude models does not change in the domain where it was defined so far. Only undefined domains are extended (see test_dynamics.py).

⚠️ Interface

BlattWeisskopf now uses z as argument, not q and d (#40)

Let the BlattWeisskopf callable only depend on z and angular_momentum. This leaves leaves the responsibility of setting z equal to break-up momentum times meson radius to the caller (too much logics going on within this class + this z = d * q is just one way to define things).

Improved API of dynamics module (#41, #54, and d79583d)

• The main dynamics module now only contains lineshape functions (801c7d9). This allows for cleaner imports, like :

  from ampform.dynamics import relativistic_breit_wigner

• Decorators that facilitate subclassing sympy.Expr have been isolated under dynamics.decorator (c1422ff)
• dynamics.builder can remain as it is (no circular dependencies), but its docstrings have been improved (ba24b2a)
• doit(), def_assumptions, and evaluate() are now hidden from the API (1c79ce4)
• Sub-classes of UnevaluatedExpr do not convert the args into properties anymore (bb1675a). This was causing a lot of code cluttering and those properties are not that useful.
• breakup_momentum now has references to the PDG (in preparation of analytic continuation) (020c5b3)

Return square value of break-up momentum (#48)

The original breakup_momentum contains a sqrt. This is inconvenient for the caller, because it does not allow handling negative values the break-up momentum squared. This is becomes important in phase space factors.

Use Mandelstam 𝑠 instead of 𝑚² (#49)

Comparable to #48, this allows handling negative values of 𝑠 or 𝑚².

Switch to square value of Blatt-Weisskopf (#53)

The value of Blatt-Weisskopf squared can be negative. This leaves it up to the caller how to handle these negative values if a square root is to be taken. Note that this becomes particularly important when the Blatt-Weisskopf function is used as a damping factor, like in relativistic_breit_wigner_with_ff and create_non_dynamics_with_ff, as opposed to coupled_width (where the square value is used).

Also improved some of the references for the lineshapes. In addition, a new interactive widget shows the effect of a Blatt-Weisskopf factor.

📝 Documentation

Improved mathematical rendering in dynamics API (#43)

#42 makes it easier to dynamically generate latex for the math in behind the dynamics module. This makes it easier to cross-reference the formulas as follows:

Screenshot of generated API

It now also becomes easier to extract for instance running width (both in coding and in math definitions).

Annotations in API are now abbreviated (#44)

Make the API more readable by abbreviating type hints. This style also mimics what one sees in the codebase.

Old

New

Insert line breaks (optional)

There's also an experimental option autodoc_insert_signature_linebreaks to insert line breaks before each argument:

but this has been switched off because it doesn't look nicely everywhere.

Added interactive dynamics lineshape widgets (#50)

Show effect of Blatt-Weisskopf factor on break-up momentum (#53)

Also improved some of the references for the lineshapes. In addition, a new interactive widget shows the effect of a Blatt-Weisskopf factor.

Improve signature of coupled_width (#54)

The signature of functions that have arguments with functions as default values (for an argument that expects a callable) do not render well. So it's better to use Optional[PhaseSpaceFactor] = None instead.

Improve dynamics page with widget output (#55)

Added phase sliders in K-matrix animation (5eda627)

Removed brackets from parenthetical citations (dda5099)

These citations are already rendered as links, so there's no need to put brackets around them. E.g.

[Chung et al. 1995], pp.2—4

becomes

Chung et al. 1995, pp.2—4

🖱️ Developer Experience

Removed myst-nb glue cells (#42)

The lineshapes notebook was used to insert a mathematical rendering of the implementations in the dynamics module into its docstrings. This has some disadvantages:

• Output cells have to be updated whenever some implementation. This could be countered with pytest-notebook, but that is bothersome if a notebook generates figures.

• The link between the module and that notebook is note immediately clear.

The math is now inserted through Sphinx only (through conf.py), which makes it easier to extend the dynamics module with more lineshapes and render their mathematics.

AmpForm 0.8.1

Release 0.8.1

See all documentation for this version here.

📝 Documentation

Generalized the procedure to create plot widgets for SymPy expressions (#31)

• Slider parameters are extracted from the remaining free symbols of an (amplitude) expression automatically. That makes it easier to plot any other amplitude model -- it's only needed to provide a domain for the sliders.
• Labels for the sliders are now the names of the (latex) symbols they represent
• The real and imaginary plot have been removed, leaving only the intensity plot and the Argand plot
• The interactive notebook can now be run independently

Extracted interactive plotting to symplot mini-package (#38)

The procedure illustrated in Inspect model interactively has been extracted to a 'mini-module' symplot. For now, it's only available to the Jupyter notebooks and to Sphinx, but if successful, it could be hosted as a separate package, so that it can also be used for the PWA pages.

Added interactive notebook for inspect K-matrix behavior (#39)

Illustrate difference between K-matrix and sum of Breit-Wigners with symplot from #38. See this notebook/page.

Added references to dependency pinning in installation instructions (580a7f2)

Added cSpell badge (4f12285)

Updated links to related projects on RTD (b7871b7)

RTD namespace "pwa" has been disabled to shorten URLs.

Documentation now renders better on mobile (a4ef501)

See https://github.com/executablebooks/sphinx-book-theme/blob/master/CHANGELOG.md#v0042v010

🔨 Internal maintenance

Adapt tests to official qrules release (#29)

Automated changes by create-pull-request GitHub action

Remove remnants from expertsystem/qrules (#34)

Remove things that are only useful to qrules, such as jsonschema, pydot, constraints, and sphobjinv (for constraints).

Clean up pylint configuration (#35)

• Remove built-ins check (flake8-builtins handles this)
• Sort pylintrc sections
• Use good-names-rgxs
• Use error names instead of error codes
• Move some of the ignores inline

Optional dependencies collection "extras" has been renamed to "all" (0f676c8)

Makes a bit more sense, i.e.:

pip install ampform[all]

instead of

pip install ampform[extras]

🖱️ Developer Experience

Moved requirements back to setup.cfg (#27)

With the release of pip-tools v6.1.0, pip-compile now correctly handles extras_require. This allows for a big clean-up of the set-up introduced by ComPWA/expertsystem#412.

Advantages:

• Easier for the user and developer! Just run: pip install -e .[dev] to get started developing, pip install -e .[dev] -U to try out upgrades, and pip install -c .constraints/py3.8.txt -e .[dev] -U in case you exactly want to reproduce the dependencies for some commit.
• The upgrade jobs become significantly faster: bit over 1min versus almost 3min
• All requirements, their version domains, and the dependencies between each of the requirement sections can be nicely overseen and maintained within setup.cfg
• Git diffs for pull requests that affect dependencies become easier to oversee
• Less complexity and fewer changes per commit

Bug fix: define testpaths in pytest.ini (#28)

Since 35aa838, it is become impossible to run tests through VSCode. Defining testpaths fixes this. In addition, it removes the last 'non-tox' section from the tox.ini file (see 81402eb).

See also ComPWA/qrules#42

Added GitHub PR template (#32)

GitPod now automatically installs VSCode extensions (#32)

Added radon complexity check (#33)

Cleaned up pylint configuration (#35)

• Remove built-ins check (flake8-builtins handles this)
• Sort pylintrc sections
• Use good-names-rgxs
• Use error names instead of error codes
• Move some of the ignores inline

Added more flake8 plugins and fixed identified issues (#36)

• flake8-comprehensions
• flake8-pytest-style
• flake8-use-fstring

Removed nbstripout from format requirements and added as pre-commit hook (#37)

Pre-commit hooks should only be local if the corresponding tool can also be used through other applications (e.g. IDEs or Jupyter Lab), so that their versions are in sync. And nbstripout can only be used through the terminal, so is best enforced through pre-commit only.

Extracted .mypy.ini file from setup.cfg (47f0004)

This cleans up the setup.cfg file so that it only contains info a the set-up of the package

Extracted config files for dev tools from tox.ini (81402eb)

Better to only keep tox job definitions in the tox.ini file. Note that config files are only extracted if their respective tools supports a config file name that starts with a dot

Run black formatting in documentation (324d684)

Doctests are now verified with pytest instead of Sphinx (35aa838)

This is much faster, allows for testing coverage, and is also easier to run locally.

Renamed CI workflows to pytest and pre-commit (0da2a84)

This works better with the CI badges

Added test explorer VSCode extension and removed redundant extensions (d04c4f8)

AmpForm 0.8.0

Release 0.8.0

See all documentation for this version here.

💡 New features

Extend Blatt-Weisskopf to L <= 8 (#15)

• Improved rendering of the BlattWeisskopf in the API and the lineshape notebook
• Extended the Blatt-Weisskopf definition to angular momentum of up to L <= 8

⚠️ Interface

Rename particle argument to resonance (#17)

First argument of the ResonanceDynamicsBuilder protocol has been renamed to resonance.

Improve BlattWeisskopf signature (#25)

Previously only had args, now it has a specific signature.

📝 Documentation

Improve citation labels and bibliography (#14)

• Both DOI and URLs are now in the bibliography file. If both are available, only the DOI is rendered in the HTML pages (with link).
• References are now shown as [Author et al. year] instead of some number e.g. [1].
• Language tags have been removed from the bibliography.bib file.
• Added more type hints to the docs/conf.py file

Improve instructions for custom dynamics (#16)

Made the custom dynamics instructions a bit more user-friendly by:

• putting the import statements where they are used (for copy-button)
• clarifying what the output of a custom dynamics builder is by declaring an expression and parameter_defaults parameter

🎉 Add notebook with interactive Argand plots (#23)

A new page has been added that illustrates how to use mpl-interactions to inspect the amplitude model. The page is a notebook that can be used interactively, but also renders nicely as an animation on the rendered HTML page itself.

Improve introductory text on main index page and usage page (#26)

🖱️ Developer Experience

Split CI workflow into sty, docs, and tests (#13)

Standardize cspell config (#18)

Use the new check-dev-files hook to rename and format the .cspell.json file.

Verify shape of amplitude model and increase test coverage (#20)

Previously, the tests did not check the shape of the complete amplitude model (specifically, the dynamics). The documentation only shows what those shapes look like, but don't check their shape. This is a problem when refactoring the dynamics (see in particular the epic/improve-dynamics branch).

Remove redundant dev dependencies (#22)

In particular pydeps and ipywidgets (which may be added later on again in the dynamics epic branch).