v0.2.1

v0.2.1

This significant update introduces a physics engine with customizable collision resolution strategies. Users can now fine-tune the engine by either switching which models are used, modifying the parameters of a given model, or integrating their own physics models. Additionally, the simulation procedure has been profiled, bottlenecks were identified and resolved, and the net result is that simulation times are 4x faster. Finally, a more robust (and faster) quartic polynomial solver that uses a hybrid approach of both numerical and analytic approaches has been added.

Key Changes

• Expanding the physics logic into a package: We have divided physics.py into multiple modules, each focusing on different types of event classes (ball-ball, ball-cushion, ball-pocket, and so on). This compartmentalized approach gives us "room to grow" for various event resolving models.

• Event Resolver: An integral addition to this release is the event resolver, located in pooltool/physics/resolve/resolver.py. The resolver applies different physics strategies for each event class, providing a comprehensive and cohesive datastructure for everything physics-related. For detailed info, read the resolver README.md

• Strategy Templates: To ensure the compatibility between the resolver's expectations and any future physics models that are added, there exists strategy templates. These static templates act as contracts, providing standardized interfaces for each collision event type. For detailed info, read the resolver README.md

• User Configuration: Users can now configure their physics resolver settings using the resolver.yaml file, stored in ~/.config/pooltool/. This file allows users to choose their preferred model for each type of collision event and specify any additional parameters. For detailed info, read the resolver README.md

• Performance Improvements: This version comes with notable speed optimizations. For a review of the changes, check out this PR. As is the case with speeding things up, some of the changes with the most dramatic changes in speed seem the most innocuous (hence the importance of profiling your code). Here are the improvements in speed per commit:

• Analytic Quartic Polynomial Solving: Solving quartic polynomials (essential process in the continuous event-based shot evolution algorithm) has been improved. Now using a hybrid approach to solve, leveraging both the numerical method of finding eigenvalues of the companion matrix (slow but precise) and closed-form analytical equations (fast but possibly imprecise), and thus improving the quartic solving speed by 1.42x. It also improves handling of events that occur within a nanosecond, and handles ball intersection with balls and cushions with better precision and avoidance

Thanks for using pooltool.

Full Changelog: v0.2.0...v0.2.1