Architectural clean up pass for 2.0

[Happypig375]

As #807 said we should start following semantic versioning, we should take the opportunity to clean up (remove) deprecated functions and redesign all APIs for consistency and correctness.

[Rafael-SOWNet]

Measured the deprecated half on master at 74b00a89, since "remove deprecated functions" is the part that can be sized rather than argued about.

28 [Obsolete] members, in six groups, and they are not equally easy to remove — the cost is in the call sites, not the deletions:

group	members	in-tree call sites	note
CompilationProtocol converter hooks + CompilationProtocolBuiltinConstantConverters	7	0	nothing in the repo uses them
Entity.Derive / .Derive(this string)	2	0	superseded by Differentiate
Entity.Matrix.Shape	1	0 outside its own declaration	ColumnCount/RowCount instead
Setting.Global / RollBackToDefault	2	0	documented as not thread-safe
MathS.Matrices.* (Matrix, Vector, MatrixMultiplication, DotProduct, ScalarProduct, Sets.Interval ×2)	7	16	all in tests
MathS.Derivative / Integral / Limit / DefiniteIntegral	9	69	see below

So 12 of the 28 can be deleted today with no call site to move at all, which is a clean first PR that shrinks the surface without touching behaviour.

The last row is the one to plan. Its 69 call sites are not all tests:

• Wrappers/AngouriMath.FSharp/Functions.fs — the F# wrapper is built on the deprecated statics, so removing them is an F# API change, not a C# one.
• Core/Antlr/AngouriMathParser.cs — generated. Whatever emits those calls has to change before the grammar is regenerated, or the removal is undone by the next regeneration.
• Evaluation.Omni.Classes.cs, InvertNode.Classes.cs, Differentiation.cs — the library calls its own deprecated API internally.

That last point is worth pulling out: a deprecated member the library itself still calls is not deprecated in any useful sense, and it is the same shape of inconsistency #497 names. The internal callers should move first regardless of when the public members go.

Suggested split, by what can be landed and measured on its own:

1. Delete the 12 with no callers. Pure removal, a BREAKING-CHANGES.md entry, nothing else moves.
2. Move the library's own internal calls off the deprecated statics. No public change at all, so it can land independently and makes step 4 smaller.
3. Move the 16 matrix call sites in tests, then delete those 7.
4. Decide the F# wrapper's story, then the remaining calculus statics. This is the one with a real design question in it, and it is the reason the row cannot just be swept.

Happy to take (1) and (2) — they are mechanical, independently verifiable, and land without a design discussion. (3) and (4) want your call on the F# surface first.

One scope note, since it interacts with the version: everything above is breaking and so belongs in 2.0 by definition. The additive work — the transformation layer from #746 that just landed in #816/#818/#819 — deliberately does not, and I would keep it out of 2.0 so the release's public diff stays readable as "breaking changes only".

[Rafael-SOWNet]

Correcting my comment above — most of its numbers were wrong, and the job is much smaller than I said.

I counted MathS.Derivative(, MathS.Integral( and MathS.Limit(. Those are not the deprecated members. There are two families with nearly the same names:

	takes	does	deprecated?
MathS.Derivative / Integral / Limit	Entity	builds a Derivativef / Integralf / Limitf node	no
MathS.Compute.Derivative / Integral / Limit / DefiniteIntegral	Variable	computes, forwarding to the Entity method	yes

Every one of the 69 call sites I reported is the first kind. Three claims fall with it:

• the library calls its own deprecated API internally — it does not. The library builds with TreatWarningsAsErrors and emits zero CS0618, which settles it; I should have checked that before asserting the opposite.
• the F# wrapper is built on the deprecated statics — it uses the node constructors.
• the generated parser emits them — likewise. Nothing has to change before regenerating the grammar.

I also mis-attributed two members: the deprecated Interval(Entity, Entity) overloads are in MathS.Matrices, not MathS.Sets. MathS.Sets.Interval is not deprecated, which is why the library can call it freely. (A deprecated Interval living inside Matrices looks like a misplacement worth its own look during this pass.)

The corrected inventory

group	members	real call sites
CompilationProtocol converter hooks + CompilationProtocolBuiltinConstantConverters	7	0
Entity.Derive / .Derive(this string)	2	0
Entity.Matrix.Shape	1	0
Setting.Global / RollBackToDefault	2	0
MathS.Matrices.* — Matrix, Vector, MatrixMultiplication, DotProduct, ScalarProduct, Interval ×2	7	16, all in tests
MathS.Compute.* — Limit ×2, Derivative ×2, Integral ×2, DefiniteIntegral ×3	9	3, all in IntegrationTest.cs (plus 6 <see cref>s)
	28	19, every one in a test

So there is no step 2 — nothing internal to move — and no F# or grammar question. The whole deprecated half is one mechanical change: move 19 test call sites onto the replacements the obsolete messages already name, delete 28 members, add a BREAKING-CHANGES.md entry.

Sorry for the noise. The lesson is the one this repo already writes down — measure before asserting — and "the counts looked plausible" is exactly how a wrong plan gets adopted.

Happy to take it as a single PR whenever you want it; it is your public surface, so I would rather you said go than assume it.

[Rafael-SOWNet]

The deprecated half is done in #832 — all 28 members, plus the two places the library was calling its own deprecated API behind #pragma warning disable CS0618, plus Entity.DefiniteIntegral, which had to be added because the member being removed pointed at a replacement that never existed.

That leaves "redesign all APIs for consistency and correctness". Rather than offer opinions, here is what I can measure on 2006af86.

The surface is one-directional

Entity instance methods (x.F())	18
MathS unary functions over Entity	40

Every Entity instance method has a MathS counterpart; 22 MathS functions have no instance counterpart — Sqrt, Sqr, Cbrt, Ln, Log, Phi, Gamma, Negation, the eight hyperbolics and their eight inverses, Factorise, TensorExpand.

So MathS.Sqrt(x) works and x.Sqrt() does not, while MathS.Sin(x) and x.Sin() both do. That is checkable, and it is the shape of inconsistency #497 names: not a wrong answer anywhere, just a caller having to remember which half of the library a function lives in.

Worth deciding as a rule rather than case by case — "every unary function of an Entity is reachable both ways" is a rule a test can enforce over the two lists, and then the gap is mechanical to close.

The clearest single instance: Stringize versus Latexise

Two methods of identical purpose, one per node, adjacent in every file they appear in:

Stringize   66 overrides
Latexise    65 overrides

One American, one British. The rest of the library is -ize — Serialize, Deserialize, Factorize, TensorExpand — with MathS.Quantum.Factorise the only other -ise (and a different operation from Entity.Factorize, which is its own small trap).

But renaming Latexise has a cost outside this repository. CSharpMath.Evaluation references it five times, and #822 has just established that this is a real cross-repo contract. A rename is a 65-site change here plus a PR there, and it is not the kind of thing to do without you deciding it is worth it.

Three ways to go, and this is your call rather than mine:

1. Rename to Latexize in 2.0, with ILatexiseable → ILatexizeable, and open the CSharpMath PR at the same time. Most consistent, costs a downstream break at the one moment a major version makes it acceptable.
2. Keep Latexise and write down that the library is -ize except this one, so the next person does not have to rediscover it. Cheapest, and the inconsistency stays.
3. Add Latexize as the name and keep Latexise forwarding. No break, but 2.0 is precisely the release where a forwarder is the wrong answer — that is how the 28 members in Remove every deprecated member for 2.0 (#821) #832 accumulated in the first place.

What I would not touch

MathS.Matrices, MathS.Compute, MathS.Sets and friends are nested static classes with overlapping membership — Interval lived in Matrices until #832, which is why I mis-attributed it. Tidying that grouping is a bigger and more subjective change than either of the above, and I would want it argued before anyone starts.

A correction I owe this issue

My second comment said the library does not call its own deprecated API, citing zero CS0618 warnings. That was wrong — the warnings were suppressed by pragmas in MatrixOperations and CompilationProtocol. An absence of warnings proves nothing where warnings are disabled, and the pragma was the thing to grep for. The same error inflated my call-site count from 5 to 19. #832's description has the full correction.

[Happypig375]

It is also possible to use the [Extension] attribute on MathS such that fluent methods are automatically defined on the entity for all applicable MathS functions. How you you think about this?

[Rafael-SOWNet]

Yes — and it turns out to be safer than I expected, but it reaches fewer of the functions than "mark MathS" suggests. Everything below is measured on 2006af86 with SDK 10.0.302. Sources/Directory.Build.props already sets LangVersion=preview, so C# 14 extension members are available today, no project change needed.

One mechanical note first: [Extension] can't be applied by hand in C# — ExtensionAttribute is compiler-emitted, and writing it yourself is CS1112. The two real forms are classic this Entity a on the existing method, or a C# 14 extension(Entity a) { ... } block. (F#'s [<Extension>] does work by attributing a type, which is likely where the shape of the idea comes from.)

The conversion is compatible in every direction I could test

I built a two-version probe: v1 with public static Ent Sqrt(Ent a) on a top-level static class that also contains nested static classes — MathS's exact shape — and v2 with the same member as a C# 14 extension(Ent a) block.

test	result
consumer binary built against v1, Lib.dll swapped to v2, no recompile	runs; MathS.Sqrt(x) still resolves
C# source recompiled against v2, old call style MathS.Sqrt(x)	compiles
C# source against v2, new call style x.Sqrt()	compiles
F# project referencing v2, MathS.Sqrt(x) and x.Sqrt()	both compile and run

The F# row is the one that mattered here, since AngouriMath.FSharp consumes these: the compatibility static form is visible to a compiler that does not know C# 14. So the change is additive — not one call site has to move, in this repo or downstream.

Where it cannot be applied

Extension members must live in a top-level, non-nested static class. Compiling both forms inside a nested static class:

error CS1109: Extension methods must be defined in a top level static class; Nested is a nested class
error CS9283: Extensions must be declared in a top-level, non-generic, static class

Of the 22 functions with no fluent counterpart, only 7 sit directly on MathS and can be converted in place:

where	members	convertible in place
MathS	Sqrt, Sqr, Cbrt, Ln, Log, Gamma, Negation	yes — 7
MathS.Hyperbolic	6 hyperbolics + 6 inverses	no — nested
MathS.NumberTheory	Phi	no — nested
MathS.Quantum	Factorise, TensorExpand	no — nested

(Correcting my own count above: the hyperbolic group is six and six, not eight and eight. The total of 22 stands.)

So it is not "mark MathS and they all appear" — it is 7 in place plus 15 forwarders in a top-level static class. One already exists and is already the home of the fluent surface: AngouriMathExtensions (Sources/AngouriMath/Convenience/AngouriMathExtensions.cs:23). And since MathS is already partial, the extension block can live in a new file without touching MathS.cs.

Two things worth deciding before any sweep

Entity is one hierarchy. 40 fluent members land on Entity.Set and Entity.Boolean as well, where .Cosech() is noise. Extension members cannot be scoped to part of a hierarchy, so this is the price of the rule, not a detail of the implementation.

"All applicable" needs a per-member decision. MathS.Log(Entity x) is log₁₀; Entity.Log(Entity x) (Entity.Continuous.Definition.cs:115) is log base this. Converted blindly, that ships x.Log() meaning log₁₀(x) beside x.Log(y) meaning log_x(y). That pair is worse than the inconsistency it would be fixing.

On readability, since it is the stated goal

Better than I assumed. The library calls its own MathS unary functions 173 times outside Convenience/ (tests another 107), so this is not only a caller-facing nicety. The gain is that the nesting inverts today: MathS.Sin(MathS.Sqrt(x)).Simplify() reads inside-out and switches style mid-expression, because Simplify() is already an instance method. x.Sqrt().Sin().Simplify() reads in evaluation order throughout.

Scope

This is additive, so by the line we drew for #832 it belongs in 2.1, not 2.0 — keeping the 2.0 diff readable as breaking changes only. The one caveat is that new extension members can produce CS0121 in a downstream project that already declared its own Sqrt(this Entity). Rare, but not zero, and worth a BREAKING-CHANGES.md line even though nothing here breaks by construction.

Whichever mechanism fills the gap, the thing that stops it reopening is a test: enumerate the MathS statics taking a single Entity and assert each is reachable fluently. That turns "consistency" from a review burden into a build-time invariant.

Happy to take it in that shape — the 7 in-place conversions plus the test first, since they are verifiable on their own, then the 15 forwarders once you have called the Log question.

[Rafael-SOWNet]

Closing this as done, with the one item that is genuinely undecided moved somewhere it will not be lost.

What the pass produced

• The deprecated half — all 28 members removed in Remove every deprecated member for 2.0 (#821) #832, plus two internal callers that were hiding behind #pragma warning disable CS0618, plus Entity.DefiniteIntegral, which had to be added because a removed member pointed at a replacement that never existed.
• The dead documentation and analyzer settings around the public API — Retire the public-API doc and its dead analyzer settings #835.
• The naming question, which is the only thing here that a major version gates, is now Decide Latexise or Latexize in 2.0, since it cannot be revisited later #840.

What is deliberately not in 2.0

The fluent-parity gap measured above — 22 unary MathS functions with no Entity counterpart — is additive, so by the same line that put the deprecations in 2.0 it belongs in 2.1. The mechanism is settled: C# 14 extension members, with the compatibility measured rather than assumed (binary, C# source, and F# consumption all verified, plus the constraint that only 7 of the 22 sit on a class that can host them). It wants its own issue when 2.1 opens rather than holding this one open across a release boundary.

@Happypig375 — your [Extension] suggestion is what that will be built on; the measurements are in the comment above.

Reopen if you would rather the architectural pass stay open as an umbrella.