pooltool.physics.resolve.transition
===================================

.. py:module:: pooltool.physics.resolve.transition

    Defining and handling ball state transitions
    --------------------------------------------
    
    
    .. note::
    
       If this module is ever extended to support multiple treatments for ball transitions,
       expand this file into a file structure modelled after ../ball_ball or
       ../ball_cushion
    

Overview
--------

.. list-table:: Classes
   :header-rows: 0
   :widths: auto
   :class: summarytable

   * - :py:obj:`EventType <pooltool.physics.resolve.transition.EventType>`
     - An Enum of event types
   * - :py:obj:`Ball <pooltool.physics.resolve.transition.Ball>`
     - A billiards ball
   * - :py:obj:`StrEnum <pooltool.physics.resolve.transition.StrEnum>`
     - Enum where members are also (and must be) strings
   * - :py:obj:`BallTransitionStrategy <pooltool.physics.resolve.transition.BallTransitionStrategy>`
     - Ball transition models must satisfy this protocol
   * - :py:obj:`BallTransitionModel <pooltool.physics.resolve.transition.BallTransitionModel>`
     - An Enum for different transition models


.. list-table:: Function
   :header-rows: 0
   :widths: auto
   :class: summarytable

   * - :py:obj:`get_transition_model <pooltool.physics.resolve.transition.get_transition_model>`\ (model, params)
     - Returns a transition model


.. list-table:: Attributes
   :header-rows: 0
   :widths: auto
   :class: summarytable

   * - :py:obj:`ModelArgs <pooltool.physics.resolve.transition.ModelArgs>`
     - A mapping of argument names to argument values


Classes
-------
.. autoclass:: EventType


   Bases: :py:obj:`pooltool.utils.strenum.StrEnum`



   .. rubric:: Methods:
   .. py:method:: is_collision() -> bool

      Returns whether the member is a collision


   .. py:method:: is_transition() -> bool

      Returns whether the member is a transition



.. autoclass:: Ball


   .. py:property:: xyz

      The displacement (from origin) vector of the ball.

      A shortcut for ``self.state.rvw[0]``.

   .. py:property:: vel

      The velocity vector of the ball.

      A shortcut for ``self.state.rvw[1]``.

   .. py:property:: avel

      The angular velocity vector of the ball.

      A shortcut for ``self.state.rvw[2]``.



   .. rubric:: Methods:
   .. py:method:: set_ballset(ballset: pooltool.objects.ball.sets.BallSet) -> None

      Update the ballset

      :raises ValueError: If the ball ID doesn't match to a model name of the ballset.

      .. seealso::

         - See :mod:`pooltool.objects.ball.sets` for details about ball sets.
         - See :meth:`pooltool.system.datatypes.System.set_ballset` for setting the
           ballset for all the balls in a system.


   .. py:method:: copy(drop_history: bool = False) -> Ball

      Create a copy

      :param drop_history: If True, the returned copy :attr:`history` and :attr:`history_cts`
                           attributes are both set to empty :class:`BallHistory` objects.


   .. py:method:: create(id: str, *, xy: Optional[Sequence[float]] = None, ballset: Optional[pooltool.objects.ball.sets.BallSet] = None, **kwargs) -> Ball
      :staticmethod:

      Create a ball using keyword arguments.

      This constructor flattens the tunable parameter space, allowing one to construct
      a ``Ball`` without directly instancing objects like like
      :class:`pooltool.objects.balls.params.BallParams` and :class:`BallState`.

      :param xy: The x and y coordinates of the ball position.
      :param ballset: A ballset.
      :param \*\*kwargs: Arguments accepted by :class:`pooltool.objects.balls.params.BallParams`



.. autoclass:: StrEnum


   Bases: :py:obj:`str`, :py:obj:`enum.Enum`




.. autoclass:: BallTransitionStrategy


   Bases: :py:obj:`Protocol`



   .. rubric:: Methods:
   .. py:method:: resolve(ball: pooltool.objects.ball.datatypes.Ball, transition: pooltool.events.datatypes.EventType, inplace: bool = False) -> pooltool.objects.ball.datatypes.Ball

      This method resolves a ball transition



.. autoclass:: BallTransitionModel


   Bases: :py:obj:`pooltool.utils.strenum.StrEnum`





Functions
---------
.. py:function:: get_transition_model(model: Optional[BallTransitionModel] = None, params: pooltool.physics.resolve.types.ModelArgs = {}) -> BallTransitionStrategy

   Returns a transition model

   :param model: An Enum specifying the desired model. If not passed,
                 :class:`CanonicalTransition` is passed with empty params.
   :param params: A mapping of parameters accepted by the model.

   :returns: An instantiated model that satisfies the :class:`BallTransitionStrategy`
             protocol.



Attributes
----------
.. py:data:: ModelArgs

   A mapping of argument names to argument values