Skip to content

feat: Implement Birge-ratio auto-balance for cov2cov and prior weighting#62

Merged
jlblancoc merged 1 commit intodevelopfrom
feat/prior-weight-mitigations
May 2, 2026
Merged

feat: Implement Birge-ratio auto-balance for cov2cov and prior weighting#62
jlblancoc merged 1 commit intodevelopfrom
feat/prior-weight-mitigations

Conversation

@jlblancoc
Copy link
Copy Markdown
Member

@jlblancoc jlblancoc commented May 2, 2026

Summary by CodeRabbit

Release Notes

  • New Features

    • Added two configuration options for tuning covariance-to-covariance contribution weighting in point cloud registration: a scaling factor to adjust influence magnitude, and automatic prior-based balancing for improved optimization stability.
  • Tests

    • Added comprehensive test suite validating covariance-to-covariance optimization behavior with and without prior handling.

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 2, 2026

📝 Walkthrough

Walkthrough

The PR introduces automatic Birge-ratio-style balancing of cov-to-cov residual contributions in the Gauss-Newton optimizer. Two new configuration parameters (cov2cov_alpha and cov2cov_auto_balance_with_prior) control tempering and optional prior-based scaling. The cov-to-cov block computation is refactored to use intermediate accumulators before scaled integration into the global system.

Changes

Cov-to-Cov Scaling and Prior Balancing

Layer / File(s) Summary
Data Shape
mp2p_icp/include/mp2p_icp/optimal_tf_gauss_newton.h
OptimalTF_GN_Parameters adds double cov2cov_alpha = 1.0 and bool cov2cov_auto_balance_with_prior = true to control tempering and Birge-ratio-style auto-balancing of the cov-to-cov contribution.
Core Scaling Logic
mp2p_icp/src/optimal_tf_gauss_newton.cpp
Cov-to-cov computation is separated into intermediate accumulators (H_cc, g_cc, chi2_cc) in both TBB and non-TBB paths. After accumulation, a scaling factor cc_scale is computed from cov2cov_alpha and optionally auto-balanced using chi2_cc / dof (Birge ratio) when a prior is present. Scaled intermediates are then added to global H, g, and errNormSqr.
Tests / Infrastructure
tests/test-mp2p_optimize_cov2cov_with_prior.cpp, tests/CMakeLists.txt, agents.md
New test validates four scenarios: (A) balancing disabled, (B) auto-balance enabled showing prior pull, (C) manual α=1/N sanity check, and (D) no-prior regression. Test target registered in CMake. Documentation updated with coding conventions.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 A rabbit hops through parameters fine,
Alpha tempers the cov-to-cov line,
Birge ratios balance with prior grace,
Intermediate terms find their proper place—
Four test paths prove the optimizer's might!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately reflects the main feature: implementing Birge-ratio auto-balance for cov2cov contribution and prior weighting, which is the core change across multiple files in the changeset.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/prior-weight-mitigations

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share
Review rate limit: 0/1 reviews remaining, refill in 60 minutes.

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
agents.md (1)

202-202: ⚡ Quick win

Clarify “long hyphens” with explicit punctuation names.

Line 202 is a bit ambiguous as written. Please name the exact characters (for example, “en dash (–)” / “em dash (—)”) so contributors can apply the rule consistently.

Suggested wording
-- Don't use long hyphens. Use American spelling.
+- Avoid en/em dashes (–, —); use the regular hyphen-minus (-). Use American spelling.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@agents.md` at line 202, Replace the ambiguous phrase "long hyphens" with
explicit punctuation names and examples: state "en dash (–) and em dash (—)" and
instruct using American spelling (e.g., "color" not "colour") so contributors
know exactly which characters to avoid; update the sentence containing "long
hyphens" to read something like: "Do not use en dash (–) or em dash (—). Use
American spelling." and ensure the phrase "long hyphens" is removed or clarified
(search for the exact string "long hyphens" to find the location).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@mp2p_icp/src/optimal_tf_gauss_newton.cpp`:
- Around line 291-299: Before the iterative solver starts, validate
gnParams.cov2cov_alpha to ensure it's finite and positive (e.g.
std::isfinite(gnParams.cov2cov_alpha) && gnParams.cov2cov_alpha > 0); if the
check fails, log an error and return false (fail fast) so the solver doesn't
proceed with an invalid global scale; add this single guard near the beginning
of the function that contains the Gauss-Newton loop (reference symbols:
cov2cov_alpha, gnParams, chi2_cc / nCov2Cov usage) so cc_scale is never
initialized from a bad value.

---

Nitpick comments:
In `@agents.md`:
- Line 202: Replace the ambiguous phrase "long hyphens" with explicit
punctuation names and examples: state "en dash (–) and em dash (—)" and instruct
using American spelling (e.g., "color" not "colour") so contributors know
exactly which characters to avoid; update the sentence containing "long hyphens"
to read something like: "Do not use en dash (–) or em dash (—). Use American
spelling." and ensure the phrase "long hyphens" is removed or clarified (search
for the exact string "long hyphens" to find the location).
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: dc789ff1-83bd-49be-8e2c-982d82bf9d6a

📥 Commits

Reviewing files that changed from the base of the PR and between 79c8fde and 3a6725a.

📒 Files selected for processing (5)
  • agents.md
  • mp2p_icp/include/mp2p_icp/optimal_tf_gauss_newton.h
  • mp2p_icp/src/optimal_tf_gauss_newton.cpp
  • tests/CMakeLists.txt
  • tests/test-mp2p_optimize_cov2cov_with_prior.cpp

Comment on lines +291 to +299
{
double cc_scale = gnParams.cov2cov_alpha;
if (gnParams.cov2cov_auto_balance_with_prior && gnParams.prior.has_value() &&
nCov2Cov >= 3)
{
const double dof = std::max(1.0, 3.0 * static_cast<double>(nCov2Cov) - 6.0);
const double kappa = std::max(1.0, chi2_cc / dof);
cc_scale /= kappa;
}
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Validate cov2cov_alpha before using it as a global scale.

A negative or non-finite cov2cov_alpha will make the normal equations invalid and can silently propagate NaNs or an indefinite Hessian while still returning true. Please fail fast on invalid values once, before the iteration loop.

Suggested guard
+#include <cmath>
...
     ASSERTMSG_(
         gnParams.linearizationPoint.has_value(), "This method requires a linearization point");
+    ASSERTMSG_(
+        std::isfinite(gnParams.cov2cov_alpha) && gnParams.cov2cov_alpha >= 0.0,
+        "`cov2cov_alpha` must be finite and non-negative");
 
     result.optimalPose = gnParams.linearizationPoint.value();
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@mp2p_icp/src/optimal_tf_gauss_newton.cpp` around lines 291 - 299, Before the
iterative solver starts, validate gnParams.cov2cov_alpha to ensure it's finite
and positive (e.g. std::isfinite(gnParams.cov2cov_alpha) &&
gnParams.cov2cov_alpha > 0); if the check fails, log an error and return false
(fail fast) so the solver doesn't proceed with an invalid global scale; add this
single guard near the beginning of the function that contains the Gauss-Newton
loop (reference symbols: cov2cov_alpha, gnParams, chi2_cc / nCov2Cov usage) so
cc_scale is never initialized from a bad value.

@jlblancoc jlblancoc merged commit 72c083d into develop May 2, 2026
8 of 11 checks passed
@jlblancoc jlblancoc deleted the feat/prior-weight-mitigations branch May 2, 2026 13:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant