galaga-matrix 1.7.0__tar.gz

galaga_matrix-1.7.0/.gitignore

@@ -0,0 +1,21 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.coverage
+.DS_Store
+__marimo__/
+# Vim
+*.swp
+*.swo
+*~
+test.py
+.kiro/
+.session.jsonl
+.spacebot/

galaga_matrix-1.7.0/High-priority correctness issues.md

@@ -0,0 +1,652 @@
+This is a copy of a shared ChatGPT conversation
+
+Report conversation
+
+
+
+Uploaded a file
+
+I wrote: Review this spec for my Geometric Algebra library, and it's matrix conversion package. Mathematically correctness is critical
+
+Chat GPT replied:
+
+I’ll treat this as a correctness review rather than a wording pass: I’m going to check the classification, dimension counts, idempotent/ideal logic, and the worked physics examples against standard Clifford algebra facts.
+
+First significant finding: the general “dimension ≥ dimension” test is not sufficient by itself. You also need the restricted map from the even subalgebra into the chosen projected column(s) to be injective; otherwise the dimensions can match but the convention can still alias elements.
+
+Thought for 55s
+
+I’d **not ship this spec as-is**. The implementation idea is salvageable, but there are several mathematically serious issues, especially around **primitive idempotents, Cl(1,3), quaternionic packaging, normalization, and chirality**.
+
+## High-priority correctness issues
+
+### 1. “Dimension ≥ even algebra dimension” is not a sufficient roundtrip test
+
+The spec says faithful roundtrip requires:
+$$
+\dim_\mathbb{R}(\text{spinor}) \ge \dim_\mathbb{R}(\mathrm{Cl}^0(p,q))
+$$
+and then uses that as the gate for whether `from_spinor_matrix(to_spinor_matrix(mv)) == mv` should work. That is only a **necessary** condition, not sufficient. You also need the concrete linear map
+$$
+\mathrm{Cl}^0(p,q) \to \text{chosen projected column space}
+$$
+to be **injective** for the chosen representation, idempotent, and extracted column(s). The spec later assumes the system is full-rank “where roundtrip is possible,” but that must be tested directly by rank, not inferred from dimension.
+
+Recommended fix: define `_spinor_roundtrip_possible` as a **computed rank check** over the even blade columns:
+
+```
+rank(A) == number_of_even_blades
+```
+
+Dimension tables can remain explanatory, but not authoritative.
+
+------
+
+### 2. The idempotent story is inconsistent for Cl(1,3)
+
+The spec says a primitive idempotent gives a minimal left ideal and “one nonzero column,” then for Cl(1,3) chooses:
+$$
+p = \frac12(1 + \gamma^0) = \operatorname{diag}(1,1,0,0)
+$$
+That is **not primitive as a complex 4×4 projector**. It has complex rank 2, not rank 1. Multiplying by it gives a matrix with **two nonzero columns**, not one. The spec notices this by saying “columns 0,1 as a pair,” but the algorithm returns only `projected[:, c:c+1]`, i.e. one column.
+
+So there are two different constructions mixed together:
+
+1. **Minimal-left-ideal construction**: choose a primitive idempotent and keep the resulting ideal element.
+2. **Reference-column construction**: choose a reference column vector $u$, then map $M(\psi)u$.
+
+For Cl(3,0), these collapse nicely because $p=\operatorname{diag}(1,0)$ is rank 1. For Cl(1,3), your chosen $p$ is not doing the same thing.
+
+Recommended fix: rewrite the algorithm around a **reference spinor vector** rather than pretending the Cl(1,3) projector is primitive:
+
+```
+Choose a reference column u.
+Map even multivector ψ to M(ψ) u.
+Recover ψ by solving the real linear system over even blades.
+Require rank(A) == dim Cl⁰.
+```
+
+Then Cl(1,3) identity mapping to $(1,0,0,0)^T$ is clean: you are using $u=e_0$, not extracting a minimal ideal from $p=\frac12(1+\gamma^0)$.
+
+------
+
+### 3. The Cl(1,3) complex matrix description is potentially misleading
+
+The spec says Cl(1,3) is $M(2,\mathbb H)$, but then talks about a compact 4×4 complex Dirac-matrix representation. That is okay **only if you are clear** that the 4×4 complex representation is a faithful **real** representation of $M(2,\mathbb H)$, not the full complex matrix algebra $M(4,\mathbb C)$. The image is a constrained real subalgebra inside $M(4,\mathbb C)$, not arbitrary complex 4×4 matrices.
+
+Recommended wording:
+
+> For quaternionic cases, the implementation uses the standard embedding $M(k,\mathbb H) \hookrightarrow M(2k,\mathbb C)$. This is faithful as a real algebra but its image is a proper real subalgebra of $M(2k,\mathbb C)$.
+
+------
+
+### 4. The Cl(3,0) Pauli signs are inconsistent
+
+The worked Cl(3,0) section has a sign/basis-order problem.
+
+It says:
+$$
+e_{12} \mapsto \sigma_1\sigma_2 = i\sigma_3
+$$
+and
+$$
+e_{23} \mapsto i\sigma_1
+$$
+Those are consistent with $e_i \mapsto \sigma_i$. But then it says:
+$$
+e_{31} \mapsto -i\sigma_2
+$$
+That is **not** consistent with $e_{31}=e_3e_1$, because:
+$$
+\sigma_3\sigma_1 = i\sigma_2
+$$
+while
+$$
+\sigma_1\sigma_3 = -i\sigma_2
+$$
+So either the blade is really $e_{13}$, or the sign is wrong. This affects the inverse formula and the Bloch sphere formula.
+
+Recommended fix: choose one convention and state it explicitly. For canonical ascending blade order, use $e_{13}$, not $e_{31}$, or adjust the signs.
+
+For example, with $e_{31}=e_3e_1$:
+
+```
+e12 ↦ iσ3
+e23 ↦ iσ1
+e31 ↦ iσ2
+```
+
+Then the extracted column for $e_{31}$ is $(0,-1)^T$, not $(0,1)^T$.
+
+------
+
+### 5. The normalization table is false for Lorentzian spinors
+
+This is probably the most important physics correctness issue.
+
+The spec says:
+$$
+\psi\tilde\psi = 1 \quad \Longleftrightarrow \quad \langle \psi|\psi\rangle = 1
+$$
+and claims a normalized rotor always maps to a unit-normalized column spinor.
+
+That is true for **Euclidean Pauli rotations** under the usual Hermitian norm. It is **not true in Cl(1,3)** for Lorentz boosts. Lorentz rotor matrices are not unitary under the ordinary positive-definite Hermitian inner product. A boost rotor satisfies:
+$$
+R\tilde R = 1
+$$
+but the ordinary column norm $\psi^\dagger\psi$ generally changes under boosts. The invariant Dirac bilinear uses the **Dirac adjoint**, not the Hilbert-space norm:
+$$
+\bar\psi \psi = \psi^\dagger \gamma^0 \psi
+$$
+Recommended fix: split the normalization section by signature:
+
+```
+For Cl(3,0) Pauli spinors, rotor normalization corresponds to unit Hermitian norm for the projected reference state.
+
+For Cl(1,3), R\tilde R = 1 corresponds to Lorentz-group normalization, not ordinary Hermitian unit norm. The relevant invariant bilinears use the Dirac adjoint or GA scalar bilinears.
+```
+
+------
+
+### 6. The quaternionic “two components = Weyl chiralities” claim is wrong as stated
+
+The spec says the two quaternion components of a Dirac spinor correspond to the two Weyl chiralities, and that boosts mix those chiralities.
+
+That is not right.
+
+A Dirac spinor can be written as two Weyl spinors in the **chiral/Weyl basis**:
+$$
+\psi =
+\begin{pmatrix}
+\psi_L \\
+\psi_R
+\end{pmatrix}
+$$
+But your earlier Cl(1,3) section chooses a Dirac-style projector $p=\frac12(1+\gamma^0)$, where the upper/lower split is not automatically the left/right chirality split. More importantly, proper Lorentz transformations do **not** mix left and right Weyl representations. Rotations and boosts act separately on $\psi_L$ and $\psi_R$, with related but inequivalent $SL(2,\mathbb C)$ actions. Mass terms, parity, or basis changes can mix interpretations, but a pure Lorentz boost does not “couple the two chiralities.”
+
+Recommended fix: remove that physical interpretation unless you explicitly choose the chiral basis and define the quaternion packaging accordingly. Safer wording:
+
+```
+A complex Dirac spinor can be packaged as two quaternions, but the physical interpretation of those two quaternionic components depends on the chosen gamma-matrix basis and reference spinor. They should not be identified with Weyl chiralities unless the representation and basis are chosen to make that identification explicit.
+```
+
+------
+
+## Medium-priority issues
+
+### 7. “Physically, Cl(1,3) is the standard choice…” is too strong
+
+The spec says Cl(1,3) is the standard choice for the Dirac equation precisely because its spinor representation has the right dimension.
+
+That is misleading. Physics often works with the **complexified** Clifford algebra, where the real-signature distinction largely disappears:
+$$
+\mathrm{Cl}_{1,3}(\mathbb R)\otimes \mathbb C
+\cong
+\mathrm{Cl}_{3,1}(\mathbb R)\otimes \mathbb C
+\cong
+M(4,\mathbb C)
+$$
+The real algebra distinction matters for Majorana/quaternionic structures and for GA formulations, but saying Cl(1,3) is “the standard choice precisely because…” overstates the case.
+
+Recommended fix:
+
+> In this library’s real-algebra convention, Cl(1,3) has a quaternionic structure that lets an even multivector be encoded in an 8-real-dimensional spinor column. Cl(3,1), using its minimal real column representation, does not provide a faithful roundtrip by this particular column-extraction method.
+
+------
+
+### 8. “Minimal left ideal = matrices with only one nonzero column” only works cleanly for $M(k,F)$ over $F$
+
+This statement is fine for $M(k,\mathbb R)$, $M(k,\mathbb C)$, or $M(k,\mathbb H)$ when viewed over the same scalar division ring. But once you embed quaternionic matrices into complex matrices, a quaternionic rank-1 column corresponds to **two complex columns**.
+
+Recommended fix: add a note:
+
+```
+For quaternionic algebras represented via complex 2×2 blocks, a rank-1 quaternionic projector appears as a rank-2 complex projector. Therefore “one nonzero column” means one quaternionic column, not one complex column.
+```
+
+------
+
+### 9. The API name `to_spinor_matrix` may obscure what is returned
+
+It returns a **column vector**, not a matrix. That may be okay if the package already has naming conventions, but mathematically `to_spinor_column` or `to_column_spinor` would be clearer.
+
+------
+
+## What I would change structurally
+
+I’d rewrite the central algorithm like this:
+
+```
+Given an even multivector ψ ∈ Cl⁰(p,q):
+
+1. Build a faithful real matrix representation ρ: Cl(p,q) → Mat_N(K),
+   implemented over real or complex NumPy arrays.
+
+2. Choose a fixed reference column u.
+
+3. Define:
+      spinor(ψ) = ρ(ψ) u
+
+4. Precompute the real basis matrix A whose columns are spinor(E_i)
+   for each even basis blade E_i.
+
+5. The conversion is faithful iff rank_R(A) = dim_R Cl⁰(p,q).
+
+6. Forward conversion is multiplication by A.
+
+7. Inverse conversion solves A c = spinor.
+```
+
+That avoids the ambiguity around primitive idempotents, rank-2 complex projectors, and whether you are extracting one column or a minimal ideal.
+
+## Verdict
+
+The broad idea is good:
+
+> represent an even GA spinor by its action on a fixed reference spinor column, then reconstruct by solving over the even blade basis.
+
+But the spec currently presents that as a minimal-left-ideal/idempotent construction, and that framing breaks down in the Cl(1,3) quaternionic/complex-embedded case.
+
+The must-fix items are:
+
+1. Replace the dimension-only roundtrip test with an actual rank test.
+2. Reframe Cl(1,3) around a reference column, not a primitive idempotent.
+3. Fix the Cl(3,0) $e_{31}$ sign convention.
+4. Remove or heavily qualify the normalization claim.
+5. Remove the “quaternion components = Weyl chiralities” claim unless you explicitly switch to a chiral basis and prove the mapping.
+6. Clarify quaternionic complex embedding: one quaternionic column = two complex rows/columns depending on representation, not a naive single complex column.
+
+Uploaded a file
+
+I wrote: Review this code to implement
+
+Chat GPT replied:
+
+I’ll review this against the spec issues from the previous pass: not just “does it run,” but whether the implementation preserves the intended Clifford/spinor mapping without hidden dimension or convention errors.
+
+A second concrete issue: the code still implements the old dimension-only roundtrip predicate. That means it can declare a spinor conversion valid without checking the actual rank of the even-blade-to-column map.
+
+Thought for 1m 58s
+
+I’d **not merge this yet**. The core full-matrix machinery is mostly reasonable, but the spinor/quaternion parts still encode the mathematical mistakes from the spec, and there is one extra serious implementation issue: the **Cl(1,3) Dirac matrices are not in the quaternionic block convention that `to_quaternion_matrix()` assumes**.
+
+I couldn’t run end-to-end tests because `galaga` is not installed in the sandbox, but I did static review and rank-checked the matrix construction by stubbing the minimal `Algebra` surface.
+
+## Biggest issues
+
+### 1. `_spinor_roundtrip_possible()` is still dimension-only
+
+Lines 524–555 decide roundtrippability from the ABS type and real dimension count. That was the main issue in the spec: dimension is necessary but not sufficient.
+
+You should make this a **rank check over the actual chosen spinor map**:
+
+```
+def _even_indices(dim: int) -> np.ndarray:
+    return np.array([i for i in range(dim) if i.bit_count() % 2 == 0])
+
+
+def _spinor_reference_vector(alg: Algebra) -> np.ndarray:
+    gammas = compact_basis(alg)
+    k = gammas[0].shape[0]
+    p = _choose_idempotent(gammas, k)
+
+    # Use the first nonzero column of p as the reference spinor.
+    # This works for diagonal and non-diagonal projectors.
+    norms = np.linalg.norm(p, axis=0)
+    col = int(np.argmax(norms))
+    if norms[col] < 1e-14:
+        u = np.zeros((k, 1), dtype=complex)
+        u[0, 0] = 1.0
+        return u
+
+    return p[:, col : col + 1]
+
+
+def _spinor_system_matrix(alg: Algebra) -> tuple[np.ndarray, np.ndarray]:
+    blade_mats = _build_compact_blade_matrices(alg)
+    even_indices = _even_indices(alg.dim)
+    u = _spinor_reference_vector(alg)
+
+    cols = (blade_mats[even_indices] @ u)[:, :, 0]  # (n_even, k)
+    A_complex = cols.T                              # (k, n_even)
+    A_real = np.vstack([A_complex.real, A_complex.imag])
+    return A_real, even_indices
+
+
+def _spinor_roundtrip_possible(alg: Algebra) -> bool:
+    try:
+        A, even_indices = _spinor_system_matrix(alg)
+    except NotImplementedError:
+        return False
+
+    return np.linalg.matrix_rank(A, tol=1e-10) == len(even_indices)
+```
+
+Then `from_spinor_matrix()` should use the same `A` and `even_indices`, not rebuild a slightly different column-selection path.
+
+------
+
+### 2. `to_spinor_matrix()` should use a reference vector, not “extract first diagonal column”
+
+Lines 608–614 do:
+
+```
+projected = mat @ p
+for col in range(k):
+    if np.abs(p[col, col]) > 0.5:
+        return projected[:, col : col + 1]
+```
+
+This works for Cl(3,0) and happens to work for Cl(1,3), but it is conceptually brittle. For a non-diagonal idempotent, the diagonal can be `0.5`, so the `> 0.5` test misses it. Then the fallback chooses the first nonzero projected column depending on the **input multivector**, which is a bad property: the reference spinor convention should not depend on the value being converted.
+
+Use:
+
+```
+def to_spinor_matrix(mv: Multivector) -> np.ndarray:
+    from galaga import is_even
+
+    if not is_even(mv):
+        raise ValueError(
+            "to_spinor_matrix requires an even-grade multivector. "
+            "Use galaga.even_grades(mv) to project to the even part first."
+        )
+
+    if not _spinor_roundtrip_possible(mv.algebra):
+        p = sum(1 for s in mv.algebra.signature if s > 0)
+        q = sum(1 for s in mv.algebra.signature if s < 0)
+        etype, _ = _classify(p, q)
+        raise TypeError(
+            f"Cl({p},{q}) (type '{etype}') does not support faithful spinor roundtrip "
+            f"with the selected compact representation and reference spinor. "
+            f"Use to_matrix(mv, mode='compact') for the full matrix representation."
+        )
+
+    return _to_compact(mv) @ _spinor_reference_vector(mv.algebra)
+```
+
+And `from_spinor_matrix()` becomes:
+
+```
+def from_spinor_matrix(alg: Algebra, spinor: np.ndarray) -> Multivector:
+    A, even_indices = _spinor_system_matrix(alg)
+
+    if np.linalg.matrix_rank(A, tol=1e-10) != len(even_indices):
+        p = sum(1 for s in alg.signature if s > 0)
+        q = sum(1 for s in alg.signature if s < 0)
+        etype, _ = _classify(p, q)
+        raise TypeError(
+            f"Cl({p},{q}) (type '{etype}') does not support faithful spinor roundtrip "
+            f"with the selected compact representation and reference spinor."
+        )
+
+    k = A.shape[0] // 2
+
+    spinor = np.asarray(spinor, dtype=complex)
+    if spinor.shape == (k,):
+        spinor = spinor.reshape(k, 1)
+    if spinor.shape != (k, 1):
+        raise ValueError(f"Expected ({k}, 1) spinor, got {spinor.shape}")
+
+    b = np.concatenate([spinor[:, 0].real, spinor[:, 0].imag])
+    coeffs_even, residuals, rank, _ = np.linalg.lstsq(A, b, rcond=None)
+
+    if rank != len(even_indices):
+        raise TypeError("Selected spinor map is rank-deficient.")
+
+    data = np.zeros(alg.dim)
+    data[even_indices] = coeffs_even
+    return Multivector(alg, data)
+```
+
+This also removes duplicated column-selection logic.
+
+------
+
+### 3. `to_quaternion_matrix()` is wrong for your Cl(1,3) Dirac basis
+
+This is the most serious new code-level issue.
+
+Your quaternion embedding convention is:
+
+```
+q = a + bi + cj + dk
+→ [[a+bi, c+di],
+   [-c+di, a-bi]]
+```
+
+That is lines 152–159 and 483–494.
+
+But your Cl(1,3) Dirac matrices in lines 210–216 use blocks like:
+
+```
+[[0, σᵢ],
+ [-σᵢ, 0]]
+```
+
+The Pauli matrix `σ1 = [[0,1],[1,0]]` is **not** a quaternion block under your embedding, because a quaternion block with top-right `+1` would have bottom-left `-1`, not `+1`.
+
+So this function:
+
+```
+block = cmat[2*i:2*i+2, 2*j:2*j+2]
+row.append(_extract_quat(block))
+```
+
+silently reads non-quaternionic 2×2 complex blocks as if they were quaternions. That gives mathematically false quaternion matrices for Cl(1,3).
+
+You have two viable options.
+
+Option A: keep standard Dirac matrices, but disable quaternion-matrix extraction for them:
+
+```
+def to_quaternion_matrix(mv: Multivector) -> list[list[Quat]]:
+    p = sum(1 for s in mv.algebra.signature if s > 0)
+    q = sum(1 for s in mv.algebra.signature if s < 0)
+    etype, qdim = _classify(p, q)
+
+    if etype != "quaternion":
+        raise TypeError(
+            f"Cl({p},{q}) is type '{etype}', not a single quaternionic matrix algebra."
+        )
+
+    # Important: this requires the compact representation to be in quaternionic
+    # 2×2 block form. The standard Dirac basis used for Cl(1,3) is not.
+    if (p, q) == (1, 3):
+        raise TypeError(
+            "to_quaternion_matrix is not valid for the current Cl(1,3) Dirac basis; "
+            "use a quaternionic-block gamma basis or to_matrix(..., mode='compact')."
+        )
+```
+
+Option B: introduce a separate **quaternionic-block Cl(1,3) basis** and use that for quaternion matrix/spinor APIs. For example, over $M(2,\mathbb H)$:
+$$
+\gamma^0 =
+\begin{pmatrix}
+1 & 0 \\
+0 & -1
+\end{pmatrix},
+\quad
+\gamma^i =
+\begin{pmatrix}
+0 & u_i \\
+u_i & 0
+\end{pmatrix}
+$$
+where $u_i \in \{i,j,k\}$. Since $u_i^2=-1$, the spatial gammas square to $-1$, and they anticommute correctly.
+
+Then embed each quaternion block using your `_quat_to_complex()` function.
+
+------
+
+### 4. `to_spinor_quaternion()` has the same representation-convention problem
+
+Lines 760–768 pair consecutive complex entries and interpret them as quaternions. That is only meaningful if the complex representation is arranged as a quaternionic module in the same block convention.
+
+For Cl(0,2), that is okay. For Cl(1,3) using your current Dirac matrices, it is at best a packaging of four complex entries into two `Quat` objects, not a mathematically natural quaternionic spinor compatible with your `M(2,H)` matrix extraction.
+
+I’d either rename it to make the weaker meaning explicit:
+
+```
+to_spinor_quaternion_packed()
+```
+
+or require a quaternionic-block representation before exposing it as a real quaternionic spinor.
+
+------
+
+### 5. Quaternionic double algebras accidentally pass the “quaternionic” check
+
+Lines 754 and 825 check:
+
+```
+if "quaternion" not in etype:
+```
+
+That allows `"quaternion+quaternion"`.
+
+But the docstring says only $(q-p)\bmod 8 \in \{2,4\}$. For $(q-p)\bmod 8=3$, the algebra is $A \oplus A$, and your compact representation chooses one summand. That can be okay for some even-subalgebra spinor maps, but it is not the same claim.
+
+Use:
+
+```
+if etype != "quaternion":
+    raise TypeError(...)
+```
+
+unless you deliberately want a `one_summand=True` mode.
+
+------
+
+### 6. `_from_compact()` should check rank and residuals
+
+Lines 417–435 recover coefficients using least squares, but for double algebras or invalid matrices this can silently return a “best fit” multivector. That is dangerous for a math library.
+
+Add rank/residual validation:
+
+```
+coeffs, residuals, rank, _ = np.linalg.lstsq(A, b, rcond=None)
+
+if rank < dim:
+    raise TypeError(
+        "Compact representation is not injective for this algebra; "
+        "cannot recover a unique multivector."
+    )
+
+err = np.linalg.norm(A @ coeffs - b)
+if err > 1e-9:
+    raise ValueError(
+        "Matrix is not in the image of this Clifford representation."
+    )
+```
+
+Or expose a `strict: bool = True` flag.
+
+------
+
+### 7. `compact_basis()` says “minimal-dimension faithful” but double algebras are not faithful
+
+Lines 358–362 say:
+
+> minimal-dimension faithful matrix representation
+
+But the module docstring already admits double algebras use one summand and may not roundtrip. The function docstring should say:
+
+```
+Return compact gamma matrices for a low-dimensional representation.
+
+For simple Clifford algebras this is faithful. For double algebras
+(s = 3 or 7) this returns one irreducible summand and is not faithful
+on the full algebra.
+```
+
+Otherwise callers will trust `from_matrix(..., mode="compact")` when they shouldn’t.
+
+------
+
+### 8. Cl(0,0) edge case breaks
+
+`_general_compact_basis(0,0)` returns `[]`, then `_build_compact_blade_matrices()` does:
+
+```
+k = gammas[0].shape[0]
+```
+
+So scalar algebra compact mode crashes. Either reject it explicitly or handle it:
+
+```
+if alg.n == 0:
+    return np.ones((1, 1, 1), dtype=complex)
+```
+
+------
+
+## What looks good
+
+The left-regular representation is straightforward and mathematically sound: first column recovery in `_from_left_regular()` is valid because left multiplication by $M$ sends $1$ to $M$.
+
+The blade construction in `_build_compact_blade_matrices()` is also conventionally correct assuming your algebra’s bitmask blade order is ascending basis-vector order. It fixes the earlier `e31` sign ambiguity by always building canonical bitmask blades as ascending products.
+
+The rank results I checked for the current selected-column map were encouraging for the headline cases:
+
+```
+Cl(3,0): rank 4 / even dim 4
+Cl(1,3): rank 8 / even dim 8
+Cl(0,2): rank 2 / even dim 2
+Cl(4,0): rank 8 / even dim 8
+Cl(3,1): rank 4 / even dim 8
+Cl(2,2): rank 4 / even dim 8
+```
+
+So the **column-spinor roundtrip idea works for the important cases**, but the code should prove it by rank, not assert it by classification.
+
+## Recommended merge gate
+
+Before shipping, I’d add tests like these:
+
+```
+@pytest.mark.parametrize("signature", [
+    [1, 1, 1],        # Cl(3,0)
+    [1, -1, -1, -1],  # Cl(1,3)
+    [-1, -1],         # Cl(0,2)
+    [1, 1, 1, 1],     # Cl(4,0)
+])
+def test_even_spinor_roundtrip(signature):
+    alg = Algebra(signature)
+    rng = np.random.default_rng(0)
+
+    data = np.zeros(alg.dim)
+    for i in range(alg.dim):
+        if i.bit_count() % 2 == 0:
+            data[i] = rng.normal()
+
+    mv = Multivector(alg, data)
+    out = from_spinor_matrix(alg, to_spinor_matrix(mv))
+
+    assert np.allclose(out.data, mv.data, atol=1e-9)
+```
+
+And negative tests:
+
+```
+@pytest.mark.parametrize("signature", [
+    [1, 1, 1, -1],       # Cl(3,1)
+    [1, 1, -1, -1],      # Cl(2,2)
+    [1, 1, 1, 1, -1],    # Cl(4,1)
+])
+def test_non_roundtrippable_spinor_rejected(signature):
+    alg = Algebra(signature)
+    assert not _spinor_roundtrip_possible(alg)
+```
+
+## Bottom line
+
+The implementation is close for `to_spinor_matrix()` / `from_spinor_matrix()` if you reframe it as:
+$$
+\psi \mapsto \rho(\psi)u
+$$
+for a fixed reference spinor $u$, with a rank-checked inverse.
+
+But I would **block the quaternion APIs** until you either:
+
+1. provide a genuine quaternionic-block representation, or
+2. clearly mark them as simple complex-pair packing rather than quaternionic Clifford matrix/spinor conversion.

galaga_matrix-1.7.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: galaga-matrix
+Version: 1.7.0
+Summary: Matrix representations for galaga Clifford algebras
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: galaga>=1.7.0
+Requires-Dist: numpy>=1.24.0