OpenMagneticsVirtualBuilder 1.0.0__tar.gz

openmagneticsvirtualbuilder-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,163 @@
+name: Build and publish the Python package
+
+# Builds the ONE Python package of MVB++ (PyPI: OpenMagneticsVirtualBuilder, module `mvbpp`)
+# for Linux, Windows and macOS, and publishes it.
+#   - a pushed tag vX.Y.Z -> PyPI (the tag must equal pyproject's version)
+#   - workflow_dispatch   -> TestPyPI, unless publish_to_pypi is ticked
+# Needs the secrets PYPI_API_TOKEN / TEST_PYPI_API_TOKEN, scoped to OpenMagneticsVirtualBuilder.
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+    inputs:
+      publish_to_pypi:
+        description: 'Publish to the real PyPI instead of TestPyPI'
+        required: false
+        default: false
+        type: boolean
+      os:
+        description: 'Build wheels only on this runner (to re-test one platform without paying for the others)'
+        required: false
+        default: 'all'
+        type: choice
+        options: [all, ubuntu-22.04, windows-2022, macos-15]
+
+env:
+  GIT_LFS_SKIP_SMUDGE: 1
+  OCCT_CACHE_KEY: occt-7.9.3-static-v1
+
+jobs:
+  check_version:
+    name: Tag matches pyproject version
+    runs-on: ubuntu-22.04
+    if: github.event_name != 'workflow_dispatch'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5   # tomllib needs Python >= 3.11; the runner's system Python is 3.10
+        with:
+          python-version: '3.12'
+      - name: Compare
+        shell: bash
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          ver=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$tag" != "$ver" ]; then
+            echo "::error::tag v$tag does not match pyproject version $ver"; exit 1
+          fi
+
+  # One job per OS builds every CPython version in turn, so OCCT (~20+ min) is built once per job
+  # and reused by every version (CMake reuses a complete OCCT install). On Windows and macOS the install is also
+  # cached across runs; on Linux it lives inside the manylinux container, which cibuildwheel does
+  # not copy back to the runner, so Linux builds it once per run.
+  build_wheels:
+    name: Wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 360
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ${{ fromJSON((github.event_name == 'workflow_dispatch' && inputs.os != 'all') && format('["{0}"]', inputs.os) || '["ubuntu-22.04","windows-2022","macos-15"]') }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Free disk space (Linux)
+        if: runner.os == 'Linux'
+        run: sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc /opt/hostedtoolcache/CodeQL
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      # MKF fetches Kirchhoff, whose PSMA submodules (RAS, SAS, TAS, AAS, ...) have SSH URLs; the
+      # runners have no SSH key, so clone them over HTTPS. (The Linux container sets the same
+      # rewrite in its before-all, since it does not see the runner's git config.)
+      - name: Clone GitHub submodules over HTTPS
+        shell: bash
+        run: git config --global url."https://github.com/".insteadOf "git@github.com:"
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      # Restore and save are separate steps so a built OCCT is saved even when a later step fails
+      # (actions/cache saves only on job success, so every failed Windows job rebuilt OCCT, ~40 min).
+      - name: Restore OCCT install
+        id: occt_cache
+        if: runner.os != 'Linux'
+        uses: actions/cache/restore@v4
+        with:
+          path: .occt-install
+          key: ${{ env.OCCT_CACHE_KEY }}-${{ runner.os }}
+
+      - name: Point the build at the OCCT install
+        shell: bash
+        run: |
+          ws=$(python -c "import os;print(os.environ['GITHUB_WORKSPACE'].replace('\\\\','/'))")
+          echo "CIBW_ENVIRONMENT_LINUX=CMAKE_BUILD_PARALLEL_LEVEL=2 SKBUILD_CMAKE_DEFINE=\"OCCT_PREFIX=/opt/occt-install\"" >> "$GITHUB_ENV"
+          echo "CIBW_ENVIRONMENT_MACOS=MACOSX_DEPLOYMENT_TARGET=14.0 CMAKE_BUILD_PARALLEL_LEVEL=3 SKBUILD_CMAKE_DEFINE=\"OCCT_PREFIX=$ws/.occt-install\"" >> "$GITHUB_ENV"
+          echo "CIBW_ENVIRONMENT_WINDOWS=CMAKE_BUILD_PARALLEL_LEVEL=1 SKBUILD_CMAKE_DEFINE=\"OCCT_PREFIX=$ws/.occt-install\"" >> "$GITHUB_ENV"
+
+      - name: Build and test wheels
+        run: |
+          python -m pip install cibuildwheel==4.2.0
+          python -m cibuildwheel --output-dir wheelhouse
+
+      - name: Save OCCT install
+        # Only a complete install (the last toolkit in OCCT_ESSENTIAL_LIBS present), only on a cache miss.
+        if: always() && runner.os != 'Linux' && steps.occt_cache.outputs.cache-hit != 'true' && hashFiles('.occt-install/lib/*TKDEVRML*') != ''
+        uses: actions/cache/save@v4
+        with:
+          path: .occt-install
+          key: ${{ env.OCCT_CACHE_KEY }}-${{ runner.os }}
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  build_sdist:
+    name: Source distribution
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: |
+          python -m pip install build
+          python -m build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    name: Publish
+    needs: [check_version, build_wheels, build_sdist]
+    # check_version is skipped on workflow_dispatch; a skipped need still lets this run.
+    # A single-platform manual run never publishes: the release must carry every wheel.
+    if: always() && needs.build_wheels.result == 'success' && needs.build_sdist.result == 'success' && needs.check_version.result != 'failure' && (github.event_name != 'workflow_dispatch' || inputs.os == 'all')
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        if: github.event_name != 'workflow_dispatch' || inputs.publish_to_pypi
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip-existing: true
+          packages-dir: dist/
+
+      - name: Publish to TestPyPI
+        if: github.event_name == 'workflow_dispatch' && !inputs.publish_to_pypi
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+          skip-existing: true
+          packages-dir: dist/

openmagneticsvirtualbuilder-1.0.0/.gitignore

@@ -0,0 +1,40 @@
+# Build outputs
+build/
+Testing/
+
+# Tool/editor caches
+.cache/
+.claude/
+
+# Generated artifacts
+mas_example_steps/
+mas_example_steps_py/
+bobbin_comparison/
+*.step
+*.stl
+*.svg
+*.png
+# ...but keep the test reference fixtures
+!tests/reference_steps/
+!tests/reference_steps/*
+
+# Local broken dir from an accidental `mkdir --help`
+--help/
+
+# External symlink (MVB's testData)
+/testData
+
+# Misc
+gmon.out
+
+__pycache__/
+*.pyc
+
+# Generated geometry galleries / demo renders (STEP+PNG+SVG, ~100 MB) -- outputs, not sources.
+mas_step_gallery/
+real_winding_demo/
+
+# Python wheel build trees (pyproject build-dir)
+build_python/
+.occt-install/
+wheelhouse/

openmagneticsvirtualbuilder-1.0.0/AGENTS.md

@@ -0,0 +1,148 @@
+# AGENTS.md — MVB++
+
+## What this is
+
+C++23 library that builds 3D magnetic component geometry (cores, bobbins, turns) from MAS JSON using OpenCASCADE 7.9.3. Produces STEP/STL files and SVG dimensioned drawings. Has Python (pybind11) and WASM (Emscripten) bindings.
+
+## Build
+
+```bash
+# Configure (fetches OCCT, MKF, MAS, nlohmann/json, Catch2 automatically)
+cmake -S . -B build -GNinja -DCMAKE_BUILD_TYPE=Release
+
+# Build library
+cmake --build build --target mvb++ -j$(nproc)
+
+# Build and run tests
+cmake --build build --target mvb_tests -j$(nproc)
+cd build && LD_LIBRARY_PATH=$PWD/occt-install/lib:$LD_LIBRARY_PATH ./mvb_tests
+
+# Run specific test tags
+./mvb_tests "[step][e]"           # E core STEP comparison
+./mvb_tests "[assembly][json]"    # Full assembly tests
+./mvb_tests "[symmetry]"          # Symmetry analysis (can be slow)
+./mvb_tests "[all_shapes]"        # All MAS core shapes
+```
+
+First build takes ~10min (OCCT builds from source). Subsequent builds are fast.
+
+### Python bindings
+
+```bash
+pip install -e .                    # scikit-build-core + pybind11
+pytest bindings/python/tests/ -v   # requires installed mvbpp wheel
+```
+
+### WASM bindings
+
+```bash
+cd bindings/wasm
+npm run build   # requires emsdk (source ~/emsdk/emsdk_env.sh)
+npm test
+```
+
+## Architecture
+
+```
+include/mvb/          Public headers (MagneticBuilder, Utils, Symmetry, StepExporter, etc.)
+src/                  Library implementation
+src/shapes/           One builder per core shape family (ShapeE, ShapeT, ShapeEr, etc.)
+tests/                Catch2 tests + reference STEPs
+tools/                CLI utilities (step_generator, section, bobbin_generator)
+bindings/python/      pybind11 Python module
+bindings/wasm/        Emscripten WASM module
+testData/             JSON test fixtures (MAS format)
+```
+
+Key types:
+- `mvb::MagneticBuilder` — main entry point, builds core/bobbin/turns geometry
+- `mvb::NamedShape` — shape + string name (survives symmetry cuts, STEP export)
+- `mvb::StepExporter` — STEP/STL export with mm scaling
+- `mvb::Symmetry` — symmetry plane detection and cutting
+- `MAS::Magnetic` — deserialized MAS JSON (generated from schema)
+- `OpenMagnetics::Magnetic` — MKF-enriched magnetic (has geometricalDescription)
+
+## Coordinate conventions
+
+- **Concentric cores** (E, T, U, etc.): profile in XY, extruded along Z, rotated -90° around X → column axis aligns with Y.
+- **Toroidal cores**: profile in XY, extruded along Z, origin at toroid center.
+- **Meters internally** — scale to mm only at STEP export (Python MVB exports in mm).
+
+## Dependencies
+
+All fetched via CMake FetchContent (no manual install needed):
+- **OCCT 7.9.3** — built from source as ExternalProject (static)
+- **MKF** — `OpenMagnetics::magnetic_autocomplete` enriches raw MAS JSON
+- **MAS** — auto-generated C++ types from JSON schema
+- **nlohmann/json v3.11.3**, **Catch2 v3.8.0**, **pybind11 v2.13.6**
+
+MKF has submodules (`cci_coords`, `CAS`, `EAS`) that are auto-initialized during CMake configure.
+
+## Code conventions
+
+- C++23 required (`std::numbers::pi`, `std::optional`, etc.)
+- `get_supported_families()` in `Utils.cpp` is implemented in `shapes/Factory.cpp` — derives from the factory switch, don't maintain a parallel list
+- OCCT boolean ops (`BRepAlgoAPI_Cut`, `BRepAlgoAPI_Fuse`) must check `IsDone()` before calling `.Shape()` — null shapes propagate silently
+- `MagneticBuilder::buildAllNamed(MAS::Magnetic)` skips MKF autocomplete when `geometricalDescription` is already present — use this for pre-enriched data
+- `DrawConfig` struct in `MagneticBuilder.h` is the unified config for all bindings — prefer it over positional parameters
+- `magnetic_autocomplete_safe` logs failures to `stderr` (not silent `catch(...)`) — check stderr when debugging enrichment issues
+
+## Gotchas
+
+### LD_LIBRARY_PATH required for tests
+OCCT builds both static and shared libs. The test binary links shared by default:
+```bash
+LD_LIBRARY_PATH=build/occt-install/lib:$LD_LIBRARY_PATH ./mvb_tests
+```
+
+### MAS schema enum casing (MAS 1.0)
+MAS 1.0 changed all enum values to camelCase/lowercase. If you see `"Input JSON does not conform to schema!"`, check:
+- `"two-piece set"` → `"twoPieceSet"` (CoreType)
+- `"Wound"` → `"wound"` (WiringTechnology)
+- `"inner or top"` → `"innerOrTop"` (CoilAlignment)
+- `"outer or bottom"` → `"outerOrBottom"` (CoilAlignment)
+
+Use `python3 MAS/scripts/migrate-to-1.0.py <file-or-dir>` to fix old JSON files.
+
+### MKF SHARED→STATIC patching
+CMakeLists.txt patches MKF's `add_library(MKF SHARED` → `STATIC` via string replace. If upstream MKF changes this string, the patch silently fails and you get link errors.
+
+### MKF submodules
+MKF needs `cci_coords`, `CAS`, `EAS` submodules. CMake auto-initializes them, but if you see `CAS.hpp: No such file or directory`, the submodule init failed. Run manually:
+```bash
+cd build/_deps/mkf-src && git submodule update --init cci_coords CAS EAS
+```
+
+### Symmetry/gapping tests can be slow
+Boolean operations on complex shapes (PQ3230, distributed gapping) can take >2min and may timeout. The gapping tests iterate ~461 shapes through MKF. Run separately:
+```bash
+./mvb_tests "[symmetry]"    # ~3min
+./mvb_tests "[gapping]"     # ~5min, iterates all MAS shapes
+./mvb_tests "[step]"        # fast, ~10s
+./mvb_tests "[stl]"         # fast, ~10s
+./mvb_tests "[assembly]"    # fast, ~30s
+```
+
+### WASM build/test
+```bash
+cd bindings/wasm && npm run build   # requires emsdk: source ~/emsdk/emsdk_env.sh
+node tests/test_mvbpp.js            # 27 tests, all pass
+```
+The embind surface is the `draw*` family: `drawMagnetic`, `drawCore`, `drawCorePiece`, `drawBobbin`, `drawTurns`, `drawWinding`, `drawSpacer`, `drawBoard`, `drawView`, plus `*ToPath` variants and the test helper `_enrichMagnetic`. All take the trailing 9-arg config pack `(mode, plane, offset, format, scale, polygonSegments, symmetry, side)` documented in `bindings/wasm/mvbpp_wasm.cpp`.
+Module-level switches (no arity change): `mvbppSetSkipChecks(bool)`, and `mvbppSetWeldMode("off"|"auto"|"all")` / `mvbppGetWeldMode()` -- how real-winding conductors are welded (`mvb::WeldMode`; C++: `DrawConfig::weld` or `MagneticBuilder::setWeldMode`).
+
+## Test data
+
+- `testData/` — MAS JSON fixtures for MVB++ tests
+- `tests/reference_steps/` — reference STEP/STL files for comparison tests
+- `MAS/examples/` — MAS example files (fetched via FetchContent)
+- `MAS/samples/` — MAS sample files (fetched via FetchContent)
+
+Test data must conform to MAS 1.0 schema. Run `python3 MAS/scripts/migrate-to-1.0.py testData/` after schema changes.
+
+## Current status
+
+- Core shapes, bobbin, turns, sections/projections, symmetry, spacers, FR4 all implemented
+- C++ tests: `[step]/[stl]/[assembly]/[shapes]/[json]/[topview]/[symmetry]/[gapping]` all pass; `[battery]` is slow (>15min) but functional
+- Python (pybind11) and WASM (Emscripten) bindings: all tests pass
+- See `PLAN.md` for detailed status and open performance/docs items