Unify `Matrix` and `Tensor` internals

Open
#24 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Refactor
Clarity
Needs clarification
Activity status
Quiet
Tech stack
c, python
Domain
data

Research direction

Start by locating the existing C implementations and the Python Matrix and Tensor entry points, then review the existing Matrix tests, examples, and downstream C ABI expectations. Done means both types share representation and inner loops while Matrix keeps its public Python behavior, rank-2 algebra, performance, and compatibility; the open conversion and interoperability questions also need decisions.

Written by the indexing model from the issue text.

Description

maths

Problem

After the Tensor work lands, the project carries two parallel C implementations of "dense array of doubles": one rank-2 (Matrix), one N-D (Tensor). Every arithmetic op, every aggregate, every cross-interpreter round-trip exists twice. New work has to be added in both places, or one side drifts. This is sustainable for one release; it is not sustainable as a long-term shape for the library.

Desired functionality

The two types share a single C representation and a single set of inner loops. Matrix becomes the rank-2 face of that shared machinery. The Python-level Matrix API — constructor, methods, return types, repr, type identity — looks identical to today from the outside; existing user code, existing examples, and existing downstream C consumers keep working unmodified.

Constraints

  • Zero public API breakage. Every existing Matrix test, every example, every downstream C ABI consumer must keep working unchanged.
  • No measurable performance regression on Matrix-shaped workloads.
  • Matrix keeps its own Python type. isinstance(x, Matrix) keeps working.
  • Rank-2-only algebra (matmul, transpose, T, axis-0 / axis-1 aggregate sugar) stays on Matrix.

Out of scope

Generalising rank-2 algebra onto Tensor (matmul on Tensor, batched matmul, transpose(axes=...), swapaxes). Removing or renaming any public Matrix surface. Treating Matrix as deprecated.

Open questions

  • Whether Matrix and Tensor should be silently interchangeable in each other's arithmetic dunders, or whether the user has to step through an explicit conversion.
  • Whether to expose explicit Matrix.to_tensor() / Tensor.to_matrix() helpers regardless.
Dominant language
Python
Stars
184
Forks
9
PR merge metrics
No merged PRs in 30d

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microsoft/bocpy

All issues in microsoft/bocpy

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.