asc-community / asc-community/AngouriMath
Five decisions whose consequences reach past their own issue
- Dominant language
- C#
- Stars
- 831
- Forks
- 79
- Avg merge
- 3h 23m
- Merged PRs (30d)
- 309
Description
Written while working out what should happen before 2.0. Each of these looks self-contained and is not — settling one changes what is possible or cheap elsewhere. Measurements are on `master` (21f0d16f).
---
## 1. Whether a new node type is breaking — #248 — gates three other issues
`Entity` is a `public abstract record` whose hierarchy is **open** (`InitDirectChildren` is `protected`, so external code can derive). Nothing states whether adding a subtype is a breaking change.
If it is, then none of these may ship in a minor version:
- **#809** — `floor`, `ceil`, `round`, and possibly `min` / `max` / `gcd`
- **#286** — functions as separate entities
- **#495** — lambdas and functions as entities
and the roadmap waits on 3.0 for years. Detail and a suggested wording in [#248](https://github.com/asc-community/AngouriMath/issues/248#issuecomment-5225941526). **This is the one to settle first**, because three other issues cannot be scheduled until it is.
---
## 2. #204 is the simplifier's objective function, not a display choice
Roots versus fractional powers reads like a printing decision. It is not, because `Simplify` generates candidates and returns the **shortest by `Complexity`**, which is node count:
| | `Complexity` |
|---|--:|
| `sqrt(x)` | **3** |
| `x ^ (1/2)` | **5** |
| `sqrt(x) + sqrt(y)` | **7** |
| `x ^ (1/2) + y ^ (1/2)` | **11** |
A radical written as a fractional power costs nearly twice as much, and the gap grows with the number of radicals. So the representation decides **which candidate wins**, everywhere a radical can appear — not merely how the winner prints. Switching to fractional powers would silently re-rank a large part of the simplifier, and the effect is not visible in any individual rule.
Whatever is decided, it wants measuring against `simpsweep` and `casbench` rather than reasoning about, and it should be decided before 2.0 since the printed form of every radical is user-visible.
---
## 3. #326 collides with a guarantee 2.0 is about to make
`Stringize` round-tripping was fixed this cycle — `BREAKING-CHANGES.md` now promises that powers, lambdas, applications **and piecewises** parse back from their own output. Changing piecewise syntax after 2.0 ships breaks expressions users have already saved, which is exactly what that guarantee is for.
It is also worse than it looks today: the syntax #326 records as current does not parse, and a near-miss of it **crashes** with a `NullReferenceException` rather than a parse error (#813).
So #326 is not a free-standing style question — it is the last cheap moment to move the syntax, and there is a crash sitting on the same grammar rule.
---
## 4. #721 and #812 are the same statement told twice
#812 is a wrong answer: `abs(x) = -1` returns a non-empty set whose members do not satisfy it, because the inversion is missing an `a >= 0` guard.
Expressing that guard needs a decision that is #721's: is "this holds only where the argument is non-negative" a `Providedf` condition on the node, or a consequence of `MathS.Settings.Codomain`? Fixing #812 without settling #721 means picking one mechanism by accident and then having two mechanisms for one statement — which is the situation #721 was opened to end.
Fix #812 first if it must be fixed first (it is a wrong answer, so it outranks tidiness), but write down which mechanism was chosen and why, so #721 inherits a decision rather than a mess.
---
## 5. The spine's third customer is the polynomial layer, and it is the expensive one
The monoid-algebra spine landed in #778 with two customers: the boolean minimiser and symbolic quantum states. `AGENTS.md` already records that the polynomial representation "is already a monoid algebra in all but name", and that most of the remaining backlog — **#381** characteristic polynomials, **#475** Diophantine equations, multivariate GCD, factorisation, **#55** — sits behind that layer.
The caveat is also already recorded and is worth repeating here because it decides the order of work: `GatherMonomialInformation` is on the hot path for solving, long division **and** simplification. So this is the one place where "unify the representation" cannot be done on the strength of the argument that it is the same structure. **Build the benchmark before the change, not after** — otherwise there is no way to tell a regression from noise, and the change is large enough that it would not be obvious.
---
None of these is a request to do the work. They are the couplings I would want known before anything schedules the features on either side of them.
Contributor guide
Research direction
Start by reading AGENTS.md and BREAKING-CHANGES.md, then follow the linked issues #248, #204, #326, #721, #812, and #778. Compare the stated dependencies with the simpsweep and casbench measurements and the referenced parser and solver behavior. Done means the cross-issue decisions and ordering are explicitly settled, not that one of the listed features is implemented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- backend
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 20/100