Stronge as the default ball-cushion model

[ekiefl]

• Added omega_ratio as a model parameter
• Added a note about how one day this should be recast as Poisson ratio and placed as a cushion property
• Set Stronge as default model
• After some experimentation, I decided to bump the omega ratio up to 1.8

Summary by CodeRabbit

• Chores

  • Physics engine version upgraded to 9.

• New Features

  • Added utility functions for physics parameter conversions.

• Refactor

  • Improved ball-cushion collision resolution with enhanced physics model and configurable parameters for better accuracy.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

The changes introduce omega_ratio as a configurable parameter to StrongeCompliant cushion collision models, replacing a hard-coded value (1.7) in eta_squared calculation. The default resolver switches from Mathavan2010 to StrongeCompliant strategies (with omega_ratio=1.8), and new utility functions enable conversion between Poisson ratio and omega_ratio.

Changes

Cohort / File(s)	Summary
StrongeCompliant model parameter introduction pooltool/physics/resolve/ball_cushion/stronge_compliant/model.py	Added omega_ratio: float = 1.7 attribute to both StrongeCompliantLinear and StrongeCompliantCircular classes; updated _solve() function signature to accept omega_ratio parameter and use it in eta_squared calculation instead of hard-coded 1.7; both solve() methods now pass self.omega_ratio to _solve().
Resolver strategy replacement pooltool/physics/resolve/resolver.py	Replaced imports from Mathavan2010 models to StrongeCompliant models; updated default resolver to instantiate StrongeCompliantLinear(omega_ratio=1.8) and StrongeCompliantCircular(omega_ratio=1.8) instead of Mathavan2010 variants; bumped VERSION constant from 8 to 9.
Utility function additions pooltool/physics/resolve/stronge_compliant.py	Added two new public functions: poisson_ratio_from_omega_ratio() and omega_ratio_from_poisson_ratio() with comprehensive docstrings describing the conversion relationship between Poisson's ratio and frequency ratio; enhanced documentation for normal_tangent_stiffness_ratio().

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Ball Cushion Stronge Compliant Lumped-Parameter #240 — Introduced the StrongeCompliant collision model modules that are being extended with the omega_ratio parameter in this PR.
• Fix numerical stability of Mathavan + make default #192 — Modified default cushion-strategy selection in the resolver, similarly changing which ball-cushion model classes are instantiated.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 55.56% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: setting Stronge as the default ball-cushion collision model, which is the primary objective reflected in the file changes across resolver.py, the model.py, and supporting utilities.

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

✨ Finishing touches

• 📝 Generate docstrings

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[codecov]

Codecov Report

❌ Patch coverage is 69.23077% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 45.34%. Comparing base (0e89b7f) to head (3043b23).
⚠️ Report is 52 commits behind head on main.

Files with missing lines	Patch %	Lines
pooltool/physics/resolve/stronge_compliant.py	33.33%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #256      +/-   ##
==========================================
+ Coverage   44.22%   45.34%   +1.12%     
==========================================
  Files         127      144      +17     
  Lines        8554    10111    +1557     
==========================================
+ Hits         3783     4585     +802     
- Misses       4771     5526     +755     

Flag	Coverage Δ
service	45.34% <69.23%> (+1.12%)	⬆️

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

☔ View full report in Codecov by Sentry.
📢 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.

[ekiefl]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[derek-mcblane]

I'm excited to see this model made the default!

[derek-mcblane]

This is actually general enough to do any two-body planar collinear collision. The beta_t and beta_n arguments come from the moments of inertia for the two bodies.

[derek-mcblane]

Just a small note: if we ever want to use the spring deformation to approximate cushion deformation and duration, this parameter affects that duration.

[derek-mcblane]

Requesting the docstring I commented on be updated: https://github.com/ekiefl/pooltool/pull/256/changes#r2751953260