Fix function name in erosion_operation.py doctest

* updating DIRECTORY.md

* added continued fractions

* updating DIRECTORY.md

* Update maths/continued_fraction.py

Co-authored-by: Caeden Perelli-Harris <caedenperelliharris@gmail.com>

* Update maths/continued_fraction.py

Co-authored-by: Caeden Perelli-Harris <caedenperelliharris@gmail.com>

---------

Co-authored-by: github-actions <${GITHUB_ACTOR}@users.noreply.github.com>
Co-authored-by: Caeden Perelli-Harris <caedenperelliharris@gmail.com>
Co-authored-by: Tianyi Zheng <tianyizheng02@gmail.com>

.devcontainer/Dockerfile

@@ -0,0 +1,8 @@
+# https://github.com/microsoft/vscode-dev-containers/blob/main/containers/python-3/README.md
+ARG VARIANT=3.11-bookworm
+FROM mcr.microsoft.com/vscode/devcontainers/python:${VARIANT}
+COPY requirements.txt /tmp/pip-tmp/
+RUN python3 -m pip install --upgrade pip \
+  && python3 -m pip install --no-cache-dir install -r /tmp/pip-tmp/requirements.txt \
+  && pipx install pre-commit ruff \
+  && pre-commit install

.devcontainer/devcontainer.json

@@ -0,0 +1,42 @@
+{
+	"name": "Python 3",
+	"build": {
+		"dockerfile": "Dockerfile",
+		"context": "..",
+		"args": {
+			// Update 'VARIANT' to pick a Python version: 3, 3.10, 3.9, 3.8, 3.7, 3.6
+			// Append -bullseye or -buster to pin to an OS version.
+			// Use -bullseye variants on local on arm64/Apple Silicon.
+			"VARIANT": "3.11-bookworm",
+		}
+	},
+
+	// Configure tool-specific properties.
+	"customizations": {
+		// Configure properties specific to VS Code.
+		"vscode": {
+			// Set *default* container specific settings.json values on container create.
+			"settings": {
+				"python.defaultInterpreterPath": "/usr/local/bin/python",
+				"python.linting.enabled": true,
+				"python.formatting.blackPath": "/usr/local/py-utils/bin/black",
+				"python.linting.mypyPath": "/usr/local/py-utils/bin/mypy"
+			},
+
+			// Add the IDs of extensions you want installed when the container is created.
+			"extensions": [
+				"ms-python.python",
+				"ms-python.vscode-pylance"
+			]
+		}
+	},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	// "postCreateCommand": "pip3 install --user -r requirements.txt",
+
+	// Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+	"remoteUser": "vscode"
+}

.github/pull_request_template.md

@@ -17,4 +17,4 @@
 * [ ] All function parameters and return values are annotated with Python [type hints](https://docs.python.org/3/library/typing.html).
 * [ ] All functions have [doctests](https://docs.python.org/3/library/doctest.html) that pass the automated testing.
 * [ ] All new algorithms include at least one URL that points to Wikipedia or another similar explanation.
-* [ ] If this pull request resolves one or more open issues then the commit message contains `Fixes: #{$ISSUE_NO}`.
+* [ ] If this pull request resolves one or more open issues then the description above includes the issue number(s) with a [closing keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue): "Fixes #ISSUE-NUMBER".

.github/workflows/build.yml

@@ -22,11 +22,9 @@ jobs:
           python -m pip install --upgrade pip setuptools six wheel
           python -m pip install pytest-cov -r requirements.txt
       - name: Run tests
-        # See: #6591 for re-enabling tests on Python v3.11
+        # TODO: #8818 Re-enable quantum tests
         run: pytest
-            --ignore=computer_vision/cnn_classification.py
+            --ignore=quantum/q_fourier_transform.py
-            --ignore=machine_learning/lstm/lstm_prediction.py
-            --ignore=quantum/
             --ignore=project_euler/
             --ignore=scripts/validate_solutions.py
             --cov-report=term-missing:skip-covered

.pre-commit-config.yaml

@@ -15,25 +15,25 @@ repos:
     hooks:
     -   id: auto-walrus
 
-  - repo: https://github.com/charliermarsh/ruff-pre-commit
+  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.0.270
+    rev: v0.0.284
     hooks:
       - id: ruff
 
   - repo: https://github.com/psf/black
-    rev: 23.3.0
+    rev: 23.7.0
     hooks:
       - id: black
 
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.2.4
+    rev: v2.2.5
     hooks:
       - id: codespell
         additional_dependencies:
           - tomli
 
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: "0.11.2"
+    rev: "0.13.1"
     hooks:
       - id: pyproject-fmt
 
@@ -51,7 +51,7 @@ repos:
       - id: validate-pyproject
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.3.0
+    rev: v1.5.0
     hooks:
       - id: mypy
         args:

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "githubPullRequests.ignoredPullRequestBranches": [
+        "master"
+    ]
+}

CONTRIBUTING.md

@@ -25,7 +25,14 @@ We appreciate any contribution, from fixing a grammar mistake in a comment to im
 
 Your contribution will be tested by our [automated testing on GitHub Actions](https://github.com/TheAlgorithms/Python/actions) to save time and mental energy.  After you have submitted your pull request, you should see the GitHub Actions tests start to run at the bottom of your submission page.  If those tests fail, then click on the ___details___ button try to read through the GitHub Actions output to understand the failure.  If you do not understand, please leave a comment on your submission page and a community member will try to help.
 
-Please help us keep our issue list small by adding fixes: #{$ISSUE_NO} to the commit message of pull requests that resolve open issues. GitHub will use this tag to auto-close the issue when the PR is merged.
+If you are interested in resolving an [open issue](https://github.com/TheAlgorithms/Python/issues), simply make a pull request with your proposed fix. __We do not assign issues in this repo__ so please do not ask for permission to work on an issue.
+
+Please help us keep our issue list small by adding `Fixes #{$ISSUE_NUMBER}` to the description of pull requests that resolve open issues.
+For example, if your pull request fixes issue #10, then please add the following to its description:
+```
+Fixes #10
+```
+GitHub will use this tag to [auto-close the issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) if and when the PR is merged.
 
 #### What is an Algorithm?
 

DIRECTORY.md

@@ -29,6 +29,7 @@
   * [Minmax](backtracking/minmax.py)
   * [N Queens](backtracking/n_queens.py)
   * [N Queens Math](backtracking/n_queens_math.py)
+  * [Power Sum](backtracking/power_sum.py)
   * [Rat In Maze](backtracking/rat_in_maze.py)
   * [Sudoku](backtracking/sudoku.py)
   * [Sum Of Subsets](backtracking/sum_of_subsets.py)
@@ -73,6 +74,7 @@
   * [Game Of Life](cellular_automata/game_of_life.py)
   * [Nagel Schrekenberg](cellular_automata/nagel_schrekenberg.py)
   * [One Dimensional](cellular_automata/one_dimensional.py)
+  * [Wa Tor](cellular_automata/wa_tor.py)
 
 ## Ciphers
   * [A1Z26](ciphers/a1z26.py)
@@ -146,6 +148,7 @@
   * [Decimal To Binary Recursion](conversions/decimal_to_binary_recursion.py)
   * [Decimal To Hexadecimal](conversions/decimal_to_hexadecimal.py)
   * [Decimal To Octal](conversions/decimal_to_octal.py)
+  * [Energy Conversions](conversions/energy_conversions.py)
   * [Excel Title To Column](conversions/excel_title_to_column.py)
   * [Hex To Bin](conversions/hex_to_bin.py)
   * [Hexadecimal To Decimal](conversions/hexadecimal_to_decimal.py)
@@ -166,6 +169,7 @@
   * Arrays
     * [Permutations](data_structures/arrays/permutations.py)
     * [Prefix Sum](data_structures/arrays/prefix_sum.py)
+    * [Product Sum](data_structures/arrays/product_sum.py)
   * Binary Tree
     * [Avl Tree](data_structures/binary_tree/avl_tree.py)
     * [Basic Binary Tree](data_structures/binary_tree/basic_binary_tree.py)
@@ -233,8 +237,8 @@
     * [Double Ended Queue](data_structures/queue/double_ended_queue.py)
     * [Linked Queue](data_structures/queue/linked_queue.py)
     * [Priority Queue Using List](data_structures/queue/priority_queue_using_list.py)
+    * [Queue By List](data_structures/queue/queue_by_list.py)
     * [Queue By Two Stacks](data_structures/queue/queue_by_two_stacks.py)
-    * [Queue On List](data_structures/queue/queue_on_list.py)
     * [Queue On Pseudo Stack](data_structures/queue/queue_on_pseudo_stack.py)
   * Stacks
     * [Balanced Parentheses](data_structures/stacks/balanced_parentheses.py)
@@ -290,7 +294,7 @@
   * [Inversions](divide_and_conquer/inversions.py)
   * [Kth Order Statistic](divide_and_conquer/kth_order_statistic.py)
   * [Max Difference Pair](divide_and_conquer/max_difference_pair.py)
-  * [Max Subarray Sum](divide_and_conquer/max_subarray_sum.py)
+  * [Max Subarray](divide_and_conquer/max_subarray.py)
   * [Mergesort](divide_and_conquer/mergesort.py)
   * [Peak](divide_and_conquer/peak.py)
   * [Power](divide_and_conquer/power.py)
@@ -321,8 +325,7 @@
   * [Matrix Chain Order](dynamic_programming/matrix_chain_order.py)
   * [Max Non Adjacent Sum](dynamic_programming/max_non_adjacent_sum.py)
   * [Max Product Subarray](dynamic_programming/max_product_subarray.py)
-  * [Max Sub Array](dynamic_programming/max_sub_array.py)
+  * [Max Subarray Sum](dynamic_programming/max_subarray_sum.py)
-  * [Max Sum Contiguous Subsequence](dynamic_programming/max_sum_contiguous_subsequence.py)
   * [Min Distance Up Bottom](dynamic_programming/min_distance_up_bottom.py)
   * [Minimum Coin Change](dynamic_programming/minimum_coin_change.py)
   * [Minimum Cost Path](dynamic_programming/minimum_cost_path.py)
@@ -333,9 +336,11 @@
   * [Minimum Tickets Cost](dynamic_programming/minimum_tickets_cost.py)
   * [Optimal Binary Search Tree](dynamic_programming/optimal_binary_search_tree.py)
   * [Palindrome Partitioning](dynamic_programming/palindrome_partitioning.py)
+  * [Regex Match](dynamic_programming/regex_match.py)
   * [Rod Cutting](dynamic_programming/rod_cutting.py)
   * [Subset Generation](dynamic_programming/subset_generation.py)
   * [Sum Of Subset](dynamic_programming/sum_of_subset.py)
+  * [Tribonacci](dynamic_programming/tribonacci.py)
   * [Viterbi](dynamic_programming/viterbi.py)
   * [Word Break](dynamic_programming/word_break.py)
 
@@ -410,6 +415,7 @@
   * [Dijkstra 2](graphs/dijkstra_2.py)
   * [Dijkstra Algorithm](graphs/dijkstra_algorithm.py)
   * [Dijkstra Alternate](graphs/dijkstra_alternate.py)
+  * [Dijkstra Binary Grid](graphs/dijkstra_binary_grid.py)
   * [Dinic](graphs/dinic.py)
   * [Directed And Undirected (Weighted) Graph](graphs/directed_and_undirected_(weighted)_graph.py)
   * [Edmonds Karp Multiple Source And Sink](graphs/edmonds_karp_multiple_source_and_sink.py)
@@ -419,8 +425,9 @@
   * [Frequent Pattern Graph Miner](graphs/frequent_pattern_graph_miner.py)
   * [G Topological Sort](graphs/g_topological_sort.py)
   * [Gale Shapley Bigraph](graphs/gale_shapley_bigraph.py)
+  * [Graph Adjacency List](graphs/graph_adjacency_list.py)
+  * [Graph Adjacency Matrix](graphs/graph_adjacency_matrix.py)
   * [Graph List](graphs/graph_list.py)
-  * [Graph Matrix](graphs/graph_matrix.py)
   * [Graphs Floyd Warshall](graphs/graphs_floyd_warshall.py)
   * [Greedy Best First](graphs/greedy_best_first.py)
   * [Greedy Min Vertex Cover](graphs/greedy_min_vertex_cover.py)
@@ -479,11 +486,15 @@
     * [Lib](linear_algebra/src/lib.py)
     * [Polynom For Points](linear_algebra/src/polynom_for_points.py)
     * [Power Iteration](linear_algebra/src/power_iteration.py)
+    * [Rank Of Matrix](linear_algebra/src/rank_of_matrix.py)
     * [Rayleigh Quotient](linear_algebra/src/rayleigh_quotient.py)
     * [Schur Complement](linear_algebra/src/schur_complement.py)
     * [Test Linear Algebra](linear_algebra/src/test_linear_algebra.py)
     * [Transformations 2D](linear_algebra/src/transformations_2d.py)
 
+## Linear Programming
+  * [Simplex](linear_programming/simplex.py)
+
 ## Machine Learning
   * [Astar](machine_learning/astar.py)
   * [Data Transformations](machine_learning/data_transformations.py)
@@ -503,7 +514,7 @@
   * Lstm
     * [Lstm Prediction](machine_learning/lstm/lstm_prediction.py)
   * [Multilayer Perceptron Classifier](machine_learning/multilayer_perceptron_classifier.py)
-  * [Polymonial Regression](machine_learning/polymonial_regression.py)
+  * [Polynomial Regression](machine_learning/polynomial_regression.py)
   * [Scoring Functions](machine_learning/scoring_functions.py)
   * [Self Organizing Map](machine_learning/self_organizing_map.py)
   * [Sequential Minimum Optimization](machine_learning/sequential_minimum_optimization.py)
@@ -514,7 +525,6 @@
   * [Xgboost Regressor](machine_learning/xgboost_regressor.py)
 
 ## Maths
-  * [3N Plus 1](maths/3n_plus_1.py)
   * [Abs](maths/abs.py)
   * [Add](maths/add.py)
   * [Addition Without Arithmetic](maths/addition_without_arithmetic.py)
@@ -545,6 +555,7 @@
   * [Chudnovsky Algorithm](maths/chudnovsky_algorithm.py)
   * [Collatz Sequence](maths/collatz_sequence.py)
   * [Combinations](maths/combinations.py)
+  * [Continued Fraction](maths/continued_fraction.py)
   * [Decimal Isolate](maths/decimal_isolate.py)
   * [Decimal To Fraction](maths/decimal_to_fraction.py)
   * [Dodecahedron](maths/dodecahedron.py)
@@ -563,9 +574,7 @@
   * [Fermat Little Theorem](maths/fermat_little_theorem.py)
   * [Fibonacci](maths/fibonacci.py)
   * [Find Max](maths/find_max.py)
-  * [Find Max Recursion](maths/find_max_recursion.py)
   * [Find Min](maths/find_min.py)
-  * [Find Min Recursion](maths/find_min_recursion.py)
   * [Floor](maths/floor.py)
   * [Gamma](maths/gamma.py)
   * [Gamma Recursive](maths/gamma_recursive.py)
@@ -578,17 +587,16 @@
   * [Hardy Ramanujanalgo](maths/hardy_ramanujanalgo.py)
   * [Hexagonal Number](maths/hexagonal_number.py)
   * [Integration By Simpson Approx](maths/integration_by_simpson_approx.py)
+  * [Interquartile Range](maths/interquartile_range.py)
   * [Is Int Palindrome](maths/is_int_palindrome.py)
   * [Is Ip V4 Address Valid](maths/is_ip_v4_address_valid.py)
   * [Is Square Free](maths/is_square_free.py)
   * [Jaccard Similarity](maths/jaccard_similarity.py)
   * [Juggler Sequence](maths/juggler_sequence.py)
-  * [Kadanes](maths/kadanes.py)
   * [Karatsuba](maths/karatsuba.py)
   * [Krishnamurthy Number](maths/krishnamurthy_number.py)
   * [Kth Lexicographic Permutation](maths/kth_lexicographic_permutation.py)
   * [Largest Of Very Large Numbers](maths/largest_of_very_large_numbers.py)
-  * [Largest Subarray Sum](maths/largest_subarray_sum.py)
   * [Least Common Multiple](maths/least_common_multiple.py)
   * [Line Length](maths/line_length.py)
   * [Liouville Lambda](maths/liouville_lambda.py)
@@ -651,6 +659,7 @@
   * [Sigmoid Linear Unit](maths/sigmoid_linear_unit.py)
   * [Signum](maths/signum.py)
   * [Simpson Rule](maths/simpson_rule.py)
+  * [Simultaneous Linear Equation Solver](maths/simultaneous_linear_equation_solver.py)
   * [Sin](maths/sin.py)
   * [Sock Merchant](maths/sock_merchant.py)
   * [Softmax](maths/softmax.py)
@@ -676,6 +685,7 @@
 ## Matrix
   * [Binary Search Matrix](matrix/binary_search_matrix.py)
   * [Count Islands In Matrix](matrix/count_islands_in_matrix.py)
+  * [Count Negative Numbers In Sorted Matrix](matrix/count_negative_numbers_in_sorted_matrix.py)
   * [Count Paths](matrix/count_paths.py)
   * [Cramers Rule 2X2](matrix/cramers_rule_2x2.py)
   * [Inverse Of Matrix](matrix/inverse_of_matrix.py)
@@ -702,7 +712,6 @@
     * [Exponential Linear Unit](neural_network/activation_functions/exponential_linear_unit.py)
   * [Back Propagation Neural Network](neural_network/back_propagation_neural_network.py)
   * [Convolution Neural Network](neural_network/convolution_neural_network.py)
-  * [Input Data](neural_network/input_data.py)
   * [Perceptron](neural_network/perceptron.py)
   * [Simple Neural Network](neural_network/simple_neural_network.py)
 
@@ -723,9 +732,9 @@
   * [Linear Congruential Generator](other/linear_congruential_generator.py)
   * [Lru Cache](other/lru_cache.py)
   * [Magicdiamondpattern](other/magicdiamondpattern.py)
-  * [Maximum Subarray](other/maximum_subarray.py)
   * [Maximum Subsequence](other/maximum_subsequence.py)
   * [Nested Brackets](other/nested_brackets.py)
+  * [Number Container System](other/number_container_system.py)
   * [Password](other/password.py)
   * [Quine](other/quine.py)
   * [Scoring Algorithm](other/scoring_algorithm.py)
@@ -733,7 +742,9 @@
   * [Tower Of Hanoi](other/tower_of_hanoi.py)
 
 ## Physics
+  * [Altitude Pressure](physics/altitude_pressure.py)
   * [Archimedes Principle](physics/archimedes_principle.py)
+  * [Basic Orbital Capture](physics/basic_orbital_capture.py)
   * [Casimir Effect](physics/casimir_effect.py)
   * [Centripetal Force](physics/centripetal_force.py)
   * [Grahams Law](physics/grahams_law.py)
@@ -749,6 +760,7 @@
   * [Potential Energy](physics/potential_energy.py)
   * [Rms Speed Of Molecule](physics/rms_speed_of_molecule.py)
   * [Shear Stress](physics/shear_stress.py)
+  * [Speed Of Sound](physics/speed_of_sound.py)
 
 ## Project Euler
   * Problem 001
@@ -1054,7 +1066,6 @@
   * [Q Fourier Transform](quantum/q_fourier_transform.py)
   * [Q Full Adder](quantum/q_full_adder.py)
   * [Quantum Entanglement](quantum/quantum_entanglement.py)
-  * [Quantum Random](quantum/quantum_random.py)
   * [Quantum Teleportation](quantum/quantum_teleportation.py)
   * [Ripple Adder Classic](quantum/ripple_adder_classic.py)
   * [Single Qubit Measure](quantum/single_qubit_measure.py)
@@ -1160,6 +1171,7 @@
   * [Is Pangram](strings/is_pangram.py)
   * [Is Spain National Id](strings/is_spain_national_id.py)
   * [Is Srilankan Phone Number](strings/is_srilankan_phone_number.py)
+  * [Is Valid Email Address](strings/is_valid_email_address.py)
   * [Jaro Winkler](strings/jaro_winkler.py)
   * [Join](strings/join.py)
   * [Knuth Morris Pratt](strings/knuth_morris_pratt.py)

README.md

@@ -13,7 +13,7 @@
     <img src="https://img.shields.io/static/v1.svg?label=Contributions&message=Welcome&color=0059b3&style=flat-square" height="20" alt="Contributions Welcome">
   </a>
   <img src="https://img.shields.io/github/repo-size/TheAlgorithms/Python.svg?label=Repo%20size&style=flat-square" height="20">
-  <a href="https://discord.gg/c7MnfGFGa6">
+  <a href="https://the-algorithms.com/discord">
     <img src="https://img.shields.io/discord/808045925556682782.svg?logo=discord&colorB=7289DA&style=flat-square" height="20" alt="Discord chat">
   </a>
   <a href="https://gitter.im/TheAlgorithms/community">
@@ -42,7 +42,7 @@ Read through our [Contribution Guidelines](CONTRIBUTING.md) before you contribut
 
 ## Community Channels
 
-We are on [Discord](https://discord.gg/c7MnfGFGa6) and [Gitter](https://gitter.im/TheAlgorithms/community)! Community channels are a great way for you to ask questions and get help. Please join us!
+We are on [Discord](https://the-algorithms.com/discord) and [Gitter](https://gitter.im/TheAlgorithms/community)! Community channels are a great way for you to ask questions and get help. Please join us!
 
 ## List of Algorithms
 

arithmetic_analysis/newton_raphson.py

@@ -25,9 +25,11 @@ def newton_raphson(
     """
     x = a
     while True:
-        x = Decimal(x) - (Decimal(eval(func)) / Decimal(eval(str(diff(func)))))
+        x = Decimal(x) - (
+            Decimal(eval(func)) / Decimal(eval(str(diff(func))))  # noqa: S307
+        )
         # This number dictates the accuracy of the answer
-        if abs(eval(func)) < precision:
+        if abs(eval(func)) < precision:  # noqa: S307
             return float(x)
 
 

backtracking/power_sum.py

@@ -0,0 +1,93 @@
+"""
+Problem source: https://www.hackerrank.com/challenges/the-power-sum/problem
+Find the number of ways that a given integer X, can be expressed as the sum
+of the Nth powers of unique, natural numbers. For example, if X=13 and N=2.
+We have to find all combinations of unique squares adding up to 13.
+The only solution is 2^2+3^2. Constraints: 1<=X<=1000, 2<=N<=10.
+"""
+
+from math import pow
+
+
+def backtrack(
+    needed_sum: int,
+    power: int,
+    current_number: int,
+    current_sum: int,
+    solutions_count: int,
+) -> tuple[int, int]:
+    """
+    >>> backtrack(13, 2, 1, 0, 0)
+    (0, 1)
+    >>> backtrack(100, 2, 1, 0, 0)
+    (0, 3)
+    >>> backtrack(100, 3, 1, 0, 0)
+    (0, 1)
+    >>> backtrack(800, 2, 1, 0, 0)
+    (0, 561)
+    >>> backtrack(1000, 10, 1, 0, 0)
+    (0, 0)
+    >>> backtrack(400, 2, 1, 0, 0)
+    (0, 55)
+    >>> backtrack(50, 1, 1, 0, 0)
+    (0, 3658)
+    """
+    if current_sum == needed_sum:
+        # If the sum of the powers is equal to needed_sum, then we have a solution.
+        solutions_count += 1
+        return current_sum, solutions_count
+
+    i_to_n = int(pow(current_number, power))
+    if current_sum + i_to_n <= needed_sum:
+        # If the sum of the powers is less than needed_sum, then continue adding powers.
+        current_sum += i_to_n
+        current_sum, solutions_count = backtrack(
+            needed_sum, power, current_number + 1, current_sum, solutions_count
+        )
+        current_sum -= i_to_n
+    if i_to_n < needed_sum:
+        # If the power of i is less than needed_sum, then try with the next power.
+        current_sum, solutions_count = backtrack(
+            needed_sum, power, current_number + 1, current_sum, solutions_count
+        )
+    return current_sum, solutions_count
+
+
+def solve(needed_sum: int, power: int) -> int:
+    """
+    >>> solve(13, 2)
+    1
+    >>> solve(100, 2)
+    3
+    >>> solve(100, 3)
+    1
+    >>> solve(800, 2)
+    561
+    >>> solve(1000, 10)
+    0
+    >>> solve(400, 2)
+    55
+    >>> solve(50, 1)
+    Traceback (most recent call last):
+        ...
+    ValueError: Invalid input
+    needed_sum must be between 1 and 1000, power between 2 and 10.
+    >>> solve(-10, 5)
+    Traceback (most recent call last):
+        ...
+    ValueError: Invalid input
+    needed_sum must be between 1 and 1000, power between 2 and 10.
+    """
+    if not (1 <= needed_sum <= 1000 and 2 <= power <= 10):
+        raise ValueError(
+            "Invalid input\n"
+            "needed_sum must be between 1 and 1000, power between 2 and 10."
+        )
+
+    return backtrack(needed_sum, power, 1, 0, 0)[1]  # Return the solutions_count
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

boolean_algebra/quine_mc_cluskey.py

@@ -74,10 +74,7 @@ def is_for_table(string1: str, string2: str, count: int) -> bool:
     """
     list1 = list(string1)
     list2 = list(string2)
-    count_n = 0
+    count_n = sum(item1 != item2 for item1, item2 in zip(list1, list2))
-    for i in range(len(list1)):
-        if list1[i] != list2[i]:
-            count_n += 1
     return count_n == count
 
 
@@ -92,40 +89,34 @@ def selection(chart: list[list[int]], prime_implicants: list[str]) -> list[str]:
     temp = []
     select = [0] * len(chart)
     for i in range(len(chart[0])):
-        count = 0
+        count = sum(row[i] == 1 for row in chart)
-        rem = -1
-        for j in range(len(chart)):
-            if chart[j][i] == 1:
-                count += 1
-                rem = j
         if count == 1:
+            rem = max(j for j, row in enumerate(chart) if row[i] == 1)
             select[rem] = 1
-    for i in range(len(select)):
+    for i, item in enumerate(select):
-        if select[i] == 1:
+        if item != 1:
-            for j in range(len(chart[0])):
+            continue
-                if chart[i][j] == 1:
+        for j in range(len(chart[0])):
-                    for k in range(len(chart)):
+            if chart[i][j] != 1:
-                        chart[k][j] = 0
+                continue
-            temp.append(prime_implicants[i])
+            for row in chart:
+                row[j] = 0
+        temp.append(prime_implicants[i])
     while True:
-        max_n = 0
+        counts = [chart[i].count(1) for i in range(len(chart))]
-        rem = -1
+        max_n = max(counts)
-        count_n = 0
+        rem = counts.index(max_n)
-        for i in range(len(chart)):
-            count_n = chart[i].count(1)
-            if count_n > max_n:
-                max_n = count_n
-                rem = i
 
         if max_n == 0:
             return temp
 
         temp.append(prime_implicants[rem])
 
-        for i in range(len(chart[0])):
+        for j in range(len(chart[0])):
-            if chart[rem][i] == 1:
+            if chart[rem][j] != 1:
-                for j in range(len(chart)):
+                continue
-                    chart[j][i] = 0
+            for i in range(len(chart)):
+                chart[i][j] = 0
 
 
 def prime_implicant_chart(

cellular_automata/game_of_life.py

@@ -10,7 +10,7 @@ Python:
   - 3.5
 
 Usage:
-  - $python3 game_o_life <canvas_size:int>
+  - $python3 game_of_life <canvas_size:int>
 
 Game-Of-Life Rules:
 
@@ -52,7 +52,8 @@ def seed(canvas: list[list[bool]]) -> None:
 
 
 def run(canvas: list[list[bool]]) -> list[list[bool]]:
-    """This  function runs the rules of game through all points, and changes their
+    """
+    This function runs the rules of game through all points, and changes their
     status accordingly.(in the same canvas)
     @Args:
     --
@@ -60,7 +61,7 @@ def run(canvas: list[list[bool]]) -> list[list[bool]]:
 
     @returns:
     --
-    None
+    canvas of population after one step
     """
     current_canvas = np.array(canvas)
     next_gen_canvas = np.array(create_canvas(current_canvas.shape[0]))
@@ -70,10 +71,7 @@ def run(canvas: list[list[bool]]) -> list[list[bool]]:
                 pt, current_canvas[r - 1 : r + 2, c - 1 : c + 2]
             )
 
-    current_canvas = next_gen_canvas
+    return next_gen_canvas.tolist()
-    del next_gen_canvas  # cleaning memory as we move on.
-    return_canvas: list[list[bool]] = current_canvas.tolist()
-    return return_canvas
 
 
 def __judge_point(pt: bool, neighbours: list[list[bool]]) -> bool:
@@ -98,7 +96,7 @@ def __judge_point(pt: bool, neighbours: list[list[bool]]) -> bool:
     if pt:
         if alive < 2:
             state = False
-        elif alive == 2 or alive == 3:
+        elif alive in {2, 3}:
             state = True
         elif alive > 3:
             state = False

cellular_automata/wa_tor.py

@@ -0,0 +1,550 @@
+"""
+Wa-Tor algorithm (1984)
+
+@ https://en.wikipedia.org/wiki/Wa-Tor
+@ https://beltoforion.de/en/wator/
+@ https://beltoforion.de/en/wator/images/wator_medium.webm
+
+This solution aims to completely remove any systematic approach
+to the Wa-Tor planet, and utilise fully random methods.
+
+The constants are a working set that allows the Wa-Tor planet
+to result in one of the three possible results.
+"""
+
+from collections.abc import Callable
+from random import randint, shuffle
+from time import sleep
+from typing import Literal
+
+WIDTH = 50  # Width of the Wa-Tor planet
+HEIGHT = 50  # Height of the Wa-Tor planet
+
+PREY_INITIAL_COUNT = 30  # The initial number of prey entities
+PREY_REPRODUCTION_TIME = 5  # The chronons before reproducing
+
+PREDATOR_INITIAL_COUNT = 50  # The initial number of predator entities
+# The initial energy value of predator entities
+PREDATOR_INITIAL_ENERGY_VALUE = 15
+# The energy value provided when consuming prey
+PREDATOR_FOOD_VALUE = 5
+PREDATOR_REPRODUCTION_TIME = 20  # The chronons before reproducing
+
+MAX_ENTITIES = 500  # The max number of organisms on the board
+# The number of entities to delete from the unbalanced side
+DELETE_UNBALANCED_ENTITIES = 50
+
+
+class Entity:
+    """
+    Represents an entity (either prey or predator).
+
+    >>> e = Entity(True, coords=(0, 0))
+    >>> e.prey
+    True
+    >>> e.coords
+    (0, 0)
+    >>> e.alive
+    True
+    """
+
+    def __init__(self, prey: bool, coords: tuple[int, int]) -> None:
+        self.prey = prey
+        # The (row, col) pos of the entity
+        self.coords = coords
+
+        self.remaining_reproduction_time = (
+            PREY_REPRODUCTION_TIME if prey else PREDATOR_REPRODUCTION_TIME
+        )
+        self.energy_value = None if prey is True else PREDATOR_INITIAL_ENERGY_VALUE
+        self.alive = True
+
+    def reset_reproduction_time(self) -> None:
+        """
+        >>> e = Entity(True, coords=(0, 0))
+        >>> e.reset_reproduction_time()
+        >>> e.remaining_reproduction_time == PREY_REPRODUCTION_TIME
+        True
+        >>> e = Entity(False, coords=(0, 0))
+        >>> e.reset_reproduction_time()
+        >>> e.remaining_reproduction_time == PREDATOR_REPRODUCTION_TIME
+        True
+        """
+        self.remaining_reproduction_time = (
+            PREY_REPRODUCTION_TIME if self.prey is True else PREDATOR_REPRODUCTION_TIME
+        )
+
+    def __repr__(self) -> str:
+        """
+        >>> Entity(prey=True, coords=(1, 1))
+        Entity(prey=True, coords=(1, 1), remaining_reproduction_time=5)
+        >>> Entity(prey=False, coords=(2, 1))  # doctest: +NORMALIZE_WHITESPACE
+        Entity(prey=False, coords=(2, 1),
+        remaining_reproduction_time=20, energy_value=15)
+        """
+        repr_ = (
+            f"Entity(prey={self.prey}, coords={self.coords}, "
+            f"remaining_reproduction_time={self.remaining_reproduction_time}"
+        )
+        if self.energy_value is not None:
+            repr_ += f", energy_value={self.energy_value}"
+        return f"{repr_})"
+
+
+class WaTor:
+    """
+    Represents the main Wa-Tor algorithm.
+
+    :attr time_passed: A function that is called every time
+        time passes (a chronon) in order to visually display
+        the new Wa-Tor planet. The time_passed function can block
+        using time.sleep to slow the algorithm progression.
+
+    >>> wt = WaTor(10, 15)
+    >>> wt.width
+    10
+    >>> wt.height
+    15
+    >>> len(wt.planet)
+    15
+    >>> len(wt.planet[0])
+    10
+    >>> len(wt.get_entities()) == PREDATOR_INITIAL_COUNT + PREY_INITIAL_COUNT
+    True
+    """
+
+    time_passed: Callable[["WaTor", int], None] | None
+
+    def __init__(self, width: int, height: int) -> None:
+        self.width = width
+        self.height = height
+        self.time_passed = None
+
+        self.planet: list[list[Entity | None]] = [[None] * width for _ in range(height)]
+
+        # Populate planet with predators and prey randomly
+        for _ in range(PREY_INITIAL_COUNT):
+            self.add_entity(prey=True)
+        for _ in range(PREDATOR_INITIAL_COUNT):
+            self.add_entity(prey=False)
+        self.set_planet(self.planet)
+
+    def set_planet(self, planet: list[list[Entity | None]]) -> None:
+        """
+        Ease of access for testing
+
+        >>> wt = WaTor(WIDTH, HEIGHT)
+        >>> planet = [
+        ... [None, None, None],
+        ... [None, Entity(True, coords=(1, 1)), None]
+        ... ]
+        >>> wt.set_planet(planet)
+        >>> wt.planet == planet
+        True
+        >>> wt.width
+        3
+        >>> wt.height
+        2
+        """
+        self.planet = planet
+        self.width = len(planet[0])
+        self.height = len(planet)
+
+    def add_entity(self, prey: bool) -> None:
+        """
+        Adds an entity, making sure the entity does
+        not override another entity
+
+        >>> wt = WaTor(WIDTH, HEIGHT)
+        >>> wt.set_planet([[None, None], [None, None]])
+        >>> wt.add_entity(True)
+        >>> len(wt.get_entities())
+        1
+        >>> wt.add_entity(False)
+        >>> len(wt.get_entities())
+        2
+        """
+        while True:
+            row, col = randint(0, self.height - 1), randint(0, self.width - 1)
+            if self.planet[row][col] is None:
+                self.planet[row][col] = Entity(prey=prey, coords=(row, col))
+                return
+
+    def get_entities(self) -> list[Entity]:
+        """
+        Returns a list of all the entities within the planet.
+
+        >>> wt = WaTor(WIDTH, HEIGHT)
+        >>> len(wt.get_entities()) == PREDATOR_INITIAL_COUNT + PREY_INITIAL_COUNT
+        True
+        """
+        return [entity for column in self.planet for entity in column if entity]
+
+    def balance_predators_and_prey(self) -> None:
+        """
+        Balances predators and preys so that prey
+        can not dominate the predators, blocking up
+        space for them to reproduce.
+
+        >>> wt = WaTor(WIDTH, HEIGHT)
+        >>> for i in range(2000):
+        ...     row, col = i // HEIGHT, i % WIDTH
+        ...     wt.planet[row][col] = Entity(True, coords=(row, col))
+        >>> entities = len(wt.get_entities())
+        >>> wt.balance_predators_and_prey()
+        >>> len(wt.get_entities()) == entities
+        False
+        """
+        entities = self.get_entities()
+        shuffle(entities)
+
+        if len(entities) >= MAX_ENTITIES - MAX_ENTITIES / 10:
+            prey = [entity for entity in entities if entity.prey]
+            predators = [entity for entity in entities if not entity.prey]
+
+            prey_count, predator_count = len(prey), len(predators)
+
+            entities_to_purge = (
+                prey[:DELETE_UNBALANCED_ENTITIES]
+                if prey_count > predator_count
+                else predators[:DELETE_UNBALANCED_ENTITIES]
+            )
+            for entity in entities_to_purge:
+                self.planet[entity.coords[0]][entity.coords[1]] = None
+
+    def get_surrounding_prey(self, entity: Entity) -> list[Entity]:
+        """
+        Returns all the prey entities around (N, S, E, W) a predator entity.
+
+        Subtly different to the try_to_move_to_unoccupied square.
+
+        >>> wt = WaTor(WIDTH, HEIGHT)
+        >>> wt.set_planet([
+        ... [None, Entity(True, (0, 1)), None],
+        ... [None, Entity(False, (1, 1)), None],
+        ... [None, Entity(True, (2, 1)), None]])
+        >>> wt.get_surrounding_prey(
+        ... Entity(False, (1, 1)))  # doctest: +NORMALIZE_WHITESPACE
+        [Entity(prey=True, coords=(0, 1), remaining_reproduction_time=5),
+        Entity(prey=True, coords=(2, 1), remaining_reproduction_time=5)]
+        >>> wt.set_planet([[Entity(False, (0, 0))]])
+        >>> wt.get_surrounding_prey(Entity(False, (0, 0)))
+        []
+        >>> wt.set_planet([
+        ... [Entity(True, (0, 0)), Entity(False, (1, 0)), Entity(False, (2, 0))],
+        ... [None, Entity(False, (1, 1)), Entity(True, (2, 1))],
+        ... [None, None, None]])
+        >>> wt.get_surrounding_prey(Entity(False, (1, 0)))
+        [Entity(prey=True, coords=(0, 0), remaining_reproduction_time=5)]
+        """
+        row, col = entity.coords
+        adjacent: list[tuple[int, int]] = [
+            (row - 1, col),  # North
+            (row + 1, col),  # South
+            (row, col - 1),  # West
+            (row, col + 1),  # East
+        ]
+
+        return [
+            ent
+            for r, c in adjacent
+            if 0 <= r < self.height
+            and 0 <= c < self.width
+            and (ent := self.planet[r][c]) is not None
+            and ent.prey
+        ]
+
+    def move_and_reproduce(
+        self, entity: Entity, direction_orders: list[Literal["N", "E", "S", "W"]]
+    ) -> None:
+        """
+        Attempts to move to an unoccupied neighbouring square
+        in either of the four directions (North, South, East, West).
+        If the move was successful and the remaining_reproduction time is
+        equal to 0, then a new prey or predator can also be created
+        in the previous square.
+
+        :param direction_orders: Ordered list (like priority queue) depicting
+                            order to attempt to move. Removes any systematic
+                            approach of checking neighbouring squares.
+
+        >>> planet = [
+        ... [None, None, None],
+        ... [None, Entity(True, coords=(1, 1)), None],
+        ... [None, None, None]
+        ... ]
+        >>> wt = WaTor(WIDTH, HEIGHT)
+        >>> wt.set_planet(planet)
+        >>> wt.move_and_reproduce(Entity(True, coords=(1, 1)), direction_orders=["N"])
+        >>> wt.planet  # doctest: +NORMALIZE_WHITESPACE
+        [[None, Entity(prey=True, coords=(0, 1), remaining_reproduction_time=4), None],
+        [None, None, None],
+        [None, None, None]]
+        >>> wt.planet[0][0] = Entity(True, coords=(0, 0))
+        >>> wt.move_and_reproduce(Entity(True, coords=(0, 1)),
+        ... direction_orders=["N", "W", "E", "S"])
+        >>> wt.planet  # doctest: +NORMALIZE_WHITESPACE
+        [[Entity(prey=True, coords=(0, 0), remaining_reproduction_time=5), None,
+        Entity(prey=True, coords=(0, 2), remaining_reproduction_time=4)],
+        [None, None, None],
+        [None, None, None]]
+        >>> wt.planet[0][1] = wt.planet[0][2]
+        >>> wt.planet[0][2] = None
+        >>> wt.move_and_reproduce(Entity(True, coords=(0, 1)),
+        ... direction_orders=["N", "W", "S", "E"])
+        >>> wt.planet  # doctest: +NORMALIZE_WHITESPACE
+        [[Entity(prey=True, coords=(0, 0), remaining_reproduction_time=5), None, None],
+        [None, Entity(prey=True, coords=(1, 1), remaining_reproduction_time=4), None],
+        [None, None, None]]
+
+        >>> wt = WaTor(WIDTH, HEIGHT)
+        >>> reproducable_entity = Entity(False, coords=(0, 1))
+        >>> reproducable_entity.remaining_reproduction_time = 0
+        >>> wt.planet = [[None, reproducable_entity]]
+        >>> wt.move_and_reproduce(reproducable_entity,
+        ... direction_orders=["N", "W", "S", "E"])
+        >>> wt.planet  # doctest: +NORMALIZE_WHITESPACE
+        [[Entity(prey=False, coords=(0, 0),
+        remaining_reproduction_time=20, energy_value=15),
+        Entity(prey=False, coords=(0, 1), remaining_reproduction_time=20,
+        energy_value=15)]]
+        """
+        row, col = coords = entity.coords
+
+        adjacent_squares: dict[Literal["N", "E", "S", "W"], tuple[int, int]] = {
+            "N": (row - 1, col),  # North
+            "S": (row + 1, col),  # South
+            "W": (row, col - 1),  # West
+            "E": (row, col + 1),  # East
+        }
+        # Weight adjacent locations
+        adjacent: list[tuple[int, int]] = []
+        for order in direction_orders:
+            adjacent.append(adjacent_squares[order])
+
+        for r, c in adjacent:
+            if (
+                0 <= r < self.height
+                and 0 <= c < self.width
+                and self.planet[r][c] is None
+            ):
+                # Move entity to empty adjacent square
+                self.planet[r][c] = entity
+                self.planet[row][col] = None
+                entity.coords = (r, c)
+                break
+
+        # (2.) See if it possible to reproduce in previous square
+        if coords != entity.coords and entity.remaining_reproduction_time <= 0:
+            # Check if the entities on the planet is less than the max limit
+            if len(self.get_entities()) < MAX_ENTITIES:
+                # Reproduce in previous square
+                self.planet[row][col] = Entity(prey=entity.prey, coords=coords)
+                entity.reset_reproduction_time()
+        else:
+            entity.remaining_reproduction_time -= 1
+
+    def perform_prey_actions(
+        self, entity: Entity, direction_orders: list[Literal["N", "E", "S", "W"]]
+    ) -> None:
+        """
+        Performs the actions for a prey entity
+
+        For prey the rules are:
+          1. At each chronon, a prey moves randomly to one of the adjacent unoccupied
+            squares. If there are no free squares, no movement takes place.
+          2. Once a prey has survived a certain number of chronons it may reproduce.
+            This is done as it moves to a neighbouring square,
+            leaving behind a new prey in its old position.
+            Its reproduction time is also reset to zero.
+
+        >>> wt = WaTor(WIDTH, HEIGHT)
+        >>> reproducable_entity = Entity(True, coords=(0, 1))
+        >>> reproducable_entity.remaining_reproduction_time = 0
+        >>> wt.planet = [[None, reproducable_entity]]
+        >>> wt.perform_prey_actions(reproducable_entity,
+        ... direction_orders=["N", "W", "S", "E"])
+        >>> wt.planet  # doctest: +NORMALIZE_WHITESPACE
+        [[Entity(prey=True, coords=(0, 0), remaining_reproduction_time=5),
+        Entity(prey=True, coords=(0, 1), remaining_reproduction_time=5)]]
+        """
+        self.move_and_reproduce(entity, direction_orders)
+
+    def perform_predator_actions(
+        self,
+        entity: Entity,
+        occupied_by_prey_coords: tuple[int, int] | None,
+        direction_orders: list[Literal["N", "E", "S", "W"]],
+    ) -> None:
+        """
+        Performs the actions for a predator entity
+
+        :param occupied_by_prey_coords: Move to this location if there is prey there
+
+        For predators the rules are:
+          1. At each chronon, a predator moves randomly to an adjacent square occupied
+            by a prey. If there is none, the predator moves to a random adjacent
+            unoccupied square. If there are no free squares, no movement takes place.
+          2. At each chronon, each predator is deprived of a unit of energy.
+          3. Upon reaching zero energy, a predator dies.
+          4. If a predator moves to a square occupied by a prey,
+            it eats the prey and earns a certain amount of energy.
+          5. Once a predator has survived a certain number of chronons
+          it may reproduce in exactly the same way as the prey.
+
+        >>> wt = WaTor(WIDTH, HEIGHT)
+        >>> wt.set_planet([[Entity(True, coords=(0, 0)), Entity(False, coords=(0, 1))]])
+        >>> wt.perform_predator_actions(Entity(False, coords=(0, 1)), (0, 0), [])
+        >>> wt.planet  # doctest: +NORMALIZE_WHITESPACE
+        [[Entity(prey=False, coords=(0, 0),
+        remaining_reproduction_time=20, energy_value=19), None]]
+        """
+        assert entity.energy_value is not None  # [type checking]
+
+        # (3.) If the entity has 0 energy, it will die
+        if entity.energy_value == 0:
+            self.planet[entity.coords[0]][entity.coords[1]] = None
+            return
+
+        # (1.) Move to entity if possible
+        if occupied_by_prey_coords is not None:
+            # Kill the prey
+            prey = self.planet[occupied_by_prey_coords[0]][occupied_by_prey_coords[1]]
+            assert prey is not None
+            prey.alive = False
+
+            # Move onto prey
+            self.planet[occupied_by_prey_coords[0]][occupied_by_prey_coords[1]] = entity
+            self.planet[entity.coords[0]][entity.coords[1]] = None
+
+            entity.coords = occupied_by_prey_coords
+            # (4.) Eats the prey and earns energy
+            entity.energy_value += PREDATOR_FOOD_VALUE
+        else:
+            # (5.) If it has survived the certain number of chronons it will also
+            # reproduce in this function
+            self.move_and_reproduce(entity, direction_orders)
+
+        # (2.) Each chronon, the predator is deprived of a unit of energy
+        entity.energy_value -= 1
+
+    def run(self, *, iteration_count: int) -> None:
+        """
+        Emulate time passing by looping iteration_count times
+
+        >>> wt = WaTor(WIDTH, HEIGHT)
+        >>> wt.run(iteration_count=PREDATOR_INITIAL_ENERGY_VALUE - 1)
+        >>> len(list(filter(lambda entity: entity.prey is False,
+        ... wt.get_entities()))) >= PREDATOR_INITIAL_COUNT
+        True
+        """
+        for iter_num in range(iteration_count):
+            # Generate list of all entities in order to randomly
+            # pop an entity at a time to simulate true randomness
+            # This removes the systematic approach of iterating
+            # through each entity width by height
+            all_entities = self.get_entities()
+
+            for __ in range(len(all_entities)):
+                entity = all_entities.pop(randint(0, len(all_entities) - 1))
+                if entity.alive is False:
+                    continue
+
+                directions: list[Literal["N", "E", "S", "W"]] = ["N", "E", "S", "W"]
+                shuffle(directions)  # Randomly shuffle directions
+
+                if entity.prey:
+                    self.perform_prey_actions(entity, directions)
+                else:
+                    # Create list of surrounding prey
+                    surrounding_prey = self.get_surrounding_prey(entity)
+                    surrounding_prey_coords = None
+
+                    if surrounding_prey:
+                        # Again, randomly shuffle directions
+                        shuffle(surrounding_prey)
+                        surrounding_prey_coords = surrounding_prey[0].coords
+
+                    self.perform_predator_actions(
+                        entity, surrounding_prey_coords, directions
+                    )
+
+            # Balance out the predators and prey
+            self.balance_predators_and_prey()
+
+            if self.time_passed is not None:
+                # Call time_passed function for Wa-Tor planet
+                # visualisation in a terminal or a graph.
+                self.time_passed(self, iter_num)
+
+
+def visualise(wt: WaTor, iter_number: int, *, colour: bool = True) -> None:
+    """
+    Visually displays the Wa-Tor planet using
+    an ascii code in terminal to clear and re-print
+    the Wa-Tor planet at intervals.
+
+    Uses ascii colour codes to colourfully display
+    the predators and prey.
+
+    (0x60f197) Prey = #
+    (0xfffff) Predator = x
+
+    >>> wt = WaTor(30, 30)
+    >>> wt.set_planet([
+    ... [Entity(True, coords=(0, 0)), Entity(False, coords=(0, 1)), None],
+    ... [Entity(False, coords=(1, 0)), None, Entity(False, coords=(1, 2))],
+    ... [None, Entity(True, coords=(2, 1)), None]
+    ... ])
+    >>> visualise(wt, 0, colour=False)  # doctest: +NORMALIZE_WHITESPACE
+    #  x  .
+    x  .  x
+    .  #  .
+    <BLANKLINE>
+    Iteration: 0 | Prey count: 2 | Predator count: 3 |
+    """
+    if colour:
+        __import__("os").system("")
+        print("\x1b[0;0H\x1b[2J\x1b[?25l")
+
+    reprint = "\x1b[0;0H" if colour else ""
+    ansi_colour_end = "\x1b[0m " if colour else " "
+
+    planet = wt.planet
+    output = ""
+
+    # Iterate over every entity in the planet
+    for row in planet:
+        for entity in row:
+            if entity is None:
+                output += " . "
+            else:
+                if colour is True:
+                    output += (
+                        "\x1b[38;2;96;241;151m"
+                        if entity.prey
+                        else "\x1b[38;2;255;255;15m"
+                    )
+                output += f" {'#' if entity.prey else 'x'}{ansi_colour_end}"
+
+        output += "\n"
+
+    entities = wt.get_entities()
+    prey_count = sum(entity.prey for entity in entities)
+
+    print(
+        f"{output}\n Iteration: {iter_number} | Prey count: {prey_count} | "
+        f"Predator count: {len(entities) - prey_count} | {reprint}"
+    )
+    # Block the thread to be able to visualise seeing the algorithm
+    sleep(0.05)
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()
+
+    wt = WaTor(WIDTH, HEIGHT)
+    wt.time_passed = visualise
+    wt.run(iteration_count=100_000)

ciphers/diffie_hellman.py

@@ -10,13 +10,13 @@ primes = {
     5: {
         "prime": int(
             "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1"
-            + "29024E088A67CC74020BBEA63B139B22514A08798E3404DD"
+            "29024E088A67CC74020BBEA63B139B22514A08798E3404DD"
-            + "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245"
+            "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245"
-            + "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED"
+            "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED"
-            + "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D"
+            "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D"
-            + "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F"
+            "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F"
-            + "83655D23DCA3AD961C62F356208552BB9ED529077096966D"
+            "83655D23DCA3AD961C62F356208552BB9ED529077096966D"
-            + "670C354E4ABC9804F1746C08CA237327FFFFFFFFFFFFFFFF",
+            "670C354E4ABC9804F1746C08CA237327FFFFFFFFFFFFFFFF",
             base=16,
         ),
         "generator": 2,
@@ -25,16 +25,16 @@ primes = {
     14: {
         "prime": int(
             "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1"
-            + "29024E088A67CC74020BBEA63B139B22514A08798E3404DD"
+            "29024E088A67CC74020BBEA63B139B22514A08798E3404DD"
-            + "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245"
+            "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245"
-            + "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED"
+            "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED"
-            + "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D"
+            "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D"
-            + "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F"
+            "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F"
-            + "83655D23DCA3AD961C62F356208552BB9ED529077096966D"
+            "83655D23DCA3AD961C62F356208552BB9ED529077096966D"
-            + "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B"
+            "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B"
-            + "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9"
+            "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9"
-            + "DE2BCBF6955817183995497CEA956AE515D2261898FA0510"
+            "DE2BCBF6955817183995497CEA956AE515D2261898FA0510"
-            + "15728E5A8AACAA68FFFFFFFFFFFFFFFF",
+            "15728E5A8AACAA68FFFFFFFFFFFFFFFF",
             base=16,
         ),
         "generator": 2,
@@ -43,21 +43,21 @@ primes = {
     15: {
         "prime": int(
             "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1"
-            + "29024E088A67CC74020BBEA63B139B22514A08798E3404DD"
+            "29024E088A67CC74020BBEA63B139B22514A08798E3404DD"
-            + "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245"
+            "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245"
-            + "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED"
+            "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED"
-            + "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D"
+            "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D"
-            + "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F"
+            "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F"
-            + "83655D23DCA3AD961C62F356208552BB9ED529077096966D"
+            "83655D23DCA3AD961C62F356208552BB9ED529077096966D"
-            + "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B"
+            "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B"
-            + "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9"
+            "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9"
-            + "DE2BCBF6955817183995497CEA956AE515D2261898FA0510"
+            "DE2BCBF6955817183995497CEA956AE515D2261898FA0510"
-            + "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64"
+            "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64"
-            + "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7"
+            "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7"
-            + "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B"
+            "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B"
-            + "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C"
+            "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C"
-            + "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31"
+            "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31"
-            + "43DB5BFCE0FD108E4B82D120A93AD2CAFFFFFFFFFFFFFFFF",
+            "43DB5BFCE0FD108E4B82D120A93AD2CAFFFFFFFFFFFFFFFF",
             base=16,
         ),
         "generator": 2,
@@ -66,27 +66,27 @@ primes = {
     16: {
         "prime": int(
             "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1"
-            + "29024E088A67CC74020BBEA63B139B22514A08798E3404DD"
+            "29024E088A67CC74020BBEA63B139B22514A08798E3404DD"
-            + "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245"
+            "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245"
-            + "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED"
+            "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED"
-            + "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D"
+            "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D"
-            + "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F"
+            "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F"
-            + "83655D23DCA3AD961C62F356208552BB9ED529077096966D"
+            "83655D23DCA3AD961C62F356208552BB9ED529077096966D"
-            + "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B"
+            "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B"
-            + "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9"
+            "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9"
-            + "DE2BCBF6955817183995497CEA956AE515D2261898FA0510"
+            "DE2BCBF6955817183995497CEA956AE515D2261898FA0510"
-            + "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64"
+            "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64"
-            + "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7"
+            "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7"
-            + "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B"
+            "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B"
-            + "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C"
+            "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C"
-            + "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31"
+            "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31"
-            + "43DB5BFCE0FD108E4B82D120A92108011A723C12A787E6D7"
+            "43DB5BFCE0FD108E4B82D120A92108011A723C12A787E6D7"
-            + "88719A10BDBA5B2699C327186AF4E23C1A946834B6150BDA"
+            "88719A10BDBA5B2699C327186AF4E23C1A946834B6150BDA"
-            + "2583E9CA2AD44CE8DBBBC2DB04DE8EF92E8EFC141FBECAA6"
+            "2583E9CA2AD44CE8DBBBC2DB04DE8EF92E8EFC141FBECAA6"
-            + "287C59474E6BC05D99B2964FA090C3A2233BA186515BE7ED"
+            "287C59474E6BC05D99B2964FA090C3A2233BA186515BE7ED"
-            + "1F612970CEE2D7AFB81BDD762170481CD0069127D5B05AA9"
+            "1F612970CEE2D7AFB81BDD762170481CD0069127D5B05AA9"
-            + "93B4EA988D8FDDC186FFB7DC90A6C08F4DF435C934063199"
+            "93B4EA988D8FDDC186FFB7DC90A6C08F4DF435C934063199"
-            + "FFFFFFFFFFFFFFFF",
+            "FFFFFFFFFFFFFFFF",
             base=16,
         ),
         "generator": 2,
@@ -95,33 +95,33 @@ primes = {
     17: {
         "prime": int(
             "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD129024E08"
-            + "8A67CC74020BBEA63B139B22514A08798E3404DDEF9519B3CD3A431B"
+            "8A67CC74020BBEA63B139B22514A08798E3404DDEF9519B3CD3A431B"
-            + "302B0A6DF25F14374FE1356D6D51C245E485B576625E7EC6F44C42E9"
+            "302B0A6DF25F14374FE1356D6D51C245E485B576625E7EC6F44C42E9"
-            + "A637ED6B0BFF5CB6F406B7EDEE386BFB5A899FA5AE9F24117C4B1FE6"
+            "A637ED6B0BFF5CB6F406B7EDEE386BFB5A899FA5AE9F24117C4B1FE6"
-            + "49286651ECE45B3DC2007CB8A163BF0598DA48361C55D39A69163FA8"
+            "49286651ECE45B3DC2007CB8A163BF0598DA48361C55D39A69163FA8"
-            + "FD24CF5F83655D23DCA3AD961C62F356208552BB9ED529077096966D"
+            "FD24CF5F83655D23DCA3AD961C62F356208552BB9ED529077096966D"
-            + "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3BE39E772C"
+            "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3BE39E772C"
-            + "180E86039B2783A2EC07A28FB5C55DF06F4C52C9DE2BCBF695581718"
+            "180E86039B2783A2EC07A28FB5C55DF06F4C52C9DE2BCBF695581718"
-            + "3995497CEA956AE515D2261898FA051015728E5A8AAAC42DAD33170D"
+            "3995497CEA956AE515D2261898FA051015728E5A8AAAC42DAD33170D"
-            + "04507A33A85521ABDF1CBA64ECFB850458DBEF0A8AEA71575D060C7D"
+            "04507A33A85521ABDF1CBA64ECFB850458DBEF0A8AEA71575D060C7D"
-            + "B3970F85A6E1E4C7ABF5AE8CDB0933D71E8C94E04A25619DCEE3D226"
+            "B3970F85A6E1E4C7ABF5AE8CDB0933D71E8C94E04A25619DCEE3D226"
-            + "1AD2EE6BF12FFA06D98A0864D87602733EC86A64521F2B18177B200C"
+            "1AD2EE6BF12FFA06D98A0864D87602733EC86A64521F2B18177B200C"
-            + "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB3143DB5BFC"
+            "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB3143DB5BFC"
-            + "E0FD108E4B82D120A92108011A723C12A787E6D788719A10BDBA5B26"
+            "E0FD108E4B82D120A92108011A723C12A787E6D788719A10BDBA5B26"
-            + "99C327186AF4E23C1A946834B6150BDA2583E9CA2AD44CE8DBBBC2DB"
+            "99C327186AF4E23C1A946834B6150BDA2583E9CA2AD44CE8DBBBC2DB"
-            + "04DE8EF92E8EFC141FBECAA6287C59474E6BC05D99B2964FA090C3A2"
+            "04DE8EF92E8EFC141FBECAA6287C59474E6BC05D99B2964FA090C3A2"
-            + "233BA186515BE7ED1F612970CEE2D7AFB81BDD762170481CD0069127"
+            "233BA186515BE7ED1F612970CEE2D7AFB81BDD762170481CD0069127"
-            + "D5B05AA993B4EA988D8FDDC186FFB7DC90A6C08F4DF435C934028492"
+            "D5B05AA993B4EA988D8FDDC186FFB7DC90A6C08F4DF435C934028492"
-            + "36C3FAB4D27C7026C1D4DCB2602646DEC9751E763DBA37BDF8FF9406"
+            "36C3FAB4D27C7026C1D4DCB2602646DEC9751E763DBA37BDF8FF9406"
-            + "AD9E530EE5DB382F413001AEB06A53ED9027D831179727B0865A8918"
+            "AD9E530EE5DB382F413001AEB06A53ED9027D831179727B0865A8918"
-            + "DA3EDBEBCF9B14ED44CE6CBACED4BB1BDB7F1447E6CC254B33205151"
+            "DA3EDBEBCF9B14ED44CE6CBACED4BB1BDB7F1447E6CC254B33205151"
-            + "2BD7AF426FB8F401378CD2BF5983CA01C64B92ECF032EA15D1721D03"
+            "2BD7AF426FB8F401378CD2BF5983CA01C64B92ECF032EA15D1721D03"
-            + "F482D7CE6E74FEF6D55E702F46980C82B5A84031900B1C9E59E7C97F"
+            "F482D7CE6E74FEF6D55E702F46980C82B5A84031900B1C9E59E7C97F"
-            + "BEC7E8F323A97A7E36CC88BE0F1D45B7FF585AC54BD407B22B4154AA"
+            "BEC7E8F323A97A7E36CC88BE0F1D45B7FF585AC54BD407B22B4154AA"
-            + "CC8F6D7EBF48E1D814CC5ED20F8037E0A79715EEF29BE32806A1D58B"
+            "CC8F6D7EBF48E1D814CC5ED20F8037E0A79715EEF29BE32806A1D58B"
-            + "B7C5DA76F550AA3D8A1FBFF0EB19CCB1A313D55CDA56C9EC2EF29632"
+            "B7C5DA76F550AA3D8A1FBFF0EB19CCB1A313D55CDA56C9EC2EF29632"
-            + "387FE8D76E3C0468043E8F663F4860EE12BF2D5B0B7474D6E694F91E"
+            "387FE8D76E3C0468043E8F663F4860EE12BF2D5B0B7474D6E694F91E"
-            + "6DCC4024FFFFFFFFFFFFFFFF",
+            "6DCC4024FFFFFFFFFFFFFFFF",
             base=16,
         ),
         "generator": 2,
@@ -130,48 +130,48 @@ primes = {
     18: {
         "prime": int(
             "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1"
-            + "29024E088A67CC74020BBEA63B139B22514A08798E3404DD"
+            "29024E088A67CC74020BBEA63B139B22514A08798E3404DD"
-            + "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245"
+            "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245"
-            + "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED"
+            "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED"
-            + "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D"
+            "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D"
-            + "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F"
+            "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F"
-            + "83655D23DCA3AD961C62F356208552BB9ED529077096966D"
+            "83655D23DCA3AD961C62F356208552BB9ED529077096966D"
-            + "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B"
+            "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B"
-            + "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9"
+            "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9"
-            + "DE2BCBF6955817183995497CEA956AE515D2261898FA0510"
+            "DE2BCBF6955817183995497CEA956AE515D2261898FA0510"
-            + "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64"
+            "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64"
-            + "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7"
+            "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7"
-            + "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B"
+            "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B"
-            + "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C"
+            "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C"
-            + "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31"
+            "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31"
-            + "43DB5BFCE0FD108E4B82D120A92108011A723C12A787E6D7"
+            "43DB5BFCE0FD108E4B82D120A92108011A723C12A787E6D7"
-            + "88719A10BDBA5B2699C327186AF4E23C1A946834B6150BDA"
+            "88719A10BDBA5B2699C327186AF4E23C1A946834B6150BDA"
-            + "2583E9CA2AD44CE8DBBBC2DB04DE8EF92E8EFC141FBECAA6"
+            "2583E9CA2AD44CE8DBBBC2DB04DE8EF92E8EFC141FBECAA6"
-            + "287C59474E6BC05D99B2964FA090C3A2233BA186515BE7ED"
+            "287C59474E6BC05D99B2964FA090C3A2233BA186515BE7ED"
-            + "1F612970CEE2D7AFB81BDD762170481CD0069127D5B05AA9"
+            "1F612970CEE2D7AFB81BDD762170481CD0069127D5B05AA9"
-            + "93B4EA988D8FDDC186FFB7DC90A6C08F4DF435C934028492"
+            "93B4EA988D8FDDC186FFB7DC90A6C08F4DF435C934028492"
-            + "36C3FAB4D27C7026C1D4DCB2602646DEC9751E763DBA37BD"
+            "36C3FAB4D27C7026C1D4DCB2602646DEC9751E763DBA37BD"
-            + "F8FF9406AD9E530EE5DB382F413001AEB06A53ED9027D831"
+            "F8FF9406AD9E530EE5DB382F413001AEB06A53ED9027D831"
-            + "179727B0865A8918DA3EDBEBCF9B14ED44CE6CBACED4BB1B"
+            "179727B0865A8918DA3EDBEBCF9B14ED44CE6CBACED4BB1B"
-            + "DB7F1447E6CC254B332051512BD7AF426FB8F401378CD2BF"
+            "DB7F1447E6CC254B332051512BD7AF426FB8F401378CD2BF"
-            + "5983CA01C64B92ECF032EA15D1721D03F482D7CE6E74FEF6"
+            "5983CA01C64B92ECF032EA15D1721D03F482D7CE6E74FEF6"
-            + "D55E702F46980C82B5A84031900B1C9E59E7C97FBEC7E8F3"
+            "D55E702F46980C82B5A84031900B1C9E59E7C97FBEC7E8F3"
-            + "23A97A7E36CC88BE0F1D45B7FF585AC54BD407B22B4154AA"
+            "23A97A7E36CC88BE0F1D45B7FF585AC54BD407B22B4154AA"
-            + "CC8F6D7EBF48E1D814CC5ED20F8037E0A79715EEF29BE328"
+            "CC8F6D7EBF48E1D814CC5ED20F8037E0A79715EEF29BE328"
-            + "06A1D58BB7C5DA76F550AA3D8A1FBFF0EB19CCB1A313D55C"
+            "06A1D58BB7C5DA76F550AA3D8A1FBFF0EB19CCB1A313D55C"
-            + "DA56C9EC2EF29632387FE8D76E3C0468043E8F663F4860EE"
+            "DA56C9EC2EF29632387FE8D76E3C0468043E8F663F4860EE"
-            + "12BF2D5B0B7474D6E694F91E6DBE115974A3926F12FEE5E4"
+            "12BF2D5B0B7474D6E694F91E6DBE115974A3926F12FEE5E4"
-            + "38777CB6A932DF8CD8BEC4D073B931BA3BC832B68D9DD300"
+            "38777CB6A932DF8CD8BEC4D073B931BA3BC832B68D9DD300"
-            + "741FA7BF8AFC47ED2576F6936BA424663AAB639C5AE4F568"
+            "741FA7BF8AFC47ED2576F6936BA424663AAB639C5AE4F568"
-            + "3423B4742BF1C978238F16CBE39D652DE3FDB8BEFC848AD9"
+            "3423B4742BF1C978238F16CBE39D652DE3FDB8BEFC848AD9"
-            + "22222E04A4037C0713EB57A81A23F0C73473FC646CEA306B"
+            "22222E04A4037C0713EB57A81A23F0C73473FC646CEA306B"
-            + "4BCBC8862F8385DDFA9D4B7FA2C087E879683303ED5BDD3A"
+            "4BCBC8862F8385DDFA9D4B7FA2C087E879683303ED5BDD3A"
-            + "062B3CF5B3A278A66D2A13F83F44F82DDF310EE074AB6A36"
+            "062B3CF5B3A278A66D2A13F83F44F82DDF310EE074AB6A36"
-            + "4597E899A0255DC164F31CC50846851DF9AB48195DED7EA1"
+            "4597E899A0255DC164F31CC50846851DF9AB48195DED7EA1"
-            + "B1D510BD7EE74D73FAF36BC31ECFA268359046F4EB879F92"
+            "B1D510BD7EE74D73FAF36BC31ECFA268359046F4EB879F92"
-            + "4009438B481C6CD7889A002ED5EE382BC9190DA6FC026E47"
+            "4009438B481C6CD7889A002ED5EE382BC9190DA6FC026E47"
-            + "9558E4475677E9AA9E3050E2765694DFC81F56E880B96E71"
+            "9558E4475677E9AA9E3050E2765694DFC81F56E880B96E71"
-            + "60C980DD98EDD3DFFFFFFFFFFFFFFFFF",
+            "60C980DD98EDD3DFFFFFFFFFFFFFFFFF",
             base=16,
         ),
         "generator": 2,

ciphers/mixed_keyword_cypher.py

@@ -1,7 +1,11 @@
-def mixed_keyword(key: str = "college", pt: str = "UNIVERSITY") -> str:
+from string import ascii_uppercase
-    """
 
-    For key:hello
+
+def mixed_keyword(
+    keyword: str, plaintext: str, verbose: bool = False, alphabet: str = ascii_uppercase
+) -> str:
+    """
+    For keyword: hello
 
     H E L O
     A B C D
@@ -12,58 +16,60 @@ def mixed_keyword(key: str = "college", pt: str = "UNIVERSITY") -> str:
     Y Z
     and map vertically
 
-    >>> mixed_keyword("college", "UNIVERSITY")  # doctest: +NORMALIZE_WHITESPACE
+    >>> mixed_keyword("college", "UNIVERSITY", True)  # doctest: +NORMALIZE_WHITESPACE
     {'A': 'C', 'B': 'A', 'C': 'I', 'D': 'P', 'E': 'U', 'F': 'Z', 'G': 'O', 'H': 'B',
      'I': 'J', 'J': 'Q', 'K': 'V', 'L': 'L', 'M': 'D', 'N': 'K', 'O': 'R', 'P': 'W',
      'Q': 'E', 'R': 'F', 'S': 'M', 'T': 'S', 'U': 'X', 'V': 'G', 'W': 'H', 'X': 'N',
      'Y': 'T', 'Z': 'Y'}
     'XKJGUFMJST'
+
+    >>> mixed_keyword("college", "UNIVERSITY", False)  # doctest: +NORMALIZE_WHITESPACE
+    'XKJGUFMJST'
     """
-    key = key.upper()
+    keyword = keyword.upper()
-    pt = pt.upper()
+    plaintext = plaintext.upper()
-    temp = []
+    alphabet_set = set(alphabet)
-    for i in key:
+
-        if i not in temp:
+    # create a list of unique characters in the keyword - their order matters
-            temp.append(i)
+    # it determines how we will map plaintext characters to the ciphertext
-    len_temp = len(temp)
+    unique_chars = []
-    # print(temp)
+    for char in keyword:
-    alpha = []
+        if char in alphabet_set and char not in unique_chars:
-    modalpha = []
+            unique_chars.append(char)
-    for j in range(65, 91):
+    # the number of those unique characters will determine the number of rows
-        t = chr(j)
+    num_unique_chars_in_keyword = len(unique_chars)
-        alpha.append(t)
+
-        if t not in temp:
+    # create a shifted version of the alphabet
-            temp.append(t)
+    shifted_alphabet = unique_chars + [
-    # print(temp)
+        char for char in alphabet if char not in unique_chars
-    r = int(26 / 4)
+    ]
-    # print(r)
+
-    k = 0
+    # create a modified alphabet by splitting the shifted alphabet into rows
-    for _ in range(r):
+    modified_alphabet = [
-        s = []
+        shifted_alphabet[k : k + num_unique_chars_in_keyword]
-        for _ in range(len_temp):
+        for k in range(0, 26, num_unique_chars_in_keyword)
-            s.append(temp[k])
+    ]
-            if k >= 25:
+
+    # map the alphabet characters to the modified alphabet characters
+    # going 'vertically' through the modified alphabet - consider columns first
+    mapping = {}
+    letter_index = 0
+    for column in range(num_unique_chars_in_keyword):
+        for row in modified_alphabet:
+            # if current row (the last one) is too short, break out of loop
+            if len(row) <= column:
                 break
-            k += 1
+
-        modalpha.append(s)
+            # map current letter to letter in modified alphabet
-    # print(modalpha)
+            mapping[alphabet[letter_index]] = row[column]
-    d = {}
+            letter_index += 1
-    j = 0
+
-    k = 0
+    if verbose:
-    for j in range(len_temp):
+        print(mapping)
-        for m in modalpha:
+    # create the encrypted text by mapping the plaintext to the modified alphabet
-            if not len(m) - 1 >= j:
+    return "".join(mapping[char] if char in mapping else char for char in plaintext)
-                break
-            d[alpha[k]] = m[j]
-            if not k < 25:
-                break
-            k += 1
-    print(d)
-    cypher = ""
-    for i in pt:
-        cypher += d[i]
-    return cypher
 
 
 if __name__ == "__main__":
+    # example use
     print(mixed_keyword("college", "UNIVERSITY"))

ciphers/rsa_key_generator.py

@@ -2,8 +2,7 @@ import os
 import random
 import sys
 
-from . import cryptomath_module as cryptoMath  # noqa: N812
+from . import cryptomath_module, rabin_miller
-from . import rabin_miller as rabinMiller  # noqa: N812
 
 
 def main() -> None:
@@ -13,20 +12,26 @@ def main() -> None:
 
 
 def generate_key(key_size: int) -> tuple[tuple[int, int], tuple[int, int]]:
-    print("Generating prime p...")
+    """
-    p = rabinMiller.generate_large_prime(key_size)
+    >>> random.seed(0) # for repeatability
-    print("Generating prime q...")
+    >>> public_key, private_key = generate_key(8)
-    q = rabinMiller.generate_large_prime(key_size)
+    >>> public_key
+    (26569, 239)
+    >>> private_key
+    (26569, 2855)
+    """
+    p = rabin_miller.generate_large_prime(key_size)
+    q = rabin_miller.generate_large_prime(key_size)
     n = p * q
 
-    print("Generating e that is relatively prime to (p - 1) * (q - 1)...")
+    # Generate e that is relatively prime to (p - 1) * (q - 1)
     while True:
         e = random.randrange(2 ** (key_size - 1), 2 ** (key_size))
-        if cryptoMath.gcd(e, (p - 1) * (q - 1)) == 1:
+        if cryptomath_module.gcd(e, (p - 1) * (q - 1)) == 1:
             break
 
-    print("Calculating d that is mod inverse of e...")
+    # Calculate d that is mod inverse of e
-    d = cryptoMath.find_mod_inverse(e, (p - 1) * (q - 1))
+    d = cryptomath_module.find_mod_inverse(e, (p - 1) * (q - 1))
 
     public_key = (n, e)
     private_key = (n, d)

compression/burrows_wheeler.py

@@ -150,7 +150,7 @@ def reverse_bwt(bwt_string: str, idx_original_string: int) -> str:
         raise ValueError("The parameter idx_original_string must not be lower than 0.")
     if idx_original_string >= len(bwt_string):
         raise ValueError(
-            "The parameter idx_original_string must be lower than" " len(bwt_string)."
+            "The parameter idx_original_string must be lower than len(bwt_string)."
         )
 
     ordered_rotations = [""] * len(bwt_string)

computer_vision/flip_augmentation.py

@@ -32,13 +32,13 @@ def main() -> None:
         letter_code = random_chars(32)
         file_name = paths[index].split(os.sep)[-1].rsplit(".", 1)[0]
         file_root = f"{OUTPUT_DIR}/{file_name}_FLIP_{letter_code}"
-        cv2.imwrite(f"/{file_root}.jpg", image, [cv2.IMWRITE_JPEG_QUALITY, 85])
+        cv2.imwrite(f"{file_root}.jpg", image, [cv2.IMWRITE_JPEG_QUALITY, 85])
         print(f"Success {index+1}/{len(new_images)} with {file_name}")
         annos_list = []
         for anno in new_annos[index]:
             obj = f"{anno[0]} {anno[1]} {anno[2]} {anno[3]} {anno[4]}"
             annos_list.append(obj)
-        with open(f"/{file_root}.txt", "w") as outfile:
+        with open(f"{file_root}.txt", "w") as outfile:
             outfile.write("\n".join(line for line in annos_list))
 
 

conversions/energy_conversions.py

@@ -0,0 +1,114 @@
+"""
+Conversion of energy units.
+
+Available units: joule, kilojoule, megajoule, gigajoule,\
+      wattsecond, watthour, kilowatthour, newtonmeter, calorie_nutr,\
+          kilocalorie_nutr, electronvolt, britishthermalunit_it, footpound
+
+USAGE :
+-> Import this file into their respective project.
+-> Use the function energy_conversion() for conversion of energy units.
+-> Parameters :
+    -> from_type : From which type you want to convert
+    -> to_type : To which type you want to convert
+    -> value : the value which you want to convert
+
+REFERENCES :
+-> Wikipedia reference: https://en.wikipedia.org/wiki/Units_of_energy
+-> Wikipedia reference: https://en.wikipedia.org/wiki/Joule
+-> Wikipedia reference: https://en.wikipedia.org/wiki/Kilowatt-hour
+-> Wikipedia reference: https://en.wikipedia.org/wiki/Newton-metre
+-> Wikipedia reference: https://en.wikipedia.org/wiki/Calorie
+-> Wikipedia reference: https://en.wikipedia.org/wiki/Electronvolt
+-> Wikipedia reference: https://en.wikipedia.org/wiki/British_thermal_unit
+-> Wikipedia reference: https://en.wikipedia.org/wiki/Foot-pound_(energy)
+-> Unit converter reference: https://www.unitconverters.net/energy-converter.html
+"""
+
+ENERGY_CONVERSION: dict[str, float] = {
+    "joule": 1.0,
+    "kilojoule": 1_000,
+    "megajoule": 1_000_000,
+    "gigajoule": 1_000_000_000,
+    "wattsecond": 1.0,
+    "watthour": 3_600,
+    "kilowatthour": 3_600_000,
+    "newtonmeter": 1.0,
+    "calorie_nutr": 4_186.8,
+    "kilocalorie_nutr": 4_186_800.00,
+    "electronvolt": 1.602_176_634e-19,
+    "britishthermalunit_it": 1_055.055_85,
+    "footpound": 1.355_818,
+}
+
+
+def energy_conversion(from_type: str, to_type: str, value: float) -> float:
+    """
+    Conversion of energy units.
+    >>> energy_conversion("joule", "joule", 1)
+    1.0
+    >>> energy_conversion("joule", "kilojoule", 1)
+    0.001
+    >>> energy_conversion("joule", "megajoule", 1)
+    1e-06
+    >>> energy_conversion("joule", "gigajoule", 1)
+    1e-09
+    >>> energy_conversion("joule", "wattsecond", 1)
+    1.0
+    >>> energy_conversion("joule", "watthour", 1)
+    0.0002777777777777778
+    >>> energy_conversion("joule", "kilowatthour", 1)
+    2.7777777777777776e-07
+    >>> energy_conversion("joule", "newtonmeter", 1)
+    1.0
+    >>> energy_conversion("joule", "calorie_nutr", 1)
+    0.00023884589662749592
+    >>> energy_conversion("joule", "kilocalorie_nutr", 1)
+    2.388458966274959e-07
+    >>> energy_conversion("joule", "electronvolt", 1)
+    6.241509074460763e+18
+    >>> energy_conversion("joule", "britishthermalunit_it", 1)
+    0.0009478171226670134
+    >>> energy_conversion("joule", "footpound", 1)
+    0.7375621211696556
+    >>> energy_conversion("joule", "megajoule", 1000)
+    0.001
+    >>> energy_conversion("calorie_nutr", "kilocalorie_nutr", 1000)
+    1.0
+    >>> energy_conversion("kilowatthour", "joule", 10)
+    36000000.0
+    >>> energy_conversion("britishthermalunit_it", "footpound", 1)
+    778.1692306784539
+    >>> energy_conversion("watthour", "joule", "a") # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+      ...
+    TypeError: unsupported operand type(s) for /: 'str' and 'float'
+    >>> energy_conversion("wrongunit", "joule", 1) # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+      ...
+    ValueError: Incorrect 'from_type' or 'to_type' value: 'wrongunit', 'joule'
+    Valid values are: joule, ... footpound
+    >>> energy_conversion("joule", "wrongunit", 1) # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+      ...
+    ValueError: Incorrect 'from_type' or 'to_type' value: 'joule', 'wrongunit'
+    Valid values are: joule, ... footpound
+    >>> energy_conversion("123", "abc", 1) # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+      ...
+    ValueError: Incorrect 'from_type' or 'to_type' value: '123', 'abc'
+    Valid values are: joule, ... footpound
+    """
+    if to_type not in ENERGY_CONVERSION or from_type not in ENERGY_CONVERSION:
+        msg = (
+            f"Incorrect 'from_type' or 'to_type' value: {from_type!r}, {to_type!r}\n"
+            f"Valid values are: {', '.join(ENERGY_CONVERSION)}"
+        )
+        raise ValueError(msg)
+    return value * ENERGY_CONVERSION[from_type] / ENERGY_CONVERSION[to_type]
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

conversions/length_conversion.py

@@ -22,9 +22,13 @@ REFERENCES :
 -> Wikipedia reference: https://en.wikipedia.org/wiki/Millimeter
 """
 
-from collections import namedtuple
+from typing import NamedTuple
+
+
+class FromTo(NamedTuple):
+    from_factor: float
+    to_factor: float
 
-from_to = namedtuple("from_to", "from_ to")
 
 TYPE_CONVERSION = {
     "millimeter": "mm",
@@ -40,14 +44,14 @@ TYPE_CONVERSION = {
 }
 
 METRIC_CONVERSION = {
-    "mm": from_to(0.001, 1000),
+    "mm": FromTo(0.001, 1000),
-    "cm": from_to(0.01, 100),
+    "cm": FromTo(0.01, 100),
-    "m": from_to(1, 1),
+    "m": FromTo(1, 1),
-    "km": from_to(1000, 0.001),
+    "km": FromTo(1000, 0.001),
-    "in": from_to(0.0254, 39.3701),
+    "in": FromTo(0.0254, 39.3701),
-    "ft": from_to(0.3048, 3.28084),
+    "ft": FromTo(0.3048, 3.28084),
-    "yd": from_to(0.9144, 1.09361),
+    "yd": FromTo(0.9144, 1.09361),
-    "mi": from_to(1609.34, 0.000621371),
+    "mi": FromTo(1609.34, 0.000621371),
 }
 
 
@@ -115,7 +119,11 @@ def length_conversion(value: float, from_type: str, to_type: str) -> float:
             f"Conversion abbreviations are: {', '.join(METRIC_CONVERSION)}"
         )
         raise ValueError(msg)
-    return value * METRIC_CONVERSION[new_from].from_ * METRIC_CONVERSION[new_to].to
+    return (
+        value
+        * METRIC_CONVERSION[new_from].from_factor
+        * METRIC_CONVERSION[new_to].to_factor
+    )
 
 
 if __name__ == "__main__":

conversions/pressure_conversions.py

@@ -19,19 +19,23 @@ REFERENCES :
 -> https://www.unitconverters.net/pressure-converter.html
 """
 
-from collections import namedtuple
+from typing import NamedTuple
+
+
+class FromTo(NamedTuple):
+    from_factor: float
+    to_factor: float
 
-from_to = namedtuple("from_to", "from_ to")
 
 PRESSURE_CONVERSION = {
-    "atm": from_to(1, 1),
+    "atm": FromTo(1, 1),
-    "pascal": from_to(0.0000098, 101325),
+    "pascal": FromTo(0.0000098, 101325),
-    "bar": from_to(0.986923, 1.01325),
+    "bar": FromTo(0.986923, 1.01325),
-    "kilopascal": from_to(0.00986923, 101.325),
+    "kilopascal": FromTo(0.00986923, 101.325),
-    "megapascal": from_to(9.86923, 0.101325),
+    "megapascal": FromTo(9.86923, 0.101325),
-    "psi": from_to(0.068046, 14.6959),
+    "psi": FromTo(0.068046, 14.6959),
-    "inHg": from_to(0.0334211, 29.9213),
+    "inHg": FromTo(0.0334211, 29.9213),
-    "torr": from_to(0.00131579, 760),
+    "torr": FromTo(0.00131579, 760),
 }
 
 
@@ -71,7 +75,9 @@ def pressure_conversion(value: float, from_type: str, to_type: str) -> float:
             + ", ".join(PRESSURE_CONVERSION)
         )
     return (
-        value * PRESSURE_CONVERSION[from_type].from_ * PRESSURE_CONVERSION[to_type].to
+        value
+        * PRESSURE_CONVERSION[from_type].from_factor
+        * PRESSURE_CONVERSION[to_type].to_factor
     )
 
 

conversions/volume_conversions.py

@@ -18,35 +18,39 @@ REFERENCES :
 -> Wikipedia reference: https://en.wikipedia.org/wiki/Cup_(unit)
 """
 
-from collections import namedtuple
+from typing import NamedTuple
+
+
+class FromTo(NamedTuple):
+    from_factor: float
+    to_factor: float
 
-from_to = namedtuple("from_to", "from_ to")
 
 METRIC_CONVERSION = {
-    "cubicmeter": from_to(1, 1),
+    "cubic meter": FromTo(1, 1),
-    "litre": from_to(0.001, 1000),
+    "litre": FromTo(0.001, 1000),
-    "kilolitre": from_to(1, 1),
+    "kilolitre": FromTo(1, 1),
-    "gallon": from_to(0.00454, 264.172),
+    "gallon": FromTo(0.00454, 264.172),
-    "cubicyard": from_to(0.76455, 1.30795),
+    "cubic yard": FromTo(0.76455, 1.30795),
-    "cubicfoot": from_to(0.028, 35.3147),
+    "cubic foot": FromTo(0.028, 35.3147),
-    "cup": from_to(0.000236588, 4226.75),
+    "cup": FromTo(0.000236588, 4226.75),
 }
 
 
 def volume_conversion(value: float, from_type: str, to_type: str) -> float:
     """
     Conversion between volume units.
-    >>> volume_conversion(4, "cubicmeter", "litre")
+    >>> volume_conversion(4, "cubic meter", "litre")
     4000
     >>> volume_conversion(1, "litre", "gallon")
     0.264172
-    >>> volume_conversion(1, "kilolitre", "cubicmeter")
+    >>> volume_conversion(1, "kilolitre", "cubic meter")
     1
-    >>> volume_conversion(3, "gallon", "cubicyard")
+    >>> volume_conversion(3, "gallon", "cubic yard")
     0.017814279
-    >>> volume_conversion(2, "cubicyard", "litre")
+    >>> volume_conversion(2, "cubic yard", "litre")
     1529.1
-    >>> volume_conversion(4, "cubicfoot", "cup")
+    >>> volume_conversion(4, "cubic foot", "cup")
     473.396
     >>> volume_conversion(1, "cup", "kilolitre")
     0.000236588
@@ -54,7 +58,7 @@ def volume_conversion(value: float, from_type: str, to_type: str) -> float:
     Traceback (most recent call last):
         ...
     ValueError: Invalid 'from_type' value: 'wrongUnit'  Supported values are:
-    cubicmeter, litre, kilolitre, gallon, cubicyard, cubicfoot, cup
+    cubic meter, litre, kilolitre, gallon, cubic yard, cubic foot, cup
     """
     if from_type not in METRIC_CONVERSION:
         raise ValueError(
@@ -66,7 +70,11 @@ def volume_conversion(value: float, from_type: str, to_type: str) -> float:
             f"Invalid 'to_type' value: {to_type!r}.  Supported values are:\n"
             + ", ".join(METRIC_CONVERSION)
         )
-    return value * METRIC_CONVERSION[from_type].from_ * METRIC_CONVERSION[to_type].to
+    return (
+        value
+        * METRIC_CONVERSION[from_type].from_factor
+        * METRIC_CONVERSION[to_type].to_factor
+    )
 
 
 if __name__ == "__main__":

data_structures/arrays/permutations.py

@@ -1,7 +1,6 @@
 def permute(nums: list[int]) -> list[list[int]]:
     """
     Return all permutations.
-
     >>> from itertools import permutations
     >>> numbers= [1,2,3]
     >>> all(list(nums) in permute(numbers) for nums in permutations(numbers))
@@ -20,7 +19,32 @@ def permute(nums: list[int]) -> list[list[int]]:
     return result
 
 
+def permute2(nums):
+    """
+    Return all permutations of the given list.
+
+    >>> permute2([1, 2, 3])
+    [[1, 2, 3], [1, 3, 2], [2, 1, 3], [2, 3, 1], [3, 2, 1], [3, 1, 2]]
+    """
+
+    def backtrack(start):
+        if start == len(nums) - 1:
+            output.append(nums[:])
+        else:
+            for i in range(start, len(nums)):
+                nums[start], nums[i] = nums[i], nums[start]
+                backtrack(start + 1)
+                nums[start], nums[i] = nums[i], nums[start]  # backtrack
+
+    output = []
+    backtrack(0)
+    return output
+
+
 if __name__ == "__main__":
     import doctest
 
+    # use res to print the data in permute2 function
+    res = permute2([1, 2, 3])
+    print(res)
     doctest.testmod()

data_structures/arrays/product_sum.py

@@ -0,0 +1,98 @@
+"""
+Calculate the Product Sum from a Special Array.
+reference: https://dev.to/sfrasica/algorithms-product-sum-from-an-array-dc6
+
+Python doctests can be run with the following command:
+python -m doctest -v product_sum.py
+
+Calculate the product sum of a "special" array which can contain integers or nested
+arrays. The product sum is obtained by adding all elements and multiplying by their
+respective depths.
+
+For example, in the array [x, y], the product sum is (x + y). In the array [x, [y, z]],
+the product sum is x + 2 * (y + z). In the array [x, [y, [z]]],
+the product sum is x + 2 * (y + 3z).
+
+Example Input:
+[5, 2, [-7, 1], 3, [6, [-13, 8], 4]]
+Output: 12
+
+"""
+
+
+def product_sum(arr: list[int | list], depth: int) -> int:
+    """
+    Recursively calculates the product sum of an array.
+
+    The product sum of an array is defined as the sum of its elements multiplied by
+    their respective depths.  If an element is a list, its product sum is calculated
+    recursively by multiplying the sum of its elements with its depth plus one.
+
+    Args:
+        arr: The array of integers and nested lists.
+        depth: The current depth level.
+
+    Returns:
+        int: The product sum of the array.
+
+    Examples:
+        >>> product_sum([1, 2, 3], 1)
+        6
+        >>> product_sum([-1, 2, [-3, 4]], 2)
+        8
+        >>> product_sum([1, 2, 3], -1)
+        -6
+        >>> product_sum([1, 2, 3], 0)
+        0
+        >>> product_sum([1, 2, 3], 7)
+        42
+        >>> product_sum((1, 2, 3), 7)
+        42
+        >>> product_sum({1, 2, 3}, 7)
+        42
+        >>> product_sum([1, -1], 1)
+        0
+        >>> product_sum([1, -2], 1)
+        -1
+        >>> product_sum([-3.5, [1, [0.5]]], 1)
+        1.5
+
+    """
+    total_sum = 0
+    for ele in arr:
+        total_sum += product_sum(ele, depth + 1) if isinstance(ele, list) else ele
+    return total_sum * depth
+
+
+def product_sum_array(array: list[int | list]) -> int:
+    """
+    Calculates the product sum of an array.
+
+    Args:
+        array (List[Union[int, List]]): The array of integers and nested lists.
+
+    Returns:
+        int: The product sum of the array.
+
+    Examples:
+        >>> product_sum_array([1, 2, 3])
+        6
+        >>> product_sum_array([1, [2, 3]])
+        11
+        >>> product_sum_array([1, [2, [3, 4]]])
+        47
+        >>> product_sum_array([0])
+        0
+        >>> product_sum_array([-3.5, [1, [0.5]]])
+        1.5
+        >>> product_sum_array([1, -2])
+        -1
+
+    """
+    return product_sum(array, 1)
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

data_structures/binary_tree/binary_search_tree.py

@@ -1,5 +1,62 @@
-"""
+r"""
 A binary search Tree
+
+Example
+              8
+             / \
+            3   10
+           / \    \
+          1   6    14
+             / \   /
+            4   7 13
+
+>>> t = BinarySearchTree()
+>>> t.insert(8, 3, 6, 1, 10, 14, 13, 4, 7)
+>>> print(" ".join(repr(i.value) for i in t.traversal_tree()))
+8 3 1 6 4 7 10 14 13
+>>> print(" ".join(repr(i.value) for i in t.traversal_tree(postorder)))
+1 4 7 6 3 13 14 10 8
+>>> t.remove(20)
+Traceback (most recent call last):
+    ...
+ValueError: Value 20 not found
+>>> BinarySearchTree().search(6)
+Traceback (most recent call last):
+    ...
+IndexError: Warning: Tree is empty! please use another.
+
+Other example:
+
+>>> testlist = (8, 3, 6, 1, 10, 14, 13, 4, 7)
+>>> t = BinarySearchTree()
+>>> for i in testlist:
+...     t.insert(i)
+
+Prints all the elements of the list in order traversal
+>>> print(t)
+{'8': ({'3': (1, {'6': (4, 7)})}, {'10': (None, {'14': (13, None)})})}
+
+Test existence
+>>> t.search(6) is not None
+True
+>>> t.search(-1) is not None
+False
+
+>>> t.search(6).is_right
+True
+>>> t.search(1).is_right
+False
+
+>>> t.get_max().value
+14
+>>> t.get_min().value
+1
+>>> t.empty()
+False
+>>> for i in testlist:
+...     t.remove(i)
+>>> t.empty()
+True
 """
 
 from collections.abc import Iterable
@@ -20,6 +77,10 @@ class Node:
             return str(self.value)
         return pformat({f"{self.value}": (self.left, self.right)}, indent=1)
 
+    @property
+    def is_right(self) -> bool:
+        return self.parent is not None and self is self.parent.right
+
 
 class BinarySearchTree:
     def __init__(self, root: Node | None = None):
@@ -35,17 +96,12 @@ class BinarySearchTree:
         if new_children is not None:  # reset its kids
             new_children.parent = node.parent
         if node.parent is not None:  # reset its parent
-            if self.is_right(node):  # If it is the right children
+            if node.is_right:  # If it is the right child
                 node.parent.right = new_children
             else:
                 node.parent.left = new_children
         else:
-            self.root = None
+            self.root = new_children
-
-    def is_right(self, node: Node) -> bool:
-        if node.parent and node.parent.right:
-            return node == node.parent.right
-        return False
 
     def empty(self) -> bool:
         return self.root is None
@@ -119,22 +175,26 @@ class BinarySearchTree:
         return node
 
     def remove(self, value: int) -> None:
-        node = self.search(value)  # Look for the node with that label
+        # Look for the node with that label
-        if node is not None:
+        node = self.search(value)
-            if node.left is None and node.right is None:  # If it has no children
+        if node is None:
-                self.__reassign_nodes(node, None)
+            msg = f"Value {value} not found"
-            elif node.left is None:  # Has only right children
+            raise ValueError(msg)
-                self.__reassign_nodes(node, node.right)
+
-            elif node.right is None:  # Has only left children
+        if node.left is None and node.right is None:  # If it has no children
-                self.__reassign_nodes(node, node.left)
+            self.__reassign_nodes(node, None)
-            else:
+        elif node.left is None:  # Has only right children
-                tmp_node = self.get_max(
+            self.__reassign_nodes(node, node.right)
-                    node.left
+        elif node.right is None:  # Has only left children
-                )  # Gets the max value of the left branch
+            self.__reassign_nodes(node, node.left)
-                self.remove(tmp_node.value)  # type: ignore
+        else:
-                node.value = (
+            predecessor = self.get_max(
-                    tmp_node.value  # type: ignore
+                node.left
-                )  # Assigns the value to the node to delete and keep tree structure
+            )  # Gets the max value of the left branch
+            self.remove(predecessor.value)  # type: ignore
+            node.value = (
+                predecessor.value  # type: ignore
+            )  # Assigns the value to the node to delete and keep tree structure
 
     def preorder_traverse(self, node: Node | None) -> Iterable:
         if node is not None:
@@ -177,55 +237,6 @@ def postorder(curr_node: Node | None) -> list[Node]:
     return node_list
 
 
-def binary_search_tree() -> None:
-    r"""
-    Example
-                  8
-                 / \
-                3   10
-               / \    \
-              1   6    14
-                 / \   /
-                4   7 13
-
-    >>> t = BinarySearchTree()
-    >>> t.insert(8, 3, 6, 1, 10, 14, 13, 4, 7)
-    >>> print(" ".join(repr(i.value) for i in t.traversal_tree()))
-    8 3 1 6 4 7 10 14 13
-    >>> print(" ".join(repr(i.value) for i in t.traversal_tree(postorder)))
-    1 4 7 6 3 13 14 10 8
-    >>> BinarySearchTree().search(6)
-    Traceback (most recent call last):
-        ...
-    IndexError: Warning: Tree is empty! please use another.
-    """
-    testlist = (8, 3, 6, 1, 10, 14, 13, 4, 7)
-    t = BinarySearchTree()
-    for i in testlist:
-        t.insert(i)
-
-    # Prints all the elements of the list in order traversal
-    print(t)
-
-    if t.search(6) is not None:
-        print("The value 6 exists")
-    else:
-        print("The value 6 doesn't exist")
-
-    if t.search(-1) is not None:
-        print("The value -1 exists")
-    else:
-        print("The value -1 doesn't exist")
-
-    if not t.empty():
-        print("Max Value: ", t.get_max().value)  # type: ignore
-        print("Min Value: ", t.get_min().value)  # type: ignore
-
-    for i in testlist:
-        t.remove(i)
-        print(t)
-
-
 if __name__ == "__main__":
     import doctest
 

data_structures/binary_tree/binary_tree_traversals.py

@@ -58,6 +58,19 @@ def inorder(root: Node | None) -> list[int]:
     return [*inorder(root.left), root.data, *inorder(root.right)] if root else []
 
 
+def reverse_inorder(root: Node | None) -> list[int]:
+    """
+    Reverse in-order traversal visits right subtree, root node, left subtree.
+    >>> reverse_inorder(make_tree())
+    [3, 1, 5, 2, 4]
+    """
+    return (
+        [*reverse_inorder(root.right), root.data, *reverse_inorder(root.left)]
+        if root
+        else []
+    )
+
+
 def height(root: Node | None) -> int:
     """
     Recursive function for calculating the height of the binary tree.
@@ -161,15 +174,12 @@ def zigzag(root: Node | None) -> Sequence[Node | None] | list[Any]:
 
 
 def main() -> None:  # Main function for testing.
-    """
+    # Create binary tree.
-    Create binary tree.
-    """
     root = make_tree()
-    """
-    All Traversals of the binary are as follows:
-    """
 
+    # All Traversals of the binary are as follows:
     print(f"In-order Traversal: {inorder(root)}")
+    print(f"Reverse In-order Traversal: {reverse_inorder(root)}")
     print(f"Pre-order Traversal: {preorder(root)}")
     print(f"Post-order Traversal: {postorder(root)}", "\n")
 

data_structures/binary_tree/distribute_coins.py

@@ -39,8 +39,8 @@ Space: O(1)
 
 from __future__ import annotations
 
-from collections import namedtuple
 from dataclasses import dataclass
+from typing import NamedTuple
 
 
 @dataclass
@@ -50,7 +50,9 @@ class TreeNode:
     right: TreeNode | None = None
 
 
-CoinsDistribResult = namedtuple("CoinsDistribResult", "moves excess")
+class CoinsDistribResult(NamedTuple):
+    moves: int
+    excess: int
 
 
 def distribute_coins(root: TreeNode | None) -> int:
@@ -79,7 +81,7 @@ def distribute_coins(root: TreeNode | None) -> int:
     # Validation
     def count_nodes(node: TreeNode | None) -> int:
         """
-        >>> count_nodes(None):
+        >>> count_nodes(None)
         0
         """
         if node is None:
@@ -89,7 +91,7 @@ def distribute_coins(root: TreeNode | None) -> int:
 
     def count_coins(node: TreeNode | None) -> int:
         """
-        >>> count_coins(None):
+        >>> count_coins(None)
         0
         """
         if node is None:

data_structures/binary_tree/red_black_tree.py

@@ -152,7 +152,7 @@ class RedBlackTree:
                     self.grandparent.color = 1
                     self.grandparent._insert_repair()
 
-    def remove(self, label: int) -> RedBlackTree:
+    def remove(self, label: int) -> RedBlackTree:  # noqa: PLR0912
         """Remove label from this tree."""
         if self.label == label:
             if self.left and self.right:

data_structures/binary_tree/segment_tree.py

@@ -7,7 +7,8 @@ class SegmentTree:
         self.st = [0] * (
             4 * self.N
         )  # approximate the overall size of segment tree with array N
-        self.build(1, 0, self.N - 1)
+        if self.N:
+            self.build(1, 0, self.N - 1)
 
     def left(self, idx):
         return idx * 2

data_structures/queue/double_ended_queue.py

@@ -32,7 +32,7 @@ class Deque:
         the number of nodes
     """
 
-    __slots__ = ["_front", "_back", "_len"]
+    __slots__ = ("_front", "_back", "_len")
 
     @dataclass
     class _Node:
@@ -54,7 +54,7 @@ class Deque:
             the current node of the iteration.
         """
 
-        __slots__ = ["_cur"]
+        __slots__ = ("_cur",)
 
         def __init__(self, cur: Deque._Node | None) -> None:
             self._cur = cur

data_structures/queue/queue_by_list.py

@@ -0,0 +1,141 @@
+"""Queue represented by a Python list"""
+
+from collections.abc import Iterable
+from typing import Generic, TypeVar
+
+_T = TypeVar("_T")
+
+
+class QueueByList(Generic[_T]):
+    def __init__(self, iterable: Iterable[_T] | None = None) -> None:
+        """
+        >>> QueueByList()
+        Queue(())
+        >>> QueueByList([10, 20, 30])
+        Queue((10, 20, 30))
+        >>> QueueByList((i**2 for i in range(1, 4)))
+        Queue((1, 4, 9))
+        """
+        self.entries: list[_T] = list(iterable or [])
+
+    def __len__(self) -> int:
+        """
+        >>> len(QueueByList())
+        0
+        >>> from string import ascii_lowercase
+        >>> len(QueueByList(ascii_lowercase))
+        26
+        >>> queue = QueueByList()
+        >>> for i in range(1, 11):
+        ...     queue.put(i)
+        >>> len(queue)
+        10
+        >>> for i in range(2):
+        ...   queue.get()
+        1
+        2
+        >>> len(queue)
+        8
+        """
+
+        return len(self.entries)
+
+    def __repr__(self) -> str:
+        """
+        >>> queue = QueueByList()
+        >>> queue
+        Queue(())
+        >>> str(queue)
+        'Queue(())'
+        >>> queue.put(10)
+        >>> queue
+        Queue((10,))
+        >>> queue.put(20)
+        >>> queue.put(30)
+        >>> queue
+        Queue((10, 20, 30))
+        """
+
+        return f"Queue({tuple(self.entries)})"
+
+    def put(self, item: _T) -> None:
+        """Put `item` to the Queue
+
+        >>> queue = QueueByList()
+        >>> queue.put(10)
+        >>> queue.put(20)
+        >>> len(queue)
+        2
+        >>> queue
+        Queue((10, 20))
+        """
+
+        self.entries.append(item)
+
+    def get(self) -> _T:
+        """
+        Get `item` from the Queue
+
+        >>> queue = QueueByList((10, 20, 30))
+        >>> queue.get()
+        10
+        >>> queue.put(40)
+        >>> queue.get()
+        20
+        >>> queue.get()
+        30
+        >>> len(queue)
+        1
+        >>> queue.get()
+        40
+        >>> queue.get()
+        Traceback (most recent call last):
+            ...
+        IndexError: Queue is empty
+        """
+
+        if not self.entries:
+            raise IndexError("Queue is empty")
+        return self.entries.pop(0)
+
+    def rotate(self, rotation: int) -> None:
+        """Rotate the items of the Queue `rotation` times
+
+        >>> queue = QueueByList([10, 20, 30, 40])
+        >>> queue
+        Queue((10, 20, 30, 40))
+        >>> queue.rotate(1)
+        >>> queue
+        Queue((20, 30, 40, 10))
+        >>> queue.rotate(2)
+        >>> queue
+        Queue((40, 10, 20, 30))
+        """
+
+        put = self.entries.append
+        get = self.entries.pop
+
+        for _ in range(rotation):
+            put(get(0))
+
+    def get_front(self) -> _T:
+        """Get the front item from the Queue
+
+        >>> queue = QueueByList((10, 20, 30))
+        >>> queue.get_front()
+        10
+        >>> queue
+        Queue((10, 20, 30))
+        >>> queue.get()
+        10
+        >>> queue.get_front()
+        20
+        """
+
+        return self.entries[0]
+
+
+if __name__ == "__main__":
+    from doctest import testmod
+
+    testmod()

data_structures/queue/queue_on_list.py

@@ -1,52 +0,0 @@
-"""Queue represented by a Python list"""
-
-
-class Queue:
-    def __init__(self):
-        self.entries = []
-        self.length = 0
-        self.front = 0
-
-    def __str__(self):
-        printed = "<" + str(self.entries)[1:-1] + ">"
-        return printed
-
-    """Enqueues {@code item}
-    @param item
-        item to enqueue"""
-
-    def put(self, item):
-        self.entries.append(item)
-        self.length = self.length + 1
-
-    """Dequeues {@code item}
-    @requirement: |self.length| > 0
-    @return dequeued
-        item that was dequeued"""
-
-    def get(self):
-        self.length = self.length - 1
-        dequeued = self.entries[self.front]
-        # self.front-=1
-        # self.entries = self.entries[self.front:]
-        self.entries = self.entries[1:]
-        return dequeued
-
-    """Rotates the queue {@code rotation} times
-    @param rotation
-        number of times to rotate queue"""
-
-    def rotate(self, rotation):
-        for _ in range(rotation):
-            self.put(self.get())
-
-    """Enqueues {@code item}
-    @return item at front of self.entries"""
-
-    def get_front(self):
-        return self.entries[0]
-
-    """Returns the length of this.entries"""
-
-    def size(self):
-        return self.length

data_structures/stacks/infix_to_postfix_conversion.py

@@ -4,9 +4,26 @@ https://en.wikipedia.org/wiki/Reverse_Polish_notation
 https://en.wikipedia.org/wiki/Shunting-yard_algorithm
 """
 
+from typing import Literal
+
 from .balanced_parentheses import balanced_parentheses
 from .stack import Stack
 
+PRECEDENCES: dict[str, int] = {
+    "+": 1,
+    "-": 1,
+    "*": 2,
+    "/": 2,
+    "^": 3,
+}
+ASSOCIATIVITIES: dict[str, Literal["LR", "RL"]] = {
+    "+": "LR",
+    "-": "LR",
+    "*": "LR",
+    "/": "LR",
+    "^": "RL",
+}
+
 
 def precedence(char: str) -> int:
     """
@@ -14,7 +31,15 @@ def precedence(char: str) -> int:
     order of operation.
     https://en.wikipedia.org/wiki/Order_of_operations
     """
-    return {"+": 1, "-": 1, "*": 2, "/": 2, "^": 3}.get(char, -1)
+    return PRECEDENCES.get(char, -1)
+
+
+def associativity(char: str) -> Literal["LR", "RL"]:
+    """
+    Return the associativity of the operator `char`.
+    https://en.wikipedia.org/wiki/Operator_associativity
+    """
+    return ASSOCIATIVITIES[char]
 
 
 def infix_to_postfix(expression_str: str) -> str:
@@ -35,6 +60,8 @@ def infix_to_postfix(expression_str: str) -> str:
     'a b c * + d e * f + g * +'
     >>> infix_to_postfix("x^y/(5*z)+2")
     'x y ^ 5 z * / 2 +'
+    >>> infix_to_postfix("2^3^2")
+    '2 3 2 ^ ^'
     """
     if not balanced_parentheses(expression_str):
         raise ValueError("Mismatched parentheses")
@@ -50,9 +77,26 @@ def infix_to_postfix(expression_str: str) -> str:
                 postfix.append(stack.pop())
             stack.pop()
         else:
-            while not stack.is_empty() and precedence(char) <= precedence(stack.peek()):
+            while True:
+                if stack.is_empty():
+                    stack.push(char)
+                    break
+
+                char_precedence = precedence(char)
+                tos_precedence = precedence(stack.peek())
+
+                if char_precedence > tos_precedence:
+                    stack.push(char)
+                    break
+                if char_precedence < tos_precedence:
+                    postfix.append(stack.pop())
+                    continue
+                # Precedences are equal
+                if associativity(char) == "RL":
+                    stack.push(char)
+                    break
                 postfix.append(stack.pop())
-            stack.push(char)
+
     while not stack.is_empty():
         postfix.append(stack.pop())
     return " ".join(postfix)

data_structures/trie/radix_tree.py

@@ -54,10 +54,17 @@ class RadixNode:
             word (str): word to insert
 
         >>> RadixNode("myprefix").insert("mystring")
+
+        >>> root = RadixNode()
+        >>> root.insert_many(['myprefix', 'myprefixA', 'myprefixAA'])
+        >>> root.print_tree()
+        - myprefix   (leaf)
+        -- A   (leaf)
+        --- A   (leaf)
         """
         # Case 1: If the word is the prefix of the node
         # Solution: We set the current node as leaf
-        if self.prefix == word:
+        if self.prefix == word and not self.is_leaf:
             self.is_leaf = True
 
         # Case 2: The node has no edges that have a prefix to the word
@@ -156,7 +163,7 @@ class RadixNode:
                         del self.nodes[word[0]]
                         # We merge the current node with its only child
                         if len(self.nodes) == 1 and not self.is_leaf:
-                            merging_node = list(self.nodes.values())[0]
+                            merging_node = next(iter(self.nodes.values()))
                             self.is_leaf = merging_node.is_leaf
                             self.prefix += merging_node.prefix
                             self.nodes = merging_node.nodes
@@ -165,7 +172,7 @@ class RadixNode:
                         incoming_node.is_leaf = False
                     # If there is 1 edge, we merge it with its child
                     else:
-                        merging_node = list(incoming_node.nodes.values())[0]
+                        merging_node = next(iter(incoming_node.nodes.values()))
                         incoming_node.is_leaf = merging_node.is_leaf
                         incoming_node.prefix += merging_node.prefix
                         incoming_node.nodes = merging_node.nodes

digital_image_processing/dithering/burkes.py

@@ -39,9 +39,18 @@ class Burkes:
     def get_greyscale(cls, blue: int, green: int, red: int) -> float:
         """
         >>> Burkes.get_greyscale(3, 4, 5)
-        3.753
+        4.185
+        >>> Burkes.get_greyscale(0, 0, 0)
+        0.0
+        >>> Burkes.get_greyscale(255, 255, 255)
+        255.0
         """
-        return 0.114 * blue + 0.587 * green + 0.2126 * red
+        """
+        Formula from https://en.wikipedia.org/wiki/HSL_and_HSV
+        cf Lightness section, and Fig 13c.
+        We use the first of four possible.
+        """
+        return 0.114 * blue + 0.587 * green + 0.299 * red
 
     def process(self) -> None:
         for y in range(self.height):
@@ -49,10 +58,10 @@ class Burkes:
                 greyscale = int(self.get_greyscale(*self.input_img[y][x]))
                 if self.threshold > greyscale + self.error_table[y][x]:
                     self.output_img[y][x] = (0, 0, 0)
-                    current_error = greyscale + self.error_table[x][y]
+                    current_error = greyscale + self.error_table[y][x]
                 else:
                     self.output_img[y][x] = (255, 255, 255)
-                    current_error = greyscale + self.error_table[x][y] - 255
+                    current_error = greyscale + self.error_table[y][x] - 255
                 """
                 Burkes error propagation (`*` is current pixel):
 

digital_image_processing/morphological_operations/erosion_operation.py

@@ -7,6 +7,7 @@ from PIL import Image
 def rgb_to_gray(rgb: np.ndarray) -> np.ndarray:
     """
     Return gray image from rgb image
+
     >>> rgb_to_gray(np.array([[[127, 255, 0]]]))
     array([[187.6453]])
     >>> rgb_to_gray(np.array([[[0, 0, 0]]]))
@@ -23,6 +24,7 @@ def rgb_to_gray(rgb: np.ndarray) -> np.ndarray:
 def gray_to_binary(gray: np.ndarray) -> np.ndarray:
     """
     Return binary image from gray image
+
     >>> gray_to_binary(np.array([[127, 255, 0]]))
     array([[False,  True, False]])
     >>> gray_to_binary(np.array([[0]]))
@@ -40,6 +42,7 @@ def gray_to_binary(gray: np.ndarray) -> np.ndarray:
 def erosion(image: np.ndarray, kernel: np.ndarray) -> np.ndarray:
     """
     Return eroded image
+
     >>> erosion(np.array([[True, True, False]]), np.array([[0, 1, 0]]))
     array([[False, False, False]])
     >>> erosion(np.array([[True, False, False]]), np.array([[1, 1, 0]]))

digital_image_processing/rotation/rotation.py

@@ -10,12 +10,12 @@ def get_rotation(
 ) -> np.ndarray:
     """
     Get image rotation
-    :param img: np.array
+    :param img: np.ndarray
     :param pt1: 3x2 list
     :param pt2: 3x2 list
     :param rows: columns image shape
     :param cols: rows image shape
-    :return: np.array
+    :return: np.ndarray
     """
     matrix = cv2.getAffineTransform(pt1, pt2)
     return cv2.warpAffine(img, matrix, (rows, cols))

divide_and_conquer/convex_hull.py

@@ -266,7 +266,7 @@ def convex_hull_bf(points: list[Point]) -> list[Point]:
             points_left_of_ij = points_right_of_ij = False
             ij_part_of_convex_hull = True
             for k in range(n):
-                if k != i and k != j:
+                if k not in {i, j}:
                     det_k = _det(points[i], points[j], points[k])
 
                     if det_k > 0:

divide_and_conquer/max_subarray.py

@@ -0,0 +1,112 @@
+"""
+The maximum subarray problem is the task of finding the continuous subarray that has the
+maximum sum within a given array of numbers. For example, given the array
+[-2, 1, -3, 4, -1, 2, 1, -5, 4], the contiguous subarray with the maximum sum is
+[4, -1, 2, 1], which has a sum of 6.
+
+This divide-and-conquer algorithm finds the maximum subarray in O(n log n) time.
+"""
+from __future__ import annotations
+
+import time
+from collections.abc import Sequence
+from random import randint
+
+from matplotlib import pyplot as plt
+
+
+def max_subarray(
+    arr: Sequence[float], low: int, high: int
+) -> tuple[int | None, int | None, float]:
+    """
+    Solves the maximum subarray problem using divide and conquer.
+    :param arr:     the given array of numbers
+    :param low:     the start index
+    :param high:    the end index
+    :return:        the start index of the maximum subarray, the end index of the
+                    maximum subarray, and the maximum subarray sum
+
+    >>> nums = [-2, 1, -3, 4, -1, 2, 1, -5, 4]
+    >>> max_subarray(nums, 0, len(nums) - 1)
+    (3, 6, 6)
+    >>> nums = [2, 8, 9]
+    >>> max_subarray(nums, 0, len(nums) - 1)
+    (0, 2, 19)
+    >>> nums = [0, 0]
+    >>> max_subarray(nums, 0, len(nums) - 1)
+    (0, 0, 0)
+    >>> nums = [-1.0, 0.0, 1.0]
+    >>> max_subarray(nums, 0, len(nums) - 1)
+    (2, 2, 1.0)
+    >>> nums = [-2, -3, -1, -4, -6]
+    >>> max_subarray(nums, 0, len(nums) - 1)
+    (2, 2, -1)
+    >>> max_subarray([], 0, 0)
+    (None, None, 0)
+    """
+    if not arr:
+        return None, None, 0
+    if low == high:
+        return low, high, arr[low]
+
+    mid = (low + high) // 2
+    left_low, left_high, left_sum = max_subarray(arr, low, mid)
+    right_low, right_high, right_sum = max_subarray(arr, mid + 1, high)
+    cross_left, cross_right, cross_sum = max_cross_sum(arr, low, mid, high)
+    if left_sum >= right_sum and left_sum >= cross_sum:
+        return left_low, left_high, left_sum
+    elif right_sum >= left_sum and right_sum >= cross_sum:
+        return right_low, right_high, right_sum
+    return cross_left, cross_right, cross_sum
+
+
+def max_cross_sum(
+    arr: Sequence[float], low: int, mid: int, high: int
+) -> tuple[int, int, float]:
+    left_sum, max_left = float("-inf"), -1
+    right_sum, max_right = float("-inf"), -1
+
+    summ: int | float = 0
+    for i in range(mid, low - 1, -1):
+        summ += arr[i]
+        if summ > left_sum:
+            left_sum = summ
+            max_left = i
+
+    summ = 0
+    for i in range(mid + 1, high + 1):
+        summ += arr[i]
+        if summ > right_sum:
+            right_sum = summ
+            max_right = i
+
+    return max_left, max_right, (left_sum + right_sum)
+
+
+def time_max_subarray(input_size: int) -> float:
+    arr = [randint(1, input_size) for _ in range(input_size)]
+    start = time.time()
+    max_subarray(arr, 0, input_size - 1)
+    end = time.time()
+    return end - start
+
+
+def plot_runtimes() -> None:
+    input_sizes = [10, 100, 1000, 10000, 50000, 100000, 200000, 300000, 400000, 500000]
+    runtimes = [time_max_subarray(input_size) for input_size in input_sizes]
+    print("No of Inputs\t\tTime Taken")
+    for input_size, runtime in zip(input_sizes, runtimes):
+        print(input_size, "\t\t", runtime)
+    plt.plot(input_sizes, runtimes)
+    plt.xlabel("Number of Inputs")
+    plt.ylabel("Time taken in seconds")
+    plt.show()
+
+
+if __name__ == "__main__":
+    """
+    A random simulation of this algorithm.
+    """
+    from doctest import testmod
+
+    testmod()

divide_and_conquer/max_subarray_sum.py

@@ -1,78 +0,0 @@
-"""
-Given a array of length n, max_subarray_sum() finds
-the maximum of sum of contiguous sub-array using divide and conquer method.
-
-Time complexity : O(n log n)
-
-Ref : INTRODUCTION TO ALGORITHMS THIRD EDITION
-(section : 4, sub-section : 4.1, page : 70)
-
-"""
-
-
-def max_sum_from_start(array):
-    """This function finds the maximum contiguous sum of array from 0 index
-
-    Parameters :
-    array (list[int]) : given array
-
-    Returns :
-    max_sum (int) : maximum contiguous sum of array from 0 index
-
-    """
-    array_sum = 0
-    max_sum = float("-inf")
-    for num in array:
-        array_sum += num
-        if array_sum > max_sum:
-            max_sum = array_sum
-    return max_sum
-
-
-def max_cross_array_sum(array, left, mid, right):
-    """This function finds the maximum contiguous sum of left and right arrays
-
-    Parameters :
-    array, left, mid, right (list[int], int, int, int)
-
-    Returns :
-    (int) :  maximum of sum of contiguous sum of left and right arrays
-
-    """
-
-    max_sum_of_left = max_sum_from_start(array[left : mid + 1][::-1])
-    max_sum_of_right = max_sum_from_start(array[mid + 1 : right + 1])
-    return max_sum_of_left + max_sum_of_right
-
-
-def max_subarray_sum(array, left, right):
-    """Maximum contiguous sub-array sum, using divide and conquer method
-
-    Parameters :
-    array, left, right (list[int], int, int) :
-    given array, current left index and current right index
-
-    Returns :
-    int :  maximum of sum of contiguous sub-array
-
-    """
-
-    # base case: array has only one element
-    if left == right:
-        return array[right]
-
-    # Recursion
-    mid = (left + right) // 2
-    left_half_sum = max_subarray_sum(array, left, mid)
-    right_half_sum = max_subarray_sum(array, mid + 1, right)
-    cross_sum = max_cross_array_sum(array, left, mid, right)
-    return max(left_half_sum, right_half_sum, cross_sum)
-
-
-if __name__ == "__main__":
-    array = [-2, -5, 6, -2, -3, 1, 5, -6]
-    array_length = len(array)
-    print(
-        "Maximum sum of contiguous subarray:",
-        max_subarray_sum(array, 0, array_length - 1),
-    )

dynamic_programming/max_sub_array.py

@@ -1,93 +0,0 @@
-"""
-author : Mayank Kumar Jha (mk9440)
-"""
-from __future__ import annotations
-
-
-def find_max_sub_array(a, low, high):
-    if low == high:
-        return low, high, a[low]
-    else:
-        mid = (low + high) // 2
-        left_low, left_high, left_sum = find_max_sub_array(a, low, mid)
-        right_low, right_high, right_sum = find_max_sub_array(a, mid + 1, high)
-        cross_left, cross_right, cross_sum = find_max_cross_sum(a, low, mid, high)
-        if left_sum >= right_sum and left_sum >= cross_sum:
-            return left_low, left_high, left_sum
-        elif right_sum >= left_sum and right_sum >= cross_sum:
-            return right_low, right_high, right_sum
-        else:
-            return cross_left, cross_right, cross_sum
-
-
-def find_max_cross_sum(a, low, mid, high):
-    left_sum, max_left = -999999999, -1
-    right_sum, max_right = -999999999, -1
-    summ = 0
-    for i in range(mid, low - 1, -1):
-        summ += a[i]
-        if summ > left_sum:
-            left_sum = summ
-            max_left = i
-    summ = 0
-    for i in range(mid + 1, high + 1):
-        summ += a[i]
-        if summ > right_sum:
-            right_sum = summ
-            max_right = i
-    return max_left, max_right, (left_sum + right_sum)
-
-
-def max_sub_array(nums: list[int]) -> int:
-    """
-    Finds the contiguous subarray which has the largest sum and return its sum.
-
-    >>> max_sub_array([-2, 1, -3, 4, -1, 2, 1, -5, 4])
-    6
-
-    An empty (sub)array has sum 0.
-    >>> max_sub_array([])
-    0
-
-    If all elements are negative, the largest subarray would be the empty array,
-    having the sum 0.
-    >>> max_sub_array([-1, -2, -3])
-    0
-    >>> max_sub_array([5, -2, -3])
-    5
-    >>> max_sub_array([31, -41, 59, 26, -53, 58, 97, -93, -23, 84])
-    187
-    """
-    best = 0
-    current = 0
-    for i in nums:
-        current += i
-        current = max(current, 0)
-        best = max(best, current)
-    return best
-
-
-if __name__ == "__main__":
-    """
-    A random simulation of this algorithm.
-    """
-    import time
-    from random import randint
-
-    from matplotlib import pyplot as plt
-
-    inputs = [10, 100, 1000, 10000, 50000, 100000, 200000, 300000, 400000, 500000]
-    tim = []
-    for i in inputs:
-        li = [randint(1, i) for j in range(i)]
-        strt = time.time()
-        (find_max_sub_array(li, 0, len(li) - 1))
-        end = time.time()
-        tim.append(end - strt)
-    print("No of Inputs       Time Taken")
-    for i in range(len(inputs)):
-        print(inputs[i], "\t\t", tim[i])
-    plt.plot(inputs, tim)
-    plt.xlabel("Number of Inputs")
-    plt.ylabel("Time taken in seconds ")
-    plt.show()

dynamic_programming/max_subarray_sum.py

@@ -0,0 +1,60 @@
+"""
+The maximum subarray sum problem is the task of finding the maximum sum that can be
+obtained from a contiguous subarray within a given array of numbers. For example, given
+the array [-2, 1, -3, 4, -1, 2, 1, -5, 4], the contiguous subarray with the maximum sum
+is [4, -1, 2, 1], so the maximum subarray sum is 6.
+
+Kadane's algorithm is a simple dynamic programming algorithm that solves the maximum
+subarray sum problem in O(n) time and O(1) space.
+
+Reference: https://en.wikipedia.org/wiki/Maximum_subarray_problem
+"""
+from collections.abc import Sequence
+
+
+def max_subarray_sum(
+    arr: Sequence[float], allow_empty_subarrays: bool = False
+) -> float:
+    """
+    Solves the maximum subarray sum problem using Kadane's algorithm.
+    :param arr: the given array of numbers
+    :param allow_empty_subarrays: if True, then the algorithm considers empty subarrays
+
+    >>> max_subarray_sum([2, 8, 9])
+    19
+    >>> max_subarray_sum([0, 0])
+    0
+    >>> max_subarray_sum([-1.0, 0.0, 1.0])
+    1.0
+    >>> max_subarray_sum([1, 2, 3, 4, -2])
+    10
+    >>> max_subarray_sum([-2, 1, -3, 4, -1, 2, 1, -5, 4])
+    6
+    >>> max_subarray_sum([2, 3, -9, 8, -2])
+    8
+    >>> max_subarray_sum([-2, -3, -1, -4, -6])
+    -1
+    >>> max_subarray_sum([-2, -3, -1, -4, -6], allow_empty_subarrays=True)
+    0
+    >>> max_subarray_sum([])
+    0
+    """
+    if not arr:
+        return 0
+
+    max_sum = 0 if allow_empty_subarrays else float("-inf")
+    curr_sum = 0.0
+    for num in arr:
+        curr_sum = max(0 if allow_empty_subarrays else num, curr_sum + num)
+        max_sum = max(max_sum, curr_sum)
+
+    return max_sum
+
+
+if __name__ == "__main__":
+    from doctest import testmod
+
+    testmod()
+
+    nums = [-2, 1, -3, 4, -1, 2, 1, -5, 4]
+    print(f"{max_subarray_sum(nums) = }")

dynamic_programming/max_sum_contiguous_subsequence.py

@@ -1,20 +0,0 @@
-def max_subarray_sum(nums: list) -> int:
-    """
-    >>> max_subarray_sum([6 , 9, -1, 3, -7, -5, 10])
-    17
-    """
-    if not nums:
-        return 0
-    n = len(nums)
-
-    res, s, s_pre = nums[0], nums[0], nums[0]
-    for i in range(1, n):
-        s = max(nums[i], s_pre + nums[i])
-        s_pre = s
-        res = max(res, s)
-    return res
-
-
-if __name__ == "__main__":
-    nums = [6, 9, -1, 3, -7, -5, 10]
-    print(max_subarray_sum(nums))

dynamic_programming/regex_match.py

@@ -0,0 +1,97 @@
+"""
+Regex matching check if a text matches pattern or not.
+Pattern:
+    '.' Matches any single character.
+    '*' Matches zero or more of the preceding element.
+More info:
+    https://medium.com/trick-the-interviwer/regular-expression-matching-9972eb74c03
+"""
+
+
+def recursive_match(text: str, pattern: str) -> bool:
+    """
+    Recursive matching algorithm.
+
+    Time complexity: O(2 ^ (|text| + |pattern|))
+    Space complexity: Recursion depth is O(|text| + |pattern|).
+
+    :param text: Text to match.
+    :param pattern: Pattern to match.
+    :return: True if text matches pattern, False otherwise.
+
+    >>> recursive_match('abc', 'a.c')
+    True
+    >>> recursive_match('abc', 'af*.c')
+    True
+    >>> recursive_match('abc', 'a.c*')
+    True
+    >>> recursive_match('abc', 'a.c*d')
+    False
+    >>> recursive_match('aa', '.*')
+    True
+    """
+    if not pattern:
+        return not text
+
+    if not text:
+        return pattern[-1] == "*" and recursive_match(text, pattern[:-2])
+
+    if text[-1] == pattern[-1] or pattern[-1] == ".":
+        return recursive_match(text[:-1], pattern[:-1])
+
+    if pattern[-1] == "*":
+        return recursive_match(text[:-1], pattern) or recursive_match(
+            text, pattern[:-2]
+        )
+
+    return False
+
+
+def dp_match(text: str, pattern: str) -> bool:
+    """
+    Dynamic programming matching algorithm.
+
+    Time complexity: O(|text| * |pattern|)
+    Space complexity: O(|text| * |pattern|)
+
+    :param text: Text to match.
+    :param pattern: Pattern to match.
+    :return: True if text matches pattern, False otherwise.
+
+    >>> dp_match('abc', 'a.c')
+    True
+    >>> dp_match('abc', 'af*.c')
+    True
+    >>> dp_match('abc', 'a.c*')
+    True
+    >>> dp_match('abc', 'a.c*d')
+    False
+    >>> dp_match('aa', '.*')
+    True
+    """
+    m = len(text)
+    n = len(pattern)
+    dp = [[False for _ in range(n + 1)] for _ in range(m + 1)]
+    dp[0][0] = True
+
+    for j in range(1, n + 1):
+        dp[0][j] = pattern[j - 1] == "*" and dp[0][j - 2]
+
+    for i in range(1, m + 1):
+        for j in range(1, n + 1):
+            if pattern[j - 1] in {".", text[i - 1]}:
+                dp[i][j] = dp[i - 1][j - 1]
+            elif pattern[j - 1] == "*":
+                dp[i][j] = dp[i][j - 2]
+                if pattern[j - 2] in {".", text[i - 1]}:
+                    dp[i][j] |= dp[i - 1][j]
+            else:
+                dp[i][j] = False
+
+    return dp[m][n]
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

dynamic_programming/tribonacci.py

@@ -0,0 +1,24 @@
+# Tribonacci sequence using Dynamic Programming
+
+
+def tribonacci(num: int) -> list[int]:
+    """
+    Given a number, return first n Tribonacci Numbers.
+    >>> tribonacci(5)
+    [0, 0, 1, 1, 2]
+    >>> tribonacci(8)
+    [0, 0, 1, 1, 2, 4, 7, 13]
+    """
+    dp = [0] * num
+    dp[2] = 1
+
+    for i in range(3, num):
+        dp[i] = dp[i - 1] + dp[i - 2] + dp[i - 3]
+
+    return dp
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

electronics/electric_power.py

@@ -1,7 +1,12 @@
 # https://en.m.wikipedia.org/wiki/Electric_power
 from __future__ import annotations
 
-from collections import namedtuple
+from typing import NamedTuple
+
+
+class Result(NamedTuple):
+    name: str
+    value: float
 
 
 def electric_power(voltage: float, current: float, power: float) -> tuple:
@@ -10,11 +15,11 @@ def electric_power(voltage: float, current: float, power: float) -> tuple:
     fundamental value of electrical system.
     examples are below:
     >>> electric_power(voltage=0, current=2, power=5)
-    result(name='voltage', value=2.5)
+    Result(name='voltage', value=2.5)
     >>> electric_power(voltage=2, current=2, power=0)
-    result(name='power', value=4.0)
+    Result(name='power', value=4.0)
     >>> electric_power(voltage=-2, current=3, power=0)
-    result(name='power', value=6.0)
+    Result(name='power', value=6.0)
     >>> electric_power(voltage=2, current=4, power=2)
     Traceback (most recent call last):
         ...
@@ -28,9 +33,8 @@ def electric_power(voltage: float, current: float, power: float) -> tuple:
         ...
     ValueError: Power cannot be negative in any electrical/electronics system
     >>> electric_power(voltage=2.2, current=2.2, power=0)
-    result(name='power', value=4.84)
+    Result(name='power', value=4.84)
     """
-    result = namedtuple("result", "name value")
     if (voltage, current, power).count(0) != 1:
         raise ValueError("Only one argument must be 0")
     elif power < 0:
@@ -38,11 +42,11 @@ def electric_power(voltage: float, current: float, power: float) -> tuple:
             "Power cannot be negative in any electrical/electronics system"
         )
     elif voltage == 0:
-        return result("voltage", power / current)
+        return Result("voltage", power / current)
     elif current == 0:
-        return result("current", power / voltage)
+        return Result("current", power / voltage)
     elif power == 0:
-        return result("power", float(round(abs(voltage * current), 2)))
+        return Result("power", float(round(abs(voltage * current), 2)))
     else:
         raise ValueError("Exactly one argument must be 0")
 

financial/interest.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 
 def simple_interest(
-    principal: float, daily_interest_rate: float, days_between_payments: int
+    principal: float, daily_interest_rate: float, days_between_payments: float
 ) -> float:
     """
     >>> simple_interest(18000.0, 0.06, 3)
@@ -42,7 +42,7 @@ def simple_interest(
 def compound_interest(
     principal: float,
     nominal_annual_interest_rate_percentage: float,
-    number_of_compounding_periods: int,
+    number_of_compounding_periods: float,
 ) -> float:
     """
     >>> compound_interest(10000.0, 0.05, 3)
@@ -77,6 +77,43 @@ def compound_interest(
     )
 
 
+def apr_interest(
+    principal: float,
+    nominal_annual_percentage_rate: float,
+    number_of_years: float,
+) -> float:
+    """
+    >>> apr_interest(10000.0, 0.05, 3)
+    1618.223072263547
+    >>> apr_interest(10000.0, 0.05, 1)
+    512.6749646744732
+    >>> apr_interest(0.5, 0.05, 3)
+    0.08091115361317736
+    >>> apr_interest(10000.0, 0.06, -4)
+    Traceback (most recent call last):
+        ...
+    ValueError: number_of_years must be > 0
+    >>> apr_interest(10000.0, -3.5, 3.0)
+    Traceback (most recent call last):
+        ...
+    ValueError: nominal_annual_percentage_rate must be >= 0
+    >>> apr_interest(-5500.0, 0.01, 5)
+    Traceback (most recent call last):
+        ...
+    ValueError: principal must be > 0
+    """
+    if number_of_years <= 0:
+        raise ValueError("number_of_years must be > 0")
+    if nominal_annual_percentage_rate < 0:
+        raise ValueError("nominal_annual_percentage_rate must be >= 0")
+    if principal <= 0:
+        raise ValueError("principal must be > 0")
+
+    return compound_interest(
+        principal, nominal_annual_percentage_rate / 365, number_of_years * 365
+    )
+
+
 if __name__ == "__main__":
     import doctest
 

fractals/sierpinski_triangle.py

@@ -82,3 +82,4 @@ if __name__ == "__main__":
 
     vertices = [(-175, -125), (0, 175), (175, -125)]  # vertices of triangle
     triangle(vertices[0], vertices[1], vertices[2], int(sys.argv[1]))
+    turtle.Screen().exitonclick()

graphs/bi_directional_dijkstra.py

@@ -26,8 +26,8 @@ def pass_and_relaxation(
     cst_bwd: dict,
     queue: PriorityQueue,
     parent: dict,
-    shortest_distance: float | int,
+    shortest_distance: float,
-) -> float | int:
+) -> float:
     for nxt, d in graph[v]:
         if nxt in visited_forward:
             continue

graphs/dijkstra_binary_grid.py

@@ -0,0 +1,89 @@
+"""
+This script implements the Dijkstra algorithm on a binary grid.
+The grid consists of 0s and 1s, where 1 represents
+a walkable node and 0 represents an obstacle.
+The algorithm finds the shortest path from a start node to a destination node.
+Diagonal movement can be allowed or disallowed.
+"""
+
+from heapq import heappop, heappush
+
+import numpy as np
+
+
+def dijkstra(
+    grid: np.ndarray,
+    source: tuple[int, int],
+    destination: tuple[int, int],
+    allow_diagonal: bool,
+) -> tuple[float | int, list[tuple[int, int]]]:
+    """
+    Implements Dijkstra's algorithm on a binary grid.
+
+    Args:
+        grid (np.ndarray): A 2D numpy array representing the grid.
+        1 represents a walkable node and 0 represents an obstacle.
+        source (Tuple[int, int]): A tuple representing the start node.
+        destination (Tuple[int, int]): A tuple representing the
+        destination node.
+        allow_diagonal (bool): A boolean determining whether
+        diagonal movements are allowed.
+
+    Returns:
+        Tuple[Union[float, int], List[Tuple[int, int]]]:
+        The shortest distance from the start node to the destination node
+        and the shortest path as a list of nodes.
+
+    >>> dijkstra(np.array([[1, 1, 1], [0, 1, 0], [0, 1, 1]]), (0, 0), (2, 2), False)
+    (4.0, [(0, 0), (0, 1), (1, 1), (2, 1), (2, 2)])
+
+    >>> dijkstra(np.array([[1, 1, 1], [0, 1, 0], [0, 1, 1]]), (0, 0), (2, 2), True)
+    (2.0, [(0, 0), (1, 1), (2, 2)])
+
+    >>> dijkstra(np.array([[1, 1, 1], [0, 0, 1], [0, 1, 1]]), (0, 0), (2, 2), False)
+    (4.0, [(0, 0), (0, 1), (0, 2), (1, 2), (2, 2)])
+    """
+    rows, cols = grid.shape
+    dx = [-1, 1, 0, 0]
+    dy = [0, 0, -1, 1]
+    if allow_diagonal:
+        dx += [-1, -1, 1, 1]
+        dy += [-1, 1, -1, 1]
+
+    queue, visited = [(0, source)], set()
+    matrix = np.full((rows, cols), np.inf)
+    matrix[source] = 0
+    predecessors = np.empty((rows, cols), dtype=object)
+    predecessors[source] = None
+
+    while queue:
+        (dist, (x, y)) = heappop(queue)
+        if (x, y) in visited:
+            continue
+        visited.add((x, y))
+
+        if (x, y) == destination:
+            path = []
+            while (x, y) != source:
+                path.append((x, y))
+                x, y = predecessors[x, y]
+            path.append(source)  # add the source manually
+            path.reverse()
+            return matrix[destination], path
+
+        for i in range(len(dx)):
+            nx, ny = x + dx[i], y + dy[i]
+            if 0 <= nx < rows and 0 <= ny < cols:
+                next_node = grid[nx][ny]
+                if next_node == 1 and matrix[nx, ny] > dist + 1:
+                    heappush(queue, (dist + 1, (nx, ny)))
+                    matrix[nx, ny] = dist + 1
+                    predecessors[nx, ny] = (x, y)
+
+    return np.inf, []
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

graphs/directed_and_undirected_(weighted)_graph.py

@@ -39,7 +39,7 @@ class DirectedGraph:
         stack = []
         visited = []
         if s == -2:
-            s = list(self.graph)[0]
+            s = next(iter(self.graph))
         stack.append(s)
         visited.append(s)
         ss = s
@@ -87,7 +87,7 @@ class DirectedGraph:
         d = deque()
         visited = []
         if s == -2:
-            s = list(self.graph)[0]
+            s = next(iter(self.graph))
         d.append(s)
         visited.append(s)
         while d:
@@ -114,7 +114,7 @@ class DirectedGraph:
         stack = []
         visited = []
         if s == -2:
-            s = list(self.graph)[0]
+            s = next(iter(self.graph))
         stack.append(s)
         visited.append(s)
         ss = s
@@ -146,7 +146,7 @@ class DirectedGraph:
     def cycle_nodes(self):
         stack = []
         visited = []
-        s = list(self.graph)[0]
+        s = next(iter(self.graph))
         stack.append(s)
         visited.append(s)
         parent = -2
@@ -199,7 +199,7 @@ class DirectedGraph:
     def has_cycle(self):
         stack = []
         visited = []
-        s = list(self.graph)[0]
+        s = next(iter(self.graph))
         stack.append(s)
         visited.append(s)
         parent = -2
@@ -305,7 +305,7 @@ class Graph:
         stack = []
         visited = []
         if s == -2:
-            s = list(self.graph)[0]
+            s = next(iter(self.graph))
         stack.append(s)
         visited.append(s)
         ss = s
@@ -353,7 +353,7 @@ class Graph:
         d = deque()
         visited = []
         if s == -2:
-            s = list(self.graph)[0]
+            s = next(iter(self.graph))
         d.append(s)
         visited.append(s)
         while d:
@@ -371,7 +371,7 @@ class Graph:
     def cycle_nodes(self):
         stack = []
         visited = []
-        s = list(self.graph)[0]
+        s = next(iter(self.graph))
         stack.append(s)
         visited.append(s)
         parent = -2
@@ -424,7 +424,7 @@ class Graph:
     def has_cycle(self):
         stack = []
         visited = []
-        s = list(self.graph)[0]
+        s = next(iter(self.graph))
         stack.append(s)
         visited.append(s)
         parent = -2

graphs/edmonds_karp_multiple_source_and_sink.py

@@ -113,7 +113,7 @@ class PushRelabelExecutor(MaximumFlowAlgorithmExecutor):
         vertices_list = [
             i
             for i in range(self.verticies_count)
-            if i != self.source_index and i != self.sink_index
+            if i not in {self.source_index, self.sink_index}
         ]
 
         # move through list

graphs/eulerian_path_and_circuit_for_undirected_graph.py

@@ -20,7 +20,7 @@ def check_circuit_or_path(graph, max_node):
     odd_degree_nodes = 0
     odd_node = -1
     for i in range(max_node):
-        if i not in graph.keys():
+        if i not in graph:
             continue
         if len(graph[i]) % 2 == 1:
             odd_degree_nodes += 1

graphs/graph_adjacency_list.py

@@ -0,0 +1,589 @@
+#!/usr/bin/env python3
+"""
+Author: Vikram Nithyanandam
+
+Description:
+The following implementation is a robust unweighted Graph data structure
+implemented using an adjacency list. This vertices and edges of this graph can be
+effectively initialized and modified while storing your chosen generic
+value in each vertex.
+
+Adjacency List: https://en.wikipedia.org/wiki/Adjacency_list
+
+Potential Future Ideas:
+- Add a flag to set edge weights on and set edge weights
+- Make edge weights and vertex values customizable to store whatever the client wants
+- Support multigraph functionality if the client wants it
+"""
+from __future__ import annotations
+
+import random
+import unittest
+from pprint import pformat
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class GraphAdjacencyList(Generic[T]):
+    def __init__(
+        self, vertices: list[T], edges: list[list[T]], directed: bool = True
+    ) -> None:
+        """
+        Parameters:
+         - vertices: (list[T]) The list of vertex names the client wants to
+        pass in. Default is empty.
+        - edges: (list[list[T]]) The list of edges the client wants to
+        pass in. Each edge is a 2-element list. Default is empty.
+        - directed: (bool) Indicates if graph is directed or undirected.
+        Default is True.
+        """
+        self.adj_list: dict[T, list[T]] = {}  # dictionary of lists of T
+        self.directed = directed
+
+        # Falsey checks
+        edges = edges or []
+        vertices = vertices or []
+
+        for vertex in vertices:
+            self.add_vertex(vertex)
+
+        for edge in edges:
+            if len(edge) != 2:
+                msg = f"Invalid input: {edge} is the wrong length."
+                raise ValueError(msg)
+            self.add_edge(edge[0], edge[1])
+
+    def add_vertex(self, vertex: T) -> None:
+        """
+        Adds a vertex to the graph. If the given vertex already exists,
+        a ValueError will be thrown.
+        """
+        if self.contains_vertex(vertex):
+            msg = f"Incorrect input: {vertex} is already in the graph."
+            raise ValueError(msg)
+        self.adj_list[vertex] = []
+
+    def add_edge(self, source_vertex: T, destination_vertex: T) -> None:
+        """
+        Creates an edge from source vertex to destination vertex. If any
+        given vertex doesn't exist or the edge already exists, a ValueError
+        will be thrown.
+        """
+        if not (
+            self.contains_vertex(source_vertex)
+            and self.contains_vertex(destination_vertex)
+        ):
+            msg = (
+                f"Incorrect input: Either {source_vertex} or "
+                f"{destination_vertex} does not exist"
+            )
+            raise ValueError(msg)
+        if self.contains_edge(source_vertex, destination_vertex):
+            msg = (
+                "Incorrect input: The edge already exists between "
+                f"{source_vertex} and {destination_vertex}"
+            )
+            raise ValueError(msg)
+
+        # add the destination vertex to the list associated with the source vertex
+        # and vice versa if not directed
+        self.adj_list[source_vertex].append(destination_vertex)
+        if not self.directed:
+            self.adj_list[destination_vertex].append(source_vertex)
+
+    def remove_vertex(self, vertex: T) -> None:
+        """
+        Removes the given vertex from the graph and deletes all incoming and
+        outgoing edges from the given vertex as well. If the given vertex
+        does not exist, a ValueError will be thrown.
+        """
+        if not self.contains_vertex(vertex):
+            msg = f"Incorrect input: {vertex} does not exist in this graph."
+            raise ValueError(msg)
+
+        if not self.directed:
+            # If not directed, find all neighboring vertices and delete all references
+            # of edges connecting to the given vertex
+            for neighbor in self.adj_list[vertex]:
+                self.adj_list[neighbor].remove(vertex)
+        else:
+            # If directed, search all neighbors of all vertices and delete all
+            # references of edges connecting to the given vertex
+            for edge_list in self.adj_list.values():
+                if vertex in edge_list:
+                    edge_list.remove(vertex)
+
+        # Finally, delete the given vertex and all of its outgoing edge references
+        self.adj_list.pop(vertex)
+
+    def remove_edge(self, source_vertex: T, destination_vertex: T) -> None:
+        """
+        Removes the edge between the two vertices. If any given vertex
+        doesn't exist or the edge does not exist, a ValueError will be thrown.
+        """
+        if not (
+            self.contains_vertex(source_vertex)
+            and self.contains_vertex(destination_vertex)
+        ):
+            msg = (
+                f"Incorrect input: Either {source_vertex} or "
+                f"{destination_vertex} does not exist"
+            )
+            raise ValueError(msg)
+        if not self.contains_edge(source_vertex, destination_vertex):
+            msg = (
+                "Incorrect input: The edge does NOT exist between "
+                f"{source_vertex} and {destination_vertex}"
+            )
+            raise ValueError(msg)
+
+        # remove the destination vertex from the list associated with the source
+        # vertex and vice versa if not directed
+        self.adj_list[source_vertex].remove(destination_vertex)
+        if not self.directed:
+            self.adj_list[destination_vertex].remove(source_vertex)
+
+    def contains_vertex(self, vertex: T) -> bool:
+        """
+        Returns True if the graph contains the vertex, False otherwise.
+        """
+        return vertex in self.adj_list
+
+    def contains_edge(self, source_vertex: T, destination_vertex: T) -> bool:
+        """
+        Returns True if the graph contains the edge from the source_vertex to the
+        destination_vertex, False otherwise. If any given vertex doesn't exist, a
+        ValueError will be thrown.
+        """
+        if not (
+            self.contains_vertex(source_vertex)
+            and self.contains_vertex(destination_vertex)
+        ):
+            msg = (
+                f"Incorrect input: Either {source_vertex} "
+                f"or {destination_vertex} does not exist."
+            )
+            raise ValueError(msg)
+
+        return destination_vertex in self.adj_list[source_vertex]
+
+    def clear_graph(self) -> None:
+        """
+        Clears all vertices and edges.
+        """
+        self.adj_list = {}
+
+    def __repr__(self) -> str:
+        return pformat(self.adj_list)
+
+
+class TestGraphAdjacencyList(unittest.TestCase):
+    def __assert_graph_edge_exists_check(
+        self,
+        undirected_graph: GraphAdjacencyList,
+        directed_graph: GraphAdjacencyList,
+        edge: list[int],
+    ) -> None:
+        self.assertTrue(undirected_graph.contains_edge(edge[0], edge[1]))
+        self.assertTrue(undirected_graph.contains_edge(edge[1], edge[0]))
+        self.assertTrue(directed_graph.contains_edge(edge[0], edge[1]))
+
+    def __assert_graph_edge_does_not_exist_check(
+        self,
+        undirected_graph: GraphAdjacencyList,
+        directed_graph: GraphAdjacencyList,
+        edge: list[int],
+    ) -> None:
+        self.assertFalse(undirected_graph.contains_edge(edge[0], edge[1]))
+        self.assertFalse(undirected_graph.contains_edge(edge[1], edge[0]))
+        self.assertFalse(directed_graph.contains_edge(edge[0], edge[1]))
+
+    def __assert_graph_vertex_exists_check(
+        self,
+        undirected_graph: GraphAdjacencyList,
+        directed_graph: GraphAdjacencyList,
+        vertex: int,
+    ) -> None:
+        self.assertTrue(undirected_graph.contains_vertex(vertex))
+        self.assertTrue(directed_graph.contains_vertex(vertex))
+
+    def __assert_graph_vertex_does_not_exist_check(
+        self,
+        undirected_graph: GraphAdjacencyList,
+        directed_graph: GraphAdjacencyList,
+        vertex: int,
+    ) -> None:
+        self.assertFalse(undirected_graph.contains_vertex(vertex))
+        self.assertFalse(directed_graph.contains_vertex(vertex))
+
+    def __generate_random_edges(
+        self, vertices: list[int], edge_pick_count: int
+    ) -> list[list[int]]:
+        self.assertTrue(edge_pick_count <= len(vertices))
+
+        random_source_vertices: list[int] = random.sample(
+            vertices[0 : int(len(vertices) / 2)], edge_pick_count
+        )
+        random_destination_vertices: list[int] = random.sample(
+            vertices[int(len(vertices) / 2) :], edge_pick_count
+        )
+        random_edges: list[list[int]] = []
+
+        for source in random_source_vertices:
+            for dest in random_destination_vertices:
+                random_edges.append([source, dest])
+
+        return random_edges
+
+    def __generate_graphs(
+        self, vertex_count: int, min_val: int, max_val: int, edge_pick_count: int
+    ) -> tuple[GraphAdjacencyList, GraphAdjacencyList, list[int], list[list[int]]]:
+        if max_val - min_val + 1 < vertex_count:
+            raise ValueError(
+                "Will result in duplicate vertices. Either increase range "
+                "between min_val and max_val or decrease vertex count."
+            )
+
+        # generate graph input
+        random_vertices: list[int] = random.sample(
+            range(min_val, max_val + 1), vertex_count
+        )
+        random_edges: list[list[int]] = self.__generate_random_edges(
+            random_vertices, edge_pick_count
+        )
+
+        # build graphs
+        undirected_graph = GraphAdjacencyList(
+            vertices=random_vertices, edges=random_edges, directed=False
+        )
+        directed_graph = GraphAdjacencyList(
+            vertices=random_vertices, edges=random_edges, directed=True
+        )
+
+        return undirected_graph, directed_graph, random_vertices, random_edges
+
+    def test_init_check(self) -> None:
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(20, 0, 100, 4)
+
+        # test graph initialization with vertices and edges
+        for num in random_vertices:
+            self.__assert_graph_vertex_exists_check(
+                undirected_graph, directed_graph, num
+            )
+
+        for edge in random_edges:
+            self.__assert_graph_edge_exists_check(
+                undirected_graph, directed_graph, edge
+            )
+        self.assertFalse(undirected_graph.directed)
+        self.assertTrue(directed_graph.directed)
+
+    def test_contains_vertex(self) -> None:
+        random_vertices: list[int] = random.sample(range(101), 20)
+
+        # Build graphs WITHOUT edges
+        undirected_graph = GraphAdjacencyList(
+            vertices=random_vertices, edges=[], directed=False
+        )
+        directed_graph = GraphAdjacencyList(
+            vertices=random_vertices, edges=[], directed=True
+        )
+
+        # Test contains_vertex
+        for num in range(101):
+            self.assertEqual(
+                num in random_vertices, undirected_graph.contains_vertex(num)
+            )
+            self.assertEqual(
+                num in random_vertices, directed_graph.contains_vertex(num)
+            )
+
+    def test_add_vertices(self) -> None:
+        random_vertices: list[int] = random.sample(range(101), 20)
+
+        # build empty graphs
+        undirected_graph: GraphAdjacencyList = GraphAdjacencyList(
+            vertices=[], edges=[], directed=False
+        )
+        directed_graph: GraphAdjacencyList = GraphAdjacencyList(
+            vertices=[], edges=[], directed=True
+        )
+
+        # run add_vertex
+        for num in random_vertices:
+            undirected_graph.add_vertex(num)
+
+        for num in random_vertices:
+            directed_graph.add_vertex(num)
+
+        # test add_vertex worked
+        for num in random_vertices:
+            self.__assert_graph_vertex_exists_check(
+                undirected_graph, directed_graph, num
+            )
+
+    def test_remove_vertices(self) -> None:
+        random_vertices: list[int] = random.sample(range(101), 20)
+
+        # build graphs WITHOUT edges
+        undirected_graph = GraphAdjacencyList(
+            vertices=random_vertices, edges=[], directed=False
+        )
+        directed_graph = GraphAdjacencyList(
+            vertices=random_vertices, edges=[], directed=True
+        )
+
+        # test remove_vertex worked
+        for num in random_vertices:
+            self.__assert_graph_vertex_exists_check(
+                undirected_graph, directed_graph, num
+            )
+
+            undirected_graph.remove_vertex(num)
+            directed_graph.remove_vertex(num)
+
+            self.__assert_graph_vertex_does_not_exist_check(
+                undirected_graph, directed_graph, num
+            )
+
+    def test_add_and_remove_vertices_repeatedly(self) -> None:
+        random_vertices1: list[int] = random.sample(range(51), 20)
+        random_vertices2: list[int] = random.sample(range(51, 101), 20)
+
+        # build graphs WITHOUT edges
+        undirected_graph = GraphAdjacencyList(
+            vertices=random_vertices1, edges=[], directed=False
+        )
+        directed_graph = GraphAdjacencyList(
+            vertices=random_vertices1, edges=[], directed=True
+        )
+
+        # test adding and removing vertices
+        for i, _ in enumerate(random_vertices1):
+            undirected_graph.add_vertex(random_vertices2[i])
+            directed_graph.add_vertex(random_vertices2[i])
+
+            self.__assert_graph_vertex_exists_check(
+                undirected_graph, directed_graph, random_vertices2[i]
+            )
+
+            undirected_graph.remove_vertex(random_vertices1[i])
+            directed_graph.remove_vertex(random_vertices1[i])
+
+            self.__assert_graph_vertex_does_not_exist_check(
+                undirected_graph, directed_graph, random_vertices1[i]
+            )
+
+        # remove all vertices
+        for i, _ in enumerate(random_vertices1):
+            undirected_graph.remove_vertex(random_vertices2[i])
+            directed_graph.remove_vertex(random_vertices2[i])
+
+            self.__assert_graph_vertex_does_not_exist_check(
+                undirected_graph, directed_graph, random_vertices2[i]
+            )
+
+    def test_contains_edge(self) -> None:
+        # generate graphs and graph input
+        vertex_count = 20
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(vertex_count, 0, 100, 4)
+
+        # generate all possible edges for testing
+        all_possible_edges: list[list[int]] = []
+        for i in range(vertex_count - 1):
+            for j in range(i + 1, vertex_count):
+                all_possible_edges.append([random_vertices[i], random_vertices[j]])
+                all_possible_edges.append([random_vertices[j], random_vertices[i]])
+
+        # test contains_edge function
+        for edge in all_possible_edges:
+            if edge in random_edges:
+                self.__assert_graph_edge_exists_check(
+                    undirected_graph, directed_graph, edge
+                )
+            elif [edge[1], edge[0]] in random_edges:
+                # since this edge exists for undirected but the reverse
+                # may not exist for directed
+                self.__assert_graph_edge_exists_check(
+                    undirected_graph, directed_graph, [edge[1], edge[0]]
+                )
+            else:
+                self.__assert_graph_edge_does_not_exist_check(
+                    undirected_graph, directed_graph, edge
+                )
+
+    def test_add_edge(self) -> None:
+        # generate graph input
+        random_vertices: list[int] = random.sample(range(101), 15)
+        random_edges: list[list[int]] = self.__generate_random_edges(random_vertices, 4)
+
+        # build graphs WITHOUT edges
+        undirected_graph = GraphAdjacencyList(
+            vertices=random_vertices, edges=[], directed=False
+        )
+        directed_graph = GraphAdjacencyList(
+            vertices=random_vertices, edges=[], directed=True
+        )
+
+        # run and test add_edge
+        for edge in random_edges:
+            undirected_graph.add_edge(edge[0], edge[1])
+            directed_graph.add_edge(edge[0], edge[1])
+            self.__assert_graph_edge_exists_check(
+                undirected_graph, directed_graph, edge
+            )
+
+    def test_remove_edge(self) -> None:
+        # generate graph input and graphs
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(20, 0, 100, 4)
+
+        # run and test remove_edge
+        for edge in random_edges:
+            self.__assert_graph_edge_exists_check(
+                undirected_graph, directed_graph, edge
+            )
+            undirected_graph.remove_edge(edge[0], edge[1])
+            directed_graph.remove_edge(edge[0], edge[1])
+            self.__assert_graph_edge_does_not_exist_check(
+                undirected_graph, directed_graph, edge
+            )
+
+    def test_add_and_remove_edges_repeatedly(self) -> None:
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(20, 0, 100, 4)
+
+        # make some more edge options!
+        more_random_edges: list[list[int]] = []
+
+        while len(more_random_edges) != len(random_edges):
+            edges: list[list[int]] = self.__generate_random_edges(random_vertices, 4)
+            for edge in edges:
+                if len(more_random_edges) == len(random_edges):
+                    break
+                elif edge not in more_random_edges and edge not in random_edges:
+                    more_random_edges.append(edge)
+
+        for i, _ in enumerate(random_edges):
+            undirected_graph.add_edge(more_random_edges[i][0], more_random_edges[i][1])
+            directed_graph.add_edge(more_random_edges[i][0], more_random_edges[i][1])
+
+            self.__assert_graph_edge_exists_check(
+                undirected_graph, directed_graph, more_random_edges[i]
+            )
+
+            undirected_graph.remove_edge(random_edges[i][0], random_edges[i][1])
+            directed_graph.remove_edge(random_edges[i][0], random_edges[i][1])
+
+            self.__assert_graph_edge_does_not_exist_check(
+                undirected_graph, directed_graph, random_edges[i]
+            )
+
+    def test_add_vertex_exception_check(self) -> None:
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(20, 0, 100, 4)
+
+        for vertex in random_vertices:
+            with self.assertRaises(ValueError):
+                undirected_graph.add_vertex(vertex)
+            with self.assertRaises(ValueError):
+                directed_graph.add_vertex(vertex)
+
+    def test_remove_vertex_exception_check(self) -> None:
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(20, 0, 100, 4)
+
+        for i in range(101):
+            if i not in random_vertices:
+                with self.assertRaises(ValueError):
+                    undirected_graph.remove_vertex(i)
+                with self.assertRaises(ValueError):
+                    directed_graph.remove_vertex(i)
+
+    def test_add_edge_exception_check(self) -> None:
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(20, 0, 100, 4)
+
+        for edge in random_edges:
+            with self.assertRaises(ValueError):
+                undirected_graph.add_edge(edge[0], edge[1])
+            with self.assertRaises(ValueError):
+                directed_graph.add_edge(edge[0], edge[1])
+
+    def test_remove_edge_exception_check(self) -> None:
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(20, 0, 100, 4)
+
+        more_random_edges: list[list[int]] = []
+
+        while len(more_random_edges) != len(random_edges):
+            edges: list[list[int]] = self.__generate_random_edges(random_vertices, 4)
+            for edge in edges:
+                if len(more_random_edges) == len(random_edges):
+                    break
+                elif edge not in more_random_edges and edge not in random_edges:
+                    more_random_edges.append(edge)
+
+        for edge in more_random_edges:
+            with self.assertRaises(ValueError):
+                undirected_graph.remove_edge(edge[0], edge[1])
+            with self.assertRaises(ValueError):
+                directed_graph.remove_edge(edge[0], edge[1])
+
+    def test_contains_edge_exception_check(self) -> None:
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(20, 0, 100, 4)
+
+        for vertex in random_vertices:
+            with self.assertRaises(ValueError):
+                undirected_graph.contains_edge(vertex, 102)
+            with self.assertRaises(ValueError):
+                directed_graph.contains_edge(vertex, 102)
+
+        with self.assertRaises(ValueError):
+            undirected_graph.contains_edge(103, 102)
+        with self.assertRaises(ValueError):
+            directed_graph.contains_edge(103, 102)
+
+
+if __name__ == "__main__":
+    unittest.main()

graphs/graph_adjacency_matrix.py

@@ -0,0 +1,608 @@
+#!/usr/bin/env python3
+"""
+Author: Vikram Nithyanandam
+
+Description:
+The following implementation is a robust unweighted Graph data structure
+implemented using an adjacency matrix. This vertices and edges of this graph can be
+effectively initialized and modified while storing your chosen generic
+value in each vertex.
+
+Adjacency Matrix: https://mathworld.wolfram.com/AdjacencyMatrix.html
+
+Potential Future Ideas:
+- Add a flag to set edge weights on and set edge weights
+- Make edge weights and vertex values customizable to store whatever the client wants
+- Support multigraph functionality if the client wants it
+"""
+from __future__ import annotations
+
+import random
+import unittest
+from pprint import pformat
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class GraphAdjacencyMatrix(Generic[T]):
+    def __init__(
+        self, vertices: list[T], edges: list[list[T]], directed: bool = True
+    ) -> None:
+        """
+        Parameters:
+        - vertices: (list[T]) The list of vertex names the client wants to
+        pass in. Default is empty.
+        - edges: (list[list[T]]) The list of edges the client wants to
+        pass in. Each edge is a 2-element list. Default is empty.
+        - directed: (bool) Indicates if graph is directed or undirected.
+        Default is True.
+        """
+        self.directed = directed
+        self.vertex_to_index: dict[T, int] = {}
+        self.adj_matrix: list[list[int]] = []
+
+        # Falsey checks
+        edges = edges or []
+        vertices = vertices or []
+
+        for vertex in vertices:
+            self.add_vertex(vertex)
+
+        for edge in edges:
+            if len(edge) != 2:
+                msg = f"Invalid input: {edge} must have length 2."
+                raise ValueError(msg)
+            self.add_edge(edge[0], edge[1])
+
+    def add_edge(self, source_vertex: T, destination_vertex: T) -> None:
+        """
+        Creates an edge from source vertex to destination vertex. If any
+        given vertex doesn't exist or the edge already exists, a ValueError
+        will be thrown.
+        """
+        if not (
+            self.contains_vertex(source_vertex)
+            and self.contains_vertex(destination_vertex)
+        ):
+            msg = (
+                f"Incorrect input: Either {source_vertex} or "
+                f"{destination_vertex} does not exist"
+            )
+            raise ValueError(msg)
+        if self.contains_edge(source_vertex, destination_vertex):
+            msg = (
+                "Incorrect input: The edge already exists between "
+                f"{source_vertex} and {destination_vertex}"
+            )
+            raise ValueError(msg)
+
+        # Get the indices of the corresponding vertices and set their edge value to 1.
+        u: int = self.vertex_to_index[source_vertex]
+        v: int = self.vertex_to_index[destination_vertex]
+        self.adj_matrix[u][v] = 1
+        if not self.directed:
+            self.adj_matrix[v][u] = 1
+
+    def remove_edge(self, source_vertex: T, destination_vertex: T) -> None:
+        """
+        Removes the edge between the two vertices. If any given vertex
+        doesn't exist or the edge does not exist, a ValueError will be thrown.
+        """
+        if not (
+            self.contains_vertex(source_vertex)
+            and self.contains_vertex(destination_vertex)
+        ):
+            msg = (
+                f"Incorrect input: Either {source_vertex} or "
+                f"{destination_vertex} does not exist"
+            )
+            raise ValueError(msg)
+        if not self.contains_edge(source_vertex, destination_vertex):
+            msg = (
+                "Incorrect input: The edge does NOT exist between "
+                f"{source_vertex} and {destination_vertex}"
+            )
+            raise ValueError(msg)
+
+        # Get the indices of the corresponding vertices and set their edge value to 0.
+        u: int = self.vertex_to_index[source_vertex]
+        v: int = self.vertex_to_index[destination_vertex]
+        self.adj_matrix[u][v] = 0
+        if not self.directed:
+            self.adj_matrix[v][u] = 0
+
+    def add_vertex(self, vertex: T) -> None:
+        """
+        Adds a vertex to the graph. If the given vertex already exists,
+        a ValueError will be thrown.
+        """
+        if self.contains_vertex(vertex):
+            msg = f"Incorrect input: {vertex} already exists in this graph."
+            raise ValueError(msg)
+
+        # build column for vertex
+        for row in self.adj_matrix:
+            row.append(0)
+
+        # build row for vertex and update other data structures
+        self.adj_matrix.append([0] * (len(self.adj_matrix) + 1))
+        self.vertex_to_index[vertex] = len(self.adj_matrix) - 1
+
+    def remove_vertex(self, vertex: T) -> None:
+        """
+        Removes the given vertex from the graph and deletes all incoming and
+        outgoing edges from the given vertex as well. If the given vertex
+        does not exist, a ValueError will be thrown.
+        """
+        if not self.contains_vertex(vertex):
+            msg = f"Incorrect input: {vertex} does not exist in this graph."
+            raise ValueError(msg)
+
+        # first slide up the rows by deleting the row corresponding to
+        # the vertex being deleted.
+        start_index = self.vertex_to_index[vertex]
+        self.adj_matrix.pop(start_index)
+
+        # next, slide the columns to the left by deleting the values in
+        # the column corresponding to the vertex being deleted
+        for lst in self.adj_matrix:
+            lst.pop(start_index)
+
+        # final clean up
+        self.vertex_to_index.pop(vertex)
+
+        # decrement indices for vertices shifted by the deleted vertex in the adj matrix
+        for vertex in self.vertex_to_index:
+            if self.vertex_to_index[vertex] >= start_index:
+                self.vertex_to_index[vertex] = self.vertex_to_index[vertex] - 1
+
+    def contains_vertex(self, vertex: T) -> bool:
+        """
+        Returns True if the graph contains the vertex, False otherwise.
+        """
+        return vertex in self.vertex_to_index
+
+    def contains_edge(self, source_vertex: T, destination_vertex: T) -> bool:
+        """
+        Returns True if the graph contains the edge from the source_vertex to the
+        destination_vertex, False otherwise. If any given vertex doesn't exist, a
+        ValueError will be thrown.
+        """
+        if not (
+            self.contains_vertex(source_vertex)
+            and self.contains_vertex(destination_vertex)
+        ):
+            msg = (
+                f"Incorrect input: Either {source_vertex} "
+                f"or {destination_vertex} does not exist."
+            )
+            raise ValueError(msg)
+
+        u = self.vertex_to_index[source_vertex]
+        v = self.vertex_to_index[destination_vertex]
+        return self.adj_matrix[u][v] == 1
+
+    def clear_graph(self) -> None:
+        """
+        Clears all vertices and edges.
+        """
+        self.vertex_to_index = {}
+        self.adj_matrix = []
+
+    def __repr__(self) -> str:
+        first = "Adj Matrix:\n" + pformat(self.adj_matrix)
+        second = "\nVertex to index mapping:\n" + pformat(self.vertex_to_index)
+        return first + second
+
+
+class TestGraphMatrix(unittest.TestCase):
+    def __assert_graph_edge_exists_check(
+        self,
+        undirected_graph: GraphAdjacencyMatrix,
+        directed_graph: GraphAdjacencyMatrix,
+        edge: list[int],
+    ) -> None:
+        self.assertTrue(undirected_graph.contains_edge(edge[0], edge[1]))
+        self.assertTrue(undirected_graph.contains_edge(edge[1], edge[0]))
+        self.assertTrue(directed_graph.contains_edge(edge[0], edge[1]))
+
+    def __assert_graph_edge_does_not_exist_check(
+        self,
+        undirected_graph: GraphAdjacencyMatrix,
+        directed_graph: GraphAdjacencyMatrix,
+        edge: list[int],
+    ) -> None:
+        self.assertFalse(undirected_graph.contains_edge(edge[0], edge[1]))
+        self.assertFalse(undirected_graph.contains_edge(edge[1], edge[0]))
+        self.assertFalse(directed_graph.contains_edge(edge[0], edge[1]))
+
+    def __assert_graph_vertex_exists_check(
+        self,
+        undirected_graph: GraphAdjacencyMatrix,
+        directed_graph: GraphAdjacencyMatrix,
+        vertex: int,
+    ) -> None:
+        self.assertTrue(undirected_graph.contains_vertex(vertex))
+        self.assertTrue(directed_graph.contains_vertex(vertex))
+
+    def __assert_graph_vertex_does_not_exist_check(
+        self,
+        undirected_graph: GraphAdjacencyMatrix,
+        directed_graph: GraphAdjacencyMatrix,
+        vertex: int,
+    ) -> None:
+        self.assertFalse(undirected_graph.contains_vertex(vertex))
+        self.assertFalse(directed_graph.contains_vertex(vertex))
+
+    def __generate_random_edges(
+        self, vertices: list[int], edge_pick_count: int
+    ) -> list[list[int]]:
+        self.assertTrue(edge_pick_count <= len(vertices))
+
+        random_source_vertices: list[int] = random.sample(
+            vertices[0 : int(len(vertices) / 2)], edge_pick_count
+        )
+        random_destination_vertices: list[int] = random.sample(
+            vertices[int(len(vertices) / 2) :], edge_pick_count
+        )
+        random_edges: list[list[int]] = []
+
+        for source in random_source_vertices:
+            for dest in random_destination_vertices:
+                random_edges.append([source, dest])
+
+        return random_edges
+
+    def __generate_graphs(
+        self, vertex_count: int, min_val: int, max_val: int, edge_pick_count: int
+    ) -> tuple[GraphAdjacencyMatrix, GraphAdjacencyMatrix, list[int], list[list[int]]]:
+        if max_val - min_val + 1 < vertex_count:
+            raise ValueError(
+                "Will result in duplicate vertices. Either increase "
+                "range between min_val and max_val or decrease vertex count"
+            )
+
+        # generate graph input
+        random_vertices: list[int] = random.sample(
+            range(min_val, max_val + 1), vertex_count
+        )
+        random_edges: list[list[int]] = self.__generate_random_edges(
+            random_vertices, edge_pick_count
+        )
+
+        # build graphs
+        undirected_graph = GraphAdjacencyMatrix(
+            vertices=random_vertices, edges=random_edges, directed=False
+        )
+        directed_graph = GraphAdjacencyMatrix(
+            vertices=random_vertices, edges=random_edges, directed=True
+        )
+
+        return undirected_graph, directed_graph, random_vertices, random_edges
+
+    def test_init_check(self) -> None:
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(20, 0, 100, 4)
+
+        # test graph initialization with vertices and edges
+        for num in random_vertices:
+            self.__assert_graph_vertex_exists_check(
+                undirected_graph, directed_graph, num
+            )
+
+        for edge in random_edges:
+            self.__assert_graph_edge_exists_check(
+                undirected_graph, directed_graph, edge
+            )
+
+        self.assertFalse(undirected_graph.directed)
+        self.assertTrue(directed_graph.directed)
+
+    def test_contains_vertex(self) -> None:
+        random_vertices: list[int] = random.sample(range(101), 20)
+
+        # Build graphs WITHOUT edges
+        undirected_graph = GraphAdjacencyMatrix(
+            vertices=random_vertices, edges=[], directed=False
+        )
+        directed_graph = GraphAdjacencyMatrix(
+            vertices=random_vertices, edges=[], directed=True
+        )
+
+        # Test contains_vertex
+        for num in range(101):
+            self.assertEqual(
+                num in random_vertices, undirected_graph.contains_vertex(num)
+            )
+            self.assertEqual(
+                num in random_vertices, directed_graph.contains_vertex(num)
+            )
+
+    def test_add_vertices(self) -> None:
+        random_vertices: list[int] = random.sample(range(101), 20)
+
+        # build empty graphs
+        undirected_graph: GraphAdjacencyMatrix = GraphAdjacencyMatrix(
+            vertices=[], edges=[], directed=False
+        )
+        directed_graph: GraphAdjacencyMatrix = GraphAdjacencyMatrix(
+            vertices=[], edges=[], directed=True
+        )
+
+        # run add_vertex
+        for num in random_vertices:
+            undirected_graph.add_vertex(num)
+
+        for num in random_vertices:
+            directed_graph.add_vertex(num)
+
+        # test add_vertex worked
+        for num in random_vertices:
+            self.__assert_graph_vertex_exists_check(
+                undirected_graph, directed_graph, num
+            )
+
+    def test_remove_vertices(self) -> None:
+        random_vertices: list[int] = random.sample(range(101), 20)
+
+        # build graphs WITHOUT edges
+        undirected_graph = GraphAdjacencyMatrix(
+            vertices=random_vertices, edges=[], directed=False
+        )
+        directed_graph = GraphAdjacencyMatrix(
+            vertices=random_vertices, edges=[], directed=True
+        )
+
+        # test remove_vertex worked
+        for num in random_vertices:
+            self.__assert_graph_vertex_exists_check(
+                undirected_graph, directed_graph, num
+            )
+
+            undirected_graph.remove_vertex(num)
+            directed_graph.remove_vertex(num)
+
+            self.__assert_graph_vertex_does_not_exist_check(
+                undirected_graph, directed_graph, num
+            )
+
+    def test_add_and_remove_vertices_repeatedly(self) -> None:
+        random_vertices1: list[int] = random.sample(range(51), 20)
+        random_vertices2: list[int] = random.sample(range(51, 101), 20)
+
+        # build graphs WITHOUT edges
+        undirected_graph = GraphAdjacencyMatrix(
+            vertices=random_vertices1, edges=[], directed=False
+        )
+        directed_graph = GraphAdjacencyMatrix(
+            vertices=random_vertices1, edges=[], directed=True
+        )
+
+        # test adding and removing vertices
+        for i, _ in enumerate(random_vertices1):
+            undirected_graph.add_vertex(random_vertices2[i])
+            directed_graph.add_vertex(random_vertices2[i])
+
+            self.__assert_graph_vertex_exists_check(
+                undirected_graph, directed_graph, random_vertices2[i]
+            )
+
+            undirected_graph.remove_vertex(random_vertices1[i])
+            directed_graph.remove_vertex(random_vertices1[i])
+
+            self.__assert_graph_vertex_does_not_exist_check(
+                undirected_graph, directed_graph, random_vertices1[i]
+            )
+
+        # remove all vertices
+        for i, _ in enumerate(random_vertices1):
+            undirected_graph.remove_vertex(random_vertices2[i])
+            directed_graph.remove_vertex(random_vertices2[i])
+
+            self.__assert_graph_vertex_does_not_exist_check(
+                undirected_graph, directed_graph, random_vertices2[i]
+            )
+
+    def test_contains_edge(self) -> None:
+        # generate graphs and graph input
+        vertex_count = 20
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(vertex_count, 0, 100, 4)
+
+        # generate all possible edges for testing
+        all_possible_edges: list[list[int]] = []
+        for i in range(vertex_count - 1):
+            for j in range(i + 1, vertex_count):
+                all_possible_edges.append([random_vertices[i], random_vertices[j]])
+                all_possible_edges.append([random_vertices[j], random_vertices[i]])
+
+        # test contains_edge function
+        for edge in all_possible_edges:
+            if edge in random_edges:
+                self.__assert_graph_edge_exists_check(
+                    undirected_graph, directed_graph, edge
+                )
+            elif [edge[1], edge[0]] in random_edges:
+                # since this edge exists for undirected but the reverse may
+                # not exist for directed
+                self.__assert_graph_edge_exists_check(
+                    undirected_graph, directed_graph, [edge[1], edge[0]]
+                )
+            else:
+                self.__assert_graph_edge_does_not_exist_check(
+                    undirected_graph, directed_graph, edge
+                )
+
+    def test_add_edge(self) -> None:
+        # generate graph input
+        random_vertices: list[int] = random.sample(range(101), 15)
+        random_edges: list[list[int]] = self.__generate_random_edges(random_vertices, 4)
+
+        # build graphs WITHOUT edges
+        undirected_graph = GraphAdjacencyMatrix(
+            vertices=random_vertices, edges=[], directed=False
+        )
+        directed_graph = GraphAdjacencyMatrix(
+            vertices=random_vertices, edges=[], directed=True
+        )
+
+        # run and test add_edge
+        for edge in random_edges:
+            undirected_graph.add_edge(edge[0], edge[1])
+            directed_graph.add_edge(edge[0], edge[1])
+            self.__assert_graph_edge_exists_check(
+                undirected_graph, directed_graph, edge
+            )
+
+    def test_remove_edge(self) -> None:
+        # generate graph input and graphs
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(20, 0, 100, 4)
+
+        # run and test remove_edge
+        for edge in random_edges:
+            self.__assert_graph_edge_exists_check(
+                undirected_graph, directed_graph, edge
+            )
+            undirected_graph.remove_edge(edge[0], edge[1])
+            directed_graph.remove_edge(edge[0], edge[1])
+            self.__assert_graph_edge_does_not_exist_check(
+                undirected_graph, directed_graph, edge
+            )
+
+    def test_add_and_remove_edges_repeatedly(self) -> None:
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(20, 0, 100, 4)
+
+        # make some more edge options!
+        more_random_edges: list[list[int]] = []
+
+        while len(more_random_edges) != len(random_edges):
+            edges: list[list[int]] = self.__generate_random_edges(random_vertices, 4)
+            for edge in edges:
+                if len(more_random_edges) == len(random_edges):
+                    break
+                elif edge not in more_random_edges and edge not in random_edges:
+                    more_random_edges.append(edge)
+
+        for i, _ in enumerate(random_edges):
+            undirected_graph.add_edge(more_random_edges[i][0], more_random_edges[i][1])
+            directed_graph.add_edge(more_random_edges[i][0], more_random_edges[i][1])
+
+            self.__assert_graph_edge_exists_check(
+                undirected_graph, directed_graph, more_random_edges[i]
+            )
+
+            undirected_graph.remove_edge(random_edges[i][0], random_edges[i][1])
+            directed_graph.remove_edge(random_edges[i][0], random_edges[i][1])
+
+            self.__assert_graph_edge_does_not_exist_check(
+                undirected_graph, directed_graph, random_edges[i]
+            )
+
+    def test_add_vertex_exception_check(self) -> None:
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(20, 0, 100, 4)
+
+        for vertex in random_vertices:
+            with self.assertRaises(ValueError):
+                undirected_graph.add_vertex(vertex)
+            with self.assertRaises(ValueError):
+                directed_graph.add_vertex(vertex)
+
+    def test_remove_vertex_exception_check(self) -> None:
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(20, 0, 100, 4)
+
+        for i in range(101):
+            if i not in random_vertices:
+                with self.assertRaises(ValueError):
+                    undirected_graph.remove_vertex(i)
+                with self.assertRaises(ValueError):
+                    directed_graph.remove_vertex(i)
+
+    def test_add_edge_exception_check(self) -> None:
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(20, 0, 100, 4)
+
+        for edge in random_edges:
+            with self.assertRaises(ValueError):
+                undirected_graph.add_edge(edge[0], edge[1])
+            with self.assertRaises(ValueError):
+                directed_graph.add_edge(edge[0], edge[1])
+
+    def test_remove_edge_exception_check(self) -> None:
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(20, 0, 100, 4)
+
+        more_random_edges: list[list[int]] = []
+
+        while len(more_random_edges) != len(random_edges):
+            edges: list[list[int]] = self.__generate_random_edges(random_vertices, 4)
+            for edge in edges:
+                if len(more_random_edges) == len(random_edges):
+                    break
+                elif edge not in more_random_edges and edge not in random_edges:
+                    more_random_edges.append(edge)
+
+        for edge in more_random_edges:
+            with self.assertRaises(ValueError):
+                undirected_graph.remove_edge(edge[0], edge[1])
+            with self.assertRaises(ValueError):
+                directed_graph.remove_edge(edge[0], edge[1])
+
+    def test_contains_edge_exception_check(self) -> None:
+        (
+            undirected_graph,
+            directed_graph,
+            random_vertices,
+            random_edges,
+        ) = self.__generate_graphs(20, 0, 100, 4)
+
+        for vertex in random_vertices:
+            with self.assertRaises(ValueError):
+                undirected_graph.contains_edge(vertex, 102)
+            with self.assertRaises(ValueError):
+                directed_graph.contains_edge(vertex, 102)
+
+        with self.assertRaises(ValueError):
+            undirected_graph.contains_edge(103, 102)
+        with self.assertRaises(ValueError):
+            directed_graph.contains_edge(103, 102)
+
+
+if __name__ == "__main__":
+    unittest.main()

graphs/graph_matrix.py

@@ -1,24 +0,0 @@
-class Graph:
-    def __init__(self, vertex):
-        self.vertex = vertex
-        self.graph = [[0] * vertex for i in range(vertex)]
-
-    def add_edge(self, u, v):
-        self.graph[u - 1][v - 1] = 1
-        self.graph[v - 1][u - 1] = 1
-
-    def show(self):
-        for i in self.graph:
-            for j in i:
-                print(j, end=" ")
-            print(" ")
-
-
-g = Graph(100)
-
-g.add_edge(1, 4)
-g.add_edge(4, 2)
-g.add_edge(4, 5)
-g.add_edge(2, 5)
-g.add_edge(5, 3)
-g.show()

graphs/greedy_best_first.py

@@ -6,14 +6,32 @@ from __future__ import annotations
 
 Path = list[tuple[int, int]]
 
-grid = [
+# 0's are free path whereas 1's are obstacles
-    [0, 0, 0, 0, 0, 0, 0],
+TEST_GRIDS = [
-    [0, 1, 0, 0, 0, 0, 0],  # 0 are free path whereas 1's are obstacles
+    [
-    [0, 0, 0, 0, 0, 0, 0],
+        [0, 0, 0, 0, 0, 0, 0],
-    [0, 0, 1, 0, 0, 0, 0],
+        [0, 1, 0, 0, 0, 0, 0],
-    [1, 0, 1, 0, 0, 0, 0],
+        [0, 0, 0, 0, 0, 0, 0],
-    [0, 0, 0, 0, 0, 0, 0],
+        [0, 0, 1, 0, 0, 0, 0],
-    [0, 0, 0, 0, 1, 0, 0],
+        [1, 0, 1, 0, 0, 0, 0],
+        [0, 0, 0, 0, 0, 0, 0],
+        [0, 0, 0, 0, 1, 0, 0],
+    ],
+    [
+        [0, 0, 0, 1, 1, 0, 0],
+        [0, 0, 0, 0, 1, 0, 1],
+        [0, 0, 0, 1, 1, 0, 0],
+        [0, 1, 0, 0, 1, 0, 0],
+        [1, 0, 0, 1, 1, 0, 1],
+        [0, 0, 0, 0, 0, 0, 0],
+    ],
+    [
+        [0, 0, 1, 0, 0],
+        [0, 1, 0, 0, 0],
+        [0, 0, 1, 0, 1],
+        [1, 0, 0, 1, 1],
+        [0, 0, 0, 0, 0],
+    ],
 ]
 
 delta = ([-1, 0], [0, -1], [1, 0], [0, 1])  # up, left, down, right
@@ -65,10 +83,14 @@ class Node:
     def __lt__(self, other) -> bool:
         return self.f_cost < other.f_cost
 
+    def __eq__(self, other) -> bool:
+        return self.pos == other.pos
+
 
 class GreedyBestFirst:
     """
-    >>> gbf = GreedyBestFirst((0, 0), (len(grid) - 1, len(grid[0]) - 1))
+    >>> grid = TEST_GRIDS[2]
+    >>> gbf = GreedyBestFirst(grid, (0, 0), (len(grid) - 1, len(grid[0]) - 1))
     >>> [x.pos for x in gbf.get_successors(gbf.start)]
     [(1, 0), (0, 1)]
     >>> (gbf.start.pos_y + delta[3][0], gbf.start.pos_x + delta[3][1])
@@ -78,11 +100,14 @@ class GreedyBestFirst:
     >>> gbf.retrace_path(gbf.start)
     [(0, 0)]
     >>> gbf.search()  # doctest: +NORMALIZE_WHITESPACE
-    [(0, 0), (1, 0), (2, 0), (3, 0), (3, 1), (4, 1), (5, 1), (6, 1),
+    [(0, 0), (1, 0), (2, 0), (2, 1), (3, 1), (4, 1), (4, 2), (4, 3),
-     (6, 2), (6, 3), (5, 3), (5, 4), (5, 5), (6, 5), (6, 6)]
+     (4, 4)]
     """
 
-    def __init__(self, start: tuple[int, int], goal: tuple[int, int]):
+    def __init__(
+        self, grid: list[list[int]], start: tuple[int, int], goal: tuple[int, int]
+    ):
+        self.grid = grid
         self.start = Node(start[1], start[0], goal[1], goal[0], 0, None)
         self.target = Node(goal[1], goal[0], goal[1], goal[0], 99999, None)
 
@@ -114,14 +139,6 @@ class GreedyBestFirst:
 
                 if child_node not in self.open_nodes:
                     self.open_nodes.append(child_node)
-                else:
-                    # retrieve the best current path
-                    better_node = self.open_nodes.pop(self.open_nodes.index(child_node))
-
-                    if child_node.g_cost < better_node.g_cost:
-                        self.open_nodes.append(child_node)
-                    else:
-                        self.open_nodes.append(better_node)
 
         if not self.reached:
             return [self.start.pos]
@@ -131,28 +148,22 @@ class GreedyBestFirst:
         """
         Returns a list of successors (both in the grid and free spaces)
         """
-        successors = []
+        return [
-        for action in delta:
+            Node(
-            pos_x = parent.pos_x + action[1]
+                pos_x,
-            pos_y = parent.pos_y + action[0]
+                pos_y,
-
+                self.target.pos_x,
-            if not (0 <= pos_x <= len(grid[0]) - 1 and 0 <= pos_y <= len(grid) - 1):
+                self.target.pos_y,
-                continue
+                parent.g_cost + 1,
-
+                parent,
-            if grid[pos_y][pos_x] != 0:
-                continue
-
-            successors.append(
-                Node(
-                    pos_x,
-                    pos_y,
-                    self.target.pos_y,
-                    self.target.pos_x,
-                    parent.g_cost + 1,
-                    parent,
-                )
             )
-        return successors
+            for action in delta
+            if (
+                0 <= (pos_x := parent.pos_x + action[1]) < len(self.grid[0])
+                and 0 <= (pos_y := parent.pos_y + action[0]) < len(self.grid)
+                and self.grid[pos_y][pos_x] == 0
+            )
+        ]
 
     def retrace_path(self, node: Node | None) -> Path:
         """
@@ -168,18 +179,21 @@ class GreedyBestFirst:
 
 
 if __name__ == "__main__":
-    init = (0, 0)
+    for idx, grid in enumerate(TEST_GRIDS):
-    goal = (len(grid) - 1, len(grid[0]) - 1)
+        print(f"==grid-{idx + 1}==")
-    for elem in grid:
-        print(elem)
-
-    print("------")
-
-    greedy_bf = GreedyBestFirst(init, goal)
-    path = greedy_bf.search()
-    if path:
-        for pos_x, pos_y in path:
-            grid[pos_x][pos_y] = 2
 
+        init = (0, 0)
+        goal = (len(grid) - 1, len(grid[0]) - 1)
         for elem in grid:
             print(elem)
+
+        print("------")
+
+        greedy_bf = GreedyBestFirst(grid, init, goal)
+        path = greedy_bf.search()
+        if path:
+            for pos_x, pos_y in path:
+                grid[pos_x][pos_y] = 2
+
+            for elem in grid:
+                print(elem)

linear_algebra/src/polynom_for_points.py

@@ -43,62 +43,43 @@ def points_to_polynomial(coordinates: list[list[int]]) -> str:
 
     x = len(coordinates)
 
-    count_of_line = 0
-    matrix: list[list[float]] = []
     # put the x and x to the power values in a matrix
-    while count_of_line < x:
+    matrix: list[list[float]] = [
-        count_in_line = 0
+        [
-        a = coordinates[count_of_line][0]
+            coordinates[count_of_line][0] ** (x - (count_in_line + 1))
-        count_line: list[float] = []
+            for count_in_line in range(x)
-        while count_in_line < x:
+        ]
-            count_line.append(a ** (x - (count_in_line + 1)))
+        for count_of_line in range(x)
-            count_in_line += 1
+    ]
-        matrix.append(count_line)
-        count_of_line += 1
 
-    count_of_line = 0
     # put the y values into a vector
-    vector: list[float] = []
+    vector: list[float] = [coordinates[count_of_line][1] for count_of_line in range(x)]
-    while count_of_line < x:
-        vector.append(coordinates[count_of_line][1])
-        count_of_line += 1
 
-    count = 0
+    for count in range(x):
-
+        for number in range(x):
-    while count < x:
+            if count == number:
-        zahlen = 0
+                continue
-        while zahlen < x:
+            fraction = matrix[number][count] / matrix[count][count]
-            if count == zahlen:
-                zahlen += 1
-            if zahlen == x:
-                break
-            bruch = matrix[zahlen][count] / matrix[count][count]
             for counting_columns, item in enumerate(matrix[count]):
                 # manipulating all the values in the matrix
-                matrix[zahlen][counting_columns] -= item * bruch
+                matrix[number][counting_columns] -= item * fraction
             # manipulating the values in the vector
-            vector[zahlen] -= vector[count] * bruch
+            vector[number] -= vector[count] * fraction
-            zahlen += 1
-        count += 1
 
-    count = 0
     # make solutions
-    solution: list[str] = []
+    solution: list[str] = [
-    while count < x:
+        str(vector[count] / matrix[count][count]) for count in range(x)
-        solution.append(str(vector[count] / matrix[count][count]))
+    ]
-        count += 1
 
-    count = 0
     solved = "f(x)="
 
-    while count < x:
+    for count in range(x):
         remove_e: list[str] = solution[count].split("E")
         if len(remove_e) > 1:
             solution[count] = f"{remove_e[0]}*10^{remove_e[1]}"
         solved += f"x^{x - (count + 1)}*{solution[count]}"
         if count + 1 != x:
             solved += "+"
-        count += 1
 
     return solved
 

linear_algebra/src/rank_of_matrix.py

@@ -0,0 +1,89 @@
+"""
+Calculate the rank of a matrix.
+
+See: https://en.wikipedia.org/wiki/Rank_(linear_algebra)
+"""
+
+
+def rank_of_matrix(matrix: list[list[int | float]]) -> int:
+    """
+    Finds the rank of a matrix.
+    Args:
+        matrix: The matrix as a list of lists.
+    Returns:
+        The rank of the matrix.
+    Example:
+    >>> matrix1 = [[1, 2, 3],
+    ...            [4, 5, 6],
+    ...            [7, 8, 9]]
+    >>> rank_of_matrix(matrix1)
+    2
+    >>> matrix2 = [[1, 0, 0],
+    ...            [0, 1, 0],
+    ...            [0, 0, 0]]
+    >>> rank_of_matrix(matrix2)
+    2
+    >>> matrix3 = [[1, 2, 3, 4],
+    ...            [5, 6, 7, 8],
+    ...            [9, 10, 11, 12]]
+    >>> rank_of_matrix(matrix3)
+    2
+    >>> rank_of_matrix([[2,3,-1,-1],
+    ...                [1,-1,-2,4],
+    ...                [3,1,3,-2],
+    ...                [6,3,0,-7]])
+    4
+    >>> rank_of_matrix([[2,1,-3,-6],
+    ...                [3,-3,1,2],
+    ...                [1,1,1,2]])
+    3
+    >>> rank_of_matrix([[2,-1,0],
+    ...                [1,3,4],
+    ...                [4,1,-3]])
+    3
+    >>> rank_of_matrix([[3,2,1],
+    ...                [-6,-4,-2]])
+    1
+    >>> rank_of_matrix([[],[]])
+    0
+    >>> rank_of_matrix([[1]])
+    1
+    >>> rank_of_matrix([[]])
+    0
+    """
+
+    rows = len(matrix)
+    columns = len(matrix[0])
+    rank = min(rows, columns)
+
+    for row in range(rank):
+        # Check if diagonal element is not zero
+        if matrix[row][row] != 0:
+            # Eliminate all the elements below the diagonal
+            for col in range(row + 1, rows):
+                multiplier = matrix[col][row] / matrix[row][row]
+                for i in range(row, columns):
+                    matrix[col][i] -= multiplier * matrix[row][i]
+        else:
+            # Find a non-zero diagonal element to swap rows
+            reduce = True
+            for i in range(row + 1, rows):
+                if matrix[i][row] != 0:
+                    matrix[row], matrix[i] = matrix[i], matrix[row]
+                    reduce = False
+                    break
+            if reduce:
+                rank -= 1
+                for i in range(rows):
+                    matrix[i][row] = matrix[i][rank]
+
+            # Reduce the row pointer by one to stay on the same row
+            row -= 1
+
+    return rank
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

linear_programming/simplex.py

@@ -0,0 +1,311 @@
+"""
+Python implementation of the simplex algorithm for solving linear programs in
+tabular form with
+- `>=`, `<=`, and `=` constraints and
+- each variable `x1, x2, ...>= 0`.
+
+See https://gist.github.com/imengus/f9619a568f7da5bc74eaf20169a24d98 for how to
+convert linear programs to simplex tableaus, and the steps taken in the simplex
+algorithm.
+
+Resources:
+https://en.wikipedia.org/wiki/Simplex_algorithm
+https://tinyurl.com/simplex4beginners
+"""
+from typing import Any
+
+import numpy as np
+
+
+class Tableau:
+    """Operate on simplex tableaus
+
+    >>> t = Tableau(np.array([[-1,-1,0,0,-1],[1,3,1,0,4],[3,1,0,1,4.]]), 2)
+    Traceback (most recent call last):
+    ...
+    ValueError: RHS must be > 0
+    """
+
+    def __init__(self, tableau: np.ndarray, n_vars: int) -> None:
+        # Check if RHS is negative
+        if np.any(tableau[:, -1], where=tableau[:, -1] < 0):
+            raise ValueError("RHS must be > 0")
+
+        self.tableau = tableau
+        self.n_rows, _ = tableau.shape
+
+        # Number of decision variables x1, x2, x3...
+        self.n_vars = n_vars
+
+        # Number of artificial variables to be minimised
+        self.n_art_vars = len(np.where(tableau[self.n_vars : -1] == -1)[0])
+
+        # 2 if there are >= or == constraints (nonstandard), 1 otherwise (std)
+        self.n_stages = (self.n_art_vars > 0) + 1
+
+        # Number of slack variables added to make inequalities into equalities
+        self.n_slack = self.n_rows - self.n_stages
+
+        # Objectives for each stage
+        self.objectives = ["max"]
+
+        # In two stage simplex, first minimise then maximise
+        if self.n_art_vars:
+            self.objectives.append("min")
+
+        self.col_titles = [""]
+
+        # Index of current pivot row and column
+        self.row_idx = None
+        self.col_idx = None
+
+        # Does objective row only contain (non)-negative values?
+        self.stop_iter = False
+
+    @staticmethod
+    def generate_col_titles(*args: int) -> list[str]:
+        """Generate column titles for tableau of specific dimensions
+
+        >>> Tableau.generate_col_titles(2, 3, 1)
+        ['x1', 'x2', 's1', 's2', 's3', 'a1', 'RHS']
+
+        >>> Tableau.generate_col_titles()
+        Traceback (most recent call last):
+        ...
+        ValueError: Must provide n_vars, n_slack, and n_art_vars
+        >>> Tableau.generate_col_titles(-2, 3, 1)
+        Traceback (most recent call last):
+        ...
+        ValueError: All arguments must be non-negative integers
+        """
+        if len(args) != 3:
+            raise ValueError("Must provide n_vars, n_slack, and n_art_vars")
+
+        if not all(x >= 0 and isinstance(x, int) for x in args):
+            raise ValueError("All arguments must be non-negative integers")
+
+        # decision | slack | artificial
+        string_starts = ["x", "s", "a"]
+        titles = []
+        for i in range(3):
+            for j in range(args[i]):
+                titles.append(string_starts[i] + str(j + 1))
+        titles.append("RHS")
+        return titles
+
+    def find_pivot(self, tableau: np.ndarray) -> tuple[Any, Any]:
+        """Finds the pivot row and column.
+        >>> t = Tableau(np.array([[-2,1,0,0,0], [3,1,1,0,6], [1,2,0,1,7.]]), 2)
+        >>> t.find_pivot(t.tableau)
+        (1, 0)
+        """
+        objective = self.objectives[-1]
+
+        # Find entries of highest magnitude in objective rows
+        sign = (objective == "min") - (objective == "max")
+        col_idx = np.argmax(sign * tableau[0, : self.n_vars])
+
+        # Choice is only valid if below 0 for maximise, and above for minimise
+        if sign * self.tableau[0, col_idx] <= 0:
+            self.stop_iter = True
+            return 0, 0
+
+        # Pivot row is chosen as having the lowest quotient when elements of
+        # the pivot column divide the right-hand side
+
+        # Slice excluding the objective rows
+        s = slice(self.n_stages, self.n_rows)
+
+        # RHS
+        dividend = tableau[s, -1]
+
+        # Elements of pivot column within slice
+        divisor = tableau[s, col_idx]
+
+        # Array filled with nans
+        nans = np.full(self.n_rows - self.n_stages, np.nan)
+
+        # If element in pivot column is greater than zeron_stages, return
+        # quotient or nan otherwise
+        quotients = np.divide(dividend, divisor, out=nans, where=divisor > 0)
+
+        # Arg of minimum quotient excluding the nan values. n_stages is added
+        # to compensate for earlier exclusion of objective columns
+        row_idx = np.nanargmin(quotients) + self.n_stages
+        return row_idx, col_idx
+
+    def pivot(self, tableau: np.ndarray, row_idx: int, col_idx: int) -> np.ndarray:
+        """Pivots on value on the intersection of pivot row and column.
+
+        >>> t = Tableau(np.array([[-2,-3,0,0,0],[1,3,1,0,4],[3,1,0,1,4.]]), 2)
+        >>> t.pivot(t.tableau, 1, 0).tolist()
+        ... # doctest: +NORMALIZE_WHITESPACE
+        [[0.0, 3.0, 2.0, 0.0, 8.0],
+        [1.0, 3.0, 1.0, 0.0, 4.0],
+        [0.0, -8.0, -3.0, 1.0, -8.0]]
+        """
+        # Avoid changes to original tableau
+        piv_row = tableau[row_idx].copy()
+
+        piv_val = piv_row[col_idx]
+
+        # Entry becomes 1
+        piv_row *= 1 / piv_val
+
+        # Variable in pivot column becomes basic, ie the only non-zero entry
+        for idx, coeff in enumerate(tableau[:, col_idx]):
+            tableau[idx] += -coeff * piv_row
+        tableau[row_idx] = piv_row
+        return tableau
+
+    def change_stage(self, tableau: np.ndarray) -> np.ndarray:
+        """Exits first phase of the two-stage method by deleting artificial
+        rows and columns, or completes the algorithm if exiting the standard
+        case.
+
+        >>> t = Tableau(np.array([
+        ... [3, 3, -1, -1, 0, 0, 4],
+        ... [2, 1, 0, 0, 0, 0, 0.],
+        ... [1, 2, -1, 0, 1, 0, 2],
+        ... [2, 1, 0, -1, 0, 1, 2]
+        ... ]), 2)
+        >>> t.change_stage(t.tableau).tolist()
+        ... # doctest: +NORMALIZE_WHITESPACE
+        [[2.0, 1.0, 0.0, 0.0, 0.0, 0.0],
+        [1.0, 2.0, -1.0, 0.0, 1.0, 2.0],
+        [2.0, 1.0, 0.0, -1.0, 0.0, 2.0]]
+        """
+        # Objective of original objective row remains
+        self.objectives.pop()
+
+        if not self.objectives:
+            return tableau
+
+        # Slice containing ids for artificial columns
+        s = slice(-self.n_art_vars - 1, -1)
+
+        # Delete the artificial variable columns
+        tableau = np.delete(tableau, s, axis=1)
+
+        # Delete the objective row of the first stage
+        tableau = np.delete(tableau, 0, axis=0)
+
+        self.n_stages = 1
+        self.n_rows -= 1
+        self.n_art_vars = 0
+        self.stop_iter = False
+        return tableau
+
+    def run_simplex(self) -> dict[Any, Any]:
+        """Operate on tableau until objective function cannot be
+        improved further.
+
+        # Standard linear program:
+        Max:  x1 +  x2
+        ST:   x1 + 3x2 <= 4
+             3x1 +  x2 <= 4
+        >>> Tableau(np.array([[-1,-1,0,0,0],[1,3,1,0,4],[3,1,0,1,4.]]),
+        ... 2).run_simplex()
+        {'P': 2.0, 'x1': 1.0, 'x2': 1.0}
+
+        # Optimal tableau input:
+        >>> Tableau(np.array([
+        ... [0, 0, 0.25, 0.25, 2],
+        ... [0, 1, 0.375, -0.125, 1],
+        ... [1, 0, -0.125, 0.375, 1]
+        ... ]), 2).run_simplex()
+        {'P': 2.0, 'x1': 1.0, 'x2': 1.0}
+
+        # Non-standard: >= constraints
+        Max: 2x1 + 3x2 +  x3
+        ST:   x1 +  x2 +  x3 <= 40
+             2x1 +  x2 -  x3 >= 10
+                 -  x2 +  x3 >= 10
+        >>> Tableau(np.array([
+        ... [2, 0, 0, 0, -1, -1, 0, 0, 20],
+        ... [-2, -3, -1, 0, 0, 0, 0, 0, 0],
+        ... [1, 1, 1, 1, 0, 0, 0, 0, 40],
+        ... [2, 1, -1, 0, -1, 0, 1, 0, 10],
+        ... [0, -1, 1, 0, 0, -1, 0, 1, 10.]
+        ... ]), 3).run_simplex()
+        {'P': 70.0, 'x1': 10.0, 'x2': 10.0, 'x3': 20.0}
+
+        # Non standard: minimisation and equalities
+        Min: x1 +  x2
+        ST: 2x1 +  x2 = 12
+            6x1 + 5x2 = 40
+        >>> Tableau(np.array([
+        ... [8, 6, 0, -1, 0, -1, 0, 0, 52],
+        ... [1, 1, 0, 0, 0, 0, 0, 0, 0],
+        ... [2, 1, 1, 0, 0, 0, 0, 0, 12],
+        ... [2, 1, 0, -1, 0, 0, 1, 0, 12],
+        ... [6, 5, 0, 0, 1, 0, 0, 0, 40],
+        ... [6, 5, 0, 0, 0, -1, 0, 1, 40.]
+        ... ]), 2).run_simplex()
+        {'P': 7.0, 'x1': 5.0, 'x2': 2.0}
+        """
+        # Stop simplex algorithm from cycling.
+        for _ in range(100):
+            # Completion of each stage removes an objective. If both stages
+            # are complete, then no objectives are left
+            if not self.objectives:
+                self.col_titles = self.generate_col_titles(
+                    self.n_vars, self.n_slack, self.n_art_vars
+                )
+
+                # Find the values of each variable at optimal solution
+                return self.interpret_tableau(self.tableau, self.col_titles)
+
+            row_idx, col_idx = self.find_pivot(self.tableau)
+
+            # If there are no more negative values in objective row
+            if self.stop_iter:
+                # Delete artificial variable columns and rows. Update attributes
+                self.tableau = self.change_stage(self.tableau)
+            else:
+                self.tableau = self.pivot(self.tableau, row_idx, col_idx)
+        return {}
+
+    def interpret_tableau(
+        self, tableau: np.ndarray, col_titles: list[str]
+    ) -> dict[str, float]:
+        """Given the final tableau, add the corresponding values of the basic
+        decision variables to the `output_dict`
+        >>> tableau = np.array([
+        ... [0,0,0.875,0.375,5],
+        ... [0,1,0.375,-0.125,1],
+        ... [1,0,-0.125,0.375,1]
+        ... ])
+        >>> t = Tableau(tableau, 2)
+        >>> t.interpret_tableau(tableau, ["x1", "x2", "s1", "s2", "RHS"])
+        {'P': 5.0, 'x1': 1.0, 'x2': 1.0}
+        """
+        # P = RHS of final tableau
+        output_dict = {"P": abs(tableau[0, -1])}
+
+        for i in range(self.n_vars):
+            # Gives ids of nonzero entries in the ith column
+            nonzero = np.nonzero(tableau[:, i])
+            n_nonzero = len(nonzero[0])
+
+            # First entry in the nonzero ids
+            nonzero_rowidx = nonzero[0][0]
+            nonzero_val = tableau[nonzero_rowidx, i]
+
+            # If there is only one nonzero value in column, which is one
+            if n_nonzero == nonzero_val == 1:
+                rhs_val = tableau[nonzero_rowidx, -1]
+                output_dict[col_titles[i]] = rhs_val
+
+        # Check for basic variables
+        for title in col_titles:
+            # Don't add RHS or slack variables to output dict
+            if title[0] not in "R-s-a":
+                output_dict.setdefault(title, 0)
+        return output_dict
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

machine_learning/forecasting/ex_data.csv

@@ -1,4 +1,4 @@
-total_user,total_events,days
+total_users,total_events,days
 18231,0.0,1
 22621,1.0,2
 15675,0.0,3

machine_learning/forecasting/run.py

@@ -1,6 +1,6 @@
 """
 this is code for forecasting
-but i modified it and used it for safety checker of data
+but I modified it and used it for safety checker of data
 for ex: you have an online shop and for some reason some data are
 missing (the amount of data that u expected are not supposed to be)
         then we can use it
@@ -11,6 +11,8 @@ missing (the amount of data that u expected are not supposed to be)
          u can just adjust it for ur own purpose
 """
 
+from warnings import simplefilter
+
 import numpy as np
 import pandas as pd
 from sklearn.preprocessing import Normalizer
@@ -45,8 +47,10 @@ def sarimax_predictor(train_user: list, train_match: list, test_match: list) ->
     >>> sarimax_predictor([4,2,6,8], [3,1,2,4], [2])
     6.6666671111109626
     """
+    # Suppress the User Warning raised by SARIMAX due to insufficient observations
+    simplefilter("ignore", UserWarning)
     order = (1, 2, 1)
-    seasonal_order = (1, 1, 0, 7)
+    seasonal_order = (1, 1, 1, 7)
     model = SARIMAX(
         train_user, exog=train_match, order=order, seasonal_order=seasonal_order
     )
@@ -102,6 +106,10 @@ def data_safety_checker(list_vote: list, actual_result: float) -> bool:
     """
     safe = 0
     not_safe = 0
+
+    if not isinstance(actual_result, float):
+        raise TypeError("Actual result should be float. Value passed is a list")
+
     for i in list_vote:
         if i > actual_result:
             safe = not_safe + 1
@@ -114,16 +122,11 @@ def data_safety_checker(list_vote: list, actual_result: float) -> bool:
 
 
 if __name__ == "__main__":
-    # data_input_df = pd.read_csv("ex_data.csv", header=None)
-    data_input = [[18231, 0.0, 1], [22621, 1.0, 2], [15675, 0.0, 3], [23583, 1.0, 4]]
-    data_input_df = pd.DataFrame(
-        data_input, columns=["total_user", "total_even", "days"]
-    )
-
     """
     data column = total user in a day, how much online event held in one day,
     what day is that(sunday-saturday)
     """
+    data_input_df = pd.read_csv("ex_data.csv")
 
     # start normalization
     normalize_df = Normalizer().fit_transform(data_input_df.values)
@@ -138,23 +141,23 @@ if __name__ == "__main__":
     x_test = x[len(x) - 1 :]
 
     # for linear regression & sarimax
-    trn_date = total_date[: len(total_date) - 1]
+    train_date = total_date[: len(total_date) - 1]
-    trn_user = total_user[: len(total_user) - 1]
+    train_user = total_user[: len(total_user) - 1]
-    trn_match = total_match[: len(total_match) - 1]
+    train_match = total_match[: len(total_match) - 1]
 
-    tst_date = total_date[len(total_date) - 1 :]
+    test_date = total_date[len(total_date) - 1 :]
-    tst_user = total_user[len(total_user) - 1 :]
+    test_user = total_user[len(total_user) - 1 :]
-    tst_match = total_match[len(total_match) - 1 :]
+    test_match = total_match[len(total_match) - 1 :]
 
     # voting system with forecasting
     res_vote = [
         linear_regression_prediction(
-            trn_date, trn_user, trn_match, tst_date, tst_match
+            train_date, train_user, train_match, test_date, test_match
         ),
-        sarimax_predictor(trn_user, trn_match, tst_match),
+        sarimax_predictor(train_user, train_match, test_match),
-        support_vector_regressor(x_train, x_test, trn_user),
+        support_vector_regressor(x_train, x_test, train_user),
     ]
 
     # check the safety of today's data
-    not_str = "" if data_safety_checker(res_vote, tst_user) else "not "
+    not_str = "" if data_safety_checker(res_vote, test_user[0]) else "not "
-    print("Today's data is {not_str}safe.")
+    print(f"Today's data is {not_str}safe.")

machine_learning/polymonial_regression.py

@@ -1,44 +0,0 @@
-import pandas as pd
-from matplotlib import pyplot as plt
-from sklearn.linear_model import LinearRegression
-
-# Splitting the dataset into the Training set and Test set
-from sklearn.model_selection import train_test_split
-
-# Fitting Polynomial Regression to the dataset
-from sklearn.preprocessing import PolynomialFeatures
-
-# Importing the dataset
-dataset = pd.read_csv(
-    "https://s3.us-west-2.amazonaws.com/public.gamelab.fun/dataset/"
-    "position_salaries.csv"
-)
-X = dataset.iloc[:, 1:2].values
-y = dataset.iloc[:, 2].values
-
-
-X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=0)
-
-
-poly_reg = PolynomialFeatures(degree=4)
-X_poly = poly_reg.fit_transform(X)
-pol_reg = LinearRegression()
-pol_reg.fit(X_poly, y)
-
-
-# Visualizing the Polymonial Regression results
-def viz_polymonial():
-    plt.scatter(X, y, color="red")
-    plt.plot(X, pol_reg.predict(poly_reg.fit_transform(X)), color="blue")
-    plt.title("Truth or Bluff (Linear Regression)")
-    plt.xlabel("Position level")
-    plt.ylabel("Salary")
-    plt.show()
-
-
-if __name__ == "__main__":
-    viz_polymonial()
-
-    # Predicting a new result with Polymonial Regression
-    pol_reg.predict(poly_reg.fit_transform([[5.5]]))
-    # output should be 132148.43750003

machine_learning/polynomial_regression.py

@@ -0,0 +1,213 @@
+"""
+Polynomial regression is a type of regression analysis that models the relationship
+between a predictor x and the response y as an mth-degree polynomial:
+
+y = β₀ + β₁x + β₂x² + ... + βₘxᵐ + ε
+
+By treating x, x², ..., xᵐ as distinct variables, we see that polynomial regression is a
+special case of multiple linear regression. Therefore, we can use ordinary least squares
+(OLS) estimation to estimate the vector of model parameters β = (β₀, β₁, β₂, ..., βₘ)
+for polynomial regression:
+
+β = (XᵀX)⁻¹Xᵀy = X⁺y
+
+where X is the design matrix, y is the response vector, and X⁺ denotes the Moore–Penrose
+pseudoinverse of X. In the case of polynomial regression, the design matrix is
+
+    |1  x₁  x₁² ⋯ x₁ᵐ|
+X = |1  x₂  x₂² ⋯ x₂ᵐ|
+    |⋮  ⋮   ⋮   ⋱ ⋮  |
+    |1  xₙ  xₙ² ⋯  xₙᵐ|
+
+In OLS estimation, inverting XᵀX to compute X⁺ can be very numerically unstable. This
+implementation sidesteps this need to invert XᵀX by computing X⁺ using singular value
+decomposition (SVD):
+
+β = VΣ⁺Uᵀy
+
+where UΣVᵀ is an SVD of X.
+
+References:
+    - https://en.wikipedia.org/wiki/Polynomial_regression
+    - https://en.wikipedia.org/wiki/Moore%E2%80%93Penrose_inverse
+    - https://en.wikipedia.org/wiki/Numerical_methods_for_linear_least_squares
+    - https://en.wikipedia.org/wiki/Singular_value_decomposition
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+
+class PolynomialRegression:
+    __slots__ = "degree", "params"
+
+    def __init__(self, degree: int) -> None:
+        """
+        @raises ValueError: if the polynomial degree is negative
+        """
+        if degree < 0:
+            raise ValueError("Polynomial degree must be non-negative")
+
+        self.degree = degree
+        self.params = None
+
+    @staticmethod
+    def _design_matrix(data: np.ndarray, degree: int) -> np.ndarray:
+        """
+        Constructs a polynomial regression design matrix for the given input data. For
+        input data x = (x₁, x₂, ..., xₙ) and polynomial degree m, the design matrix is
+        the Vandermonde matrix
+
+            |1  x₁  x₁² ⋯ x₁ᵐ|
+        X = |1  x₂  x₂² ⋯ x₂ᵐ|
+            |⋮  ⋮   ⋮   ⋱ ⋮  |
+            |1  xₙ  xₙ² ⋯  xₙᵐ|
+
+        Reference: https://en.wikipedia.org/wiki/Vandermonde_matrix
+
+        @param data:    the input predictor values x, either for model fitting or for
+                        prediction
+        @param degree:  the polynomial degree m
+        @returns:       the Vandermonde matrix X (see above)
+        @raises ValueError: if input data is not N x 1
+
+        >>> x = np.array([0, 1, 2])
+        >>> PolynomialRegression._design_matrix(x, degree=0)
+        array([[1],
+               [1],
+               [1]])
+        >>> PolynomialRegression._design_matrix(x, degree=1)
+        array([[1, 0],
+               [1, 1],
+               [1, 2]])
+        >>> PolynomialRegression._design_matrix(x, degree=2)
+        array([[1, 0, 0],
+               [1, 1, 1],
+               [1, 2, 4]])
+        >>> PolynomialRegression._design_matrix(x, degree=3)
+        array([[1, 0, 0, 0],
+               [1, 1, 1, 1],
+               [1, 2, 4, 8]])
+        >>> PolynomialRegression._design_matrix(np.array([[0, 0], [0 , 0]]), degree=3)
+        Traceback (most recent call last):
+        ...
+        ValueError: Data must have dimensions N x 1
+        """
+        rows, *remaining = data.shape
+        if remaining:
+            raise ValueError("Data must have dimensions N x 1")
+
+        return np.vander(data, N=degree + 1, increasing=True)
+
+    def fit(self, x_train: np.ndarray, y_train: np.ndarray) -> None:
+        """
+        Computes the polynomial regression model parameters using ordinary least squares
+        (OLS) estimation:
+
+        β = (XᵀX)⁻¹Xᵀy = X⁺y
+
+        where X⁺ denotes the Moore–Penrose pseudoinverse of the design matrix X. This
+        function computes X⁺ using singular value decomposition (SVD).
+
+        References:
+            - https://en.wikipedia.org/wiki/Moore%E2%80%93Penrose_inverse
+            - https://en.wikipedia.org/wiki/Singular_value_decomposition
+            - https://en.wikipedia.org/wiki/Multicollinearity
+
+        @param x_train: the predictor values x for model fitting
+        @param y_train: the response values y for model fitting
+        @raises ArithmeticError:    if X isn't full rank, then XᵀX is singular and β
+                                    doesn't exist
+
+        >>> x = np.array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+        >>> y = x**3 - 2 * x**2 + 3 * x - 5
+        >>> poly_reg = PolynomialRegression(degree=3)
+        >>> poly_reg.fit(x, y)
+        >>> poly_reg.params
+        array([-5.,  3., -2.,  1.])
+        >>> poly_reg = PolynomialRegression(degree=20)
+        >>> poly_reg.fit(x, y)
+        Traceback (most recent call last):
+        ...
+        ArithmeticError: Design matrix is not full rank, can't compute coefficients
+
+        Make sure errors don't grow too large:
+        >>> coefs = np.array([-250, 50, -2, 36, 20, -12, 10, 2, -1, -15, 1])
+        >>> y = PolynomialRegression._design_matrix(x, len(coefs) - 1) @ coefs
+        >>> poly_reg = PolynomialRegression(degree=len(coefs) - 1)
+        >>> poly_reg.fit(x, y)
+        >>> np.allclose(poly_reg.params, coefs, atol=10e-3)
+        True
+        """
+        X = PolynomialRegression._design_matrix(x_train, self.degree)  # noqa: N806
+        _, cols = X.shape
+        if np.linalg.matrix_rank(X) < cols:
+            raise ArithmeticError(
+                "Design matrix is not full rank, can't compute coefficients"
+            )
+
+        # np.linalg.pinv() computes the Moore–Penrose pseudoinverse using SVD
+        self.params = np.linalg.pinv(X) @ y_train
+
+    def predict(self, data: np.ndarray) -> np.ndarray:
+        """
+        Computes the predicted response values y for the given input data by
+        constructing the design matrix X and evaluating y = Xβ.
+
+        @param data:    the predictor values x for prediction
+        @returns:       the predicted response values y = Xβ
+        @raises ArithmeticError:    if this function is called before the model
+                                    parameters are fit
+
+        >>> x = np.array([0, 1, 2, 3, 4])
+        >>> y = x**3 - 2 * x**2 + 3 * x - 5
+        >>> poly_reg = PolynomialRegression(degree=3)
+        >>> poly_reg.fit(x, y)
+        >>> poly_reg.predict(np.array([-1]))
+        array([-11.])
+        >>> poly_reg.predict(np.array([-2]))
+        array([-27.])
+        >>> poly_reg.predict(np.array([6]))
+        array([157.])
+        >>> PolynomialRegression(degree=3).predict(x)
+        Traceback (most recent call last):
+        ...
+        ArithmeticError: Predictor hasn't been fit yet
+        """
+        if self.params is None:
+            raise ArithmeticError("Predictor hasn't been fit yet")
+
+        return PolynomialRegression._design_matrix(data, self.degree) @ self.params
+
+
+def main() -> None:
+    """
+    Fit a polynomial regression model to predict fuel efficiency using seaborn's mpg
+    dataset
+
+    >>> pass    # Placeholder, function is only for demo purposes
+    """
+    import seaborn as sns
+
+    mpg_data = sns.load_dataset("mpg")
+
+    poly_reg = PolynomialRegression(degree=2)
+    poly_reg.fit(mpg_data.weight, mpg_data.mpg)
+
+    weight_sorted = np.sort(mpg_data.weight)
+    predictions = poly_reg.predict(weight_sorted)
+
+    plt.scatter(mpg_data.weight, mpg_data.mpg, color="gray", alpha=0.5)
+    plt.plot(weight_sorted, predictions, color="red", linewidth=3)
+    plt.title("Predicting Fuel Efficiency Using Polynomial Regression")
+    plt.xlabel("Weight (lbs)")
+    plt.ylabel("Fuel Efficiency (mpg)")
+    plt.show()
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()
+
+    main()

maths/3n_plus_1.py

@@ -1,151 +0,0 @@
-from __future__ import annotations
-
-
-def n31(a: int) -> tuple[list[int], int]:
-    """
-    Returns the Collatz sequence and its length of any positive integer.
-    >>> n31(4)
-    ([4, 2, 1], 3)
-    """
-
-    if not isinstance(a, int):
-        msg = f"Must be int, not {type(a).__name__}"
-        raise TypeError(msg)
-    if a < 1:
-        msg = f"Given integer must be positive, not {a}"
-        raise ValueError(msg)
-
-    path = [a]
-    while a != 1:
-        if a % 2 == 0:
-            a //= 2
-        else:
-            a = 3 * a + 1
-        path.append(a)
-    return path, len(path)
-
-
-def test_n31():
-    """
-    >>> test_n31()
-    """
-    assert n31(4) == ([4, 2, 1], 3)
-    assert n31(11) == ([11, 34, 17, 52, 26, 13, 40, 20, 10, 5, 16, 8, 4, 2, 1], 15)
-    assert n31(31) == (
-        [
-            31,
-            94,
-            47,
-            142,
-            71,
-            214,
-            107,
-            322,
-            161,
-            484,
-            242,
-            121,
-            364,
-            182,
-            91,
-            274,
-            137,
-            412,
-            206,
-            103,
-            310,
-            155,
-            466,
-            233,
-            700,
-            350,
-            175,
-            526,
-            263,
-            790,
-            395,
-            1186,
-            593,
-            1780,
-            890,
-            445,
-            1336,
-            668,
-            334,
-            167,
-            502,
-            251,
-            754,
-            377,
-            1132,
-            566,
-            283,
-            850,
-            425,
-            1276,
-            638,
-            319,
-            958,
-            479,
-            1438,
-            719,
-            2158,
-            1079,
-            3238,
-            1619,
-            4858,
-            2429,
-            7288,
-            3644,
-            1822,
-            911,
-            2734,
-            1367,
-            4102,
-            2051,
-            6154,
-            3077,
-            9232,
-            4616,
-            2308,
-            1154,
-            577,
-            1732,
-            866,
-            433,
-            1300,
-            650,
-            325,
-            976,
-            488,
-            244,
-            122,
-            61,
-            184,
-            92,
-            46,
-            23,
-            70,
-            35,
-            106,
-            53,
-            160,
-            80,
-            40,
-            20,
-            10,
-            5,
-            16,
-            8,
-            4,
-            2,
-            1,
-        ],
-        107,
-    )
-
-
-if __name__ == "__main__":
-    num = 4
-    path, length = n31(num)
-    print(f"The Collatz sequence of {num} took {length} steps. \nPath: {path}")

maths/area_under_curve.py

@@ -7,9 +7,9 @@ from collections.abc import Callable
 
 
 def trapezoidal_area(
-    fnc: Callable[[int | float], int | float],
+    fnc: Callable[[float], float],
-    x_start: int | float,
+    x_start: float,
-    x_end: int | float,
+    x_end: float,
     steps: int = 100,
 ) -> float:
     """

maths/average_median.py

@@ -19,7 +19,9 @@ def median(nums: list) -> int | float:
     Returns:
         Median.
     """
-    sorted_list = sorted(nums)
+    # The sorted function returns list[SupportsRichComparisonT@sorted]
+    # which does not support `+`
+    sorted_list: list[int] = sorted(nums)
     length = len(sorted_list)
     mid_index = length >> 1
     return (

maths/collatz_sequence.py

@@ -1,43 +1,66 @@
+"""
+The Collatz conjecture is a famous unsolved problem in mathematics. Given a starting
+positive integer, define the following sequence:
+- If the current term n is even, then the next term is n/2.
+- If the current term n is odd, then the next term is 3n + 1.
+The conjecture claims that this sequence will always reach 1 for any starting number.
+
+Other names for this problem include the 3n + 1 problem, the Ulam conjecture, Kakutani's
+problem, the Thwaites conjecture, Hasse's algorithm, the Syracuse problem, and the
+hailstone sequence.
+
+Reference: https://en.wikipedia.org/wiki/Collatz_conjecture
+"""
+
 from __future__ import annotations
 
+from collections.abc import Generator
 
-def collatz_sequence(n: int) -> list[int]:
+
+def collatz_sequence(n: int) -> Generator[int, None, None]:
     """
-    Collatz conjecture: start with any positive integer n. The next term is
+    Generate the Collatz sequence starting at n.
-    obtained as follows:
+    >>> tuple(collatz_sequence(2.1))
-        If n term is even, the next term is: n / 2 .
-        If n is odd, the next term is: 3 * n + 1.
-
-    The conjecture states the sequence will always reach 1 for any starting value n.
-    Example:
-    >>> collatz_sequence(2.1)
     Traceback (most recent call last):
         ...
-    Exception: Sequence only defined for natural numbers
+    Exception: Sequence only defined for positive integers
-    >>> collatz_sequence(0)
+    >>> tuple(collatz_sequence(0))
     Traceback (most recent call last):
         ...
-    Exception: Sequence only defined for natural numbers
+    Exception: Sequence only defined for positive integers
-    >>> collatz_sequence(43)  # doctest: +NORMALIZE_WHITESPACE
+    >>> tuple(collatz_sequence(4))
-    [43, 130, 65, 196, 98, 49, 148, 74, 37, 112, 56, 28, 14, 7,
+    (4, 2, 1)
-     22, 11, 34, 17, 52, 26, 13, 40, 20, 10, 5, 16, 8, 4, 2, 1]
+    >>> tuple(collatz_sequence(11))
+    (11, 34, 17, 52, 26, 13, 40, 20, 10, 5, 16, 8, 4, 2, 1)
+    >>> tuple(collatz_sequence(31))     # doctest: +NORMALIZE_WHITESPACE
+    (31, 94, 47, 142, 71, 214, 107, 322, 161, 484, 242, 121, 364, 182, 91, 274, 137,
+    412, 206, 103, 310, 155, 466, 233, 700, 350, 175, 526, 263, 790, 395, 1186, 593,
+    1780, 890, 445, 1336, 668, 334, 167, 502, 251, 754, 377, 1132, 566, 283, 850, 425,
+    1276, 638, 319, 958, 479, 1438, 719, 2158, 1079, 3238, 1619, 4858, 2429, 7288, 3644,
+    1822, 911, 2734, 1367, 4102, 2051, 6154, 3077, 9232, 4616, 2308, 1154, 577, 1732,
+    866, 433, 1300, 650, 325, 976, 488, 244, 122, 61, 184, 92, 46, 23, 70, 35, 106, 53,
+    160, 80, 40, 20, 10, 5, 16, 8, 4, 2, 1)
+    >>> tuple(collatz_sequence(43))     # doctest: +NORMALIZE_WHITESPACE
+    (43, 130, 65, 196, 98, 49, 148, 74, 37, 112, 56, 28, 14, 7, 22, 11, 34, 17, 52, 26,
+    13, 40, 20, 10, 5, 16, 8, 4, 2, 1)
     """
-
     if not isinstance(n, int) or n < 1:
-        raise Exception("Sequence only defined for natural numbers")
+        raise Exception("Sequence only defined for positive integers")
 
-    sequence = [n]
+    yield n
     while n != 1:
-        n = 3 * n + 1 if n & 1 else n // 2
+        if n % 2 == 0:
-        sequence.append(n)
+            n //= 2
-    return sequence
+        else:
+            n = 3 * n + 1
+        yield n
 
 
 def main():
-    n = 43
+    n = int(input("Your number: "))
-    sequence = collatz_sequence(n)
+    sequence = tuple(collatz_sequence(n))
     print(sequence)
-    print(f"collatz sequence from {n} took {len(sequence)} steps.")
+    print(f"Collatz sequence from {n} took {len(sequence)} steps.")
 
 
 if __name__ == "__main__":

maths/continued_fraction.py

@@ -0,0 +1,51 @@
+"""
+Finding the continuous fraction for a rational number using python
+
+https://en.wikipedia.org/wiki/Continued_fraction
+"""
+
+
+from fractions import Fraction
+
+
+def continued_fraction(num: Fraction) -> list[int]:
+    """
+    :param num:
+    Fraction of the number whose continued fractions to be found.
+    Use Fraction(str(number)) for more accurate results due to
+    float inaccuracies.
+
+    :return:
+    The continued fraction of rational number.
+    It is the all commas in the (n + 1)-tuple notation.
+
+    >>> continued_fraction(Fraction(2))
+    [2]
+    >>> continued_fraction(Fraction("3.245"))
+    [3, 4, 12, 4]
+    >>> continued_fraction(Fraction("2.25"))
+    [2, 4]
+    >>> continued_fraction(1/Fraction("2.25"))
+    [0, 2, 4]
+    >>> continued_fraction(Fraction("415/93"))
+    [4, 2, 6, 7]
+    """
+    numerator, denominator = num.as_integer_ratio()
+    continued_fraction_list: list[int] = []
+    while True:
+        integer_part = int(numerator / denominator)
+        continued_fraction_list.append(integer_part)
+        numerator -= integer_part * denominator
+        if numerator == 0:
+            break
+        numerator, denominator = denominator, numerator
+
+    return continued_fraction_list
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()
+
+    print("Continued Fraction of 0.84375 is: ", continued_fraction(Fraction("0.84375")))

maths/decimal_to_fraction.py

@@ -1,4 +1,4 @@
-def decimal_to_fraction(decimal: int | float | str) -> tuple[int, int]:
+def decimal_to_fraction(decimal: float | str) -> tuple[int, int]:
     """
     Return a decimal number in its simplest fraction form
     >>> decimal_to_fraction(2)

maths/euler_modified.py

@@ -5,7 +5,7 @@ import numpy as np
 
 def euler_modified(
     ode_func: Callable, y0: float, x0: float, step_size: float, x_end: float
-) -> np.array:
+) -> np.ndarray:
     """
     Calculate solution at each step to an ODE using Euler's Modified Method
     The Euler Method is straightforward to implement, but can't give accurate solutions.

maths/factorial.py

@@ -55,7 +55,7 @@ def factorial_recursive(n: int) -> int:
         raise ValueError("factorial() only accepts integral values")
     if n < 0:
         raise ValueError("factorial() not defined for negative values")
-    return 1 if n == 0 or n == 1 else n * factorial(n - 1)
+    return 1 if n in {0, 1} else n * factorial(n - 1)
 
 
 if __name__ == "__main__":

maths/find_max.py

@@ -1,23 +1,23 @@
 from __future__ import annotations
 
 
-def find_max(nums: list[int | float]) -> int | float:
+def find_max_iterative(nums: list[int | float]) -> int | float:
     """
     >>> for nums in ([3, 2, 1], [-3, -2, -1], [3, -3, 0], [3.0, 3.1, 2.9]):
-    ...     find_max(nums) == max(nums)
+    ...     find_max_iterative(nums) == max(nums)
     True
     True
     True
     True
-    >>> find_max([2, 4, 9, 7, 19, 94, 5])
+    >>> find_max_iterative([2, 4, 9, 7, 19, 94, 5])
     94
-    >>> find_max([])
+    >>> find_max_iterative([])
     Traceback (most recent call last):
         ...
-    ValueError: find_max() arg is an empty sequence
+    ValueError: find_max_iterative() arg is an empty sequence
     """
     if len(nums) == 0:
-        raise ValueError("find_max() arg is an empty sequence")
+        raise ValueError("find_max_iterative() arg is an empty sequence")
     max_num = nums[0]
     for x in nums:
         if x > max_num:
@@ -25,6 +25,59 @@ def find_max(nums: list[int | float]) -> int | float:
     return max_num
 
 
+# Divide and Conquer algorithm
+def find_max_recursive(nums: list[int | float], left: int, right: int) -> int | float:
+    """
+    find max value in list
+    :param nums: contains elements
+    :param left: index of first element
+    :param right: index of last element
+    :return: max in nums
+
+    >>> for nums in ([3, 2, 1], [-3, -2, -1], [3, -3, 0], [3.0, 3.1, 2.9]):
+    ...     find_max_recursive(nums, 0, len(nums) - 1) == max(nums)
+    True
+    True
+    True
+    True
+    >>> nums = [1, 3, 5, 7, 9, 2, 4, 6, 8, 10]
+    >>> find_max_recursive(nums, 0, len(nums) - 1) == max(nums)
+    True
+    >>> find_max_recursive([], 0, 0)
+    Traceback (most recent call last):
+        ...
+    ValueError: find_max_recursive() arg is an empty sequence
+    >>> find_max_recursive(nums, 0, len(nums)) == max(nums)
+    Traceback (most recent call last):
+        ...
+    IndexError: list index out of range
+    >>> find_max_recursive(nums, -len(nums), -1) == max(nums)
+    True
+    >>> find_max_recursive(nums, -len(nums) - 1, -1) == max(nums)
+    Traceback (most recent call last):
+        ...
+    IndexError: list index out of range
+    """
+    if len(nums) == 0:
+        raise ValueError("find_max_recursive() arg is an empty sequence")
+    if (
+        left >= len(nums)
+        or left < -len(nums)
+        or right >= len(nums)
+        or right < -len(nums)
+    ):
+        raise IndexError("list index out of range")
+    if left == right:
+        return nums[left]
+    mid = (left + right) >> 1  # the middle
+    left_max = find_max_recursive(nums, left, mid)  # find max in range[left, mid]
+    right_max = find_max_recursive(
+        nums, mid + 1, right
+    )  # find max in range[mid + 1, right]
+
+    return left_max if left_max >= right_max else right_max
+
+
 if __name__ == "__main__":
     import doctest
 

maths/find_max_recursion.py

@@ -1,58 +0,0 @@
-from __future__ import annotations
-
-
-# Divide and Conquer algorithm
-def find_max(nums: list[int | float], left: int, right: int) -> int | float:
-    """
-    find max value in list
-    :param nums: contains elements
-    :param left: index of first element
-    :param right: index of last element
-    :return: max in nums
-
-    >>> for nums in ([3, 2, 1], [-3, -2, -1], [3, -3, 0], [3.0, 3.1, 2.9]):
-    ...     find_max(nums, 0, len(nums) - 1) == max(nums)
-    True
-    True
-    True
-    True
-    >>> nums = [1, 3, 5, 7, 9, 2, 4, 6, 8, 10]
-    >>> find_max(nums, 0, len(nums) - 1) == max(nums)
-    True
-    >>> find_max([], 0, 0)
-    Traceback (most recent call last):
-        ...
-    ValueError: find_max() arg is an empty sequence
-    >>> find_max(nums, 0, len(nums)) == max(nums)
-    Traceback (most recent call last):
-        ...
-    IndexError: list index out of range
-    >>> find_max(nums, -len(nums), -1) == max(nums)
-    True
-    >>> find_max(nums, -len(nums) - 1, -1) == max(nums)
-    Traceback (most recent call last):
-        ...
-    IndexError: list index out of range
-    """
-    if len(nums) == 0:
-        raise ValueError("find_max() arg is an empty sequence")
-    if (
-        left >= len(nums)
-        or left < -len(nums)
-        or right >= len(nums)
-        or right < -len(nums)
-    ):
-        raise IndexError("list index out of range")
-    if left == right:
-        return nums[left]
-    mid = (left + right) >> 1  # the middle
-    left_max = find_max(nums, left, mid)  # find max in range[left, mid]
-    right_max = find_max(nums, mid + 1, right)  # find max in range[mid + 1, right]
-
-    return left_max if left_max >= right_max else right_max
-
-
-if __name__ == "__main__":
-    import doctest
-
-    doctest.testmod(verbose=True)

maths/find_min.py

@@ -1,33 +1,86 @@
 from __future__ import annotations
 
 
-def find_min(nums: list[int | float]) -> int | float:
+def find_min_iterative(nums: list[int | float]) -> int | float:
     """
     Find Minimum Number in a List
     :param nums: contains elements
     :return: min number in list
 
     >>> for nums in ([3, 2, 1], [-3, -2, -1], [3, -3, 0], [3.0, 3.1, 2.9]):
-    ...     find_min(nums) == min(nums)
+    ...     find_min_iterative(nums) == min(nums)
     True
     True
     True
     True
-    >>> find_min([0, 1, 2, 3, 4, 5, -3, 24, -56])
+    >>> find_min_iterative([0, 1, 2, 3, 4, 5, -3, 24, -56])
     -56
-    >>> find_min([])
+    >>> find_min_iterative([])
     Traceback (most recent call last):
         ...
-    ValueError: find_min() arg is an empty sequence
+    ValueError: find_min_iterative() arg is an empty sequence
     """
     if len(nums) == 0:
-        raise ValueError("find_min() arg is an empty sequence")
+        raise ValueError("find_min_iterative() arg is an empty sequence")
     min_num = nums[0]
     for num in nums:
         min_num = min(min_num, num)
     return min_num
 
 
+# Divide and Conquer algorithm
+def find_min_recursive(nums: list[int | float], left: int, right: int) -> int | float:
+    """
+    find min value in list
+    :param nums: contains elements
+    :param left: index of first element
+    :param right: index of last element
+    :return: min in nums
+
+    >>> for nums in ([3, 2, 1], [-3, -2, -1], [3, -3, 0], [3.0, 3.1, 2.9]):
+    ...     find_min_recursive(nums, 0, len(nums) - 1) == min(nums)
+    True
+    True
+    True
+    True
+    >>> nums = [1, 3, 5, 7, 9, 2, 4, 6, 8, 10]
+    >>> find_min_recursive(nums, 0, len(nums) - 1) == min(nums)
+    True
+    >>> find_min_recursive([], 0, 0)
+    Traceback (most recent call last):
+        ...
+    ValueError: find_min_recursive() arg is an empty sequence
+    >>> find_min_recursive(nums, 0, len(nums)) == min(nums)
+    Traceback (most recent call last):
+        ...
+    IndexError: list index out of range
+    >>> find_min_recursive(nums, -len(nums), -1) == min(nums)
+    True
+    >>> find_min_recursive(nums, -len(nums) - 1, -1) == min(nums)
+    Traceback (most recent call last):
+        ...
+    IndexError: list index out of range
+    """
+    if len(nums) == 0:
+        raise ValueError("find_min_recursive() arg is an empty sequence")
+    if (
+        left >= len(nums)
+        or left < -len(nums)
+        or right >= len(nums)
+        or right < -len(nums)
+    ):
+        raise IndexError("list index out of range")
+    if left == right:
+        return nums[left]
+    mid = (left + right) >> 1  # the middle
+    left_min = find_min_recursive(nums, left, mid)  # find min in range[left, mid]
+    right_min = find_min_recursive(
+        nums, mid + 1, right
+    )  # find min in range[mid + 1, right]
+
+    return left_min if left_min <= right_min else right_min
+
+
 if __name__ == "__main__":
     import doctest
 

maths/find_min_recursion.py

@@ -1,58 +0,0 @@
-from __future__ import annotations
-
-
-# Divide and Conquer algorithm
-def find_min(nums: list[int | float], left: int, right: int) -> int | float:
-    """
-    find min value in list
-    :param nums: contains elements
-    :param left: index of first element
-    :param right: index of last element
-    :return: min in nums
-
-    >>> for nums in ([3, 2, 1], [-3, -2, -1], [3, -3, 0], [3.0, 3.1, 2.9]):
-    ...     find_min(nums, 0, len(nums) - 1) == min(nums)
-    True
-    True
-    True
-    True
-    >>> nums = [1, 3, 5, 7, 9, 2, 4, 6, 8, 10]
-    >>> find_min(nums, 0, len(nums) - 1) == min(nums)
-    True
-    >>> find_min([], 0, 0)
-    Traceback (most recent call last):
-        ...
-    ValueError: find_min() arg is an empty sequence
-    >>> find_min(nums, 0, len(nums)) == min(nums)
-    Traceback (most recent call last):
-        ...
-    IndexError: list index out of range
-    >>> find_min(nums, -len(nums), -1) == min(nums)
-    True
-    >>> find_min(nums, -len(nums) - 1, -1) == min(nums)
-    Traceback (most recent call last):
-        ...
-    IndexError: list index out of range
-    """
-    if len(nums) == 0:
-        raise ValueError("find_min() arg is an empty sequence")
-    if (
-        left >= len(nums)
-        or left < -len(nums)
-        or right >= len(nums)
-        or right < -len(nums)
-    ):
-        raise IndexError("list index out of range")
-    if left == right:
-        return nums[left]
-    mid = (left + right) >> 1  # the middle
-    left_min = find_min(nums, left, mid)  # find min in range[left, mid]
-    right_min = find_min(nums, mid + 1, right)  # find min in range[mid + 1, right]
-
-    return left_min if left_min <= right_min else right_min
-
-
-if __name__ == "__main__":
-    import doctest
-
-    doctest.testmod(verbose=True)

maths/gaussian_error_linear_unit.py

@@ -13,7 +13,7 @@ This script is inspired by a corresponding research paper.
 import numpy as np
 
 
-def sigmoid(vector: np.array) -> np.array:
+def sigmoid(vector: np.ndarray) -> np.ndarray:
     """
     Mathematical function sigmoid takes a vector x of K real numbers as input and
     returns 1/ (1 + e^-x).
@@ -25,7 +25,7 @@ def sigmoid(vector: np.array) -> np.array:
     return 1 / (1 + np.exp(-vector))
 
 
-def gaussian_error_linear_unit(vector: np.array) -> np.array:
+def gaussian_error_linear_unit(vector: np.ndarray) -> np.ndarray:
     """
     Implements the Gaussian Error Linear Unit (GELU) function
 

maths/interquartile_range.py

@@ -0,0 +1,66 @@
+"""
+An implementation of interquartile range (IQR) which is a measure of statistical
+dispersion, which is the spread of the data.
+
+The function takes the list of numeric values as input and returns the IQR.
+
+Script inspired by this Wikipedia article:
+https://en.wikipedia.org/wiki/Interquartile_range
+"""
+from __future__ import annotations
+
+
+def find_median(nums: list[int | float]) -> float:
+    """
+    This is the implementation of the median.
+    :param nums: The list of numeric nums
+    :return: Median of the list
+    >>> find_median(nums=([1, 2, 2, 3, 4]))
+    2
+    >>> find_median(nums=([1, 2, 2, 3, 4, 4]))
+    2.5
+    >>> find_median(nums=([-1, 2, 0, 3, 4, -4]))
+    1.5
+    >>> find_median(nums=([1.1, 2.2, 2, 3.3, 4.4, 4]))
+    2.65
+    """
+    div, mod = divmod(len(nums), 2)
+    if mod:
+        return nums[div]
+    return (nums[div] + nums[(div) - 1]) / 2
+
+
+def interquartile_range(nums: list[int | float]) -> float:
+    """
+    Return the interquartile range for a list of numeric values.
+    :param nums: The list of numeric values.
+    :return: interquartile range
+
+    >>> interquartile_range(nums=[4, 1, 2, 3, 2])
+    2.0
+    >>> interquartile_range(nums = [-2, -7, -10, 9, 8, 4, -67, 45])
+    17.0
+    >>> interquartile_range(nums = [-2.1, -7.1, -10.1, 9.1, 8.1, 4.1, -67.1, 45.1])
+    17.2
+    >>> interquartile_range(nums = [0, 0, 0, 0, 0])
+    0.0
+    >>> interquartile_range(nums=[])
+    Traceback (most recent call last):
+    ...
+    ValueError: The list is empty. Provide a non-empty list.
+    """
+    if not nums:
+        raise ValueError("The list is empty. Provide a non-empty list.")
+    nums.sort()
+    length = len(nums)
+    div, mod = divmod(length, 2)
+    q1 = find_median(nums[:div])
+    half_length = sum((div, mod))
+    q3 = find_median(nums[half_length:length])
+    return q3 - q1
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

maths/jaccard_similarity.py

@@ -14,7 +14,11 @@ Jaccard similarity is widely used with MinHashing.
 """
 
 
-def jaccard_similarity(set_a, set_b, alternative_union=False):
+def jaccard_similarity(
+    set_a: set[str] | list[str] | tuple[str],
+    set_b: set[str] | list[str] | tuple[str],
+    alternative_union=False,
+):
     """
     Finds the jaccard similarity between two sets.
     Essentially, its intersection over union.
@@ -37,41 +41,52 @@ def jaccard_similarity(set_a, set_b, alternative_union=False):
     >>> set_b = {'c', 'd', 'e', 'f', 'h', 'i'}
     >>> jaccard_similarity(set_a, set_b)
     0.375
-
     >>> jaccard_similarity(set_a, set_a)
     1.0
-
     >>> jaccard_similarity(set_a, set_a, True)
     0.5
-
     >>> set_a = ['a', 'b', 'c', 'd', 'e']
     >>> set_b = ('c', 'd', 'e', 'f', 'h', 'i')
     >>> jaccard_similarity(set_a, set_b)
     0.375
+    >>> set_a = ('c', 'd', 'e', 'f', 'h', 'i')
+    >>> set_b = ['a', 'b', 'c', 'd', 'e']
+    >>> jaccard_similarity(set_a, set_b)
+    0.375
+    >>> set_a = ('c', 'd', 'e', 'f', 'h', 'i')
+    >>> set_b = ['a', 'b', 'c', 'd']
+    >>> jaccard_similarity(set_a, set_b, True)
+    0.2
+    >>> set_a = {'a', 'b'}
+    >>> set_b = ['c', 'd']
+    >>> jaccard_similarity(set_a, set_b)
+    Traceback (most recent call last):
+        ...
+    ValueError: Set a and b must either both be sets or be either a list or a tuple.
     """
 
     if isinstance(set_a, set) and isinstance(set_b, set):
-        intersection = len(set_a.intersection(set_b))
+        intersection_length = len(set_a.intersection(set_b))
 
         if alternative_union:
-            union = len(set_a) + len(set_b)
+            union_length = len(set_a) + len(set_b)
         else:
-            union = len(set_a.union(set_b))
+            union_length = len(set_a.union(set_b))
 
-        return intersection / union
+        return intersection_length / union_length
 
-    if isinstance(set_a, (list, tuple)) and isinstance(set_b, (list, tuple)):
+    elif isinstance(set_a, (list, tuple)) and isinstance(set_b, (list, tuple)):
         intersection = [element for element in set_a if element in set_b]
 
         if alternative_union:
-            union = len(set_a) + len(set_b)
+            return len(intersection) / (len(set_a) + len(set_b))
-            return len(intersection) / union
         else:
-            union = set_a + [element for element in set_b if element not in set_a]
+            # Cast set_a to list because tuples cannot be mutated
+            union = list(set_a) + [element for element in set_b if element not in set_a]
             return len(intersection) / len(union)
-
+    raise ValueError(
-        return len(intersection) / len(union)
+        "Set a and b must either both be sets or be either a list or a tuple."
-    return None
+    )
 
 
 if __name__ == "__main__":

maths/kadanes.py

@@ -1,63 +0,0 @@
-"""
-Kadane's algorithm to get maximum subarray sum
-https://medium.com/@rsinghal757/kadanes-algorithm-dynamic-programming-how-and-why-does-it-work-3fd8849ed73d
-https://en.wikipedia.org/wiki/Maximum_subarray_problem
-"""
-test_data: tuple = ([-2, -8, -9], [2, 8, 9], [-1, 0, 1], [0, 0], [])
-
-
-def negative_exist(arr: list) -> int:
-    """
-    >>> negative_exist([-2,-8,-9])
-    -2
-    >>> [negative_exist(arr) for arr in test_data]
-    [-2, 0, 0, 0, 0]
-    """
-    arr = arr or [0]
-    max_number = arr[0]
-    for i in arr:
-        if i >= 0:
-            return 0
-        elif max_number <= i:
-            max_number = i
-    return max_number
-
-
-def kadanes(arr: list) -> int:
-    """
-    If negative_exist() returns 0 than this function will execute
-    else it will return the value return by negative_exist function
-
-    For example: arr = [2, 3, -9, 8, -2]
-        Initially we set value of max_sum to 0 and max_till_element to 0 than when
-        max_sum is less than max_till particular element it will assign that value to
-        max_sum and when value of max_till_sum is less than 0 it will assign 0 to i
-        and after that whole process, return the max_sum
-    So the output for above arr is 8
-
-    >>> kadanes([2, 3, -9, 8, -2])
-    8
-    >>> [kadanes(arr) for arr in test_data]
-    [-2, 19, 1, 0, 0]
-    """
-    max_sum = negative_exist(arr)
-    if max_sum < 0:
-        return max_sum
-
-    max_sum = 0
-    max_till_element = 0
-
-    for i in arr:
-        max_till_element += i
-        max_sum = max(max_sum, max_till_element)
-        max_till_element = max(max_till_element, 0)
-    return max_sum
-
-
-if __name__ == "__main__":
-    try:
-        print("Enter integer values sepatated by spaces")
-        arr = [int(x) for x in input().split()]
-        print(f"Maximum subarray sum of {arr} is {kadanes(arr)}")
-    except ValueError:
-        print("Please enter integer values.")

maths/largest_subarray_sum.py

@@ -1,21 +0,0 @@
-from sys import maxsize
-
-
-def max_sub_array_sum(a: list, size: int = 0):
-    """
-    >>> max_sub_array_sum([-13, -3, -25, -20, -3, -16, -23, -12, -5, -22, -15, -4, -7])
-    -3
-    """
-    size = size or len(a)
-    max_so_far = -maxsize - 1
-    max_ending_here = 0
-    for i in range(0, size):
-        max_ending_here = max_ending_here + a[i]
-        max_so_far = max(max_so_far, max_ending_here)
-        max_ending_here = max(max_ending_here, 0)
-    return max_so_far
-
-
-if __name__ == "__main__":
-    a = [-13, -3, -25, -20, 1, -16, -23, -12, -5, -22, -15, -4, -7]
-    print(("Maximum contiguous sum is", max_sub_array_sum(a, len(a))))

maths/least_common_multiple.py

@@ -67,7 +67,7 @@ def benchmark():
 
 
 class TestLeastCommonMultiple(unittest.TestCase):
-    test_inputs = [
+    test_inputs = (
         (10, 20),
         (13, 15),
         (4, 31),
@@ -77,8 +77,8 @@ class TestLeastCommonMultiple(unittest.TestCase):
         (12, 25),
         (10, 25),
         (6, 9),
-    ]
+    )
-    expected_results = [20, 195, 124, 210, 1462, 60, 300, 50, 18]
+    expected_results = (20, 195, 124, 210, 1462, 60, 300, 50, 18)
 
     def test_lcm_function(self):
         for i, (first_num, second_num) in enumerate(self.test_inputs):

maths/line_length.py

@@ -5,9 +5,9 @@ from collections.abc import Callable
 
 
 def line_length(
-    fnc: Callable[[int | float], int | float],
+    fnc: Callable[[float], float],
-    x_start: int | float,
+    x_start: float,
-    x_end: int | float,
+    x_end: float,
     steps: int = 100,
 ) -> float:
     """

maths/newton_raphson.py

@@ -1,16 +1,20 @@
 """
-    Author: P Shreyas Shetty
+Author: P Shreyas Shetty
-    Implementation of Newton-Raphson method for solving equations of kind
+Implementation of Newton-Raphson method for solving equations of kind
-    f(x) = 0. It is an iterative method where solution is found by the expression
+f(x) = 0. It is an iterative method where solution is found by the expression
-        x[n+1] = x[n] + f(x[n])/f'(x[n])
+    x[n+1] = x[n] + f(x[n])/f'(x[n])
-    If no solution exists, then either the solution will not be found when iteration
+If no solution exists, then either the solution will not be found when iteration
-    limit is reached or the gradient f'(x[n]) approaches zero. In both cases, exception
+limit is reached or the gradient f'(x[n]) approaches zero. In both cases, exception
-    is raised. If iteration limit is reached, try increasing maxiter.
+is raised. If iteration limit is reached, try increasing maxiter.
-    """
+"""
+
 import math as m
+from collections.abc import Callable
+
+DerivativeFunc = Callable[[float], float]
 
 
-def calc_derivative(f, a, h=0.001):
+def calc_derivative(f: DerivativeFunc, a: float, h: float = 0.001) -> float:
     """
     Calculates derivative at point a for function f using finite difference
     method
@@ -18,7 +22,14 @@ def calc_derivative(f, a, h=0.001):
     return (f(a + h) - f(a - h)) / (2 * h)
 
 
-def newton_raphson(f, x0=0, maxiter=100, step=0.0001, maxerror=1e-6, logsteps=False):
+def newton_raphson(
+    f: DerivativeFunc,
+    x0: float = 0,
+    maxiter: int = 100,
+    step: float = 0.0001,
+    maxerror: float = 1e-6,
+    logsteps: bool = False,
+) -> tuple[float, float, list[float]]:
     a = x0  # set the initial guess
     steps = [a]
     error = abs(f(a))
@@ -36,7 +47,7 @@ def newton_raphson(f, x0=0, maxiter=100, step=0.0001, maxerror=1e-6, logsteps=Fa
     if logsteps:
         # If logstep is true, then log intermediate steps
         return a, error, steps
-    return a, error
+    return a, error, []
 
 
 if __name__ == "__main__":

maths/numerical_integration.py

@@ -7,9 +7,9 @@ from collections.abc import Callable
 
 
 def trapezoidal_area(
-    fnc: Callable[[int | float], int | float],
+    fnc: Callable[[float], float],
-    x_start: int | float,
+    x_start: float,
-    x_end: int | float,
+    x_end: float,
     steps: int = 100,
 ) -> float:
     """

maths/polynomials/single_indeterminate_operations.py

@@ -87,7 +87,7 @@ class Polynomial:
 
         return Polynomial(self.degree + polynomial_2.degree, coefficients)
 
-    def evaluate(self, substitution: int | float) -> int | float:
+    def evaluate(self, substitution: float) -> float:
         """
         Evaluates the polynomial at x.
         >>> p = Polynomial(2, [1, 2, 3])
@@ -144,7 +144,7 @@ class Polynomial:
             coefficients[i] = self.coefficients[i + 1] * (i + 1)
         return Polynomial(self.degree - 1, coefficients)
 
-    def integral(self, constant: int | float = 0) -> Polynomial:
+    def integral(self, constant: float = 0) -> Polynomial:
         """
         Returns the integral of the polynomial.
         >>> p = Polynomial(2, [1, 2, 3])

maths/primelib.py

@@ -154,7 +154,7 @@ def prime_factorization(number):
 
     quotient = number
 
-    if number == 0 or number == 1:
+    if number in {0, 1}:
         ans.append(number)
 
     # if 'number' not prime then builds the prime factorization of 'number'

maths/qr_decomposition.py

@@ -1,7 +1,7 @@
 import numpy as np
 
 
-def qr_householder(a):
+def qr_householder(a: np.ndarray):
     """Return a QR-decomposition of the matrix A using Householder reflection.
 
     The QR-decomposition decomposes the matrix A of shape (m, n) into an

maths/series/geometric_series.py

@@ -14,10 +14,10 @@ from __future__ import annotations
 
 
 def geometric_series(
-    nth_term: float | int,
+    nth_term: float,
-    start_term_a: float | int,
+    start_term_a: float,
-    common_ratio_r: float | int,
+    common_ratio_r: float,
-) -> list[float | int]:
+) -> list[float]:
     """
     Pure Python implementation of Geometric Series algorithm
 
@@ -48,7 +48,7 @@ def geometric_series(
     """
     if not all((nth_term, start_term_a, common_ratio_r)):
         return []
-    series: list[float | int] = []
+    series: list[float] = []
     power = 1
     multiple = common_ratio_r
     for _ in range(int(nth_term)):

maths/series/p_series.py

@@ -13,7 +13,7 @@ python3 p_series.py
 from __future__ import annotations
 
 
-def p_series(nth_term: int | float | str, power: int | float | str) -> list[str]:
+def p_series(nth_term: float | str, power: float | str) -> list[str]:
     """
     Pure Python implementation of P-Series algorithm
     :return: The P-Series starting from 1 to last (nth) term

maths/sigmoid.py

@@ -11,7 +11,7 @@ https://en.wikipedia.org/wiki/Sigmoid_function
 import numpy as np
 
 
-def sigmoid(vector: np.array) -> np.array:
+def sigmoid(vector: np.ndarray) -> np.ndarray:
     """
     Implements the sigmoid function
 

maths/sigmoid_linear_unit.py

@@ -17,7 +17,7 @@ This script is inspired by a corresponding research paper.
 import numpy as np
 
 
-def sigmoid(vector: np.array) -> np.array:
+def sigmoid(vector: np.ndarray) -> np.ndarray:
     """
     Mathematical function sigmoid takes a vector x of K real numbers as input and
     returns 1/ (1 + e^-x).
@@ -29,17 +29,15 @@ def sigmoid(vector: np.array) -> np.array:
     return 1 / (1 + np.exp(-vector))
 
 
-def sigmoid_linear_unit(vector: np.array) -> np.array:
+def sigmoid_linear_unit(vector: np.ndarray) -> np.ndarray:
     """
     Implements the Sigmoid Linear Unit (SiLU) or swish function
 
     Parameters:
-        vector (np.array): A  numpy array consisting of real
+        vector (np.ndarray): A  numpy array consisting of real values
-        values.
 
     Returns:
-        swish_vec (np.array): The input numpy array, after applying
+        swish_vec (np.ndarray): The input numpy array, after applying swish
-        swish.
 
     Examples:
     >>> sigmoid_linear_unit(np.array([-1.0, 1.0, 2.0]))

maths/simultaneous_linear_equation_solver.py

@@ -0,0 +1,142 @@
+"""
+https://en.wikipedia.org/wiki/Augmented_matrix
+
+This algorithm solves simultaneous linear equations of the form
+λa + λb + λc + λd + ... = γ as [λ, λ, λ, λ, ..., γ]
+Where λ & γ are individual coefficients, the no. of equations = no. of coefficients - 1
+
+Note in order to work there must exist 1 equation where all instances of λ and γ != 0
+"""
+
+
+def simplify(current_set: list[list]) -> list[list]:
+    """
+    >>> simplify([[1, 2, 3], [4, 5, 6]])
+    [[1.0, 2.0, 3.0], [0.0, 0.75, 1.5]]
+    >>> simplify([[5, 2, 5], [5, 1, 10]])
+    [[1.0, 0.4, 1.0], [0.0, 0.2, -1.0]]
+    """
+    # Divide each row by magnitude of first term --> creates 'unit' matrix
+    duplicate_set = current_set.copy()
+    for row_index, row in enumerate(duplicate_set):
+        magnitude = row[0]
+        for column_index, column in enumerate(row):
+            if magnitude == 0:
+                current_set[row_index][column_index] = column
+                continue
+            current_set[row_index][column_index] = column / magnitude
+    # Subtract to cancel term
+    first_row = current_set[0]
+    final_set = [first_row]
+    current_set = current_set[1::]
+    for row in current_set:
+        temp_row = []
+        # If first term is 0, it is already in form we want, so we preserve it
+        if row[0] == 0:
+            final_set.append(row)
+            continue
+        for column_index in range(len(row)):
+            temp_row.append(first_row[column_index] - row[column_index])
+        final_set.append(temp_row)
+    # Create next recursion iteration set
+    if len(final_set[0]) != 3:
+        current_first_row = final_set[0]
+        current_first_column = []
+        next_iteration = []
+        for row in final_set[1::]:
+            current_first_column.append(row[0])
+            next_iteration.append(row[1::])
+        resultant = simplify(next_iteration)
+        for i in range(len(resultant)):
+            resultant[i].insert(0, current_first_column[i])
+        resultant.insert(0, current_first_row)
+        final_set = resultant
+    return final_set
+
+
+def solve_simultaneous(equations: list[list]) -> list:
+    """
+    >>> solve_simultaneous([[1, 2, 3],[4, 5, 6]])
+    [-1.0, 2.0]
+    >>> solve_simultaneous([[0, -3, 1, 7],[3, 2, -1, 11],[5, 1, -2, 12]])
+    [6.4, 1.2, 10.6]
+    >>> solve_simultaneous([])
+    Traceback (most recent call last):
+        ...
+    IndexError: solve_simultaneous() requires n lists of length n+1
+    >>> solve_simultaneous([[1, 2, 3],[1, 2]])
+    Traceback (most recent call last):
+        ...
+    IndexError: solve_simultaneous() requires n lists of length n+1
+    >>> solve_simultaneous([[1, 2, 3],["a", 7, 8]])
+    Traceback (most recent call last):
+        ...
+    ValueError: solve_simultaneous() requires lists of integers
+    >>> solve_simultaneous([[0, 2, 3],[4, 0, 6]])
+    Traceback (most recent call last):
+        ...
+    ValueError: solve_simultaneous() requires at least 1 full equation
+    """
+    if len(equations) == 0:
+        raise IndexError("solve_simultaneous() requires n lists of length n+1")
+    _length = len(equations) + 1
+    if any(len(item) != _length for item in equations):
+        raise IndexError("solve_simultaneous() requires n lists of length n+1")
+    for row in equations:
+        if any(not isinstance(column, (int, float)) for column in row):
+            raise ValueError("solve_simultaneous() requires lists of integers")
+    if len(equations) == 1:
+        return [equations[0][-1] / equations[0][0]]
+    data_set = equations.copy()
+    if any(0 in row for row in data_set):
+        temp_data = data_set.copy()
+        full_row = []
+        for row_index, row in enumerate(temp_data):
+            if 0 not in row:
+                full_row = data_set.pop(row_index)
+                break
+        if not full_row:
+            raise ValueError("solve_simultaneous() requires at least 1 full equation")
+        data_set.insert(0, full_row)
+    useable_form = data_set.copy()
+    simplified = simplify(useable_form)
+    simplified = simplified[::-1]
+    solutions: list = []
+    for row in simplified:
+        current_solution = row[-1]
+        if not solutions:
+            if row[-2] == 0:
+                solutions.append(0)
+                continue
+            solutions.append(current_solution / row[-2])
+            continue
+        temp_row = row.copy()[: len(row) - 1 :]
+        while temp_row[0] == 0:
+            temp_row.pop(0)
+        if len(temp_row) == 0:
+            solutions.append(0)
+            continue
+        temp_row = temp_row[1::]
+        temp_row = temp_row[::-1]
+        for column_index, column in enumerate(temp_row):
+            current_solution -= column * solutions[column_index]
+        solutions.append(current_solution)
+    final = []
+    for item in solutions:
+        final.append(float(round(item, 5)))
+    return final[::-1]
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()
+    eq = [
+        [2, 1, 1, 1, 1, 4],
+        [1, 2, 1, 1, 1, 5],
+        [1, 1, 2, 1, 1, 6],
+        [1, 1, 1, 2, 1, 7],
+        [1, 1, 1, 1, 2, 8],
+    ]
+    print(solve_simultaneous(eq))
+    print(solve_simultaneous([[4, 2]]))

maths/tanh.py

@@ -12,12 +12,12 @@ https://en.wikipedia.org/wiki/Activation_function
 import numpy as np
 
 
-def tangent_hyperbolic(vector: np.array) -> np.array:
+def tangent_hyperbolic(vector: np.ndarray) -> np.ndarray:
     """
         Implements the tanh function
 
         Parameters:
-            vector: np.array
+            vector: np.ndarray
 
         Returns:
             tanh (np.array): The input numpy array after applying tanh.

maths/volume.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 from math import pi, pow
 
 
-def vol_cube(side_length: int | float) -> float:
+def vol_cube(side_length: float) -> float:
     """
     Calculate the Volume of a Cube.
     >>> vol_cube(1)

matrix/count_negative_numbers_in_sorted_matrix.py

@@ -0,0 +1,151 @@
+"""
+Given an matrix of numbers in which all rows and all columns are sorted in decreasing
+order, return the number of negative numbers in grid.
+
+Reference: https://leetcode.com/problems/count-negative-numbers-in-a-sorted-matrix
+"""
+
+
+def generate_large_matrix() -> list[list[int]]:
+    """
+    >>> generate_large_matrix() # doctest: +ELLIPSIS
+    [[1000, ..., -999], [999, ..., -1001], ..., [2, ..., -1998]]
+    """
+    return [list(range(1000 - i, -1000 - i, -1)) for i in range(1000)]
+
+
+grid = generate_large_matrix()
+test_grids = (
+    [[4, 3, 2, -1], [3, 2, 1, -1], [1, 1, -1, -2], [-1, -1, -2, -3]],
+    [[3, 2], [1, 0]],
+    [[7, 7, 6]],
+    [[7, 7, 6], [-1, -2, -3]],
+    grid,
+)
+
+
+def validate_grid(grid: list[list[int]]) -> None:
+    """
+    Validate that the rows and columns of the grid is sorted in decreasing order.
+    >>> for grid in test_grids:
+    ...     validate_grid(grid)
+    """
+    assert all(row == sorted(row, reverse=True) for row in grid)
+    assert all(list(col) == sorted(col, reverse=True) for col in zip(*grid))
+
+
+def find_negative_index(array: list[int]) -> int:
+    """
+    Find the smallest negative index
+
+    >>> find_negative_index([0,0,0,0])
+    4
+    >>> find_negative_index([4,3,2,-1])
+    3
+    >>> find_negative_index([1,0,-1,-10])
+    2
+    >>> find_negative_index([0,0,0,-1])
+    3
+    >>> find_negative_index([11,8,7,-3,-5,-9])
+    3
+    >>> find_negative_index([-1,-1,-2,-3])
+    0
+    >>> find_negative_index([5,1,0])
+    3
+    >>> find_negative_index([-5,-5,-5])
+    0
+    >>> find_negative_index([0])
+    1
+    >>> find_negative_index([])
+    0
+    """
+    left = 0
+    right = len(array) - 1
+
+    # Edge cases such as no values or all numbers are negative.
+    if not array or array[0] < 0:
+        return 0
+
+    while right + 1 > left:
+        mid = (left + right) // 2
+        num = array[mid]
+
+        # Num must be negative and the index must be greater than or equal to 0.
+        if num < 0 and array[mid - 1] >= 0:
+            return mid
+
+        if num >= 0:
+            left = mid + 1
+        else:
+            right = mid - 1
+    # No negative numbers so return the last index of the array + 1 which is the length.
+    return len(array)
+
+
+def count_negatives_binary_search(grid: list[list[int]]) -> int:
+    """
+    An O(m logn) solution that uses binary search in order to find the boundary between
+    positive and negative numbers
+
+    >>> [count_negatives_binary_search(grid) for grid in test_grids]
+    [8, 0, 0, 3, 1498500]
+    """
+    total = 0
+    bound = len(grid[0])
+
+    for i in range(len(grid)):
+        bound = find_negative_index(grid[i][:bound])
+        total += bound
+    return (len(grid) * len(grid[0])) - total
+
+
+def count_negatives_brute_force(grid: list[list[int]]) -> int:
+    """
+    This solution is O(n^2) because it iterates through every column and row.
+
+    >>> [count_negatives_brute_force(grid) for grid in test_grids]
+    [8, 0, 0, 3, 1498500]
+    """
+    return len([number for row in grid for number in row if number < 0])
+
+
+def count_negatives_brute_force_with_break(grid: list[list[int]]) -> int:
+    """
+    Similar to the brute force solution above but uses break in order to reduce the
+    number of iterations.
+
+    >>> [count_negatives_brute_force_with_break(grid) for grid in test_grids]
+    [8, 0, 0, 3, 1498500]
+    """
+    total = 0
+    for row in grid:
+        for i, number in enumerate(row):
+            if number < 0:
+                total += len(row) - i
+                break
+    return total
+
+
+def benchmark() -> None:
+    """Benchmark our functions next to each other"""
+    from timeit import timeit
+
+    print("Running benchmarks")
+    setup = (
+        "from __main__ import count_negatives_binary_search, "
+        "count_negatives_brute_force, count_negatives_brute_force_with_break, grid"
+    )
+    for func in (
+        "count_negatives_binary_search",  # took 0.7727 seconds
+        "count_negatives_brute_force_with_break",  # took 4.6505 seconds
+        "count_negatives_brute_force",  # took 12.8160 seconds
+    ):
+        time = timeit(f"{func}(grid=grid)", setup=setup, number=500)
+        print(f"{func}() took {time:0.4f} seconds")
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()
+    benchmark()

matrix/matrix_class.py

@@ -141,7 +141,7 @@ class Matrix:
 
     @property
     def order(self) -> tuple[int, int]:
-        return (self.num_rows, self.num_columns)
+        return self.num_rows, self.num_columns
 
     @property
     def is_square(self) -> bool:
@@ -315,7 +315,7 @@ class Matrix:
             ]
         )
 
-    def __mul__(self, other: Matrix | int | float) -> Matrix:
+    def __mul__(self, other: Matrix | float) -> Matrix:
         if isinstance(other, (int, float)):
             return Matrix(
                 [[int(element * other) for element in row] for row in self.rows]

matrix/matrix_operation.py

@@ -47,7 +47,7 @@ def subtract(matrix_a: list[list[int]], matrix_b: list[list[int]]) -> list[list[
     raise TypeError("Expected a matrix, got int/list instead")
 
 
-def scalar_multiply(matrix: list[list[int]], n: int | float) -> list[list[float]]:
+def scalar_multiply(matrix: list[list[int]], n: float) -> list[list[float]]:
     """
     >>> scalar_multiply([[1,2],[3,4]],5)
     [[5, 10], [15, 20]]
@@ -189,9 +189,7 @@ def main() -> None:
     matrix_c = [[11, 12, 13, 14], [21, 22, 23, 24], [31, 32, 33, 34], [41, 42, 43, 44]]
     matrix_d = [[3, 0, 2], [2, 0, -2], [0, 1, 1]]
     print(f"Add Operation, {add(matrix_a, matrix_b) = } \n")
-    print(
+    print(f"Multiply Operation, {multiply(matrix_a, matrix_b) = } \n")
-        f"Multiply Operation, {multiply(matrix_a, matrix_b) = } \n",
-    )
     print(f"Identity: {identity(5)}\n")
     print(f"Minor of {matrix_c} = {minor(matrix_c, 1, 2)} \n")
     print(f"Determinant of {matrix_b} = {determinant(matrix_b)} \n")