documentation and readthedocs initialization

.readthedocs.yaml

@@ -0,0 +1,26 @@
+
+
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#    install:
+#    - requirements: docs/requirements.txt
+
+

docs/num_theory_documentation.ipynb

@@ -0,0 +1,221 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# num-theory: Documentation\n",
+    "This notebook provides documentation for all functions within the num-theory package. It will include a multitude of examples to calrify how each of its functions is meant to be used.\n",
+    "\n",
+    "<img src=\"img/Spirale_Ulam_150.jpg\" alt=\"Ulam Spiral\" width=\"400\"/>\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Installation\n",
+    "To install the num-theory package, run the following command in your terminal:\n",
+    "    ```\n",
+    "    pip install num_theory\n",
+    "    ```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Running this command will install the num-theory package as well as all of its dependencies. After installing the package, you may import all of its functions or any specific one by using the following commands:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from num_theory import *                        # to import all functions from the package\n",
+    "from num_theory.get_primes import get_primes    # to import just the get_primes function\n",
+    "\n",
+    "from num_theory.prime_factorization import *    # how can we import all our functions at once???"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "## prime_factorization()\n",
+    "### Real World Application: Analyzing Prime Factor Distributions in Cryptography\n",
+    "\n",
+    "A cybersecurity researcher is investigating the factorization of large integers as part of a study on cryptographic algorithms, specifically RSA encryption. The security of RSA relies on the difficulty of factoring the product of two large prime numbers. To demonstrate this concept, the researcher uses the prime_factorization function to:\n",
+    "\n",
+    "1. Factorize smaller integers to explain the concept of prime factorization to a team of non-technical stakeholders.\n",
+    "2. Test and validate a set of randomly generated composite numbers to confirm their factorization as part of the cryptographic key analysis process.\n",
+    "3. Analyze the distribution of prime factors in datasets of composite numbers to study patterns or anomalies that may reveal vulnerabilities in certain key-generation techniques.\n",
+    "\n",
+    "This function serves as an educational tool and a basic analysis tool for smaller numbers, helping the researcher communicate and validate fundamental cryptographic concepts.\n",
+    "Examples\n",
+    "\n",
+    "Below are examples demonstrating the use of the prime_factorization function.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[(2, 2), (7, 1)]\n",
+      "[(2, 2), (5, 2)]\n",
+      "[(5, 1), (7, 1), (13, 1), (29, 1)]\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Example 1: Factorizing 28\n",
+    "print(prime_factorization(28))  # Output: [(2, 2), (7, 1)]\n",
+    "\n",
+    "# Example 2: Factorizing 100\n",
+    "print(prime_factorization(100))  # Output: [(2, 2), (5, 2)]\n",
+    "\n",
+    "# Example 3: Factorizing 13195\n",
+    "print(prime_factorization(13195))  # Output: [(5, 1), (7, 1), (13, 1), (29, 1)]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "### Additional notes\n",
+    "\n",
+    "1. Edge Cases:\n",
+    "   - Input validation ensures non-integers and integers <= 1 raise an error.\n",
+    "\n",
+    "2. Performance:\n",
+    "   - Efficient for small numbers.\n",
+    "   - May be slow for very large numbers due to the use of trial division.\n",
+    "\n",
+    "3. Future Improvements:\n",
+    "   - Implement more advanced factorization algorithms for better performance on large inputs.\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## get_primes()\n",
+    "\n",
+    "The \"get_primes()\" retrieves a list of all prime numbers under a given number. This list of prime numbers can aid you in solving Project Euler problems, creating hashing methods, as well as many other number theory and cryptography applications."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Example 1: Project Euler's prime numbers sum.\n",
+    "Project Euler's 10th problem states: \"Find the sum of all the primes below two million\". Using our \"get_primes()\" function trivializes this solution, as we can simply use Python's built-in \"sum()\" function with our function while passing 2,000,000 as the argument. Our function will retrieve the list of all primes under 2,000,000 and \"sum()\" will calculate thier sum to reach the answer."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "142913828922"
+      ]
+     },
+     "execution_count": 14,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from num_theory.get_primes import get_primes \n",
+    "\n",
+    "sum(get_primes(2000000))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Example 2: Hashing\n",
+    "Let's say you want to create a simple hash function that hashes a given number into a number within the range of 0 and 255. You can use the modulo \"%\" operation alongside a sum of our \"get_primes()\" function's output to create a simple algorithm that achieves this. please note that this hashing function is too primitive for most practical uses and is only used here to provide an easy to understand example."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "201\n",
+      "58\n",
+      "100\n"
+     ]
+    }
+   ],
+   "source": [
+    "def simple_hash(num: int) -> int:\n",
+    "    return sum(get_primes(num)) % 256\n",
+    "\n",
+    "print(simple_hash(2025))\n",
+    "print(simple_hash(1999))\n",
+    "print(simple_hash(23))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Additional notes\n",
+    "1. Edge cases:\n",
+    "    - This function will return an empty list for negative numbers, 0, and 1.\n",
+    "    - This function accepts fractional numbers but floors them so `get_primes(10.8)` is equivalent to `get_primes(10)`\n",
+    "2. Performance:\n",
+    "   - This algorithm has a time complexity of O(n log(log(n))) and a space complexity of O(n).\n",
+    "   - The get_primes() function uses a custom Sieve of Eratosthenes algorithm to retrieve the list of prime numbers. It does this by initializing a list of all number under n, then it iterates through all of them from the bottom to the top and assigns their multiples as non-primes. Once done, it leaves you with a list containing only prime numbers under n. \n",
+    "3. Future improvements:\n",
+    "- This function's utility could be improved through additional functionalities that can be selected through parameters (e.g., return the list reversed or return just the largest prime under n)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "524",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.1"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}