plumial.core.P._P

class plumial.core.P._P(p, basis=None, pred=None, next=None)

Bases: object

Internal class representing a path polynomial in Collatz analysis.

This class encapsulates the mathematical structure of a Collatz path polynomial, providing methods for polynomial evaluation, cycle navigation, and various mathematical transformations. It maintains cached expressions for performance and supports both symbolic and numerical operations.

The class implements the mathematical relationships between different polynomial representations used in Collatz analysis, including UV polynomials, difference polynomials, and the fundamental relationship x*d = a*k.

This class should not be instantiated directly. Use the P() factory function instead.

_p

The integer p-value this polynomial represents

_d

Cached D object D(p)

_next

Cached next element in the cycle

_pred

Cached predecessor element in the cycle

_expr_*

Cached symbolic expressions for various polynomial forms

_P.D()	Return the D object.
_P.G()	Create column vector of g powers from g^(o-1) down to g^0.
_P.H()	Create matrix of k polynomial coefficients for odd cycle elements.
_P.__init__(p[, basis, pred, next])	Initialize a path polynomial.
_P.a()	Calculate the a coefficient.
_P.ax()	Calculate a pair of polynomials a,x such that x*d = a*k.
_P.b([width])	Return binary string representation of the p-value.
_P.basis()	Return the basis of this encoding.
_P.c()	Calculate the ceiling of log_h(g).
_P.cycle([map, filter])	Iterate through the cycle.
_P.d()	Return the d-polynomial or its evaluation.
_P.e()	Return the number of even bits.
_P.encode([basis, g, h])	Create a new P object encoded in a different basis.
_P.f()	Calculate the f polynomial (GCD factor).
_P.isforced()	Determine if the cycle is forced by the p-value bit pattern.
_P.k()	Calculate the k polynomial.
_P.n()	Return the number of path bits.
_P.next()	Get the next element in the cycle.
_P.o()	Return the number of odd bits.
_P.p()	Return the p-value.
_P.pred()	Get the predecessor element in the cycle.
_P.r()	Calculate the remainder: c() * o() - e().
_P.uv()	Generate UV polynomial representation.
_P.x()	Calculate the x polynomial.

D()

Return the D object.

G()

Create column vector of g powers from g^(o-1) down to g^0.

This method delegates to the D object’s G() method to generate a column vector containing powers of g in descending order, used for matrix operations with polynomial coefficients.

Return type:

MutableDenseMatrix

Returns:

SymPy Matrix column vector with g powers [g^(o-1), g^(o-2), …, g^1, g^0]

Mathematical Structure:

For o odd bits, creates: [g^(o-1), g^(o-2), …, g^1, g^0]^T

Examples

>>> p = P(133)  # o=2, e=5
>>> g_vector = p.G()
>>> # Returns Matrix([[g], [1]]) for powers g^1, g^0

Matrix Operations:

>>> p = P(281)  # o=3, e=5
>>> G_vec = p.G()
>>> # Returns Matrix([[g**2], [g], [1]]) for use in polynomial operations

Note

This method delegates to the associated D object: self._d.G()

H()

Create matrix of k polynomial coefficients for odd cycle elements.

This method generates a matrix where each row contains the coefficients of the k polynomial (with respect to g) for each odd p-value in the cycle. This is used for matrix operations analyzing the polynomial structure of Collatz cycles.

Return type:

MutableDenseMatrix

Returns:

SymPy Matrix with each row containing k polynomial coefficients for odd cycle elements

Mathematical Structure:

For each odd p in cycle, extract coefficients of p.k() polynomial w.r.t. g Matrix shape: (number_of_odd_elements, max_polynomial_degree + 1)

Examples

>>> p = P(133)  # Cycle with odd elements
>>> h_matrix = p.H()
>>> # Returns matrix with k polynomial coefficients for each odd cycle element

Matrix Operations:

>>> p = P(281)  # 8-element cycle
>>> H_mat = p.H()
>>> # Matrix with rows for each odd element's k polynomial coefficients

Note

Only processes odd cycle elements as these are most relevant for analysis

__init__(p, basis=None, pred=None, next=None)

Initialize a path polynomial.

Parameters:

• p (int) – The p-value (must be a positive integer)

• basis (Optional[Basis]) – The mathematical basis for this encoding (default: symbolic basis)

• pred (Optional[_P]) – Optional predecessor P instance for cycle linking

• next (Optional[_P]) – Optional next P instance for cycle linking

Note

This constructor is internal. Use P() factory function instead.

a()

Calculate the a coefficient.

Return type:

Union[Expr, int, float]

Returns:

a coefficient or its evaluation

ax()

Calculate a pair of polynomials a,x such that x*d = a*k.

This method computes the polynomial factorization that satisfies the fundamental relationship x*d = a*k, where d is the d-polynomial and k is the k polynomial. The factorization separates the d-polynomial ratio d/k into numerator (a) and denominator (x) components.

Return type:

Tuple[Expr, Expr]

Returns:

Tuple of (a_polynomial, x_polynomial) where both are SymPy expressions

Mathematical Relationship:

x * d = a * k a = d / f (where f is the GCD factor) x = k / f

Examples

>>> p = P(133)
>>> a, x = p.ax()
>>> # Verify the relationship symbolically
>>> d_poly = p.d()
>>> k_poly = p.k()
>>> assert sy.expand(x * d_poly) == sy.expand(a * k_poly)

b(width=0)

Return binary string representation of the p-value.

Parameters:

width (int) – Minimum width (right-justified with zeros, default: 0)

Return type:

str

Returns:

Binary string representation

Examples

>>> p = P(133)
>>> p.b()
'10000101'
>>> p.b(10)
'0010000101'

basis()

Return the basis of this encoding.

Return type:

Basis

c()

Calculate the ceiling of log_h(g).

Delegates to the D object’s c() method.

Return type:

Union[Expr, int, float]

Returns:

Ceiling value, either symbolic or evaluated based on the basis

cycle(map=None, filter=None)

Iterate through the cycle.

Return type:

Iterator[_P]

d()

Return the d-polynomial or its evaluation.

Return type:

Union[Expr, int, float, Rational]

Returns:

Difference polynomial h^e - g^o, either symbolic or evaluated

Examples

>>> p = P(133)
>>> p.d()  # Symbolic form
h**5 - g**2
>>> collatz_p = P(133).encode(B.Collatz)
>>> collatz_p.d()  # Uses basis automatically
23

e()

Return the number of even bits.

Return type:

int

encode(basis=None, g=None, h=None)

Create a new P object encoded in a different basis.

This method enables the transitive encoding property where P objects can be transformed between different coordinate systems while preserving the underlying p-value identity.

Parameters:

• basis (Optional[Basis]) – Target basis for encoding

• g (Union[int, float, None]) – g parameter for custom basis (alternative to basis parameter)

• h (Union[int, float, None]) – h parameter for custom basis (alternative to basis parameter)

Return type:

_P

Returns:

New P object with same p-value but different basis

Examples

>>> p = P(281)                    # Symbolic basis
>>> collatz_p = p.encode(B.Collatz)  # Collatz basis
>>> custom_p = p.encode(g=5, h=2)    # Custom basis
>>> back_p = collatz_p.encode()      # Back to symbolic basis
>>> assert back_p == p              # Round-trip equality

f()

Calculate the f polynomial (GCD factor).

The f polynomial represents the greatest common divisor factor that appears in the relationship between the d-polynomial d and the k polynomial. It is computed as the GCD of d and k, with special handling for even/odd values of g.

Return type:

Union[Expr, int, float]

Returns:

f polynomial (symbolic) or its numerical evaluation

Mathematical Background:

f = gcd(d, k) where d is the d-polynomial and k is the k polynomial For even g: f is computed over the entire cycle For odd g: f is the simple GCD of d and k

Examples

>>> p = P(133)
>>> f_symbolic = p.f()  # Symbolic form
>>> collatz_p = P(133).encode(B.Collatz)
>>> f_numeric = collatz_p.f()  # Numerical evaluation

isforced()

Determine if the cycle is forced by the p-value bit pattern.

A cycle is considered “forced” if the next operation cannot be determined by inspecting the LSB bit of the x-value alone, but instead is determined by the LSB bit of the p-value. This occurs when:

1. The p-value contains any adjacent 1 bits in its binary representation, OR

2. The top and bottom path bits are both 1

This is a critical property for Collatz analysis: any counterexample to the Collatz conjecture would have isforced() == False.

Return type:

bool

Returns:

True if the cycle is forced by the p-value bit pattern, False otherwise

Mathematical Background:

For unforced cycles: all(p.x(3,2) % 2 == p.p() % 2 for p in cycle) For forced cycles: the above condition is False for at least one element

Examples

>>> P(9).isforced()   # Unforced cycle
False
>>> P(291).isforced() # Forced cycle
True
>>> # Verify unforced property for P(9)
>>> all(p.x(3,2) % 2 == p.p() % 2 for p in P(9).cycle())
True
>>> # Verify forced property for P(291)
>>> all(p.x(3,2) % 2 == p.p() % 2 for p in P(291).cycle())
False

k()

Calculate the k polynomial.

The k polynomial is derived from the gh transformation of the uv polynomial.

Return type:

Union[Expr, int, float]

Returns:

k polynomial or its evaluation

Examples

>>> p = P(133)
>>> p.k()  # Symbolic form
# Returns symbolic k polynomial
>>> collatz_p = P(133).encode(B.Collatz)
>>> collatz_p.k()  # Uses basis automatically
# Returns numerical value using Collatz basis

n()

Return the number of path bits.

Return type:

int

next()

Get the next element in the cycle.

Return type:

_P

o()

Return the number of odd bits.

Return type:

int

p()

Return the p-value.

Return type:

int

pred()

Get the predecessor element in the cycle.

Return type:

_P

r()

Calculate the remainder: c() * o() - e().

Delegates to the D object’s r() method.

Return type:

Union[Expr, int, float]

Returns:

Remainder value, either symbolic or evaluated based on the basis

uv()

Generate UV polynomial representation.

This creates a polynomial in u and v variables that encodes the binary path structure of the p-value.

Return type:

Expr

Returns:

SymPy expression in u and v variables

x()

Calculate the x polynomial.

Return type:

Union[Expr, int, float]

Returns:

x polynomial or its evaluation