pooltool.ptmath¶

Math functions¶

Subpackages¶

pooltool.ptmath.roots

Submodules¶

pooltool.ptmath.utils

Overview¶

Function¶
`angle`(v2, v1)	Returns counter-clockwise angle of projections of v1 and v2 onto the x-y plane
`angle_between_vectors`(v1, v2)	Returns angles between [-180, 180]
`are_points_on_same_side`(p1, p2, p3, p4)	Are points p3, p4 are on the same side of the line formed by points p1 and p2?
`convert_2D_to_3D`(array)	Convert a 2D vector to a 3D vector, setting z=0
`coordinate_rotation`(v, phi)	Rotate vector/matrix from one frame of reference to another (3D FIXME)
`cross`(u, v)	Compute cross product u x v, where u and v are 3-dimensional vectors
`find_intersection_2D`(l1x, l1y, l10, l2x, l2y, l20)	Find the intersection point of two lines in 2D space
`get_ball_energy`(rvw, R, m)	Get the energy of a ball
`get_roll_time`(rvw, u_r, g)	-
`get_slide_time`(rvw, R, u_s, g)	-
`get_spin_time`(rvw, R, u_sp, g)	-
`get_u_vec`(rvw, phi, R, s)	-
`is_overlapping`(rvw1, rvw2, R1, R2)	-
`norm2d`(vec)	Calculate the norm of a 2D vector
`norm3d`(vec)	Calculate the norm of a 3D vector
`point_on_line_closest_to_point`(p1, p2, p0)	Returns point on line defined by points p1 and p2 closest to the point p0
`rel_velocity`(rvw, R)	Compute velocity of ball’s point of contact with the cloth relative to the cloth
`solve_transcendental`(f, a, b, tol, max_iter)	Solve transcendental equation f(x) = 0 in interval [a, b] using bisection method
`surface_velocity`(rvw, d, R)	Compute velocity of a point on ball’s surface (specified by unit direction vector)
`tangent_surface_velocity`(rvw, d, R)	Compute velocity tangent to surface at a point on ball’s surface (specified by unit direction vector)
`unit_vector`(vector, handle_zero)	Returns the unit vector of the vector (just-in-time compiled)
`unit_vector_slow`(vector, handle_zero)	Returns the unit vector of the vector.
`wiggle`(x, val)	Vary a float or int x by +- val according to a uniform distribution

Functions¶

pooltool.ptmath.angle(v2: numpy.typing.NDArray[numpy.float64], v1: numpy.typing.NDArray[numpy.float64] = np.array([1, 0])) → float[source]¶

Returns counter-clockwise angle of projections of v1 and v2 onto the x-y plane

(just-in-time compiled)

Return type:: float

pooltool.ptmath.angle_between_vectors(v1: numpy.typing.NDArray[numpy.float64], v2: numpy.typing.NDArray[numpy.float64]) → float[source]¶

Returns angles between [-180, 180]

Return type:: float

pooltool.ptmath.are_points_on_same_side(p1, p2, p3, p4) → bool[source]¶

Are points p3, p4 are on the same side of the line formed by points p1 and p2?

Accepts indexable objects. This is a 2D function, but if higher dimensions are provided, that’s ok (only the first two dimensions will be used).

Return type:: bool

pooltool.ptmath.convert_2D_to_3D(array: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64][source]¶

Convert a 2D vector to a 3D vector, setting z=0

Return type:: numpy.typing.NDArray[numpy.float64]

pooltool.ptmath.coordinate_rotation(v: numpy.typing.NDArray[numpy.float64], phi: float) → numpy.typing.NDArray[numpy.float64][source]¶

Rotate vector/matrix from one frame of reference to another (3D FIXME)

(just-in-time compiled)

Return type:: numpy.typing.NDArray[numpy.float64]

pooltool.ptmath.cross(u: numpy.typing.NDArray[numpy.float64], v: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64][source]¶

Compute cross product u x v, where u and v are 3-dimensional vectors

(just-in-time compiled)

Return type:: numpy.typing.NDArray[numpy.float64]

pooltool.ptmath.find_intersection_2D(l1x: float, l1y: float, l10: float, l2x: float, l2y: float, l20: float) → tuple[float, float][source]¶

Find the intersection point of two lines in 2D space

The lines are defined by their linear equations in the general form: (l1x)x + (l1y)y + l10 = 0 and (l2x)x + (l2y)y + l20 = 0.

Parameters:

l1x (float) -- The coefficient of x in the first line equation.
l1y (float) -- The coefficient of y in the first line equation.
l10 (float) -- The constant term in the first line equation.
l2x (float) -- The coefficient of x in the second line equation.
l2y (float) -- The coefficient of y in the second line equation.
l20 (float) -- The constant term in the second line equation.

Returns:

A tuple (x, y) representing the intersection point if the lines intersect at a single point. Returns None if the lines are parallel or coincident (no unique intersection).

Return type:

tuple[float, float]

pooltool.ptmath.get_ball_energy(rvw: numpy.typing.NDArray[numpy.float64], R: float, m: float) → float[source]¶

Get the energy of a ball

Currently calculating linear and rotational kinetic energy. Need to add potential energy if z-axis is freed

Return type:: float

pooltool.ptmath.get_roll_time(rvw: numpy.typing.NDArray[numpy.float64], u_r: float, g: float) → float[source]¶

Return type:: float

pooltool.ptmath.get_slide_time(rvw: numpy.typing.NDArray[numpy.float64], R: float, u_s: float, g: float) → float[source]¶

Return type:: float

pooltool.ptmath.get_spin_time(rvw: numpy.typing.NDArray[numpy.float64], R: float, u_sp: float, g: float) → float[source]¶

Return type:: float

pooltool.ptmath.get_u_vec(rvw: numpy.typing.NDArray[numpy.float64], phi: float, R: float, s: int) → numpy.typing.NDArray[numpy.float64][source]¶

Return type:: numpy.typing.NDArray[numpy.float64]

pooltool.ptmath.is_overlapping(rvw1: numpy.typing.NDArray[numpy.float64], rvw2: numpy.typing.NDArray[numpy.float64], R1: float, R2: float) → bool[source]¶

Return type:: bool

pooltool.ptmath.norm2d(vec: numpy.typing.NDArray[numpy.float64]) → float[source]¶

Calculate the norm of a 2D vector

This is faster than np.linalg.norm

Return type:: float

pooltool.ptmath.norm3d(vec: numpy.typing.NDArray[numpy.float64]) → float[source]¶

Calculate the norm of a 3D vector

This is ~10x faster than np.linalg.norm

>>> import numpy as np
>>> from pooltool.ptmath import *
>>> vec = np.random.rand(3)
>>> norm3d(vec)
>>> %timeit np.linalg.norm(vec)
>>> %timeit norm3d(vec)
2.65 µs ± 63 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)
241 ns ± 2.57 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)

Return type:: float

pooltool.ptmath.point_on_line_closest_to_point(p1: numpy.typing.NDArray[numpy.float64], p2: numpy.typing.NDArray[numpy.float64], p0: numpy.typing.NDArray[numpy.float64]) → numpy.typing.NDArray[numpy.float64][source]¶

Returns point on line defined by points p1 and p2 closest to the point p0

Equations from https://mathworld.wolfram.com/Point-LineDistance3-Dimensional.html

Return type:: numpy.typing.NDArray[numpy.float64]

pooltool.ptmath.rel_velocity(rvw: numpy.typing.NDArray[numpy.float64], R: float) → numpy.typing.NDArray[numpy.float64][source]¶

Compute velocity of ball’s point of contact with the cloth relative to the cloth

This vector is non-zero whenever the ball is sliding

Return type:: numpy.typing.NDArray[numpy.float64]

pooltool.ptmath.solve_transcendental(f: collections.abc.Callable[[float], float], a: float, b: float, tol: float = 1e-05, max_iter: int = 100) → float[source]¶

Solve transcendental equation f(x) = 0 in interval [a, b] using bisection method

Parameters:

f (collections.abc.Callable[[float], float]) -- A function representing the transcendental equation.
a (float) -- The lower bound of the interval.
b (float) -- The upper bound of the interval.
tol (float) -- The tolerance level for the solution. The function stops when the absolute difference between the upper and lower bounds is less than tol.
max_iter (int) -- The maximum number of iterations to perform.

Returns:

The approximate root of f within the interval [a, b].

Raises:

ValueError -- If f(a) and f(b) have the same sign, indicating no root within the interval.
RuntimeError -- If the maximum number of iterations is reached without convergence.

Return type:

float

pooltool.ptmath.surface_velocity(rvw: numpy.typing.NDArray[numpy.float64], d: numpy.typing.NDArray[numpy.float64], R: float) → numpy.typing.NDArray[numpy.float64][source]¶

Compute velocity of a point on ball’s surface (specified by unit direction vector)

Return type:: numpy.typing.NDArray[numpy.float64]

pooltool.ptmath.tangent_surface_velocity(rvw: numpy.typing.NDArray[numpy.float64], d: numpy.typing.NDArray[numpy.float64], R: float) → numpy.typing.NDArray[numpy.float64][source]¶

Compute velocity tangent to surface at a point on ball’s surface (specified by unit direction vector)

Return type:: numpy.typing.NDArray[numpy.float64]

pooltool.ptmath.unit_vector(vector: numpy.typing.NDArray[numpy.float64], handle_zero: bool = False) → numpy.typing.NDArray[numpy.float64][source]¶

Returns the unit vector of the vector (just-in-time compiled)

Parameters:: handle_zero (bool, False) -- If True and vector = <0,0,0>, <0,0,0> is returned.
Return type:: numpy.typing.NDArray[numpy.float64]

Notes

Only supports 3D (for 2D see unit_vector_slow)

pooltool.ptmath.unit_vector_slow(vector: numpy.typing.NDArray[numpy.float64], handle_zero: bool = False) → numpy.typing.NDArray[numpy.float64][source]¶

Returns the unit vector of the vector.

“Slow”, but supports more than just 3D.

Parameters:: handle_zero (bool, False) -- If True and vector = <0,0,0>, <0,0,0> is returned.
Return type:: numpy.typing.NDArray[numpy.float64]

pooltool.ptmath.wiggle(x: float, val: float)[source]¶

Vary a float or int x by +- val according to a uniform distribution