Merge branch 'master' into issue-12108

Author: cclauss

DIRECTORY.md

@@ -717,6 +717,7 @@
   * [Mini Batch Gradient Descent](machine_learning/mini_batch_gradient_descent.py)
   * [Multilayer Perceptron Classifier](machine_learning/multilayer_perceptron_classifier.py)
   * [Naive Bayes Text Classification](machine_learning/naive_bayes_text_classification.py)
+  * [Ordinary Least Squares Regression](machine_learning/ordinary_least_squares_regression.py)
   * [Polynomial Regression](machine_learning/polynomial_regression.py)
   * [Principle Component Analysis](machine_learning/principle_component_analysis.py)
   * [Q Learning](machine_learning/q_learning.py)

backtracking/m_coloring_problem.py

@@ -0,0 +1,86 @@
+def is_safe(
+    node: int,
+    color: int,
+    graph: list[list[int]],
+    num_vertices: int,
+    col: list[int],
+) -> bool:
+    """
+    Check if it is safe to assign a color to a node.
+
+    >>> is_safe(0, 1, [[0,1],[1,0]], 2, [0,1])
+    False
+    >>> is_safe(0, 2, [[0,1],[1,0]], 2, [0,1])
+    True
+    """
+    return all(
+        not (graph[node][k] == 1 and col[k] == color) for k in range(num_vertices)
+    )
+
+
+def solve(
+    node: int,
+    col: list[int],
+    max_colors: int,
+    num_vertices: int,
+    graph: list[list[int]],
+) -> bool:
+    """
+    Recursively try to color the graph using at most max_colors.
+
+    >>> solve(0, [0]*3, 3, 3, [[0,1,0],[1,0,1],[0,1,0]])
+    True
+    >>> solve(0, [0]*3, 2, 3, [[0,1,0],[1,0,1],[0,1,0]])
+    True
+    """
+    if node == num_vertices:
+        return True
+    for c in range(1, max_colors + 1):
+        if is_safe(node, c, graph, num_vertices, col):
+            col[node] = c
+            if solve(node + 1, col, max_colors, num_vertices, graph):
+                return True
+            col[node] = 0
+    return False
+
+
+def graph_coloring(graph: list[list[int]], max_colors: int, num_vertices: int) -> bool:
+    """
+    Determine if the graph can be colored with at most max_colors.
+
+    >>> graph_coloring([[0,1,1],[1,0,1],[1,1,0]], 3, 3)
+    True
+    >>> graph_coloring([[0,1,1],[1,0,1],[1,1,0]], 2, 3)
+    False
+    """
+    col = [0] * num_vertices
+    return solve(0, col, max_colors, num_vertices, graph)
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()
+
+    num_vertices = int(input("Enter vertices: "))
+    num_edges = int(input("Enter edges: "))
+    graph = [[0] * num_vertices for _ in range(num_vertices)]
+
+    print("Enter edges (u v):")
+    for _ in range(num_edges):
+        try:
+            u, v = map(int, input().split())
+            if 0 <= u < num_vertices and 0 <= v < num_vertices:
+                graph[u][v] = 1
+                graph[v][u] = 1
+            else:
+                print("Invalid edge.")
+        except ValueError:
+            print("Invalid input.")
+
+    max_colors = int(input("Enter max colors: "))
+
+    if graph_coloring(graph, max_colors, num_vertices):
+        print("Coloring possible.")
+    else:
+        print("Coloring not possible.")

blockchain/merkle_tree.py

@@ -0,0 +1,107 @@
+"""
+Merkle Tree Construction and Verification
+
+This module implements the construction of a Merkle Tree and
+verification of inclusion proofs for blockchain data integrity.
+
+Each leaf is a SHA-256 hash of a transaction, and internal nodes are
+computed by hashing the concatenation of their child nodes.
+
+References:
+https://en.wikipedia.org/wiki/Merkle_tree
+"""
+
+import hashlib
+
+
+def sha256(data: str) -> str:
+    """
+    Compute the SHA-256 hash of the given string.
+
+    Args:
+        data (str): Input string.
+
+    Returns:
+        str: Hexadecimal SHA-256 hash of the input.
+
+    Example:
+        >>> sha256("abc")
+        'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad'
+    """
+    return hashlib.sha256(data.encode()).hexdigest()
+
+
+def build_merkle_tree(leaves: list[str]) -> list[list[str]]:
+    """
+    Build a Merkle Tree from the given leaf nodes.
+
+    Args:
+        leaves: List of data strings (transactions).
+
+    Returns:
+        A list of lists representing tree levels,
+        with the last level containing the Merkle root.
+
+    >>> len(build_merkle_tree(["a", "b", "c", "d"])[-1][0])
+    64
+    """
+    if not leaves:
+        raise ValueError("Leaf list cannot be empty.")
+
+    current_level = [sha256(x) for x in leaves]
+    tree = [current_level]
+
+    while len(current_level) > 1:
+        next_level = []
+        for i in range(0, len(current_level), 2):
+            left = current_level[i]
+            right = current_level[i + 1] if i + 1 < len(current_level) else left
+            next_level.append(sha256(left + right))
+        current_level = next_level
+        tree.append(current_level)
+
+    return tree
+
+
+def merkle_root(leaves: list[str]) -> str:
+    """
+    Return the Merkle root hash for a given list of data.
+
+    >>> r = merkle_root(["tx1", "tx2", "tx3"])
+    >>> isinstance(r, str)
+    True
+    """
+    return build_merkle_tree(leaves)[-1][0]
+
+
+def verify_proof(leaf: str, proof: list[str], root: str) -> bool:
+    """
+    Verify inclusion of a leaf using a Merkle proof.
+
+    Args:
+        leaf: Original data string.
+        proof: List of sibling hashes up the path.
+        root: Expected Merkle root hash.
+
+    Returns:
+        True if proof is valid, else False.
+
+    >>> data = ["a", "b", "c", "d"]
+    >>> tree = build_merkle_tree(data)
+    >>> root = tree[-1][0]
+    >>> leaf = "a"
+    >>> proof = [sha256("b"), sha256(sha256("c") + sha256("d"))]
+    >>> verify_proof(leaf, proof, root)
+    True
+    """
+    computed_hash = sha256(leaf)
+    for sibling in proof:
+        combined = sha256(computed_hash + sibling)
+        computed_hash = combined
+    return computed_hash == root
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

blockchain/simple_blockchain.py

@@ -0,0 +1,168 @@
+"""
+A simple blockchain implementation with Proof-of-Work (PoW).
+
+This educational example demonstrates:
+- Block structure with index, timestamp, data, previous hash, nonce, and hash
+- Mining via Proof-of-Work
+- Chain integrity verification
+
+Author: Letitia Gilbert
+"""
+
+import hashlib
+from time import time
+
+
+class Block:
+    """
+    Represents a single block in a blockchain.
+
+    Attributes:
+        index (int): Position of the block in the chain.
+        timestamp (float): Creation time of the block.
+        data (str): Data stored in the block.
+        previous_hash (str): Hash of the previous block.
+        nonce (int): Number used for mining.
+        hash (str): SHA256 hash of the block's content.
+    """
+
+    def __init__(
+        self, index: int, data: str, previous_hash: str, difficulty: int = 2
+    ) -> None:
+        self.index = index
+        self.timestamp = time()
+        self.data = data
+        self.previous_hash = previous_hash
+        self.nonce, self.hash = self.mine_block(difficulty)
+
+    def compute_hash(self, nonce: int) -> str:
+        """
+        Compute SHA256 hash of the block with given nonce.
+
+        Args:
+            nonce (int): Nonce to include in the hash.
+
+        Returns:
+            str: Hexadecimal hash string.
+
+        >>> block = Block(0, "Genesis", "0", difficulty=2)
+        >>> len(block.compute_hash(0)) == 64
+        True
+        >>> isinstance(block.compute_hash(0), str)
+        True
+        """
+        block_string = (
+            f"{self.index}{self.timestamp}{self.data}{self.previous_hash}{nonce}"
+        )
+        return hashlib.sha256(block_string.encode()).hexdigest()
+
+    def mine_block(self, difficulty: int) -> tuple[int, str]:
+        """
+        Simple Proof-of-Work mining algorithm.
+
+        Args:
+            difficulty (int): Number of leading zeros required in the hash.
+
+        Returns:
+            Tuple[int, str]: Valid nonce and resulting hash that satisfies difficulty.
+
+        >>> block = Block(0, "Genesis", "0", difficulty=2)
+        >>> block.hash.startswith('00')
+        True
+        """
+        if difficulty < 1:
+            raise ValueError("Difficulty must be at least 1")
+        nonce = 0
+        target = "0" * difficulty
+        while True:
+            hash_result = self.compute_hash(nonce)
+            if hash_result.startswith(target):
+                return nonce, hash_result
+            nonce += 1
+
+
+class Blockchain:
+    """
+    Simple blockchain class maintaining a list of blocks.
+
+    Attributes:
+        chain (List[Block]): List of blocks forming the chain.
+    """
+
+    def __init__(self, difficulty: int = 2) -> None:
+        self.difficulty = difficulty
+        self.chain: list[Block] = [self.create_genesis_block()]
+
+    def create_genesis_block(self) -> Block:
+        """
+        Create the first block in the blockchain.
+
+        Returns:
+            Block: Genesis block.
+
+        >>> bc = Blockchain()
+        >>> bc.chain[0].index
+        0
+        >>> bc.chain[0].hash.startswith('00')
+        True
+        """
+        return Block(0, "Genesis Block", "0", self.difficulty)
+
+    def add_block(self, data: str) -> Block:
+        """
+        Add a new block to the blockchain with given data.
+
+        Args:
+            data (str): Data to store in the block.
+
+        Returns:
+            Block: Newly added block.
+
+        >>> bc = Blockchain()
+        >>> new_block = bc.add_block("Test Data")
+        >>> new_block.index
+        1
+        >>> new_block.previous_hash == bc.chain[0].hash
+        True
+        >>> new_block.hash.startswith('00')
+        True
+        >>> bc.is_valid()
+        True
+        """
+        prev_hash = self.chain[-1].hash
+        new_block = Block(len(self.chain), data, prev_hash, self.difficulty)
+        self.chain.append(new_block)
+        return new_block
+
+    def is_valid(self) -> bool:
+        """
+        Verify the integrity of the blockchain.
+
+        Returns:
+            bool: True if chain is valid, False otherwise.
+
+        >>> bc = Blockchain()
+        >>> new_block = bc.add_block("Test")
+        >>> new_block.index
+        1
+        >>> new_block.previous_hash == bc.chain[0].hash
+        True
+        >>> new_block.hash.startswith('00')
+        True
+        >>> bc.is_valid()
+        True
+        >>> bc.chain[1].previous_hash = "tampered"
+        >>> bc.is_valid()
+        False
+
+        """
+        for i in range(1, len(self.chain)):
+            current = self.chain[i]
+            prev = self.chain[i - 1]
+            if current.previous_hash != prev.hash:
+                return False
+            if not current.hash.startswith("0" * self.difficulty):
+                return False
+            if current.hash != current.compute_hash(current.nonce):
+                return False
+        return True