Wolfram Language Paclet Repository
Community-contributed installable additions to the Wolfram Language
Adding New Transformation Rules
This explains how to find, test, and deploy new transformation rules.
Finding Rules
Generating Canonical Forms of Expressions
Generating Canonical Forms of Expressions
converts an expression into canonical form | |
converts an expression into canonical form without evaluation |
Utility functions for seeing the canonical form of an expression.
Equivalence of code is determined by comparing their canonical representations.
Check if two expressions are equivalent:
In[7]:=
 | CodeEquivalentQ |
Out[7]=
True
Compare their canonical forms:
In[8]:=
| MakeCanonicalForm |
Out[8]=
TableDiscreteUniformDistribution0,,,1,5,1
ℛ
S1∷Int
S1∷Int
In[9]:=
| MakeCanonicalForm |
Out[9]=
TableDiscreteUniformDistribution0,,,1,5,1
ℛ
S1∷Int
S1∷Int
These can be directly compared:
In[10]:=
%===%%
Out[10]=
True
By tracing the sequence of transformations, you can get an idea of what kind of rule to introduce to get the transformations to converge.
In[3]:=
expr1=HoldForm[Table[RandomReal[],10]]
Out[3]=
Table[RandomReal[],10]
In[4]:=
expr2=HoldForm[Table[RandomReal[1],10]]
Out[4]=
Table[RandomReal[1],10]
 | ToCanonicalForm |
Table[RandomReal[],10] |
Table[RandomReal[],{S,1,10,1}] |
TableRandomReal[], S1∷Int |
| ToCanonicalForm |
RandomReal[1,10] |
Table[RandomReal[1],10] |
Table[RandomReal[1],{S,1,10,1}] |
TableRandomReal[1], S1∷Int |
TableRandomReal[{0,1}], S1∷Int |
TableRandomValue[UniformDistribution[{0,1}]], S1∷Int |
Notice that the only difference between expr1 and the second transformation of expr2 is that one has instead of . Since is equivalent to , this might be a good idea to use as a rule.
Adding new rules temporarily
$TransformationRules | the set of transformation rules used to convert expressions to their canonical forms |
BuildDispatch |
Tools for building new conversion rules.
The symbol (defined in Kernel/CanonicalForms/Rules.m) contains the rules used by . For testing, we can modify the rules in the current session without reloading the package by using .
$TransformationRules
BuildDispatch
Here's the desired rule from the previous example:
newRule=HoldPattern[RandomReal[]]RandomReal[1];
Create a new set of rules that includes this one:
newTransformationRules=Append[$TransformationRules,newRule];
BuildDispatch[newTransformationRules]
Rebuilt transformation rules----------------------------Count: 138Added: 1Removed: 0----------------------------
Now we can verify that expr1 reaches the desired canonical form:
| ToCanonicalForm |
| ToCanonicalForm |
True
| ToCanonicalForm |
Table[RandomReal[],10] |
Table[RandomReal[],{S,1,10,1}] |
TableRandomReal[], S1∷Int |
TableRandomReal[1], S1∷Int |
TableRandomReal[{0,1}], S1∷Int |
TableRandomValue[UniformDistribution[{0,1}]], S1∷Int |
Testing new rules
Run the included unit tests to make sure that adding the new rule doesn't interfere with anything else:
testFile=FileNameJoin[{Lookup[PacletInformation["CodeEquivalence"],"Location"],"Tests","CanonicalForms","Rules.wlt"}];
results=Block[{CodeEquivalence`EvaluationControl`$Memoize=False(*toavoidusinganycachedresults*)},TestReport[testFile,TimeConstraint1]]
TestReportObject
 |  |
| ||||
Adding new rules permanently
Current method (soon to be obsolete)
Current method (soon to be obsolete)
Once a new rule has been successfully tested, it should be added to in Kernel/CanonicalForms/Rules.m.
$TransformationRules
The format of elements in is somewhat flexible. Items can be given as single transformation rules, such as:
$TransformationRules
HoldPattern[RandomReal[]]RandomReal[1]
However, in order to separate rules into conceptual categories, it can also accept groups of transformation rules (wrapped in or ), which is how almost all the rules are defined in Kernel/CanonicalForms/Rules.m.
For convenience, when rules are contained inside a , the build code will automatically wrap the left-hand side of the rules in , so the previous rule (if given inside a group) could also be written as which is a bit easier to read.
New method (still a work in progress)
New method (still a work in progress)
Eventually, rules will be stored as associations that contain additional metadata. For this example, the corresponding transformation rule could be written as:
"Category""Random","Usage"{"CanonicalForm"},"Rule"HoldPattern[RandomReal[]]RandomReal[1],"Description""Eliminate instances of RandomReal with no arguments."
However, this system is still a work in progress and subject to change, so don’t worry about it too much yet.
Adding new unit tests
Once a new rule is added, a corresponding unit test should be added to Tests/CanonicalForms/Rules.wlt. In this case, the following test would be appropriate:
Utilities for transformation rules
Symbols that are useful in defining new transformation rules.
TrEval
TrEval
Forces evaluation of the right-hand side of a transformation rule.
WithHolding
WithHolding
Also allows use of local values in subsequent assignments:
TempHold
TempHold
NewLocalSymbol / LocalContextQ
NewLocalSymbol / LocalContextQ
CodeEquivalence`CanonicalForms`Scope`LocalSymbols`S$12
Other forms:
{CodeEquivalence`CanonicalForms`Scope`LocalSymbols`S$23,
CodeEquivalence`CanonicalForms`Scope`LocalSymbols`S1337,
CodeEquivalence`CanonicalForms`Scope`LocalSymbols`symbol$24,
CodeEquivalence`CanonicalForms`Scope`LocalSymbols`name$25,
CodeEquivalence`CanonicalForms`Scope`LocalSymbols`definition$26}
CodeEquivalence`CanonicalForms`Scope`LocalSymbols`S1337,
CodeEquivalence`CanonicalForms`Scope`LocalSymbols`symbol$24,
CodeEquivalence`CanonicalForms`Scope`LocalSymbols`name$25,
CodeEquivalence`CanonicalForms`Scope`LocalSymbols`definition$26}
SymbolQ
SymbolQ
Useful for when matching against _Symbol isn’t enough:
Doesn’t evaluate the symbol:
Inline
Inline
Replaces symbols with their value:
SafeEvaluatedQ
SafeEvaluatedQ
Tests if an expression has been fully evaluated:
Only works if the evaluation would be free of side effects:
Useful for reducing simple subexpressions: