Return named structs from the normalization functions

[zfergus]

Description

normalization_and_jacobian and normalization_and_jacobian_and_hessian returned std::tuple, so callers had to remember that element 1 was the Jacobian and reach for std::get<1> to pull it out. They now return named aggregates.

• NormalizationAndJacobian<T, dim, max_dim> — .normalized, .jacobian
• NormalizationAndJacobianAndHessian<T, dim, max_dim> — the above plus .hessian
• Both are templated on max_dim so the fixed-size (Eigen::Vector<T, dim>) and dynamic (VectorMax3<T>) return paths are one type rather than two unrelated tuple spellings.

The accessor helpers read directly off the field now — normalization_jacobian returns ...(x).jacobian instead of std::get<1>(...), and normalization_hessian returns .hessian instead of std::get<2>(...).

API changes

• The three in-tree call sites (math.cpp, smooth_contact/primitives/point3.cpp, edge3.cpp) and test_barrier.cpp are unchanged: the structs are aggregates, so existing const auto [xhat, J] = ... structured bindings keep working as-is.
• normalization_jacobian and normalization_hessian are unchanged in signature and behavior.
• Python is unaffected. The bindings now convert to a tuple explicitly, so ipctk.normalization_and_jacobian and ipctk.normalization_and_jacobian_and_hessian return exactly what they returned before.

💥 Breaking changes

C++ callers that name std::tuple explicitly, or use std::get<N>, must move to the .normalized / .jacobian / .hessian members. Structured-binding callers need no change. There is no deprecation path — the return type changes outright.

How Has This Been Tested?

• [normal] [barrier] [angle] — 24 test cases, 16,790 assertions, all passing. Includes the autodiff cross-check in test_barrier.cpp, which compares the returned Jacobian and Hessian against ADHessian<3> derivatives.
• ipc_toolkit, ipc_toolkit_tests, and ipctk all build clean.
• Python round-trip against the built module: both functions unpack as tuples, and normalization_jacobian / normalization_hessian return the same shapes as before.

Test Configuration:

• OS and Version: macOS 26.6 (arm64)
• Compiler and Version: AppleClang 21.0, CMAKE_BUILD_TYPE=Release, IPC_TOOLKIT_BUILD_TESTS=ON, IPC_TOOLKIT_WITH_CUDA=OFF

Checklist

• I have followed the project style guide
• My code follows the clang-format style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.70%. Comparing base (b778f64) to head (5c4f16f).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #253   +/-   ##
=======================================
  Coverage   96.70%   96.70%           
=======================================
  Files         191      191           
  Lines       17292    17292           
  Branches      928      928           
=======================================
  Hits        16722    16722           
  Misses        570      570           

Flag	Coverage Δ
unittests	96.70% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.