diff --git a/mathics/core/rules.py b/mathics/core/rules.py index 4285b72c6..6af8f5ff5 100644 --- a/mathics/core/rules.py +++ b/mathics/core/rules.py @@ -1,15 +1,51 @@ # -*- coding: utf-8 -*- -"""Rules are a core part of the way WMA and Mathics3 executes a +"""Rules are a core part of the way Mathematica and Mathics3 execute a program. Expressions which are transformed by rewrite rules (AKA transformation -rules) are handed by the Rule class. +rules) are handed by the `Rule` class. -There are also rules for how to match, assign parameter arguments, and -apply Mathics3 functions that are implemented in Python code. The -FunctionApplyRule class handles this. +There are also rules for how to match, assign function parameter +arguments, and then apply a Python "evaluation" function to a Mathics3 Expression. +These kinds of rules are handled by objects in the `FunctionApplyRule` class. This module contains the classes for these two types of rules. + +In a `FunctionApplyRule` rule, the match status of a rule depends on the evaluation return. + +For example, suppose that we try to apply rule `F[x_]->x^2` to the expression `F[2]`. The pattern part of the rule,`F[x_]` matches +the expression, `Blank[x]` (or `x_`) is replaced by `2`, giving the substitution expression `2^2`. Evaluation then stops +looking for other rules to be applied over `F[2]`. + +On the other hand, suppose that we define a `FunctionApplyRule` that associates `F[x_]` with the function: + +``` +... +class MyFunction(Builtin): + ... + def eval_f(self, x, evaluation) -> Optional[Expression]: + "F[x_]" # pattern part of FunctionApplyRule + if x>3: + return Expression(SymbolPower, x, Integer2) + return None +``` + +Then, if we apply the rule to `F[2]`, the function is evaluated returning `None`. Then, in the evaluation loop, we get the same +effect as if the pattern didn't match with the expression. The loop continues then with the next rule associated with `F`. + +Why do things this way? + +Sometimes, the cost of deciding if the rule match is similar to the cost of evaluating the function. Suppose for example a rule + + F[x_/;(G[x]>0)]:=G[x] + +with G[x] a computationally expensive function. To decide if G[x] is larger than 0, we need to evaluate it, +and once we have evaluated it, just need to return its value. + +Also, this allows us to handle several rules in the same function, without relying on our very slow pattern-matching routines. +In particular, this is used for for some critical low-level tasks like building lists in iterators, processing arithmetic expressions, +plotting functions, or evaluating derivatives and integrals. + """ @@ -224,7 +260,8 @@ def __repr__(self) -> str: class FunctionApplyRule(BaseRule): - """A FunctionApplyRule is a rule that has a replacement term that + """ + A FunctionApplyRule is a rule that has a replacement term that is associated a Python function rather than a Mathics Expression as happens in a transformation Rule. @@ -260,7 +297,7 @@ class FunctionApplyRule(BaseRule): sets the attribute ``NumericFunction`` in the definition of the symbol ``F`` and returns Null (``SymbolNull`)`. - This will cause `Expression.evalate() to perform an additional + This will cause `Expression.evaluate() to perform an additional ``rewrite_apply_eval()`` step. """