If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/zalo/MathUtilities shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 4 active contributors
• Unlicense licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 95% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live zalo/MathUtilities repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/zalo/MathUtilities.

What it runs against: a local clone of zalo/MathUtilities — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in zalo/MathUtilities | Confirms the artifact applies here, not a fork | | 2 | License is still Unlicense | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 653 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of zalo/MathUtilities. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/zalo/MathUtilities.git
#   cd MathUtilities
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of zalo/MathUtilities and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "zalo/MathUtilities(\\.git)?\\b" \\
  && ok "origin remote is zalo/MathUtilities" \\
  || miss "origin remote is not zalo/MathUtilities (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Unlicense)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Unlicense\"" package.json 2>/dev/null) \\
  && ok "license is Unlicense" \\
  || miss "license drift — was Unlicense at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Assets/Automatic Differentiation/DualNumber.cs" \\
  && ok "Assets/Automatic Differentiation/DualNumber.cs" \\
  || miss "missing critical file: Assets/Automatic Differentiation/DualNumber.cs"
test -f "Assets/Automatic Differentiation/Optimizer.cs" \\
  && ok "Assets/Automatic Differentiation/Optimizer.cs" \\
  || miss "missing critical file: Assets/Automatic Differentiation/Optimizer.cs"
test -f "Assets/Amoeba/NelderMead.cs" \\
  && ok "Assets/Amoeba/NelderMead.cs" \\
  || miss "missing critical file: Assets/Amoeba/NelderMead.cs"
test -f "Assets/Bezier/Bezier.cs" \\
  && ok "Assets/Bezier/Bezier.cs" \\
  || miss "missing critical file: Assets/Bezier/Bezier.cs"
test -f "Assets/BSP/BSP.cs" \\
  && ok "Assets/BSP/BSP.cs" \\
  || miss "missing critical file: Assets/BSP/BSP.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 653 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~623d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/zalo/MathUtilities"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

MathUtilities is a Unity C# library collecting optimized algorithms for mesh deformation, inverse kinematics, numerical optimization, and geometric computation. It provides production-grade implementations of techniques like Kabsch algorithm (rigid alignment), Nelder-Mead simplex optimization, automatic differentiation for IK solving, and signed distance field rendering—enabling game developers and graphics programmers to solve complex spatial and physics problems efficiently. Flat monorepo structure under Assets/ with feature-scoped folders: Assets/Deform/, Assets/Kabsch/, Assets/Amoeba/ (Nelder-Mead), Assets/Automatic Differentiation/, Assets/Assignment/ (LAP solver), etc. Each feature folder contains one or more C# algorithm implementations, companion .unity scene files for interactive demos, and example usage scripts. No separation of core library vs. examples—everything lives in Assets/.

Game developers and graphics programmers using Unity who need to solve IK chains, deform meshes, fit geometric primitives to point clouds, or perform numerical optimization without implementing these algorithms from scratch. Particularly valuable for character animation, procedural modeling, and physics simulation workflows.

Actively maintained with substantial code depth (415KB C#, organized into 8+ feature modules with example scenes). Contains complete working implementations with .unity scene files demonstrating each technique. No obvious CI/test infrastructure visible, and appears to be a personal engineering notebook rather than a formal library release, but code quality suggests production-ready individual components.

Single-maintainer project with no formal versioning, dependency management, or test suite visible. No CI pipeline evident. Risk of breaking changes if the author refactors core algorithms. However, the monolithic nature (no external dependencies beyond Unity itself) minimizes integration risk. Code appears battle-tested in real projects given the breadth of non-trivial algorithms.

No commit history or PR data visible in provided metadata. The README describes implemented features (Kabsch, mesh deformation, SDF rendering, least squares fitting, IK solvers via Nelder-Mead and autodiff) as completed work. Project appears to be a mature collection rather than one under active development iteration.

Clone the repo: git clone https://github.com/zalo/MathUtilities.git. Open the project in Unity (2019+ recommended based on C# version). Navigate to any Assets/*/folder and open the corresponding .unity scene file to see interactive demos (e.g., Assets/Kabsch/Kabsch.unity, Assets/Deform/MeshDeformation.unity).

Daily commands: Open the project in Unity Editor. For any feature module (e.g., Assets/Kabsch/, Assets/Amoeba/), double-click the .unity scene to load it. Use the Editor Play button to visualize the algorithm. Examples include NelderMeadExample.cs, AutoDiffIK.cs, and AccelerationDamping.cs which can be attached to GameObjects to drive interactive visualizations.

• Assets/Automatic Differentiation/DualNumber.cs — Core dual number implementation enabling automatic differentiation; foundational for all optimization and IK systems in the codebase.
• Assets/Automatic Differentiation/Optimizer.cs — Primary optimization engine used across AutoDiffIK, AutoDiffFitting, and AutoDiffTransform modules; every optimization workflow depends on this.
• Assets/Amoeba/NelderMead.cs — Alternative optimization algorithm (Nelder-Mead simplex); critical for gradient-free IK solutions and numerical optimization fallback paths.
• Assets/Bezier/Bezier.cs — Foundational bezier curve implementation used across multiple demo scenes and deformation algorithms.
• Assets/BSP/BSP.cs — Binary space partition tree implementation; demonstrates spatial data structure patterns used in mesh operations and collision detection.
• Assets/Assignment/LAP.cs — Linear Assignment Problem solver; demonstrates combinatorial optimization techniques applicable to IK and matching problems.
• Assets/Automatic Differentiation/Math.cs — Extended math library providing dual number arithmetic operations; required by all AutoDiff modules.

Add a new inverse kinematics solver variant

1. Choose base optimization approach: create new file in Assets/Automatic Differentiation/AutoDiffIK/ for autodiff-based, or Assets/Amoeba/ for Nelder-Mead based. (Assets/Automatic Differentiation/AutoDiffIK/AutoDiffIK.cs or Assets/Amoeba/NelderMeadIK.cs)
2. Implement objective function computing distance from end effector to target using either DualVector3 (autodiff) or float (numerical). (Your new IK solver file)
3. Call Optimizer.Optimize() with your objective, or NelderMead.Optimize() for gradient-free approach. (Assets/Automatic Differentiation/Optimizer.cs or Assets/Amoeba/NelderMead.cs)
4. Create a Unity scene in Assets/[YourName]/ with example solver applied to a chain of transforms. (Assets/[YourName]/[YourName].unity)

Add a new curve or spline type

1. Create new file in Assets/Bezier/ extending from or alongside Bezier.cs and CubicBezier.cs patterns. (Assets/Bezier/YourCurve.cs)
2. Implement Evaluate(t) for point interpolation and optionally EvaluateDerivative(t) for tangent/curvature. (Assets/Bezier/YourCurve.cs)
3. If fitting curve to data, integrate with AutoDiffFitting by adding objective function using DualVector3. (Assets/Automatic Differentiation/AutoDiffFitting/AutoDiffFitting.cs)
4. Create demo scene in Assets/Bezier/YourCurve.unity visualizing control points and evaluated path. (Assets/Bezier/YourCurve.unity)

Add a spatial query optimization using existing data structures

1. Identify if BSP.cs (spatial partitioning) or BoundingSphere.cs (hierarchy) suits your query pattern. (Assets/BSP/BSP.cs or Assets/BSH/BoundingSphere.cs)
2. Build tree from your point/mesh data using the public Build() or constructor methods. (Your integration code)
3. Query the tree using provided methods (e.g., FindNearest, IsInside, RayIntersection depending on structure). (Your query code)
4. Write unit tests following LAPTest.cs or BSPTest.cs patterns. (Assets/[Feature]/[Feature]Test.cs)

Add automatic differentiation support to a new operation

1. Extend Math.cs to implement your operation for DualNumber, ensuring chain rule via dual parts. (Assets/Automatic Differentiation/Math.cs)
2. If vector/matrix operation, add overload to DualVector3.cs or DualMatrix4x3.cs respectively. (Assets/Automatic Differentiation/DualVector3.cs or DualMatrix4x3.cs)
3. Test derivative correctness by comparing autodiff gradient against numerical gradient in a demo scene. (Assets/Automatic Differentiation/[Feature]/[Feature].unity)
4. Use new operation in Optimizer.cs objective functions or custom optimization loops. (Assets/Automatic Differentiation/Optimizer.cs)

• Dual Numbers & Automatic Differentiation — Enables exact gradient computation without numerical approximation; critical for robust IK and optimization with arbitrary constraints.
• Unity C# — Primary target runtime; provides Transform hierarchy, scene graph, and immediate visualization of algorithm results.
• Nelder-Mead — undefined

No .gitignore patterns or environment variable documentation visible. Assumes Unity Editor is available (not usable from CLI). Scene files (.unity) are binary and prone to merge conflicts in team environments. Some shader files (ShaderLab/GLSL) may require specific GPU feature levels; no fallback path documented. No version constraints or target Unity version explicitly stated—assumes recent Unity 2019+. Numerical algorithms (Nelder-Mead, autodiff) have no tunable convergence thresholds documented; you must inspect source code to adjust epsilon values.

• Kabsch Algorithm (Procrustes Analysis) — Core technique in this repo for finding optimal rigid transformations (rotation + translation) between point sets; used in IK, mesh alignment, and animation retargeting
• Polar Decomposition — MathUtilities avoids expensive SVD by using Matthias Muller's polar decomposition to extract rotation from deformation matrices; critical optimization for real-time applications
• Inverse Distance Weighting (IDW) — Fundamental interpolation method used in mesh deformation to automatically compute skinning weights; enables smooth blending of multiple control points without manual rigging
• Nelder-Mead Simplex Optimization — Gradient-free numerical optimization algorithm implemented in Assets/Amoeba/; used for IK solving when gradient computation is infeasible
• Automatic Differentiation (Autodiff) — Enables gradient-based optimization for IK and curve fitting without manually coding derivatives; implemented via forward/reverse mode chain rule in AutoDiffTransform.cs
• Signed Distance Fields (SDF) — Implicit surface representation storing distance to nearest geometry; enables efficient volumetric rendering, collision detection, and physics queries as demonstrated in Assets/Volume/
• Hungarian Algorithm (Linear Assignment Problem) — Optimal bipartite matching solver in Assets/Assignment/LAP.cs; used for correspondence problems in point cloud registration and skeletal animation retargeting
• Orthogonal Regression (Least Squares Fitting) — Matrix-free method for fitting lines and planes to point clouds using only linear algebra; more numerically stable than SVD-based approaches as implemented in LeastSquaresFitting.cs

• g-truc/glm — C++ math library for graphics; equivalent low-level vector/matrix utilities that MathUtilities builds upon for more specialized algorithms
• keijiro/Kukulkan — Unity library for procedural mesh deformation using GPU compute; complementary approach to MathUtilities' CPU-side mesh deformation
• aras-p/UnityGaussianSplatting — Another Unity graphics/math exploration repo demonstrating advanced numerical techniques in the same ecosystem
• jcalabrese/DexterousHand — Unity IK solver for complex articulated systems; practical use case for algorithms from MathUtilities (Kabsch, Nelder-Mead)
• laurentlb/Shader-Minifier — Tool for optimizing ShaderLab/GLSL; relevant since MathUtilities includes volumetric rendering shaders that could be minified for production

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for NelderMead.cs optimization algorithm

NelderMead.cs (Assets/Amoeba/NelderMead.cs) is a complex numerical optimization algorithm with multiple example implementations (NelderMeadExample.cs, NelderMeadIK.cs) but no automated tests. A test suite would validate convergence behavior, edge cases (degenerate simplices, singular matrices), and numerical stability across different problem dimensions.

• [ ] Create Assets/Amoeba/Tests/NelderMeadTests.cs
• [ ] Add convergence tests for standard optimization benchmarks (Rosenbrock, Sphere function)
• [ ] Add edge case tests: singular matrices, NaN/Infinity handling
• [ ] Add regression tests comparing NelderMead vs NumericalGradientDescent.cs on IK problems
• [ ] Configure test runner in project settings if not already present

Add comprehensive documentation for DualNumber.cs automatic differentiation system

The Automatic Differentiation module (DualNumber.cs, DualVector3.cs, DualMatrix4x3.cs, Math.cs) implements forward-mode AD but lacks usage documentation. Three different IK solvers depend on this, but there's no guide explaining dual number semantics, limitations, or numerical accuracy guarantees.

• [ ] Create Assets/Automatic Differentiation/README.md documenting dual number theory and usage
• [ ] Add code examples in README showing: basic dual operations, gradient computation, and IK solver integration
• [ ] Document numerical precision characteristics (epsilon values, accuracy vs analytical gradients)
• [ ] Add comparison table: DualNumber vs NumericalGradientDescent.cs performance/accuracy tradeoffs
• [ ] Reference the LICENSE file and attribute sources

Create integration tests for IK solvers across different algorithms

The repo contains multiple IK implementations (AmoebaIK, GradientIK, AutoDiffIK, NelderMeadIK) but no comparative integration tests. Adding tests would verify they produce equivalent results on standard IK benchmarks and catch regressions when core algorithms (NelderMead.cs, Optimizer.cs) change.

• [ ] Create Assets/Amoeba/Tests/IKSolverComparisonTests.cs
• [ ] Implement standard IK test scenarios: 2-link arm reaching, 3-link chain, constrained targets
• [ ] Add assertions comparing solution quality across AmoebaIK.cs, NumericalGradientDescentIK.cs, NelderMeadIK.cs, AutoDiffIK.cs
• [ ] Measure convergence speed and final error for each solver
• [ ] Document performance characteristics in test output or separate benchmark file

• Add unit test suite for Assets/Kabsch/Kabsch.cs covering edge cases: collinear points, identical point sets, inverted point clouds. Currently only demonstrated in .unity scenes; no automated test coverage.
• Document the convergence criteria and tunable parameters for Assets/Amoeba/NelderMead.cs (simplex size, tolerance threshold, max iterations) with code comments and a parameter tuning guide in the scene examples.
• Extend Assets/LeastSquares/LeastSquaresFitting.cs with 2D line fitting and add a .unity demo scene (LeastSquaresFitting.unity) showing interactive point cloud fitting like the GIF in the README—currently only .cs file exists without a demo.

This repository contains a collection of math and physics utility code for Unity/C#. Security analysis reveals a minimal attack surface for several reasons: (1) It is a library/utility codebase without network I/O, database interactions, or user input handling; (2) No external dependencies are declared (empty package file); (3) No hardcoded credentials or secrets are present in the file structure; (4) No injection vectors (SQL, XSS) exist in a math/physics utility library; (5) No Docker or infrastructure misconfiguration present. The codebase appears to be well-scoped and focused. Minor recommendations include adding root-level licensing documentation and a security policy for vulnerability reporting. Overall security posture is strong for this type of utility library.

• Low · No LICENSE file in root directory — Repository root. While a LICENSE file exists in Assets/Automatic Differentiation/, there is no LICENSE file in the repository root. This could create ambiguity about the licensing terms for the entire project. Fix: Add a LICENSE file to the repository root that clearly specifies the licensing terms for the entire project.
• Low · Missing security policy documentation — Repository root. There is no SECURITY.md or security policy file visible in the repository structure. This makes it unclear how security vulnerabilities should be reported. Fix: Create a SECURITY.md file that outlines the process for reporting security vulnerabilities responsibly.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.