cmb-format 0.1.0__tar.gz

cmb_format-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,85 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --group test -e .
+
+      - name: Test
+        run: python -m pytest -q
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --group lint -e .
+
+      - name: Lint
+        run: python -m ruff check .
+
+      - name: Format
+        run: python -m ruff format --check .
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build distributions
+        # Build the wheel from the sdist to verify both distribution paths.
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check --strict dist/*
+
+      - name: Install wheel and test dependencies
+        run: python -m pip install --group test dist/*.whl
+
+      - name: Test installed wheel
+        run: |
+          cd "$RUNNER_TEMP"
+          python -c 'from importlib.resources import files; assert files("cmb_format").joinpath("py.typed").is_file()'
+          python -m pytest -q "$GITHUB_WORKSPACE/tests"

cmb_format-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Verify the tag matches the packaged version
+        # PyPI versions are immutable, so catch a tag/version mismatch here
+        # rather than after an upload that cannot be replaced.
+        run: |
+          version=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')
+          if [ "$version" != "${GITHUB_REF_NAME#v}" ]; then
+            echo "::error::tag ${GITHUB_REF_NAME} does not match pyproject version ${version}"
+            exit 1
+          fi
+
+      - name: Build distributions
+        # Build the wheel from the sdist to verify both distribution paths.
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check --strict dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Must match the pending publisher configured at
+    # https://pypi.org/manage/account/publishing/
+    environment: pypi
+    permissions:
+      # Required for Trusted Publishing; the job requests an OIDC token
+      # instead of holding a long-lived API token.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

cmb_format-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Environments (the workspace venv lives in the parent dev/ directory)
+.venv/
+venv/
+.env
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+
+# NOTE: tests/goldens/ is deliberately NOT ignored. Those committed bytes are
+# the format's reference -- they are the whole point of this repository.
+
+# Local Claude Code instructions -- not meant to be committed
+/CLAUDE.md

cmb_format-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+Notable changes to `cmb-format`, the Python reference implementation.
+
+This file tracks the **package**. The CMB **format** versions separately —
+see `docs/binary-format.md`'s Versioning section. Which format versions a
+build handles is stated in code, as `WRITTEN_FORMAT_VERSION` and
+`READABLE_FORMAT_VERSIONS`.
+
+## [0.1.0]
+
+Initial release.
+
+[0.1.0]: https://github.com/dwfmarchant/cmb-format/releases/tag/v0.1.0

cmb_format-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Marchant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cmb_format-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: cmb-format
+Version: 0.1.0
+Summary: Specification and reference implementation of CMB (Cell Model Binary), a file format for cell-based meshes and the models defined on them
+Project-URL: Homepage, https://github.com/dwfmarchant/cmb-format
+Project-URL: Repository, https://github.com/dwfmarchant/cmb-format
+Project-URL: Changelog, https://github.com/dwfmarchant/cmb-format/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/dwfmarchant/cmb-format/issues
+Project-URL: Specification, https://github.com/dwfmarchant/cmb-format/blob/main/docs/binary-format.md
+Author-email: David Marchant <dwfmarchant@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: binary-format,cmb,file-format,geophysics,mesh,octree
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Description-Content-Type: text/markdown
+
+# cmb-format
+
+**CMB (Cell Model Binary)** is a binary file format and Python I/O library
+for storing UBC GIF–style tensor and octree meshes and their associated
+models. It provides an alternative to the ASCII mesh and model files used
+by UBC GIF software. CMB supports uniform and variable-spacing tensor
+meshes, octree meshes, multiple named models, and file- and model-level
+metadata.
+
+CMB stores mesh geometry and model values as typed arrays, with metadata in
+JSON, so consumers can avoid parsing millions of numbers from text. Large
+octree consumers that need only arrays can also avoid allocating a full
+consumer mesh; see the [discretize round trips and benchmarks](https://github.com/dwfmarchant/cmb-format/blob/main/docs/discretize.md).
+
+## Capabilities
+
+- Store mesh geometry and per-cell model arrays together in a `.cmb` file.
+- Store models separately from geometry to avoid duplicating large meshes.
+- Read individual arrays without loading the whole file.
+- Verify each array's integrity with a SHA-256 checksum.
+
+## Installation
+
+Requires Python 3.11 or newer. NumPy is the only runtime dependency.
+From a local checkout:
+
+```bash
+python -m pip install .
+```
+
+## Usage
+
+The API accepts dictionaries of NumPy arrays describing meshes and models.
+CMB uses a different cell ordering from UBC GIF; these routines do not
+convert between the two. See
+[Cell numbering / ordering](https://github.com/dwfmarchant/cmb-format/blob/main/docs/binary-format.md#cell-numbering-ordering)
+in the format specification.
+
+Write a four-cell tensor mesh and a resistivity model, then read them back:
+
+```python
+import numpy as np
+
+import cmb_format as cmb
+
+mesh = {
+    "mode": "embedded",
+    "mesh_class": "TensorMesh",
+    "arrays": {
+        "origin": np.zeros(3),
+        "h_x": np.array([1.0, 2.0]),
+        "h_y": np.array([1.0, 1.0]),
+        "h_z": np.array([3.0]),
+    },
+}
+models = {
+    "rho": {
+        "metadata": {"units": "ohm-m"},
+        "array": np.array([10.0, 20.0, 30.0, 40.0]),
+    }
+}
+cmb.write_file("example.cmb", mesh, models)
+
+mesh, models, metadata = cmb.read_file("example.cmb")
+rho = models["rho"]["array"]
+```
+
+`read_file` loads and checksum-verifies all geometry and model arrays,
+including nested base-mesh geometry. Its three results match `write_file`'s
+`mesh`, `models`, and `metadata` parameters, so passing them straight back
+preserves the mesh geometry, model arrays, and metadata. The NumPy arrays are
+read-only; use `.copy()` if you need to modify them.
+
+To read individual arrays without loading the whole file:
+
+```python
+with open("example.cmb", "rb") as f:
+    header, data_start = cmb.read_header(f)
+    metadata = header["metadata"]
+    geometry = cmb.read_arrays(f, data_start, header["mesh"]["arrays"])
+    rho = cmb.read_array(f, data_start, header["models"]["rho"]["array"])
+```
+
+For measured large-octree and tensor round trips and timing methodology, see
+[the discretize interoperability notes](https://github.com/dwfmarchant/cmb-format/blob/main/docs/discretize.md). On the measured
+2.18-million-leaf sample, the generated CMB file is 10.4 MiB versus 28.8 MiB
+for UBC, and conversion plus CMB writing is about 21× faster.
+
+## Development
+
+From a local checkout, with pip 25.1 or newer:
+
+```bash
+python -m pip install --group dev -e .
+python -m pytest
+python -m ruff check .
+python -m ruff format --check .
+```
+
+Committed reference files in `tests/goldens/` test compatibility with the
+binary format alongside round-trip tests.
+
+The [format specification](https://github.com/dwfmarchant/cmb-format/blob/main/docs/binary-format.md) defines the file layout
+and mesh schemas. Package and format versions are independent; see
+[versioning](https://github.com/dwfmarchant/cmb-format/blob/main/docs/binary-format.md#versioning) and the
+[package changelog](https://github.com/dwfmarchant/cmb-format/blob/main/CHANGELOG.md).

cmb_format-0.1.0/README.md

@@ -0,0 +1,106 @@
+# cmb-format
+
+**CMB (Cell Model Binary)** is a binary file format and Python I/O library
+for storing UBC GIF–style tensor and octree meshes and their associated
+models. It provides an alternative to the ASCII mesh and model files used
+by UBC GIF software. CMB supports uniform and variable-spacing tensor
+meshes, octree meshes, multiple named models, and file- and model-level
+metadata.
+
+CMB stores mesh geometry and model values as typed arrays, with metadata in
+JSON, so consumers can avoid parsing millions of numbers from text. Large
+octree consumers that need only arrays can also avoid allocating a full
+consumer mesh; see the [discretize round trips and benchmarks](https://github.com/dwfmarchant/cmb-format/blob/main/docs/discretize.md).
+
+## Capabilities
+
+- Store mesh geometry and per-cell model arrays together in a `.cmb` file.
+- Store models separately from geometry to avoid duplicating large meshes.
+- Read individual arrays without loading the whole file.
+- Verify each array's integrity with a SHA-256 checksum.
+
+## Installation
+
+Requires Python 3.11 or newer. NumPy is the only runtime dependency.
+From a local checkout:
+
+```bash
+python -m pip install .
+```
+
+## Usage
+
+The API accepts dictionaries of NumPy arrays describing meshes and models.
+CMB uses a different cell ordering from UBC GIF; these routines do not
+convert between the two. See
+[Cell numbering / ordering](https://github.com/dwfmarchant/cmb-format/blob/main/docs/binary-format.md#cell-numbering-ordering)
+in the format specification.
+
+Write a four-cell tensor mesh and a resistivity model, then read them back:
+
+```python
+import numpy as np
+
+import cmb_format as cmb
+
+mesh = {
+    "mode": "embedded",
+    "mesh_class": "TensorMesh",
+    "arrays": {
+        "origin": np.zeros(3),
+        "h_x": np.array([1.0, 2.0]),
+        "h_y": np.array([1.0, 1.0]),
+        "h_z": np.array([3.0]),
+    },
+}
+models = {
+    "rho": {
+        "metadata": {"units": "ohm-m"},
+        "array": np.array([10.0, 20.0, 30.0, 40.0]),
+    }
+}
+cmb.write_file("example.cmb", mesh, models)
+
+mesh, models, metadata = cmb.read_file("example.cmb")
+rho = models["rho"]["array"]
+```
+
+`read_file` loads and checksum-verifies all geometry and model arrays,
+including nested base-mesh geometry. Its three results match `write_file`'s
+`mesh`, `models`, and `metadata` parameters, so passing them straight back
+preserves the mesh geometry, model arrays, and metadata. The NumPy arrays are
+read-only; use `.copy()` if you need to modify them.
+
+To read individual arrays without loading the whole file:
+
+```python
+with open("example.cmb", "rb") as f:
+    header, data_start = cmb.read_header(f)
+    metadata = header["metadata"]
+    geometry = cmb.read_arrays(f, data_start, header["mesh"]["arrays"])
+    rho = cmb.read_array(f, data_start, header["models"]["rho"]["array"])
+```
+
+For measured large-octree and tensor round trips and timing methodology, see
+[the discretize interoperability notes](https://github.com/dwfmarchant/cmb-format/blob/main/docs/discretize.md). On the measured
+2.18-million-leaf sample, the generated CMB file is 10.4 MiB versus 28.8 MiB
+for UBC, and conversion plus CMB writing is about 21× faster.
+
+## Development
+
+From a local checkout, with pip 25.1 or newer:
+
+```bash
+python -m pip install --group dev -e .
+python -m pytest
+python -m ruff check .
+python -m ruff format --check .
+```
+
+Committed reference files in `tests/goldens/` test compatibility with the
+binary format alongside round-trip tests.
+
+The [format specification](https://github.com/dwfmarchant/cmb-format/blob/main/docs/binary-format.md) defines the file layout
+and mesh schemas. Package and format versions are independent; see
+[versioning](https://github.com/dwfmarchant/cmb-format/blob/main/docs/binary-format.md#versioning) and the
+[package changelog](https://github.com/dwfmarchant/cmb-format/blob/main/CHANGELOG.md).