deprecated

import ampform.sympy.deprecated

Deprecated classes and functions for constructing unevaluated expressions.

Deprecated since version 0.15.0.

class UnevaluatedExpression(*args, name: str | None = None, **hints)

Bases: Expr

Base class for expression classes with an evaluate() method.

Deriving from Expr allows us to keep expression trees condense before unfolding them with their doit method. This allows us to:

1. condense the LaTeX representation of an expression tree by providing a custom _latex() method.

2. overwrite its printer methods (see NumPyPrintable and e.g. Custom lambdification).

The UnevaluatedExpression base class makes implementations of its derived classes more secure by enforcing the developer to provide implementations for these methods, so that SymPy mechanisms work correctly. Decorators like implement_expr() and implement_doit_method() provide convenient means to implement the missing methods.

static __new__(cls: type[DecoratedClass], *args, name: str | None = None, **hints) → DecoratedClass

Constructor for a class derived from UnevaluatedExpression.

This __new__() method correctly sets the args, assumptions etc. Overwrite it in order to further specify its signature. The function create_expression() can be used in its implementation, like so:

>>> class MyExpression(UnevaluatedExpression):
...     def __new__(
...         cls, x: sp.Symbol, y: sp.Symbol, n: int, **hints
...     ) -> "MyExpression":
...         return create_expression(cls, x, y, n, **hints)
...
...     def evaluate(self) -> sp.Expr:
...         x, y, n = self.args
...         return (x + y) ** n
>>> x, y = sp.symbols("x y")
>>> expr = MyExpression(x, y, n=3)
>>> expr
MyExpression(x, y, 3)
>>> expr.evaluate()
(x + y)**3

abstract evaluate() → Expr

Evaluate and ‘unfold’ this UnevaluatedExpression by one level.

>>> from ampform.dynamics import BreakupMomentumSquared
>>> s, m1, m2 = sp.symbols("s m1 m2")
>>> expr = BreakupMomentumSquared(s, m1, m2)
>>> expr
BreakupMomentumSquared(s, m1, m2)
>>> expr.evaluate()
(s - (m1 - m2)**2)*(s - (m1 + m2)**2)/(4*s)
>>> expr.doit(deep=False)
(s - (m1 - m2)**2)*(s - (m1 + m2)**2)/(4*s)

Note

When decorating this class with implement_doit_method(), its evaluate() method is equivalent to doit() with deep=False.

_latex(printer: LatexPrinter, *args) → str

Provide a mathematical Latex representation for pretty printing.

>>> from ampform.dynamics import BreakupMomentumSquared
>>> s, m1 = sp.symbols("s m1")
>>> expr = BreakupMomentumSquared(s, m1, m1)
>>> print(sp.latex(expr))
q^2\left(s\right)
>>> print(sp.latex(expr.doit()))
- m_{1}^{2} + \frac{s}{4}

class DecoratedClass

TypeVar for decorators like implement_doit_method().

alias of TypeVar(‘DecoratedClass’, bound=UnevaluatedExpression)

implement_expr(n_args: int) → Callable[[type[DecoratedClass]], type[DecoratedClass]]

Decorator for classes that derive from UnevaluatedExpression.

Implement a __new__() and doit() method for a class that derives from Expr (via UnevaluatedExpression).

implement_new_method(n_args: int) → Callable[[type[DecoratedClass]], type[DecoratedClass]]

Implement UnevaluatedExpression.__new__() on a derived class.

Implement a __new__() method for a class that derives from Expr (via UnevaluatedExpression).

implement_doit_method(decorated_class: type[DecoratedClass]) → type[DecoratedClass]

Implement doit() method for an UnevaluatedExpression class.

Implement a doit() method for a class that derives from Expr (via UnevaluatedExpression). A doit() method is an extension of an evaluate() method in the sense that it can work recursively on deeper expression trees.

class DecoratedExpr

TypeVar for decorators like make_commutative().

alias of TypeVar(‘DecoratedExpr’, bound=Expr)

make_commutative(decorated_class: type[DecoratedExpr]) → type[DecoratedExpr]

Set commutative and ‘extended real’ assumptions on expression class.

See also

Assumptions

create_expression(cls: type[DecoratedExpr], *args, evaluate: bool = False, name: str | None = None, **kwargs) → DecoratedExpr

Helper function for implementing UnevaluatedExpression.__new__.