Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions BREAKING-CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,10 @@ read first.
| **Silent** | `"1/x - 1/x".ToEntity().Simplify()`, and every difference of a term from itself where that term can be undefined | `0`, including at `x = 0` where neither side has a value | `0 provided not x = 0` |
| **Silent** | `"(x + 1)!/(x + 1)!".ToEntity().Simplify()`, and every cancelled quotient whose repeated part can be undefined | `1 provided not (1 + x)! = 0` | `1 provided 1 + x in RR and (1 + x >= 0 or not 1 + x in ZZ)` — the same value everywhere, a condition that says why |
| | `"ln(x)/ln(x)".ToEntity().Simplify()`, and every quotient divided out by a divisor that can be undefined | `1 provided not ln(x) = 0` — which is `1` at `x = 0`, where the quotient has no value | `1 provided not ln(x) = 0 and not x = 0` |
| | `Transformation.CanonicalizationOverGraph(budget).ApplyOrKeep("(x + y) * (x - y)")`, and every input one of `Common`'s sixteen newly declared rules collects | `(-y + x) * (x + y)` — not the tree `x ^ 2 - y ^ 2` reaches | `-y ^ 2 + x ^ 2` — one tree for both |
| | the same on `x + x`, and `x + x * y` | `x + x`, `x * y + x` — left as written | `2 * x`, `(1 + y) * x` |
| **Silent** | `RewriteRules.Common.Rules[i].Growth`, for sixteen rules | `Unknown` | `Collects` for fourteen, `Rearranges` and `Expands` for the reciprocal-factor pair |
| **Silent** | what `RewriteRuleGrowth.Collects` promises | fewer nodes for every input | never more, and fewer for some — every rule that was `Collects` still is |

### A cancelled quotient says its operand is defined, not only non-zero

Expand Down Expand Up @@ -865,6 +869,37 @@ the middle of a rewrite. It is a bound where there was none, not a tight one.
[#896](https://github.com/asc-community/AngouriMath/issues/896) said a caller could not previously
find out.

### `Collects` promises never larger, and `Common` declares sixteen growths

`RewriteRuleGrowth.Collects` used to mean the replacement is written with fewer nodes than the
pattern for every input. It now means **never more, and fewer for some** — `Rearranges` is still
the same size for every input and `Expands` still larger for every input. Every rule that was
`Collects` still is, and every count written beside one ("exactly −2", "at most −4") still holds; the
promise is weaker only where nothing relied on the strong one. The reason is the commonest
collecting shape in the library: a hole matched twice and written once beside one new node,
`a + a = 2 * a`, `a * a = a ^ 2`, `a + a * b = a * (1 + b)`, which is `1 − |a|` — exactly as large
at a leaf and smaller everywhere else. Under the strict reading it could not be declared at all,
and thirteen of `Common`'s rules sat at `Unknown` for it.

Sixteen of `Common`'s rules declare a growth now, so `RewriteRules.Common.Rules[i].Growth` changes
for them, and `Saturation.RulesUpTo(Rearranges)` — the ceiling `Transformation.CanonicalizationOverGraph`
runs at by default — admits fifteen more rules, 157 of 324 where it was 142. What that changes on
ordinary input is what those rules do: a repeated term collects over the graph where it used to be
left as written, and the difference of squares reaches the tree its expansion reaches.
`Entity.Canonicalize()` runs `Transformation.Canonicalization`, the rule pass rather than the graph,
and answers exactly as before on every input below.

| | Was | Is |
|---|---|---|
| `Transformation.CanonicalizationOverGraph(budget).ApplyOrKeep("(x + y) * (x - y)")` | `(-y + x) * (x + y)` — not the tree `x ^ 2 - y ^ 2` reaches, `-y ^ 2 + x ^ 2` | `-y ^ 2 + x ^ 2` — one tree for both |
| the same on `(x + 1) * (x - 1)` | `(1 + x) * (-1 + x)` | `-1 + x ^ 2` |
| the same on `x + x` | `x + x` — left as written | `2 * x` |
| the same on `x + x * y` | `x * y + x` — reordered, not collected | `(1 + y) * x` |
| `RewriteRules.Common.Rules[i].Growth`, for sixteen rules | `Unknown` | `Collects` for fourteen; `Rearranges` for `a-reciprocal-rational-factor-is-a-division`, `Expands` for its negated twin |
| `RewriteRules.Common.Rules` by growth — collects / rearranges / expands / unknown | 21 / 14 / 5 / 22 | 35 / 15 / 6 / 6 |
| `RewriteRules.All` by growth | 97 / 45 / 30 / 152 | 111 / 46 / 31 / 136 |
| what `RewriteRuleGrowth.Collects` promises | fewer nodes for every input | never more, and fewer for some |

## 2.4.0 — since 2.3.0

Released 2026-08-28. These entries sat under “Unreleased” while 2.4.0 was tagged and
Expand Down
97 changes: 81 additions & 16 deletions Sources/AngouriMath/Core/Transformations/Matching/MatchedRules.cs

Large diffs are not rendered by default.

12 changes: 11 additions & 1 deletion Sources/AngouriMath/Core/Transformations/RewriteRule.cs
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,17 @@ namespace AngouriMath.Core.Transformations
/// </remarks>
public enum RewriteRuleGrowth
{
/// <summary>The replacement is written with fewer operators and operands than the pattern.</summary>
/// <summary>
/// The replacement is never written with more operators and operands than the pattern,
/// and with fewer for some of what the pattern matches.
/// </summary>
/// <remarks>
/// "Never more" is the half the growth ceiling relies on; "fewer for some" is what
/// separates this from <see cref="Rearranges"/>. The commonest collecting shape — a hole
/// matched twice and written once beside one new node, <c>a + a = 2 * a</c> — is exactly
/// as large at a leaf and smaller everywhere else, and a strict "always fewer" would have
/// left it unjudged.
/// </remarks>
Collects,

/// <summary>The two are written with the same number, so the rule moves things about.</summary>
Expand Down
4 changes: 2 additions & 2 deletions Sources/AngouriMath/Core/Transformations/Saturation.cs
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,8 @@ internal static class Saturation
/// ceiling should refuse — it means the rule's growth was not judged, because its
/// replacement is code rather than a written pattern, so admitting it accepts a rewrite
/// nobody measured. But it is where the rules are: of the 324 rules in
/// <see cref="MatchedRules"/>, <b>97 collect, 45 rearrange, 30 expand and 152 are
/// unjudged</b>. A ceiling that refuses the fourth value still refuses 47% of the library,
/// <see cref="MatchedRules"/>, <b>111 collect, 46 rearrange, 31 expand and 136 are
/// unjudged</b>. A ceiling that refuses the fourth value still refuses 42% of the library,
/// and what is left could not do much when this was written — over six expression pairs
/// equal only through a larger intermediate form, the
/// <see cref="RewriteRuleGrowth.Rearranges"/> ceiling proved two, and
Expand Down
31 changes: 21 additions & 10 deletions Sources/AngouriMath/Docs/Contributing/WritingARule.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ A pattern replacement gets:
- **an exact growth**, counted from the two patterns rather than declared.

A code replacement gets neither, and its growth is `Unknown` unless you declare one. That is the
honest default — **152** rules sit at `Unknown` — but declare it where you can justify it:
honest default — **136** rules sit at `Unknown` — but declare it where you can justify it:

```csharp
// The Chebyshev expansion of sin(n * a) is a sum of n terms where the pattern is one node,
Expand All @@ -157,30 +157,41 @@ cannot argue the claim from the code, leave it `Unknown`.

**Count the pattern against the replacement in terms of the holes**, and the answer is usually one
of a few shapes. A hole matched twice and written once gives `-(1 + |a|)`, which is a `Collects`
stronger than the corpus will show you, since the corpus fills its holes with single nodes. A
stronger than the corpus will show you, since the corpus fills its holes with single nodes. The same
hole beside one new node — `a + a = 2 * a`, `a * a = a ^ 2`, `a + a * b = a * (1 + b)` — gives
`1 - |a|`: exactly as large at a leaf and smaller everywhere else, and that is `Collects` too.
**`Collects` promises never larger, and smaller for some input**; `Rearranges` promises the same
size for every input. "Never larger" is the half the growth ceiling relies on, and the corpus checks
`Collects` by looking for a firing that grew, not for one that failed to shrink. A
replacement holding no hole at all — a constant, or `pi/2` — collects by the whole of the pattern.
Operators mapping one for one with every hole used once is `Rearranges`. A pattern that binds
nothing — `arctan(sqrt(3)) = pi/3`, `{ True, False }` — has a fixed size on both sides, so its delta
is a number and there is nothing to argue. And two numbers combined with `Number` arithmetic **fold
into one node** as the replacement is built, which is worth two on its own: `(c * v) * d` collects
where the same rule written without the cast would only rearrange.

**Four shapes look declarable and are not.** Each of these measured a clean, constant delta over the
**Two shapes look declarable and are not.** Each of these measured a clean, constant delta over the
corpus, and each is false:

| | |
|---|---|
| the replacement is built with `<`, `>` and their kin | they **chain**: `(x > y) < 0` is `x > y and y < 0`, so a three-node replacement becomes seven. `EqualTo` does not chain, which is why the `equals` rules are declared and their comparison twins are not |
| the replacement attaches a `Provided` built from the operands | its size grows with them while the pattern's shrinks away, so the delta changes sign: `2 - |c|` for the shared-factor cancellation, `4 - |a| - |b|` for `(a - b) / (b - a)` |
| a hole can be filled by two spellings of one thing | `IsWholeReciprocal` takes the literal `1/3`, which is one node, and a written `1 / c`, which is three — so the delta is 0 in one and −2 in the other |
| a hole is repeated and the replacement squares it | `a * (a * b) = a^2 * b` is `1 - |a|`: zero for a leaf and negative for anything bigger |
| the replacement attaches a `Provided` built from the operands | its size grows with them while the pattern's shrinks away, so the delta changes sign: `2 - |c|` for the shared-factor cancellation, `3 - |a| - |b|` for `(a - b) / (b - a)`, and `3 - |a|` for `a + a / b = a * (1 + 1 / b)`, which is *larger* at a leaf though the corpus never fired it |

Two more used to be listed here and are not. The repeated hole that pays a literal to be gathered —
`a * (a * b) = a ^ 2 * b`, `k + k = 2 * k` and their relatives, every one `1 - |a|` — was
undeclarable only while `Collects` was read as "always fewer"; it is the commonest collecting shape
there is, and `Collects` promises never larger. `Common`'s thirteen are declared, with the count in
each one's comment; the relatives in `Power` and `Factorization` — `a ^ n * a`, `a / b / b` and
theirs — are the next to declare, each on its own count. And the reciprocal-factor rules were said
to admit two spellings of one thing; `IsWholeReciprocal` is `entity is Rational(...)`, so it admits
the literal only, and the pair is exactly `Rearranges` and exactly `Expands`.

**Every rule still at `Unknown` has been looked at, and each falls into one of the shapes above.**
Most of them compute their answer through a helper, so there is nothing to count; the rest either
build a comparison, attach a `Provided` sized by their own operands, or are the repeated hole that
pays a literal to be gathered — `a ^ n * a`, `a / b / b`, `a * a`, `k + k` and their two dozen
relatives, every one of them `1 - |a|`. So `Unknown` here is a finding rather than a gap, and a new
`Unknown` should be one too.
build a comparison or attach a `Provided` sized by their own operands. So `Unknown` here is a
finding rather than a gap, and a new `Unknown` should be one too — written beside the rule, as
`Common`'s six are.

**The comparison set is settled, and settled as `Unknown`.** Its sixty-odd rules were gone through
one at a time and all but seven fall into the shapes above: most build their replacement with `<` or
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -261,17 +261,20 @@ public void TheWideCeilingReachesWhatARulePassCannot()
}

/// <summary>
/// Widening the ceiling brings the difference of squares together — the narrow ceiling
/// leaves the product and the expansion as two forms, and the widest one canonicalises
/// both to the same tree.
/// The difference of squares used to need the widest ceiling: the narrow one left the
/// product and the expansion as two forms. It does not since
/// <c>a-difference-times-a-sum-of-one-pair-is-a-difference-of-squares</c> was declared
/// <c>Collects</c> on its count — <c>1 - |b|</c>, never larger — which is what admits it
/// to the narrow ceiling. Both ceilings canonicalise the two to one tree now, and this
/// used to assert the narrow one could not.
/// </summary>
[Fact]
public void TheWidestCeilingBringsTheDifferenceOfSquaresTogether()
public void TheNarrowCeilingBringsTheDifferenceOfSquaresTogether()
{
var product = "(x + y) * (x - y)".ToEntity();
var squares = "x ^ 2 - y ^ 2".ToEntity();

Assert.NotEqual(Narrow.ApplyOrKeep(product), Narrow.ApplyOrKeep(squares));
Assert.Equal(Narrow.ApplyOrKeep(product), Narrow.ApplyOrKeep(squares));
Assert.Equal(Wide.ApplyOrKeep(product), Wide.ApplyOrKeep(squares));
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -84,15 +84,17 @@ public void NoWrittenPatternIntroducesACondition()
}

/// <summary>
/// <b>The safe ceiling is nearly inert on ordinary input.</b> Four of these five come back
/// exactly as they went in; only the Pythagorean identity moves. That is not a defect in
/// <b>The safe ceiling is nearly inert on ordinary input.</b> Three of these five come back
/// exactly as they went in; the Pythagorean identity moves, and the difference of squares
/// has since its rule was declared <c>Collects</c> — to <c>x ^ 2 - 1 ^ 2</c>, since no
/// safe rule folds a numeric power. That is not a defect in
/// the expressions — it is what the graph can do today with the rules it is allowed to
/// use, and it is the measurement
/// <a href="https://github.com/asc-community/AngouriMath/issues/746">#746</a> tier 2 needs
/// before the graph is wired into anything.
/// </summary>
/// <remarks>
/// <c>SafeRules</c> is <c>RulesUpTo(Rearranges)</c>, 142 of 324 rules. The 152 sitting at
/// <c>SafeRules</c> is <c>RulesUpTo(Rearranges)</c>, 157 of 324 rules. The 136 sitting at
/// <c>Unknown</c> are excluded by design, since their growth was never judged — so the
/// ceiling that is safe to run finds little, and the ceiling that finds things admits
/// rewrites nobody measured. That trade is the open part of tier 2, and this pins where it
Expand All @@ -116,8 +118,8 @@ public void TheSafeCeilingIsNearlyInertOnOrdinaryInput()
moved.Add($"{source} -> {extracted.Stringize()}");
}

Assert.True(still.Count == 4 && moved.Count == 1,
$"the safe ceiling moved {moved.Count} of 5 and left {still.Count}; it was 1 and 4.\n"
Assert.True(still.Count == 3 && moved.Count == 2,
$"the safe ceiling moved {moved.Count} of 5 and left {still.Count}; it was 2 and 3.\n"
+ "moved:\n" + string.Join("\n", moved)
+ "\nunchanged:\n" + string.Join("\n", still));
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -89,19 +89,19 @@ public void ReplacementAPatternOrCode()
"how many rules have a pattern on both sides");
Stated(33, rules.Count(rule => rule.Reversed is not null),
"how many two-sided rules have a direction");
Stated(152, rules.Count(rule => rule.Growth is RewriteRuleGrowth.Unknown),
Stated(136, rules.Count(rule => rule.Growth is RewriteRuleGrowth.Unknown),
"how many rules sit at Unknown growth");

// The rest of the census, because `Saturation.RulesUpTo` argues from it in prose and
// the figures it quoted had gone stale by a factor of four -- "26 collect, 17
// rearrange, 9 expand and 270 unjudged", measured before the growth declarations
// went in. The argument survived; the arithmetic did not. A number a remark reasons
// from belongs somewhere that fails when it moves.
Stated(97, rules.Count(rule => rule.Growth is RewriteRuleGrowth.Collects),
Stated(111, rules.Count(rule => rule.Growth is RewriteRuleGrowth.Collects),
"how many rules are declared Collects");
Stated(45, rules.Count(rule => rule.Growth is RewriteRuleGrowth.Rearranges),
Stated(46, rules.Count(rule => rule.Growth is RewriteRuleGrowth.Rearranges),
"how many rules are declared Rearranges");
Stated(30, rules.Count(rule => rule.Growth is RewriteRuleGrowth.Expands),
Stated(31, rules.Count(rule => rule.Growth is RewriteRuleGrowth.Expands),
"how many rules are declared Expands");

// And the two the document names. By their own names rather than by what the prose
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,11 @@ public sealed class RuleGrowthAgreesWithTheCorpusTest
"x! = 0", "(x - y) / (y - x)", "x - (x - y)", "(x - y) - x",
"x * y - x", "x - x * y", "x * x", "x * x * y", "x * (x * y)",
"sin(x) * 2", "2 * sin(x)",

// The collecting shapes that are exactly as large at a leaf -- a term beside a product,
// a sum or a difference of itself -- and the sign-times-absolute-value cancellation.
"x + x * y", "x + (x + y)", "x + (x - y)", "x - (y - x)", "(y - x) - x",
"sgn(x) * (y * x) / abs(x)",
};

private static List<Entity> Corpus()
Expand Down Expand Up @@ -211,7 +216,10 @@ public void NoDeclaredGrowthIsContradictedByTheCorpus()
var delta = Size(after) - Size(before);
var contradicts = rule.Growth switch
{
RewriteRuleGrowth.Collects => delta >= 0,
// Collects promises never larger and smaller for some input, so the same
// size is not a contradiction: the corpus fills holes with leaves, where
// `a + a = 2 * a` is exactly as large as it was.
RewriteRuleGrowth.Collects => delta > 0,
RewriteRuleGrowth.Rearranges => delta != 0,
RewriteRuleGrowth.Expands => delta <= 0,
_ => false
Expand Down
Loading