fix(solver): use world-anchored reference normal in PlanarConstraint distance residual

PlanarConstraint's point-in-plane residual used a body-attached normal
(z_j) that rotates with body_j. When combined with CylindricalConstraint,
which allows rotation about the shared axis, the plane normal tilts
during Newton iteration. This allows the body to drift along the cylinder
axis while technically satisfying the rotated distance residual.

Fix: snapshot the world-frame normal at system-build time (as Const
nodes) and use it in the distance residual. The cross-product residuals
still use body-attached normals to enforce parallelism. Only the
distance residual needs the fixed reference direction.

Works for any offset value: (p_i - p_j) · z_ref - offset = 0.

.gitea/workflows/ci.yaml

@@ -1,65 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-
-      - name: Install dependencies
-        run: |
-          pip install ruff mypy
-          pip install -e ".[dev]" || pip install ruff mypy numpy
-
-      - name: Ruff check
-        run: ruff check solver/ freecad/ tests/ scripts/
-
-      - name: Ruff format check
-        run: ruff format --check solver/ freecad/ tests/ scripts/
-
-  type-check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-
-      - name: Install dependencies
-        run: |
-          pip install mypy numpy
-          pip install torch --index-url https://download.pytorch.org/whl/cpu
-          pip install torch-geometric
-          pip install -e ".[dev]"
-
-      - name: Mypy
-        run: mypy solver/ freecad/
-
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-
-      - name: Install dependencies
-        run: |
-          pip install torch --index-url https://download.pytorch.org/whl/cpu
-          pip install torch-geometric
-          pip install -e ".[train,dev]"
-
-      - name: Run tests
-        run: pytest tests/ freecad/tests/ -v --tb=short

GNN/.gitea/workflows/ci.yaml

@@ -0,0 +1,209 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      run_datagen:
+        description: "Run dataset generation"
+        required: false
+        type: boolean
+        default: false
+      num_assemblies:
+        description: "Number of assemblies to generate"
+        required: false
+        type: string
+        default: "100000"
+      num_workers:
+        description: "Parallel workers for datagen"
+        required: false
+        type: string
+        default: "4"
+
+env:
+  PIP_CACHE_DIR: /tmp/pip-cache-solver
+  TORCH_INDEX: https://download.pytorch.org/whl/cpu
+  VIRTUAL_ENV: /tmp/solver-venv
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # Lint — fast, no torch required
+  # ---------------------------------------------------------------------------
+  lint:
+    runs-on: ubuntu-latest
+    env:
+      PATH: /tmp/solver-venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+    steps:
+      - name: Trust internal CA
+        run: |
+          curl -sk https://ipa.kindred.internal/ipa/config/ca.crt \
+            -o /usr/local/share/ca-certificates/kindred-internal.crt
+          update-ca-certificates
+
+      - name: Checkout
+        uses: https://github.com/actions/checkout@v4
+
+      - name: Set up venv
+        run: python3 -m venv $VIRTUAL_ENV
+
+      - name: Install lint tools
+        run: pip install --cache-dir $PIP_CACHE_DIR ruff
+
+      - name: Ruff check
+        run: ruff check solver/ freecad/ tests/ scripts/
+
+      - name: Ruff format check
+        run: ruff format --check solver/ freecad/ tests/ scripts/
+
+  # ---------------------------------------------------------------------------
+  # Type check
+  # ---------------------------------------------------------------------------
+  type-check:
+    runs-on: ubuntu-latest
+    env:
+      PATH: /tmp/solver-venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+    steps:
+      - name: Trust internal CA
+        run: |
+          curl -sk https://ipa.kindred.internal/ipa/config/ca.crt \
+            -o /usr/local/share/ca-certificates/kindred-internal.crt
+          update-ca-certificates
+
+      - name: Checkout
+        uses: https://github.com/actions/checkout@v4
+
+      - name: Set up venv
+        run: python3 -m venv $VIRTUAL_ENV
+
+      - name: Install dependencies
+        run: |
+          pip install --cache-dir $PIP_CACHE_DIR \
+            mypy numpy scipy \
+            torch --index-url $TORCH_INDEX
+          pip install --cache-dir $PIP_CACHE_DIR torch-geometric
+          pip install --cache-dir $PIP_CACHE_DIR -e ".[dev]"
+
+      - name: Mypy
+        run: mypy solver/ freecad/
+
+  # ---------------------------------------------------------------------------
+  # Tests
+  # ---------------------------------------------------------------------------
+  test:
+    runs-on: ubuntu-latest
+    env:
+      PATH: /tmp/solver-venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+    steps:
+      - name: Trust internal CA
+        run: |
+          curl -sk https://ipa.kindred.internal/ipa/config/ca.crt \
+            -o /usr/local/share/ca-certificates/kindred-internal.crt
+          update-ca-certificates
+
+      - name: Checkout
+        uses: https://github.com/actions/checkout@v4
+
+      - name: Set up venv
+        run: python3 -m venv $VIRTUAL_ENV
+
+      - name: Install dependencies
+        run: |
+          pip install --cache-dir $PIP_CACHE_DIR \
+            torch --index-url $TORCH_INDEX
+          pip install --cache-dir $PIP_CACHE_DIR torch-geometric
+          pip install --cache-dir $PIP_CACHE_DIR -e ".[train,dev]"
+
+      - name: Run tests
+        run: pytest tests/ freecad/tests/ -v --tb=short
+
+  # ---------------------------------------------------------------------------
+  # Dataset generation — manual trigger or on main push
+  # ---------------------------------------------------------------------------
+  datagen:
+    runs-on: ubuntu-latest
+    if: >-
+      (github.event_name == 'workflow_dispatch' && inputs.run_datagen == true) ||
+      (github.event_name == 'push' && github.ref == 'refs/heads/main')
+    needs: [test]
+    env:
+      PATH: /tmp/solver-venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+    steps:
+      - name: Trust internal CA
+        run: |
+          curl -sk https://ipa.kindred.internal/ipa/config/ca.crt \
+            -o /usr/local/share/ca-certificates/kindred-internal.crt
+          update-ca-certificates
+
+      - name: Checkout
+        uses: https://github.com/actions/checkout@v4
+
+      - name: Set up venv
+        run: python3 -m venv $VIRTUAL_ENV
+
+      - name: Install dependencies
+        run: |
+          pip install --cache-dir $PIP_CACHE_DIR \
+            torch --index-url $TORCH_INDEX
+          pip install --cache-dir $PIP_CACHE_DIR torch-geometric
+          pip install --cache-dir $PIP_CACHE_DIR -e ".[train]"
+
+      - name: Restore datagen checkpoint
+        id: datagen-cache
+        uses: https://github.com/actions/cache/restore@v4
+        with:
+          path: data/synthetic
+          key: datagen-${{ github.sha }}
+          restore-keys: |
+            datagen-
+
+      - name: Generate dataset
+        run: |
+          NUM=${INPUTS_NUM_ASSEMBLIES:-100000}
+          WORKERS=${INPUTS_NUM_WORKERS:-4}
+          echo "Generating ${NUM} assemblies with ${WORKERS} workers"
+          python3 scripts/generate_synthetic.py \
+            --num-assemblies "${NUM}" \
+            --num-workers "${WORKERS}" \
+            --output-dir data/synthetic
+        env:
+          INPUTS_NUM_ASSEMBLIES: ${{ inputs.num_assemblies }}
+          INPUTS_NUM_WORKERS: ${{ inputs.num_workers }}
+
+      - name: Save datagen checkpoint
+        if: always()
+        uses: https://github.com/actions/cache/save@v4
+        with:
+          path: data/synthetic
+          key: datagen-${{ github.sha }}
+
+      - name: Upload dataset
+        uses: https://github.com/actions/upload-artifact@v3
+        with:
+          name: synthetic-dataset
+          path: |
+            data/synthetic/index.json
+            data/synthetic/stats.json
+            data/synthetic/shards/
+          retention-days: 90
+
+      - name: Print summary
+        if: always()
+        run: |
+          echo "=== Dataset Generation Results ==="
+          if [ -f data/synthetic/stats.json ]; then
+            python3 -c "
+          import json
+          with open('data/synthetic/stats.json') as f:
+              s = json.load(f)
+          print(f'Total examples: {s[\"total_examples\"]}')
+          print(f'Classification: {json.dumps(s[\"classification_distribution\"], indent=2)}')
+          print(f'Rigid: {s[\"rigidity\"][\"rigid_fraction\"]*100:.1f}%')
+          print(f'Degeneracy: {s[\"geometric_degeneracy\"][\"fraction_with_degeneracy\"]*100:.1f}%')
+          "
+          else
+            echo "stats.json not found — generation may have failed"
+            ls -la data/synthetic/ 2>/dev/null || echo "output dir missing"
+          fi