Skip to content

Add the monoid-algebra spine (#768) - #778

Merged
Rafael-SOWNet merged 1 commit into
masterfrom
feat/monoid-algebra-spine
Aug 7, 2026
Merged

Add the monoid-algebra spine (#768)#778
Rafael-SOWNet merged 1 commit into
masterfrom
feat/monoid-algebra-spine

Conversation

@Rafael-SOWNet

Copy link
Copy Markdown
Collaborator

The representation four features share, per One structure under several features in AGENTS.md (#773). No behaviour change: nothing references it yet.

Three types

Semiring Zero, One, Add, Multiply, IsIdempotent — instances Field and Boolean
IBasisOps<TBasis> Identity, Combine, Meet, TryDivide
SparseTerms<TBasis> immutable; Add, Scale, Multiply, FactorOutCommon

IsIdempotent is why Semiring is a type rather than a pair of delegates. a or a = a holds in the boolean semiring and fails in the complex one, and that single difference is what separates covering from superposition. Anything reading the flag is asking whether it may cover the same basis element twice.

Meet is why this is one abstraction rather than two. Dividing out the meet of the support is simultaneously "take the common monomial out of a polynomial" and "detect that a quantum state is separable":

x^2*y + x^2     meet of (2,1),(2,0) is (2,0)   leaving  y + 1
|001> + |011>   meet of 001,011     is 0-1     leaving  |0> + |1>

What is deliberately absent

Cover selection, factorisation into irreducibles, series truncation. Each belongs to exactly one feature, and a shared engine that swallowed them would be wrong in a way that still type-checks. That list is in AGENTS.md too, so it survives someone finding this class inviting later.

Two things found by building it

  • TBasis must compare by value, now documented on the type parameter. Terms are keyed on it, so a basis with reference equality leaves every element distinct and quietly stops collecting like terms — no error anywhere, just a wrong answer. Writing the tests is what surfaced it.
  • netstandard2.0 has no Deconstruct on KeyValuePair. The net7.0 build said nothing. Third such catch today, after ToHashSet and BitOperations.

Unverified, and why that is not neglect

Every type here is internal, and InternalsVisibleTo("UnitTests") cannot simply be uncommented — I tried:

error CS1726: Friend assembly reference 'UnitTests' is invalid.
Strong-name signed assemblies must specify a public key in their InternalsVisibleTo declarations.

SignAssembly is on with key.snk, so a friend reference needs the test assembly signed with the same key and its public key named in the attribute. That is a change to the build and to an assembly's identity — the maintainer's call, not mine, so I reverted it.

The tests are written and waiting: two IBasisOps implementations over one value-typed basis — exponent vectors (meet = componentwise minimum) and kets (meet = agree-or-free) — put through the same FactorOutCommon, which is the one claim this whole design rests on. They land the moment the access question is settled.

Nothing references the spine, so the suite is unchanged at 5359 passing. That says the build is sound and says nothing about whether these types are correct.

Reviewer's note: if you would rather not sign the test assembly, the alternative is to let the quantum module be the spine's first test, through its public surface. Merging this as-is is reasonable because it is inert — but it should not be read as verified.

The representation four features share, per *One structure under several features*
in AGENTS.md: a finitely-supported map from a basis into a coefficient semiring,
where the basis is a monoid.

Three types, no more:

- Semiring -- Zero, One, Add, Multiply, IsIdempotent. That last is the whole
  reason this is a type rather than a pair of delegates: `a or a = a` holds in the
  boolean semiring and fails in the complex one, and that single difference is
  what separates covering from superposition. Anything reading the flag is asking
  whether it may cover the same basis element twice.
- IBasisOps<TBasis> -- Identity, Combine, Meet, TryDivide. Meet is what makes
  factoring one operation across features: dividing out the meet of the support is
  simultaneously "take the common monomial out of a polynomial" and "detect that a
  quantum state is separable".
- SparseTerms<TBasis> -- immutable, with the invariant that no term carries a zero
  coefficient. Add, Scale, Multiply and FactorOutCommon. Collecting like terms in
  an idempotent semiring *is* absorption, so it needs no special case.

Deliberately absent: cover selection, factorisation into irreducibles and series
truncation. Each is specific to one feature, and a shared engine that swallowed
them would be wrong in a way that still type-checks.

Not System.Collections.Immutable -- that would be the library's first package
reference of its kind, which is a packaging decision rather than a design one, so
the dictionary is copied on construction and never handed out.

TBasis must compare by value, and that is documented on the type parameter rather
than left to be discovered: the terms are keyed on it, so a basis with reference
equality leaves every element distinct and quietly stops collecting like terms --
not an error anywhere, just a wrong answer. Writing the tests is what surfaced it.

netstandard2.0 has no Deconstruct on KeyValuePair, and the net7.0 build said
nothing about it.

**Unverified, and the reason is not neglect.** Every type here is internal, and
InternalsVisibleTo("UnitTests") cannot simply be uncommented: this assembly is
strong-name signed, so a friend reference needs the test assembly signed with the
same key and its public key named in the attribute. That is a change to the build
and to an assembly's identity, and it is the maintainer's to make. The tests are
written -- two IBasisOps over one value-typed basis, exercising the claim that a
single Meet covers both an exponent vector and a ket -- and land the moment the
access question is settled. Nothing references the spine, so the suite is
unchanged at 5359.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Rafael-SOWNet Rafael-SOWNet added the Proposal Contribute to the project by proposing some improvements label Aug 7, 2026
@Rafael-SOWNet
Rafael-SOWNet merged commit 4ab9448 into master Aug 7, 2026
24 checks passed
@Rafael-SOWNet
Rafael-SOWNet deleted the feat/monoid-algebra-spine branch August 7, 2026 07:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Proposal Contribute to the project by proposing some improvements

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant