num_theory
==========

.. py:module:: num_theory


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/num_theory/arithmetic_progression/index
   /autoapi/num_theory/get_primes/index
   /autoapi/num_theory/is_prime/index
   /autoapi/num_theory/prime_factorization/index


Attributes
----------

.. autoapisummary::

   num_theory.__version__


Functions
---------

.. autoapisummary::

   num_theory.arithmetic_progression
   num_theory.is_prime
   num_theory.prime_factorization
   num_theory.get_primes


Package Contents
----------------

.. py:data:: __version__

.. py:function:: arithmetic_progression(a, d, n, compute_sum=False, nth_term=False)

   Generate terms of an arithmetic progression (AP), compute the nth term, or calculate the sum of the first n terms.

   :param a: The first term of the AP.
   :type a: float
   :param d: The common difference between consecutive terms.
   :type d: float
   :param n: The number of terms, the term to compute, or the term index.
   :type n: int
   :param compute_sum: If True, computes the sum of the first n terms. Default is False.
   :type compute_sum: bool, optional
   :param nth_term: If True, computes the nth term of the AP instead of generating terms. Default is False.
   :type nth_term: bool, optional

   :returns:

             - If `compute_sum` and `nth_term` are both False, returns a list of the first n terms of the AP.
             - If `nth_term` is True, returns the nth term as a float.
             - If `compute_sum` is True, returns the sum of the first n terms as a float.
             - If both `nth_term` and `compute_sum` is True, it will return the nth term as a float.
   :rtype: list or float

   .. rubric:: Examples

   >>> arithmetic_progression(a=2, d=3, n=5)
   [2, 5, 8, 11, 14]

   >>> arithmetic_progression(a=2, d=3, n=5, compute_sum=True)
   40.0

   >>> arithmetic_progression(a=2, d=3, n=5, nth_term=True)
   14

   >>> arithmetic_progression(a=1, d=2, n=5, nth_term=True)
   9


.. py:function:: is_prime(n)

   Check if a number is prime.

   :param n: The number to check for primality. Must be a positive integer greater than 1.
   :type n: int

   :returns: Returns True if the number is prime, otherwise False.
   :rtype: bool

   :raises ValueError: If the input is not a positive integer greater than 1.

   .. rubric:: Examples

   >>> is_prime(2)
   True
   >>> is_prime(4)
   False
   >>> is_prime(13)
   True


.. py:function:: prime_factorization(n)

   Compute the prime factorization of a given integer.

   :param n: The integer to factorize. Must be a positive integer greater than 1.
   :type n: int

   :returns: A list of tuples where each tuple represents a prime factor and its corresponding power.
             Example: For n=28, the output will be [(2, 2), (7, 1)], indicating 28 = 2^2 * 7^1.
   :rtype: list of tuple

   :raises ValueError: If the input `n` is not a positive integer greater than 1.

   .. rubric:: Examples

   >>> prime_factorization(28)
   [(2, 2), (7, 1)]

   >>> prime_factorization(100)
   [(2, 2), (5, 2)]

   .. rubric:: Notes

   - This function uses trial division to determine the prime factors.
   - For large values of `n`, consider optimized algorithms such as Pollard's Rho or
     the Quadratic Sieve for better performance.


.. py:function:: get_primes(num: int) -> list

   Returns the list of all prime numbers less than or equal to n.

   :param n:
   :type n: int.

   :rtype: list (containing integers)

   .. rubric:: Examples

   >>> get_primes(14)
   [2, 5, 7, 11, 13]

   >>> get_primes(5)
   [2, 5]

   >>> get_primes(-2)
   []