brepax 0.1.0__tar.gz

brepax-0.1.0/.devcontainer/Dockerfile

@@ -0,0 +1,5 @@
+FROM mcr.microsoft.com/devcontainers/python:1-3.12-bookworm
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+ENV UV_LINK_MODE=copy

brepax-0.1.0/.devcontainer/devcontainer.json

@@ -0,0 +1,24 @@
+{
+  "name": "BRepAX",
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/python:1": {
+      "version": "3.12"
+    }
+  },
+  "postCreateCommand": "curl -LsSf https://astral.sh/uv/install.sh | sh && uv sync --extra dev",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "charliermarsh.ruff",
+        "ms-python.mypy-type-checker"
+      ],
+      "settings": {
+        "python.defaultInterpreterPath": ".venv/bin/python"
+      }
+    }
+  }
+}

brepax-0.1.0/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{yaml,yml,toml,json}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

brepax-0.1.0/.gitattributes

@@ -0,0 +1,17 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+
+# Python
+*.py text diff=python
+
+# Lockfile — binary diff, always merge ours
+uv.lock -diff merge=ours linguist-generated
+
+# Documentation
+*.md text diff=markdown
+
+# Notebooks — stored as JSON, output stripped on commit
+*.ipynb filter=nbstripout diff=json linguist-generated
+
+# Benchmark results
+benchmarks/gradient_accuracy/results/*.json linguist-generated

brepax-0.1.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @lv416e

brepax-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -0,0 +1,46 @@
+name: Bug Report
+description: Report a bug in BRepAX
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear description of the bug.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal code to reproduce the issue.
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What you expected to happen.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: BRepAX Version
+      placeholder: e.g., 0.1.0
+    validations:
+      required: true
+  - type: input
+    id: jax-version
+    attributes:
+      label: JAX Version
+      placeholder: e.g., 0.4.34
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - Linux
+        - macOS
+        - Windows

brepax-0.1.0/.github/ISSUE_TEMPLATE/config.yaml

@@ -0,0 +1 @@
+blank_issues_enabled: true

brepax-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -0,0 +1,23 @@
+name: Feature Request
+description: Suggest a new feature
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear description of the feature you'd like.
+    validations:
+      required: true
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation
+      description: Why is this feature needed? What problem does it solve?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any alternative solutions you've considered.

brepax-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+## What changed
+
+<!-- 1-3 sentences describing the essence of this change -->
+
+## Why
+
+<!-- Motivation, link to spec section or ADR if applicable -->
+
+## How verified
+
+- [ ] Tests pass (`uv run pytest`)
+- [ ] Type checking passes (`uv run mypy src/`)
+- [ ] Linting passes (`uv run ruff check src/ tests/`)
+
+<!-- Benchmark results or unexpected behaviors, if applicable -->
+
+## Open questions
+
+<!-- Unresolved points to address in follow-up PRs -->
+
+## Checklist
+
+- [ ] Property tests added/updated
+- [ ] Unit tests added/updated
+- [ ] Type annotations complete
+- [ ] Docstrings with Examples section
+- [ ] ADR updated if architectural decision was made
+- [ ] Commit messages follow Conventional Commits

brepax-0.1.0/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      jax:
+        patterns:
+          - "jax*"
+      testing:
+        patterns:
+          - "pytest*"
+          - "hypothesis"
+          - "chex"

brepax-0.1.0/.github/workflows/ci.yaml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --extra dev
+      - run: uv run ruff check src/ tests/
+      - run: uv run ruff format --check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --extra dev
+      - run: uv run mypy src/
+
+  test:
+    needs: [lint, typecheck]
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --extra dev
+      - run: uv run pytest --cov=brepax --cov-report=xml -x -m "not slow"
+      - uses: codecov/codecov-action@v6
+        if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest'
+        with:
+          file: coverage.xml
+          fail_ci_if_error: false

brepax-0.1.0/.github/workflows/docs.yaml

@@ -0,0 +1,26 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --extra docs
+      - run: uv run mkdocs build --strict
+      - name: Deploy to GitHub Pages
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        run: uv run mkdocs gh-deploy --force

brepax-0.1.0/.github/workflows/publish-test.yaml

@@ -0,0 +1,29 @@
+name: Publish to TestPyPI
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*.*.*-rc*"
+      - "v*.*.*-beta*"
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/brepax/
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

brepax-0.1.0/.github/workflows/publish.yaml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/brepax/
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

brepax-0.1.0/.github/workflows/release-please.yaml

@@ -0,0 +1,22 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json

brepax-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+.hypothesis/
+.benchmarks/
+
+# mypy
+.mypy_cache/
+
+# ruff
+.ruff_cache/
+
+# Documentation
+site/
+
+# Secrets and credentials
+.env
+.env.*
+credentials.*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Jupyter
+.ipynb_checkpoints/
+
+# nox
+.nox/

brepax-0.1.0/.lefthook.yml

@@ -0,0 +1,20 @@
+pre-commit:
+  parallel: false
+  commands:
+    ruff-format:
+      glob: "*.py"
+      run: uv run ruff format src/ tests/
+    ruff-check:
+      glob: "*.py"
+      run: uv run ruff check src/ tests/ --fix
+      stage_fixed: true
+    mypy:
+      glob: "*.py"
+      run: uv run mypy src/
+
+commit-msg:
+  commands:
+    conventional-commit:
+      run: >
+        head -1 {1} | grep -qE '^(feat|fix|refactor|docs|test|perf|ci|chore|build|style|revert)(\(.+\))?!?: .+'
+        || (echo "Commit message must follow Conventional Commits: <type>(<scope>): <description>" && exit 1)

brepax-0.1.0/.mise.toml

@@ -0,0 +1,42 @@
+# BRepAX Development Environment
+# Managed by mise (https://mise.jdx.dev)
+
+[tools]
+python = "3.12"
+uv = "latest"
+lefthook = "latest"
+
+[tasks.sync]
+description = "Sync dependencies"
+run = "uv sync"
+
+[tasks.test]
+description = "Run tests"
+run = "uv run pytest"
+
+[tasks.lint]
+description = "Run ruff linter"
+run = "uv run ruff check src/ tests/"
+
+[tasks.fmt]
+description = "Format code"
+run = ["uv run ruff format src/ tests/", "uv run ruff check --fix src/ tests/"]
+
+[tasks.type-check]
+description = "Run mypy type checker"
+run = "uv run mypy src/"
+
+[tasks.check]
+description = "Run all checks (lint + type-check + test)"
+depends = ["lint", "type-check", "test"]
+
+[tasks.docs]
+description = "Serve documentation locally"
+run = "uv run mkdocs serve"
+
+[tasks.bench]
+description = "Run benchmarks"
+run = "uv run pytest tests/benchmarks/ --benchmark-only"
+
+[env]
+UV_LINK_MODE = "copy"

brepax-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

brepax-0.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.0.0"
+}

brepax-0.1.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).

brepax-0.1.0/CITATION.cff

@@ -0,0 +1,16 @@
+cff-version: 1.2.0
+title: BRepAX
+message: "If you use this software, please cite it as below."
+type: software
+authors:
+  - given-names: lv416e
+    email: mary.lv416e@gmail.com
+repository-code: https://github.com/lv416e/brepax
+license: Apache-2.0
+keywords:
+  - jax
+  - cad
+  - differentiable
+  - brep
+  - boolean-operations
+  - signed-distance-function

brepax-0.1.0/CLAUDE.md

@@ -0,0 +1,155 @@
+<!-- markdownlint-disable MD013 -->
+# Project Guidelines
+
+## Language and Style
+
+**English** -- code, comments, docstrings, commit messages, log messages.
+**Japanese** -- PR titles/bodies, issue titles/bodies, markdown documentation, user-facing communication.
+No emojis in code, comments, or documentation.
+
+## Project Mission
+
+BRepAX is a JAX-native library providing a differentiable rasterizer for CAD Boolean operations. It translates contact dynamics formulations from differentiable physics into the CAD domain, enabling gradient-based optimization through B-Rep topology changes. BRepAX is NOT a general CAD kernel, mesh library, or physics simulator.
+
+## Technical Thesis
+
+The gradient discontinuities at topological boundaries in CAD Boolean operations (where edges/faces appear or disappear) are mathematically isomorphic to contact events in differentiable physics simulation. By mapping LCP/convex/compliant/PBD contact formulations to stratum tracking / boundary smoothing / event-based correction / penalty strategies, we build a differentiable B-Rep kernel without inventing new theory.
+
+## Comments
+
+Comments explain **why**, not what or how. Keep them minimal and concise.
+
+Prohibited:
+
+- Development stage markers: "Phase 1", "Step 2", "TODO Phase 3", "WIP", "FIXME"
+- Commented-out code or debug print statements
+- Restated logic ("loop through users", "compute distance")
+- Personal notes: "will fix later", "temp solution"
+
+## Repository Conventions
+
+- **src layout**: All library code lives under `src/brepax/`
+- **Diataxis documentation**: `docs/` follows tutorials / how-to / reference / explanation separation
+- **ADR pattern**: All significant architectural decisions are recorded in `docs/architecture/adr/`
+- **Test-first development**: New features must include property tests and unit tests simultaneously
+- **Conventional Commits**: All commit messages follow the Conventional Commits specification
+
+## Development Workflow
+
+```bash
+# Install dependencies
+uv sync --extra dev
+
+# Run tests
+uv run pytest
+
+# Run linter
+uv run ruff check src/ tests/
+
+# Format code
+uv run ruff format src/ tests/
+
+# Type checking
+uv run mypy src/
+
+# Run all checks via nox
+uv run nox -s test
+uv run nox -s lint
+uv run nox -s typecheck
+
+# Install git hooks (lefthook, managed via mise)
+lefthook install
+
+# Build documentation
+uv run mkdocs serve
+```
+
+### PR Checklist
+
+1. All tests pass (`uv run pytest`)
+2. Type checking passes (`uv run mypy src/`)
+3. Linting passes (`uv run ruff check src/ tests/`)
+4. New public API has docstrings with Examples section
+5. Commit messages follow Conventional Commits
+6. ADR added if an architectural decision was made
+
+## Imports
+
+Follow PEP 8 grouping (stdlib, third-party, local). All imports at the top of the file.
+
+Local imports are allowed only for: circular import avoidance, lazy loading of heavy dependencies,
+optional dependency isolation, or plugin/backend switching. Add a comment explaining which applies.
+
+For type hints causing circular imports, use `TYPE_CHECKING` guard with string annotations.
+
+## JAX-Specific Patterns
+
+- **Base class**: All geometric types inherit from `equinox.Module`
+- **Type annotations**: All public APIs use `jaxtyping` annotations (`Float[Array, "..."]`)
+- **Static shapes**: JAX requires static shapes for jit. Use padding + masking for variable-size structures (see ADR-0005)
+- **Transformations**: Every public function must be compatible with `jit`, `vmap`, and `grad`. Verified by integration tests in `tests/integration/`
+- **Custom differentiation**: Use `jax.custom_vjp` for boundary corrections, `jax.custom_jvp` for numerical stability. Prefer implicit differentiation via `optimistix` for root-finding operations
+- **Runtime type checking**: `jaxtyping` + `beartype` are enabled during tests via pytest hook
+
+## Scope Boundaries
+
+Implemented:
+
+- 8 primitives: Disk (2D), Sphere, Cylinder, Plane, Cone, Torus, Box, FiniteCylinder
+- Union, intersection, and subtract Boolean operations via Method (A) smoothing and Method (C) stratum-aware
+- Stratum-dispatched gradients: analytical exact in 3/4 strata for bounded pairs
+- Hybrid optimizer API skeleton in `experimental/optimizers/`
+- Mold direction optimizer demonstrator in `experimental/applications/`
+- 2D Disk analytical ground truth + 3D Sphere analytical ground truth
+- 7 example notebooks, 13 ADRs
+
+Not yet in scope (defer to future work):
+
+- Method (B) TOI correction implementation (deferred to hybrid optimizer context, ADR-0009)
+- STEP file read / analytical primitive conversion
+- Topology data structures (half-edge mesh)
+- Persistent homology integration
+- B-Rep bridge layer (OCP-to-JAX conversion)
+- C++ extensions
+
+If scope expansion is needed, add an ADR documenting the decision. Do not expand scope without explicit approval.
+
+## Things to Avoid
+
+- **No C++ extensions** until benchmarks show a specific bottleneck (pure JAX for now)
+- **No code copying** from existing OSS (JAX-FEM, Manifold, etc.) -- reference only
+- **No private API exposure** -- `_internal/` must never be imported from public modules
+- **No dynamic shapes** without explicit justification -- use padding strategies instead
+- **No backward compatibility code** -- this project is in alpha; prefer clean breaks
+- **OCCT dependency is core identity** -- do not propose removing cadquery-ocp-novtk; changes to OCCT strategy require an ADR
+- **No direct OCP imports** outside `brepax/_occt/` -- all OCCT access goes through `brepax._occt.backend` (see ADR-0008)
+
+## Development Philosophy
+
+- **Understand before changing**: Read existing code and docs before modifying anything.
+- **Research first**: Investigate modern best practices before implementing non-trivial decisions.
+- **No over-abstraction**: Three similar lines are better than a premature abstraction.
+- **No hardcoding**: Magic numbers and defaults must be defined in constants or configuration.
+
+## Code Quality Checks (mandatory before EVERY commit and push)
+
+**NEVER commit or push without running ALL of these checks first.**
+A CI failure after push means the check was skipped locally. No exceptions.
+
+```bash
+uv run ruff format src/ tests/
+uv run ruff check src/ tests/ --fix
+uv run mypy src/
+uv run pytest -m "not slow"
+```
+
+All four must pass with zero errors before `git commit`. If any fails, fix it before committing.
+Do not rely on CI to catch errors -- CI is a safety net, not the primary gate.
+
+## Reference Materials
+
+- JAX documentation: https://docs.jax.dev
+- Equinox documentation: https://docs.kidger.site/equinox
+- jaxtyping documentation: https://docs.kidger.site/jaxtyping
+- Diataxis framework: https://diataxis.fr
+- ADR pattern: https://github.com/joelparkerhenderson/architecture-decision-record