algepy Package API

Submodules

algepy.DiscreteFunctions module

class algepy.DiscreteFunctions.PrimalityTesting

Bases: object

A collection of methods to test the primality of positive integers.

Preconditions:

• All methods assume that input integers are positive (n > 0).

• For methods that use random sampling (Fermat and Miller–Rabin tests), it is assumed that n is sufficiently large (typically n > 3) to ensure a meaningful random base can be selected.

static coprime(a: int, b: int) → bool

Determine whether two integers are coprime, i.e., their greatest common divisor is 1.

Mathematical Intuition:

The integers a and b are coprime if:

\[\gcd(a, b) = 1.\]

This function verifies that no prime factor (other than 1) divides both a and b.

Preconditions:

• a and b are positive integers.

Parameters:

• a -- A positive integer.

• b -- A positive integer.

Returns:

True if a and b are coprime; False otherwise.

static extended_euclidean(a: int, b: int) → tuple[int, int]

Compute the coefficients (x, y) that satisfy Bezout's identity:

\[a \cdot x + b \cdot y = \gcd(a, b).\]

Mathematical Intuition:

This function returns integers x and y such that:

\[a x + b y = \gcd(a, b),\]

which is fundamental in solving Diophantine equations and computing modular inverses.

Preconditions:

• a and b are positive integers, not both zero.

Parameters:

• a -- A positive integer.

• b -- A positive integer.

Returns:

A tuple (x, y) satisfying the equation above.

static eratosthenes_primality(n: int) → bool

Test if a number n is prime using a simple variant of the Sieve of Eratosthenes.

Mathematical Intuition:

An integer n > 1 is prime if it is not divisible by any integer in the range:

\[2 \leq v \leq \sqrt{n}.\]

This method checks divisibility only up to the integer square root of n.

Preconditions:

• n is an integer greater than 1.

Parameters:

n -- An integer > 1.

Returns:

True if n is prime; False otherwise.

static fermat_primality(n: int) → bool

Probabilistically test if a number is prime using Fermat's little theorem.

Mathematical Intuition:

Fermat's little theorem states that if n is prime and a is an integer with 1 < a < n, then:

\[a^{n-1} \equiv 1 \pmod{n}.\]

If this congruence fails for some a, then n is composite.

Preconditions:

• n is an integer greater than 3 (with 2 and 3 handled explicitly).

• n is odd (as even numbers > 2 are composite).

Parameters:

n -- An integer greater than 3.

Returns:

True if n passes Fermat's test (and is likely prime); False if n fails the test.

static miller_rabin_primality(n: int) → bool

Test if a number is prime using the Miller–Rabin probabilistic test.

Mathematical Intuition:

Write n - 1 as:

\[n - 1 = 2^s \cdot d,\]

with d odd. Then for a random base a (2 ≤ a ≤ n − 2), compute:

\[x = a^d \mod n.\]

n is composite if:

\[x \not\in \{1, n-1\} \quad \text{and} \quad x^{2^r} \not\equiv n-1 \, (\forall\, 0 \leq r < s).\]

Preconditions:

• n is an odd integer greater than 3 (with 2 and 3 handled explicitly).

Parameters:

n -- An odd integer > 3.

Returns:

True if n passes the Miller–Rabin test (likely prime); False if n fails (composite).

class algepy.DiscreteFunctions.PrimeNumberTheorem

Bases: object

Provides functions related to the prime number theorem (PNT) and approximations for the count of primes.

Preconditions:

• Input values are positive integers (typically x > 1).

static π(x: int) → int

Count the number of primes less than or equal to x.

Mathematical Intuition:

This function estimates:

\[\pi(x) = \#\{ p \leq x \mid p \text{ is prime} \},\]

by testing each integer n (2 ≤ n ≤ x) for primality.

Preconditions:

• x is an integer ≥ 2.

Parameters:

x -- A positive integer (x ≥ 2).

Returns:

The count of primes ≤ x.

static prob(n: int) → float

Compute a heuristic probability that an integer n is prime.

Mathematical Intuition:

It uses a product over primes up to √n:

\[P(n) \approx \prod_{f \leq \sqrt{n}} \frac{f-1}{f},\]

which estimates the density of primes.

Preconditions:

• n is an integer ≥ 2.

Parameters:

n -- A positive integer.

Returns:

A floating-point estimate of the probability that n is prime.

static pnt_prime_count(x: int) → float

Estimate the number of primes up to x via summation.

Mathematical Intuition:

The prime number theorem suggests the prime density near n is ~1/ln(n), so:

\[\pi(x) \approx \sum_{n=2}^{x} \frac{1}{\ln(n)}.\]

Preconditions:

• x is an integer > 1.

Parameters:

x -- A positive integer > 1.

Returns:

A floating-point estimate of the number of primes ≤ x.

static approx_pnt_prime_count(x: int) → float

Approximate the number of primes up to x using the continuous form of the prime number theorem.

Mathematical Intuition:

The prime number theorem states:

\[\pi(x) \sim \frac{x}{\ln(x)},\]

so this function returns:

\[\frac{x}{\ln(x)}.\]

Preconditions:

• x is an integer > 1.

Parameters:

x -- A positive integer > 1.

Returns:

A floating-point approximation of the number of primes ≤ x.

class algepy.DiscreteFunctions.Factorization

Bases: object

Provides methods for computing the divisors and prime factorization of a positive integer.

Preconditions:

• All functions assume that n is a positive integer (n ≥ 1).

static divisors(n: int) → list[int]

Compute all positive divisors of n.

Mathematical Intuition:

Divisors of n are numbers d such that:

\[d \mid n.\]

This function finds all such d by testing up to \(\sqrt{n}\) and including their complementary divisors.

Preconditions:

• n is an integer with n ≥ 1.

Parameters:

n -- A positive integer.

Returns:

A list of positive divisors of n.

static prime_factors(n: int) → list[int]

Determine the distinct prime factors of n.

Mathematical Intuition:

A prime factor p of n satisfies:

\[p \mid n \quad \text{and} \quad p \text{ is prime}.\]

This function returns each prime factor once.

Preconditions:

• n is an integer greater than 1.

Parameters:

n -- A positive integer > 1.

Returns:

A list of prime numbers dividing n.

static factorize(n: int) → list[tuple[int, int]]

Factorize n into its prime factors with exponents.

Mathematical Intuition:

For a positive integer n > 1, there exist primes \(p_1, p_2, \dots, p_k\) and exponents \(e_1, e_2, \dots, e_k\) such that:

\[n = p_1^{e_1} \cdots p_k^{e_k}.\]

This function returns a list of tuples \((p_i, e_i)\).

Preconditions:

• n is an integer > 1.

Parameters:

n -- A positive integer > 1.

Returns:

A list of tuples, where each tuple is (prime, exponent).

class algepy.DiscreteFunctions.ArithmeticFunctions

Bases: object

Implements several arithmetic functions from number theory, including divisor functions and multiplicative functions such as Euler's totient function, Liouville's function, and the Möbius function.

Preconditions:

• The input n should be a positive integer (n ≥ 1).

static σ(n: int) → int

Compute the sum-of-divisors function σ(n).

Mathematical Intuition:

The function is defined by:

\[\sigma(n) = \sum_{d \mid n} d,\]

where the sum runs over all positive divisors d of n.

Preconditions:

• n is an integer with n ≥ 1.

Parameters:

n -- A positive integer.

Returns:

The sum of all positive divisors of n.

static σ_k(n: int, k: int) → int

Compute the generalized divisor function σₖ(n), which sums the k-th powers of all divisors of n.

Mathematical Intuition:

It is defined as:

\[\sigma_k(n) = \sum_{d \mid n} d^k.\]

For k = 1, this reduces to the standard sum-of-divisors function.

Preconditions:

• n is an integer with n ≥ 1.

• k is an integer.

Parameters:

• n -- A positive integer.

• k -- An integer exponent.

Returns:

The sum of each divisor of n raised to the power k.

static Τ(n: int) → int

Compute the divisor-counting function Τ(n), i.e., the total number of positive divisors of n.

Mathematical Intuition:

\[T(n) = \#\{d \mid n\}.\]

Preconditions:

• n is an integer with n ≥ 1.

Parameters:

n -- A positive integer.

Returns:

The number of positive divisors of n.

static ω(n: int) → int

Compute the number of distinct prime factors of n.

Mathematical Intuition:

\[\omega(n) = \#\{p \mid n : p \text{ is prime}\}.\]

Preconditions:

• n is an integer with n ≥ 1.

Parameters:

n -- A positive integer.

Returns:

The number of distinct prime factors of n.

static Ω(n: int) → int

Compute the total number of prime factors of n, counting multiplicities.

Mathematical Intuition:

If

\[n = \prod_{i=1}^{k} p_i^{e_i},\]

then

\[\Omega(n) = \sum_{i=1}^{k} e_i.\]

Preconditions:

• n is an integer with n ≥ 1.

Parameters:

n -- A positive integer.

Returns:

The total number of prime factors of n (with multiplicity).

static φ(n: int) → int

Compute Euler's totient function ϕ(n), which counts the number of integers between 1 and n that are coprime to n.

Mathematical Intuition:

Euler's totient function is given by:

\[\varphi(n) = n \prod_{p \mid n} \left(1 - \frac{1}{p}\right),\]

where the product is over all distinct prime factors of n.

Preconditions:

• n is an integer with n ≥ 1.

Parameters:

n -- A positive integer.

Returns:

The value of Euler's totient function ϕ(n).

static λ(n: int) → int

Compute the Liouville function λ(n).

Mathematical Intuition:

The Liouville function is defined as:

\[\lambda(n) = (-1)^{\Omega(n)},\]

where Ω(n) is the total number of prime factors of n (with multiplicity).

Preconditions:

• n is an integer with n ≥ 1.

Parameters:

n -- A positive integer.

Returns:

1 if Ω(n) is even, -1 if Ω(n) is odd.

static μ(n: int) → int

Compute the Möbius function μ(n).

Mathematical Intuition:

The Möbius function is defined by:

\[\begin{split}\mu(n) = \begin{cases} (-1)^{\omega(n)} & \text{if } n \text{ is square-free,} \\ 0 & \text{otherwise.} \end{cases}\end{split}\]

Preconditions:

• n is an integer with n ≥ 1.

Parameters:

n -- A positive integer.

Returns:

The Möbius function value: -1, 0, or 1.

static I(n: int) → int

The indicator function I(n), defined as:

\[\begin{split}I(n) = \begin{cases} 1 & \text{if } n = 1, \\ 0 & \text{otherwise.} \end{cases}\end{split}\]

Preconditions:

• n is an integer.

Parameters:

n -- An integer.

Returns:

1 if n == 1, 0 otherwise.

static N(n: int) → int

The identity function N(n), which returns n itself.

Mathematical Intuition:

\[N(n) = n.\]

This function acts as the natural number identity in various arithmetic convolutions.

Preconditions:

• n is an integer.

Parameters:

n -- An integer.

Returns:

static is_perfect(n: int) → bool

Determine whether n is a perfect number.

Mathematical Intuition:

A number n is perfect if:

\[\sigma(n) = 2n,\]

where σ(n) is the sum-of-divisors function.

Preconditions:

• n is a positive integer.

Parameters:

n -- A positive integer.

Returns:

True if n is perfect; False otherwise.

static is_square_free(n: int) → bool

Check if n is square-free (i.e., no prime factor appears with exponent greater than 1).

Mathematical Intuition:

n is square-free if:

\[p^2 \nmid n \quad \text{for every prime } p.\]

Preconditions:

• n is a positive integer.

Parameters:

n -- A positive integer.

Returns:

True if n is square-free; False otherwise.

algepy.QuadraticStructures module

class algepy.QuadraticStructures.C(a, b)

Bases: object

A lightweight wrapper for Python's built-in complex numbers, used primarily for embedding purposes in normalization routines for imaginary quadratic integer rings.

Mathematical Intuition:

Elements are represented as:

\[c = a + bi, \quad a, b \in \mathbb{R},\]

and arithmetic is performed using the standard operations on complex numbers.

conjugate() → Self

Returns the complex conjugate of the element.

Mathematical Intuition:

For an element \(c = a + bi\), the conjugate is defined as:

\[\overline{c} = a - bi.\]

This operation is used in the computation of norms and is fundamental in normalizing elements of imaginary quadratic rings.

to_tuple() → tuple[float, float]

static zero() → Self

Returns the additive identity, \(0 + 0i\), in the complex wrapper.

Mathematical Intuition:

\[0 \in \mathbb{C}, \quad \text{such that } z + 0 = z.\]

Returns:

The zero element as a C object.

static mul_id() → Self

Returns the multiplicative identity, \(1 + 0i\), in the complex wrapper.

Mathematical Intuition:

\[1 \in \mathbb{C}, \quad \text{such that } z \cdot 1 = z.\]

Returns:

The identity element as a C object.

static norm(c: Self) → R

Computes the norm of a complex number.

Mathematical Intuition:

The norm is defined as:

\[\|c\| = \sqrt{a^2 + b^2} \quad \text{for } c = a+bi.\]

Parameters:

c -- A complex element.

Returns:

The norm as an element of R.

class algepy.QuadraticStructures.Q(n, d)

Bases: object

Represents an element of the quadratic rational field \(\mathbb{Q}(\sqrt{d})\) in standard form.

An element is stored in reduced form as:

\[q = \frac{n}{d}, \quad \text{with } \gcd(n,d)=1 \text{ and } d > 0.\]

Mathematical Intuition:

This representation ensures each element is uniquely determined by its numerator and denominator, analogous to a rational number.

reciprocal() → Self

Returns the multiplicative inverse of this rational element.

Mathematical Intuition:

For a nonzero \(\frac{n}{d}\), its reciprocal is:

\[\left(\frac{n}{d}\right)^{-1} = \frac{d}{n}.\]

Preconditions:

• \(\frac{n}{d} \neq 0\).

to_tuple() → tuple[int, int]

static zero() → Self

Returns the additive identity \(\frac{0}{1}\) in this rational form.

Mathematical Intuition:

\[0 \in \mathbb{Q}, \quad \text{such that } q + 0 = q.\]

Returns:

The zero element as a Q object.

static mul_id() → Self

Returns the multiplicative identity \(\frac{1}{1}\).

Mathematical Intuition:

\[1 \in \mathbb{Q}, \quad \text{such that } q \cdot 1 = q.\]

Returns:

The identity element as a Q object.

static abs(q: Self) → Self

class algepy.QuadraticStructures.QuadInt(a, b, d)

Bases: object

Represents an element of a quadratic integer ring (e.g. \(\mathbb{Z}[\sqrt{d}]\) or its half-integral variant).

An element is represented as:

\[a + b\omega,\]

where \(\omega = \sqrt{d}\) (or \(\omega = \frac{1+\sqrt{d}}{2}\) when \(d \equiv 1 \mod 4\)).

Mathematical Intuition:

Quadratic integers form an integral domain, and when the ring is a UFD, every element factors uniquely (up to units). The operations (addition, multiplication, etc.) follow the usual algebraic rules.

conjugate() → Self

Returns the conjugate of the quadratic integer.

Mathematical Intuition:

For an element

\[a + b\sqrt{d},\]

the conjugate is defined as:

\[a - b\sqrt{d}.\]

In the half-integral case (when \(d \equiv 1 \mod 4\)), the conjugation is adjusted accordingly.

static norm(z: Self) → Z

Computes the norm of a quadratic integer.

Mathematical Intuition:

For \(z = a + b\sqrt{d}\) (or its half-integral variant), the norm is given by:

\[N(z) = z \cdot \overline{z} = a^2 - d\,b^2.\]

The norm is an integer and is multiplicative.

static trace(z: Self) → Z

Computes the trace of a quadratic integer.

Mathematical Intuition:

The trace is defined as:

\[\operatorname{Tr}(z) = z + \overline{z} = 2a \quad \text{(for standard form)},\]

and is an integer.

inverse() → Self

Computes the inverse of a quadratic integer, when it exists.

Mathematical Intuition:

For a unit \(z\) (i.e., one with norm ±1), the inverse is given by:

\[z^{-1} = \frac{\overline{z}}{N(z)}.\]

Preconditions:

• \(z\) must be a unit (i.e., \(|N(z)| = 1\)).

Returns:

The inverse of \(z\).

Raises:

Exception -- If \(z\) is not a unit.

algepy.QuadraticStructures.QuadIntRing(d: int, force_ufd: bool = False) → Callable[[int, int], QuadInt]

Constructs the quadratic integer ring with generator \(\omega\) determined by d.

Mathematical Intuition:

• For a square-free integer \(d \neq 0,1\), the quadratic integer ring is given by:

  \[\mathbb{Z}[\sqrt{d}] \quad \text{if } d \not\equiv 1 \pmod{4},\]

  or

  \[\mathbb{Z}\left[\frac{1+\sqrt{d}}{2}\right] \quad \text{if } d \equiv 1 \pmod{4}.\]

• Additional operations (such as division in the Euclidean case, normalization, and factorization) are provided when the ring is known to be norm-Euclidean or a UFD.

Preconditions:

• \(d\) must be a square-free integer with \(d \not\in \{0,1\}\).

Parameters:

• d -- A square-free integer (not 0 or 1) representing the parameter of the quadratic field.

• known_ufd -- Boolean flag indicating if the ring is known to be a UFD.

Returns:

A callable class for constructing elements of the quadratic integer ring.

Raises:

Exception -- If d is invalid.

class algepy.QuadraticStructures.Quad_Z_(a, b, d=None)

Bases: QuadInt

NOTE: This is the subclass constructed by function QuadIntRing().

classmethod embed(z: Self) → R

Embeds a quadratic integer into the real numbers.

Mathematical Intuition:

For \(z = a + b\sqrt{d}\), the embedding is:

\[\sigma(z) = a + b\sqrt{d} \in \mathbb{R}.\]

epsilon = None

classmethod factorize(z: Self) → list[tuple[Self, Z]]

Factorizes a quadratic integer into irreducible factors (up to units).

Mathematical Intuition:

In a UFD, every nonzero non-unit element can be written uniquely (up to units) as:

\[z = \pi_1^{e_1} \pi_2^{e_2} \cdots \pi_k^{e_k}.\]

This method computes such a factorization by using the norm to guide a trial division approach. It terminates because the norm is a positive integer that strictly decreases with each factor extraction.

Preconditions:

• \(z\) must be a nonzero element of the quadratic integer ring.

Returns:

A list of tuples, each consisting of an irreducible factor and its exponent.

classmethod fundamental_unit() → Self

Computes the fundamental unit of the real quadratic ring.

Mathematical Intuition:

For \(\mathbb{Z}[\sqrt{d}]\) (or its half-integral variant), the fundamental unit \(\varepsilon\) is the smallest unit \(> 1\) (in absolute value) satisfying:

\[\varepsilon = x + y\sqrt{d} \quad \text{with} \quad x^2 - d\,y^2 = \pm 1.\]

The method uses a continued fraction approach.

Preconditions:

• \(d > 1\) and square-free.

classmethod gcd(w: Self, z: Self) → Self

Computes the greatest common divisor (gcd) of two quadratic integers via the Euclidean algorithm.

Mathematical Intuition:

In a Euclidean domain, for \(w\) and \(z\), the gcd is computed as:

\[\gcd(w, z) = \gcd(z, w \mod z),\]

iterated until the remainder is zero.

Preconditions:

• \(w\) and \(z\) belong to the same ring.

classmethod get_fundamental_unit() → Self

Returns the fundamental unit of the ring.

Mathematical Intuition:

The fundamental unit is the generator of the infinite part of the unit group in a real quadratic field.

classmethod internal_div(self: Self, z: Self) → Self

Computes the floor division of two quadratic integers.

Mathematical Intuition:

For norm-Euclidean domains, given \(w\) and a nonzero \(z\), there exists a quotient \(q\) and remainder \(r\) such that:

\[w = zq + r \quad \text{with} \quad N(r) < N(z).\]

This method returns the quotient \(q\).

Preconditions:

• \(z\) must be nonzero and belong to the same ring.

classmethod internal_mod(self: Self, z: Self) → Self

is_euclidean_domain = True

is_ufd = True

classmethod mul_id() → Self

Returns the multiplicative identity \(1\) in the quadratic integer ring.

Mathematical Intuition:

\[1 + 0\omega,\]

is the unique element satisfying \(z \cdot 1 = z\).

normalize() → Self

Returns the canonical representative (via normalization) of the associate class.

Mathematical Intuition:

For real quadratic rings, every element \(z\) has associates of the form \(\varepsilon^n z\) (with \(\varepsilon\) the fundamental unit). Normalization selects the unique representative \(z_{\mathrm{can}}\) such that:

\[1 \leq |\sigma(z_{\mathrm{can}})| < |\sigma(\varepsilon)|.\]

Preconditions:

• \(d > 1\).

omega = 5

classmethod unit_power(u: Self, n: int) → Self

classmethod zero() → Self

Returns the additive identity \(0\) in the quadratic integer ring.

Mathematical Intuition:

\[0 + 0\omega,\]

is the unique element satisfying \(z + 0 = z\).

class algepy.QuadraticStructures.QuadRat(a, b, d)

Bases: object

Represents an element of a quadratic rational field \(\mathbb{Q}(\sqrt{d})\) in standard form.

Each element is represented as:

\[a + b\sqrt{d}, \quad a,b \in \mathbb{Q},\]

where the representation is assumed to be in lowest terms.

Mathematical Intuition:

This class models the field \(\mathbb{Q}(\sqrt{d})\), in which every nonzero element is invertible. Arithmetic operations follow the usual rules for addition, multiplication, and inversion in a field.

conjugate() → Self

Returns the conjugate of a quadratic rational element.

Mathematical Intuition:

For an element \(q = a + b\sqrt{d} \in \mathbb{Q}(\sqrt{d})\), the conjugate is:

\[\overline{q} = a - b\sqrt{d}.\]

This operation is essential for computing the norm and inversion.

static norm(q: Self) → Q

Computes the norm of a quadratic rational element.

Mathematical Intuition:

For \(q = a + b\sqrt{d}\), the norm is given by:

\[N(q) = (a+b\sqrt{d})(a-b\sqrt{d}) = a^2 - d\,b^2.\]

The norm is a rational number.

static trace(q: Self) → Z

Computes the trace of a quadratic rational element.

Mathematical Intuition:

The trace is defined by:

\[\operatorname{Tr}(q) = q + \overline{q} = 2a.\]

It is an element of ℤ.

inverse() → Self

Computes the inverse of a nonzero quadratic rational element.

Mathematical Intuition:

Given \(q = a + b\sqrt{d}\) with nonzero norm, its inverse is:

\[q^{-1} = \frac{\overline{q}}{N(q)} = \frac{a-b\sqrt{d}}{a^2-d\,b^2}.\]

Preconditions:

• \(q\) must be nonzero.

algepy.QuadraticStructures.QuadRatField(d: int) → Callable[[Q, Q], QuadRat]

Constructs the quadratic rational field \(\mathbb{Q}(\sqrt{d})\) in standard form.

Mathematical Intuition:

For a square-free integer \(d \neq 0,1\), the field is:

\[\mathbb{Q}(\sqrt{d}) = \{\, a + b\sqrt{d} : a, b \in \mathbb{Q} \,\}.\]

The field is represented in standard form; all arithmetic operations follow the usual field properties.

Preconditions:

• \(d\) must be a nonzero square-free integer, and \(d \neq 1\).

Parameters:

d -- A square-free integer (not 0 or 1).

Returns:

A callable class for constructing elements of \(\mathbb{Q}(\sqrt{d})\).

Raises:

Exception -- If d is invalid.

class algepy.QuadraticStructures.Quad_Q_(a, b, d=None)

Bases: QuadRat

NOTE: This is the subclass constructed by function QuadRatField().

classmethod discriminant() → Z

Computes the field discriminant of \(\mathbb{Q}(\sqrt{d})\).

Mathematical Intuition:

The field discriminant is given by:

\[\begin{split}\Delta = \begin{cases} d, & \text{if } d \equiv 1 \mod 4, \\ 4d, & \text{otherwise.} \end{cases}\end{split}\]

Returns:

The discriminant as a Z object.

classmethod embed(q: Self) → R

Embeds an element \(q = a+b\sqrt{d}\) into \(\mathbb{R}\).

Mathematical Intuition:

The standard embedding is:

\[\sigma(q) = a + b\sqrt{d}.\]

Parameters:

q -- An element of \(\mathbb{Q}(\sqrt{d})\).

Returns:

The real number \(\sigma(q)\).

classmethod embed_prime(q: Self) → R

Provides the second real embedding for \(q = a+b\sqrt{d}\) into \(\mathbb{R}\).

Mathematical Intuition:

The second embedding is:

\[\sigma'(q) = a - b\sqrt{d}.\]

Parameters:

q -- An element of \(\mathbb{Q}(\sqrt{d})\).

Returns:

The real number \(\sigma'(q)\).

classmethod integer_ring()

omega = 5

algepy.SingletonStructures module

class algepy.SingletonStructures.Z(z: int)

Bases: object

Represents an element of the ring of integers, ℤ.

This class wraps a Python integer and implements standard arithmetic operations (addition, multiplication, subtraction, etc.) consistent with the algebraic structure of ℤ.

Preconditions:

• The input`z` must be a Python integer.

Mathematical Intuition:

The set ℤ is closed under addition, subtraction, and multiplication. In particular, for any integers \(a, b \in \mathbb{Z}\):

\[a + b \in \mathbb{Z}, \quad a - b \in \mathbb{Z}, \quad a \cdot b \in \mathbb{Z}.\]

This class provides operator overloading so that arithmetic in ℤ can be performed using natural syntax.

Parameters:

z -- An integer representing the element in ℤ.

Raises:

Exception -- If`z` is not an integer.

static zero() → Self

Returns the additive identity (0) in ℤ.

Mathematical Intuition:

The identity element \(0 \in \mathbb{Z}\) satisfies:

\[a + 0 = a \quad \forall a \in \mathbb{Z}.\]

Returns:

The integer 0 wrapped as a Z object.

static mul_id() → Self

Returns the multiplicative identity (1) in ℤ.

Mathematical Intuition:

The identity element \(1 \in \mathbb{Z}\) satisfies:

\[a \cdot 1 = a \quad \forall a \in \mathbb{Z}.\]

Returns:

The integer 1 wrapped as a Z object.

static abs(z: Self) → Self

Returns the absolute value of the integer element.

Mathematical Intuition:

The absolute value function is defined by:

\[\begin{split}|a| = \begin{cases} a, & a \ge 0 \\ -a, & a < 0 \end{cases}.\end{split}\]

Parameters:

z -- A Z object.

Returns:

A new Z object with the absolute value of z.

class algepy.SingletonStructures.R(r: float)

Bases: object

Represents an element of the field of real numbers, ℝ.

This class wraps a real number (float or int) and defines standard arithmetic operations as they occur in ℝ.

Preconditions:

• The input`r` must be a real number (either an int or a float).

Mathematical Intuition:

ℝ is a field; every nonzero element has a multiplicative inverse. For any \(r, s \in \mathbb{R}\):

\[r + s \in \mathbb{R}, \quad r \cdot s \in \mathbb{R}, \quad r - s \in \mathbb{R}, \quad \text{and if } r \neq 0,\; \frac{1}{r} \in \mathbb{R}.\]

This class models ℝ using floating-point arithmetic.

Parameters:

r -- A real number to be encapsulated as an element of ℝ.

Raises:

Exception -- If`r` is not a number.

static zero() → Self

Returns the additive identity (0.0) in ℝ.

Mathematical Intuition:

0 is the unique element satisfying:

\[r + 0 = r \quad \forall r \in \mathbb{R}.\]

Returns:

An R object representing 0.

static mul_id() → Self

Returns the multiplicative identity (1.0) in ℝ.

Mathematical Intuition:

1 is the unique element satisfying:

\[r \cdot 1 = r \quad \forall r \in \mathbb{R}.\]

Returns:

An R object representing 1.

static abs(a: Self) → Self

Returns the absolute value of a real number element.

Mathematical Intuition:

Defined as:

\[\begin{split}|r| = \begin{cases} r, & r \ge 0 \\ -r, & r < 0 \end{cases}.\end{split}\]

Parameters:

a -- An R object.

Returns:

An R object containing the absolute value of a.

class algepy.SingletonStructures.Z_n(z, n)

Bases: object

Represents an element of the ring of integers modulo n, ℤₙ.

Each element is stored as a residue class modulo n. Arithmetic operations are performed modulo n. This class supports addition, multiplication, subtraction, exponentiation, and, for units, computing inverses and orders.

Preconditions:

• The modulus`n` must be a positive integer.

• The element`z` must be a Python integer; it is automatically reduced modulo n.

Mathematical Intuition:

In ℤₙ, for an integer \(a\) and modulus \(n\):

\[a \mod n \in \{0, 1, \dots, n-1\},\]

and when n is prime, ℤₙ forms a field. This class models the residue classes with the usual modular arithmetic.

Parameters:

• z -- An integer representing the element in ℤ.

• n -- The modulus for the residue class.

Raises:

Exception -- If z or n is not an integer, or if n is invalid.

order() → Z

Compute the order of the element in the multiplicative group of units U(n).

Mathematical Intuition:

For an element \(a \in \mathbb{Z}_n\) that is invertible, its order is the smallest positive integer \(k\) such that:

\[a^k \equiv 1 \pmod{n}.\]

Preconditions:

• The element must be a unit (i.e., \(\gcd(a, n) = 1\)).

Returns:

A Z object representing the order.

Raises:

Exception -- If the element is not a unit.

inverse() → Self

Compute the multiplicative inverse of the element in ℤₙ.

Mathematical Intuition:

For a unit \(a \in \mathbb{Z}_n\) (with \(\gcd(a, n) = 1\)), there exists an inverse \(a^{-1}\) such that:

\[a \cdot a^{-1} \equiv 1 \pmod{n}.\]

Preconditions:

• The element must be a unit.

Returns:

A Z_n object representing the inverse.

Raises:

Exception -- If the element is not invertible.

algepy.SingletonStructures.Z_mod_(n: int) → Callable[[int], Z_n]

Returns a specialized constructor for the ring ℤₙ (integers modulo n).

Mathematical Intuition:

ℤₙ consists of residue classes:

\[\mathbb{Z}_n = \{0, 1, \dots, n-1\},\]

with operations defined modulo n. For prime n, ℤₙ is a field; for composite n, the unit group (the set of invertible elements) is given by:

\[U(n) = \{ a \in \mathbb{Z}_n : \gcd(a, n) = 1 \}.\]

This function returns a subclass of Z_n that encapsulates additional properties (e.g., cyclicity, primitive roots) depending on whether n is prime or composite.

Preconditions:

• n must be a positive integer (n ∈ ℕ, n > 0).

• n = 0 is not allowed.

Parameters:

n -- A positive integer representing the modulus.

Returns:

A callable (class) for constructing elements of ℤₙ with the given modulus.

Raises:

Exception -- If n is not a positive integer or if n equals 0.

algepy.SingletonStructures.Z__

alias of Z_

class algepy.SingletonStructures.Z_(z)

Bases: Z_n

NOTE: This is the subclass constructed by function Z_mod_().

classmethod elements() → list[Self]

classmethod is_cyclic() → bool

classmethod legendre(z: Self) → Z

Computes the Legendre symbol \(\left(\frac{a}{p}\right)\) for a in ℤ, where p is an odd prime.

Mathematical Intuition:

For an odd prime \(p\), the Legendre symbol is defined by:

\[\begin{split}\left(\frac{a}{p}\right) = \begin{cases} 0, & \text{if } p \mid a, \\ 1, & \text{if } a \text{ is a quadratic residue modulo } p, \\ -1, & \text{if } a \text{ is a non-residue modulo } p. \end{cases}\end{split}\]

Preconditions:

• p (here, the modulus) must be an odd prime.

Parameters:

z -- An element of ℤₙ.

Returns:

The Legendre symbol as a Z object.

Raises:

Exception -- If the modulus is 2.

modulus = 2

classmethod mul_id() → Self

classmethod primitive_roots() → Self

classmethod total_order() → Z

classmethod unit_order() → Z

classmethod units() → list[Self]

classmethod zero() → Self

Module contents