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
26 changes: 26 additions & 0 deletions BREAKING-CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -233,6 +233,32 @@ returned as all of them. `MathS.Equations("y^2 - 2", "x^2 + (P - Q y) * x - 3").

---

### A set `MathS.Settings.Budget` caps a budget passed as an argument instead of replacing it

**Silent: the same call stops sooner.** A set `MathS.Settings.Budget` replaced every budget in the library, including one
a caller passed by hand, so `EqualitySaturation(budget, ...)` and `CanonicalizationOverGraph(budget)` inside a scope set
to `WorkBudget.Unlimited` ran unlimited. Now what a set budget does depends on what the budget it meets is for
([#2454](https://github.com/asc-community/AngouriMath/issues/2454)): a budget passed as an argument runs under the smaller
limit on each axis of it and the setting, so `Unlimited` leaves it as passed; the perfect-square proof that `Factorize`
runs and `Simplify` offers keeps its own lid of 2,000 steps and 50 ms under the same rule, so a set budget only tightens
it; and the system solver and its Gröbner path are replaced by the setting as before, so raising it still allows more.
With `budget = new WorkBudget { Steps = 5, Time = TimeSpan.FromSeconds(30) }`, inside
`MathS.Settings.Budget.Set(WorkBudget.Unlimited)`:

| Input | Was (2.7.0) | Now |
|---|---|---|
| `Transformation.EqualitySaturation(budget, CostModel.Default).ApplyOrKeep("x * 2 * 3 + x")` | `x * 7` | `x * 2 * 3 + x` |
| `Transformation.EqualitySaturation(budget, CostModel.Default).ApplyOrKeep("2 * sqrt(2) * sqrt(3)")` | `2 * sqrt(6)` | `2 * sqrt(2) * sqrt(3)` |
| `Transformation.CanonicalizationOverGraph(budget).ApplyOrKeep("a * b + b * a")` | `2 * a * b` | `a * b + a * b` |
| `Transformation.CanonicalizationOverGraph(budget).ApplyOrKeep("x + 0 + 2 * x")` | `3 * x` | `2 * x + x` |

Unset, nothing moves. `Factorize` and `Simplify` give the same answers on 2.7.0 and now under an unset,
an `Unlimited`, a `{ Steps = 1 }` and a `{ Steps = 1_000_000 }` budget, measured on `2 + 2 * sqrt(2) * sqrt(3) + 3`,
`a + 2 * sqrt(a) * sqrt(b) + b` and `2 + 2 * sqrt(6) + 3`: a proof the lid stops is "not proved", and the symbolic test
behind it still answers.

---

### An indexed union or intersection binds its index

**Silent: a bound name is no longer reported free.** `FreeVariables` of `union(A_k, k in I)` and `intersection(A_k, k in I)`
Expand Down
3 changes: 2 additions & 1 deletion Sources/AngouriMath/Convenience/MathS.Equality.cs
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,8 @@ partial class MathS
/// tried, a rule's match attempt, a node the graph grows by -- so the same question under
/// the same steps gets the same answer on any machine; a <see cref="WorkBudget.Time"/>
/// makes it depend on the machine, and <see cref="EqualityAnswer.Budget"/> says when it
/// did. <see cref="Settings.Budget"/>, where set, overrides this.
/// did. <see cref="Settings.Budget"/>, where set, caps this: the smaller limit on each axis
/// applies, so an ambient <see cref="WorkBudget.Unlimited"/> leaves it as passed.
/// </param>
/// <param name="weakest">
/// The weakest soundness a proof may rest on. <see cref="Soundness.Sound"/>, the default,
Expand Down
52 changes: 37 additions & 15 deletions Sources/AngouriMath/Convenience/MathS.cs
Original file line number Diff line number Diff line change
Expand Up @@ -6694,11 +6694,40 @@ internal static EDecimal DowncastingTolerance
/// <para>
/// <b>Leaving this alone is not the same as setting it to
/// <see cref="WorkBudget.Unlimited"/>.</b> Unset, each algorithm keeps the budget
/// it chose for itself -- the Gr&#246;bner path bounds itself by five seconds and
/// by five structural ceilings, and did so before this setting existed. Set, this
/// replaces those defaults wherever a budget is honoured, so
/// it chose for itself. Set, what it does depends on what that budget is for
/// (<a href="https://github.com/asc-community/AngouriMath/issues/2454">#2454</a>):
/// </para>
/// <list type="bullet">
/// <item><b>A working allowance is replaced.</b> The system solver
/// (<see cref="Core.EquationSystem.Solve(Variable[])"/>: 10,000 steps and 60 seconds
/// over the whole call) and its Gr&#246;bner path (5 seconds) run under this budget
/// instead of their own, so this is how a caller raises them -- and
/// <see cref="WorkBudget.Unlimited"/> here means "do not stop", which for a
/// doubly-exponential algorithm means what it says.
/// doubly-exponential algorithm means what it says.</item>
/// <item><b>A lid can only be tightened.</b> The proof that a written-out perfect
/// square is one, which <see cref="Entity.Factorize(int)"/> runs and
/// <see cref="Entity.Simplify(int)"/> offers as a candidate, bounds itself by 2,000
/// steps and 50 milliseconds against a stall. It runs under the smaller limit on
/// each axis of that and this, so setting this never makes <c>Simplify</c> or
/// <c>Factorize</c> run longer. A proof stopped early is "not proved" and falls back
/// to the symbolic test, so tightening it costs time, not answers.</item>
/// <item><b>A budget passed as an argument is capped.</b>
/// <see cref="Core.Transformations.Transformation.EqualitySaturation(WorkBudget, Core.CostModel)"/>,
/// <see cref="Core.Transformations.Transformation.CanonicalizationOverGraph(WorkBudget)"/> and
/// <see cref="AreEqual(Entity, Entity, WorkBudget, Core.Transformations.Soundness, Core.Domain)"/>
/// spend the budget they were given, under the smaller limit on each axis of it and
/// this: the outer scope bounds the inner one, and
/// <see cref="WorkBudget.Unlimited"/> here leaves the argument as passed.</item>
/// </list>
/// <para>
/// <b>A budget names both axes.</b> <see cref="WorkBudget"/> cannot say "no opinion"
/// about one of them, so a <see cref="WorkBudget.Time"/> left <see langword="null"/>
/// is "no clock": <c>new WorkBudget { Steps = 1_000_000 }</c> raises the solver's
/// steps and also removes its 60 seconds. Against a lid or an argument the missing
/// clock is simply the looser limit, and theirs applies -- the lid's 50 milliseconds
/// included, which decide how soon the proof gives up and not the answer. Saying
/// "no opinion" per axis is a change to <see cref="WorkBudget"/> itself, left to v3
/// (<a href="https://github.com/asc-community/AngouriMath/issues/746">#746</a>).
/// </para>
/// <para>
/// A budget in <see cref="WorkBudget.Steps"/> is reproducible and one in
Expand All @@ -6709,17 +6738,10 @@ internal static EDecimal DowncastingTolerance
/// (<a href="https://github.com/asc-community/AngouriMath/issues/373">#373</a>)
/// </para>
/// <para>
/// It is honoured only where an algorithm asks. Today that is the system solver --
/// its Gr&#246;bner path, and the ledger <see cref="Core.EquationSystem.Solve(Variable[])"/>
/// keeps over the whole call --, the rewrite graph wherever it runs:
/// <see cref="Core.Transformations.Transformation.EqualitySaturation(WorkBudget, Core.CostModel)"/>,
/// <see cref="Core.Transformations.Transformation.CanonicalizationOverGraph(WorkBudget)"/> and
/// <see cref="AreEqual(Entity, Entity, WorkBudget, Core.Transformations.Soundness, Core.Domain)"/>, and the proof that a written-out perfect
/// square is one, which <see cref="Entity.Factorize(int)"/> runs and
/// <see cref="Entity.Simplify(int)"/> offers as a candidate. <c>Simplify</c> itself
/// is not bounded by it, and nor is anything else in the library, each of which
/// bounds itself by ceilings of its own that this does not reach; so setting it does
/// not make an arbitrary call bounded.
/// It is honoured only at the sites listed above. <c>Simplify</c> itself is not
/// bounded by it, and nor is anything else in the library, each of which bounds
/// itself by ceilings of its own that this does not reach; so setting it does not
/// make an arbitrary call bounded.
/// </para>
/// </remarks>
/// <example>
Expand Down
45 changes: 41 additions & 4 deletions Sources/AngouriMath/Core/Budgets/BudgetLedger.cs
Original file line number Diff line number Diff line change
Expand Up @@ -69,11 +69,48 @@ private BudgetLedger(string where, WorkBudget limits)

/// <summary>
/// A ledger for one computation. <paramref name="ownDefault"/> is what the algorithm
/// bounds itself by when nobody has said otherwise; a caller who sets
/// <see cref="MathS.Settings.Budget"/> replaces it.
/// bounds itself by when nobody has set <see cref="MathS.Settings.Budget"/>;
/// <paramref name="role"/> says what a set one does to it.
/// https://github.com/asc-community/AngouriMath/issues/2454
/// </summary>
internal static BudgetLedger For(string where, WorkBudget ownDefault)
=> new(where, MathS.Settings.Budget.IsOverriden ? MathS.Settings.Budget.Value : ownDefault);
internal static BudgetLedger For(string where, WorkBudget ownDefault, BudgetRole role)
=> new(where, Limits(ownDefault, role));

/// <summary>The limits a computation of <paramref name="role"/> runs under.</summary>
internal static WorkBudget Limits(WorkBudget ownDefault, BudgetRole role)
{
var setting = MathS.Settings.Budget;
if (!setting.IsOverriden)
return ownDefault;
var set = setting.Value;
// A lid is tightened on both axes, not on the clock alone, although a step means
// something different to each algorithm. The incomparability is a reason not to
// *raise* one algorithm's ceiling by a number chosen for another, and a lid is never
// raised. Taking only the clock would ignore a caller who set steps -- the
// reproducible axis -- at exactly the sites where they asked for less. And it is
// cheap: the one lid, the perfect-square proof, completes in 15 to 1,203 steps over
// the unit suite (median 212), and a proof stopped short is "not proved", which falls
// back to the symbolic test -- so a budget below that costs time, and no answer of
// Factorize or Simplify was measured to move under one.
return role switch
{
BudgetRole.Allowance => set,
BudgetRole.Lid or BudgetRole.Argument => Tighter(ownDefault, set),
_ => throw new ArgumentOutOfRangeException(nameof(role), role, null),
};
}

/// <summary>
/// The smaller limit on each axis: what both <paramref name="a"/> and
/// <paramref name="b"/> allow. A missing <see cref="WorkBudget.Time"/> is no ceiling,
/// so it yields to any clock.
/// </summary>
private static WorkBudget Tighter(WorkBudget a, WorkBudget b)
=> new()
{
Steps = Math.Min(a.Steps, b.Steps),
Time = a.Time is { } x && b.Time is { } y ? (x < y ? x : y) : a.Time ?? b.Time,
};

/// <summary>
/// Charges <paramref name="units"/> of work and answers whether the computation may
Expand Down
39 changes: 39 additions & 0 deletions Sources/AngouriMath/Core/Budgets/BudgetRole.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
//
// Copyright (c) 2019-2026 Angouri.
// AngouriMath is licensed under MIT.
// Details: https://github.com/asc-community/AngouriMath/blob/master/LICENSE.md.
// Website: https://am.angouri.org.
//

namespace AngouriMath.Core.Budgets
{
/// <summary>
/// What a computation's own budget is for, which decides what a set
/// <see cref="MathS.Settings.Budget"/> does to it. Declared where the ledger is made,
/// <see cref="BudgetLedger.For"/>, so that each site says which it is.
/// https://github.com/asc-community/AngouriMath/issues/2454
/// </summary>
internal enum BudgetRole
{
/// <summary>
/// A guard against a stall inside an operation that is not about this computation
/// at all -- the perfect-square proof <c>Factorize</c> runs. A set budget can only
/// tighten it, so setting one never makes <c>Simplify</c> or <c>Factorize</c> run
/// longer than they would unset.
/// </summary>
Lid,

/// <summary>
/// The working allowance of an algorithm a caller asks for by name -- the system
/// solver, the Gr&#246;bner path. A set budget replaces it, which is what lets a caller
/// raise it; capping it instead would make raising it do nothing.
/// </summary>
Allowance,

/// <summary>
/// A budget the caller passed as an argument. It is the allowance, and a set budget,
/// being the outer scope, caps it: the smaller limit on each axis.
/// </summary>
Argument,
}
}
4 changes: 2 additions & 2 deletions Sources/AngouriMath/Core/Budgets/WorkBudget.cs
Original file line number Diff line number Diff line change
Expand Up @@ -62,8 +62,8 @@ public sealed record WorkBudget
/// <summary>
/// No ceiling on either axis. This is what <see cref="MathS.Settings.Budget"/>
/// reads as its default — but see that property: leaving it alone means each
/// algorithm keeps its own default, and it is only a caller who sets it who gets
/// this.
/// algorithm keeps its own default, and setting it to this lifts only the working
/// allowances, never a lid.
/// </summary>
public static WorkBudget Unlimited { get; } = new();
}
Expand Down
3 changes: 2 additions & 1 deletion Sources/AngouriMath/Core/Transformations/EqualityOracle.cs
Original file line number Diff line number Diff line change
Expand Up @@ -203,7 +203,8 @@ internal static EqualityAnswer Ask(Entity left, Entity right, WorkBudget budget,
throw new ArgumentOutOfRangeException(nameof(domain), domain,
"Equality is asked over the complex or the real numbers.");

var ledger = BudgetLedger.For(Where, budget);
// The caller's argument, capped by a set MathS.Settings.Budget.
var ledger = BudgetLedger.For(Where, budget, BudgetRole.Argument);
try
{
if (left.Equals(right))
Expand Down
4 changes: 3 additions & 1 deletion Sources/AngouriMath/Core/Transformations/Saturation.cs
Original file line number Diff line number Diff line change
Expand Up @@ -270,7 +270,9 @@ internal static bool ProvesEqual(Entity left, Entity right,
var b = graph.AddEntity(right);
graph.Rebuild();

var ledger = BudgetLedger.For(nameof(ProvesEqual), budget);
// A lid: the one caller passes a guard against stalls, not an allowance a user
// chose, so a set MathS.Settings.Budget can only tighten it.
var ledger = BudgetLedger.For(nameof(ProvesEqual), budget, BudgetRole.Lid);
Run(graph, rules, ledger, CostModel.Default.Cost);
ledger.Report();
return graph.Find(a) == graph.Find(b);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -441,9 +441,9 @@ private static class PolynomialFactorizationHolder
/// <param name="budget">
/// What this call may spend before it settles for the best it has found so far.
/// <see cref="WorkBudget.Steps"/> is charged once per e-node the graph actually creates;
/// <see cref="WorkBudget.Time"/> is the wall-clock backstop. A caller who sets
/// <see cref="MathS.Settings.Budget"/> overrides this, the same as every other bounded
/// computation in the library.
/// <see cref="WorkBudget.Time"/> is the wall-clock backstop. A set
/// <see cref="MathS.Settings.Budget"/> caps this, the smaller limit on each axis
/// applying, and does not replace it.
/// </param>
/// <param name="costModel">Which candidate counts as cheapest once exploration stops.</param>
/// <remarks>
Expand Down Expand Up @@ -770,7 +770,9 @@ internal EqualitySaturationTransformation(WorkBudget budget, CostModel costModel
var root = graph.AddEntity(input);
graph.Rebuild();

var ledger = BudgetLedger.For(Name, budget);
// The caller passed this budget, so it is theirs to spend and a set
// MathS.Settings.Budget, the outer scope, caps it.
var ledger = BudgetLedger.For(Name, budget, BudgetRole.Argument);
// Stop once the answer has: after two passes in which the cheapest member of the
// root's class did not change, further merging can only add members this
// extraction would not choose. That is the fixed point a caller who extracts
Expand Down Expand Up @@ -829,7 +831,8 @@ internal GraphCanonicalizationTransformation(WorkBudget budget, RewriteRuleGrowt
var root = graph.AddEntity(input);
graph.Rebuild();

var ledger = BudgetLedger.For(Name, budget);
// An argument, as in EqualitySaturationTransformation.
var ledger = BudgetLedger.For(Name, budget, BudgetRole.Argument);
// The same stop as EqualitySaturationTransformation's, on the least member
// rather than the cheapest, since that is what this extracts.
Entity? last = null;
Expand Down
3 changes: 2 additions & 1 deletion Sources/AngouriMath/Functions/Algebra/Groebner/Buchberger.cs
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,8 @@ internal sealed class GroebnerBudget
[ConstantField]
internal static readonly WorkBudget Default = new() { Time = TimeSpan.FromSeconds(5) };

private readonly BudgetLedger ledger = BudgetLedger.For("Gröbner", Default);
// An allowance: a set MathS.Settings.Budget replaces Default, so a caller can raise it.
private readonly BudgetLedger ledger = BudgetLedger.For("Gröbner", Default, BudgetRole.Allowance);

/// <summary>
/// Charges one unit of work and answers whether to carry on. Called where the
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,9 @@ internal static Set Solve(Entity equation, Variable x)
// budget of its own is what bounded the fast path and left the fall-through
// unbounded, so the same `Solve` finished or did not depending on which internal
// path accepted it. https://github.com/asc-community/AngouriMath/issues/896
var ledger = BudgetLedger.For("SolveSystem", SystemSolveBudget);
// An allowance: a set MathS.Settings.Budget replaces SystemSolveBudget, which is
// what the exceptions below mean by "raise MathS.Settings.Budget to allow more".
var ledger = BudgetLedger.For("SolveSystem", SystemSolveBudget, BudgetRole.Allowance);
try
{
var variables = new Variable[vars.Length];
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -201,8 +201,10 @@ internal static Entity PerfectSquareRules(Entity x)
/// What the rewrite graph may spend proving a cross term equal to its candidate: two
/// thousand steps and fifty milliseconds. On the corpus the safe ceiling saturates a
/// term of this size in under a millisecond and a few dozen e-nodes, so this is a lid
/// against the stall family rather than a working allowance.
/// against the stall family rather than a working allowance, and is declared as one: a set
/// <see cref="MathS.Settings.Budget"/> can only tighten it.
/// https://github.com/asc-community/AngouriMath/issues/1200
/// https://github.com/asc-community/AngouriMath/issues/2454
/// </summary>
[ConstantField] private static readonly WorkBudget PerfectSquareProofBudget
= new() { Steps = 2_000, Time = TimeSpan.FromMilliseconds(50) };
Expand Down
Loading
Loading