plumial.core.D._D

class plumial.core.D._D(o, e, basis=None)

Bases: object

Internal class representing a d-polynomial d_p(g,h) = h^e - g^o.

This class encapsulates the mathematical structure of a d-polynomial used in Collatz sequence analysis. It provides methods for symbolic manipulation and numerical evaluation.

The class maintains the fundamental parameters n, o, e for the polynomial form h^e - g^o.

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

Mathematical Structure:

• n: total number of bits (path length)

• o: number of odd bits (3x+1 operations)

• e: number of even bits (halving operations), where e = n - o

• The polynomial form: h^e - g^o

_o

Number of odd bits

_e

Number of even bits

_n

Total number of bits (computed as o + e)

_expr

Cached symbolic expression

_D.G()	Create column vector of g powers from g^(o-1) down to g^0.
_D.__init__(o, e[, basis])	Initialize d-polynomial from odd and even bit counts.
_D.as_expr()	Return the symbolic expression h^e - g^o.
_D.basis()	Return the basis of this encoding.
_D.c()	Calculate the ceiling of log_h(g).
_D.d()	Evaluate the d-polynomial.
_D.e()	Return number of even bits.
_D.encode([basis, g, h])	Create a new D object encoded in a different basis.
_D.n()	Return total number of bits (computed as o + e).
_D.o()	Return number of odd bits.
_D.r()	Calculate the remainder: c() * o() - e().

G()

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

This method generates a column vector containing powers of g in descending order, used for matrix operations with polynomial coefficients. The vector has o elements corresponding to the number of odd bits.

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

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

Matrix Operations:

>>> d = D(3, 4)  # o=3, e=4
>>> G_vec = d.G()
>>> # Returns Matrix([[g**2], [g], [1]]) for use in polynomial operations

__init__(o, e, basis=None)

Initialize d-polynomial from odd and even bit counts.

Parameters:

• o (int) – Number of odd bits (must be >= 0)

• e (int) – Number of even bits (must be >= 0)

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

Raises:

ValueError – If o < 0 or e < 0

Note

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

as_expr()

Return the symbolic expression h^e - g^o.

Return type:

Expr

Returns:

SymPy expression representing the d-polynomial

basis()

Return the basis of this encoding.

Return type:

Basis

c()

Calculate the ceiling of log_h(g).

This method computes ceil(log_h(g)) where log_h(g) is the logarithm of g with base h. The result represents an important mathematical bound related to the d-polynomial structure.

Return type:

Union[Expr, int, float, Rational]

Returns:

Ceiling value, either symbolic or evaluated based on the basis

Mathematical Formula:

c = ceil(log_h(g)) = ceil(log(g) / log(h))

Examples

>>> d = D(2, 5)
>>> d.c()  # Symbolic form
>>> collatz_d = D(2, 5).encode(B.Collatz)
>>> collatz_d.c()  # Numerical evaluation for g=3, h=2

d()

Evaluate the d-polynomial.

Return type:

Union[Expr, int, float, Rational]

Returns:

Evaluated expression or symbolic form

Examples

>>> d = D(2, 5)
>>> d.d()  # Symbolic form
h**5 - g**2
>>> collatz_d = D(2, 5).encode(B.Collatz)
>>> collatz_d.d()  # Uses basis automatically
23

e()

Return number of even bits.

Return type:

int

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

Create a new D object encoded in a different basis.

This method enables the transitive encoding property where D objects can be transformed between different coordinate systems while preserving the underlying mathematical structure.

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:

_D

Returns:

New D object with same n,o values but different basis

Examples

>>> d = D(2, 5)                   # Symbolic basis
>>> collatz_d = d.encode(B.Collatz)  # Collatz basis
>>> custom_d = d.encode(g=5, h=2)    # Custom basis
>>> back_d = collatz_d.encode()      # Back to symbolic basis
>>> assert back_d == d              # Round-trip equality

n()

Return total number of bits (computed as o + e).

Return type:

int

o()

Return number of odd bits.

Return type:

int

r()

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

This method computes the remainder value defined as the ceiling of log_h(g) times the number of odd bits minus the number of even bits.

Return type:

Union[Expr, int, float, Rational]

Returns:

Remainder value, either symbolic or evaluated based on the basis

Mathematical Formula:

r = c * o - e = ceil(log_h(g)) * o - e

Examples

>>> d = D(2, 5)
>>> d.r()  # Symbolic form
>>> collatz_d = D(2, 5).encode(B.Collatz)
>>> collatz_d.r()  # Numerical evaluation: 2 * 2 - 5 = -1