Skip to content

Conversation

@e-lo
Copy link
Member

@e-lo e-lo commented Dec 16, 2025

This PR introduces a new, normative, versioned core specification for the OMX file format (“OMX 0.2.1") and provides a unified structure for defining:

  1. The serialized on-disk format for .omx files
  2. Requirements for official language bindings (Python, R, Java, C++, C#, etc.)
  3. A clear distinction between language bindings, host-application compliance and plug-ins

The goal is to provide a clearer, more rigorous, and more maintainable specification than the current mix of wiki pages ("Data Structure 0.2", "Open matrix requirements", and "Specification v0.2"), which combine design goals, project requirements, and partial format rules.

Key changes:

  1. Adds omx.md - contains the normative language for the OMX specification in the core repo in a way that is declarative and can be version-controlled.
  2. Updates readme.md to refer to omx.md

What it does not do:

  • update any of the wiki pages since those are not in the same version control branch (one of their key deficiencies!)
  • change anything in the intended interpretation of the OMX file specification or break compatibility with existing OMX 0.2 files

Things for @bstabler and @billyc to review - in order (if we aren't in agreement about 1, no need to discuss 2 yet!):

  1. Should we define OMX in an RFC-style document as this PR does?
  2. Do you generally agree with Section 1: Definitions?
  3. Do you generally agree with Section 2: File Specification?
  4. Do you generally agree with Section 3: Language Binding Specification?
  5. Any edits to the above that you would propose?
  6. Any other minor usability/clarity/structure that we should consider? (save larger changes for a subsequent PR)

Fixes issue #40

@e-lo e-lo requested review from billyc and bstabler December 16, 2025 22:12
@e-lo e-lo self-assigned this Dec 16, 2025
@e-lo e-lo linked an issue Dec 16, 2025 that may be closed by this pull request

### 2.4 Matrix datasets: `/data/*`

Each dataset under `/data` represents one matrix “core”:

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to move away from the "matrix core" terminology? It isn't mentioned any where else in this document nor elsewhere on any of the OMX repositories.

As an anecdote, within AequilibraE we've seen some users confuse this term with compute cores/threads, additionally the idea of a "matrix" having multiple "cores" was novel. Instead they used more typical terms, "matrix" and "matrices", to refer to the 2D structures.

My understanding is the "core" term comes from some other piece of software that I am not familiar with.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Adopt Normative Definitions

3 participants