diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index 6aa0073bf95b..edee3bc4febb 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -1,8 +1,7 @@ # https://github.com/microsoft/vscode-dev-containers/blob/main/containers/python-3/README.md -ARG VARIANT=3.12-bookworm +ARG VARIANT=3.13-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 + && python3 -m pip install --no-cache-dir -r /tmp/pip-tmp/requirements.txt \ + && pipx install pre-commit ruff diff --git a/.devcontainer/README.md b/.devcontainer/README.md index ec3cdb61de7a..af7502768154 100644 --- a/.devcontainer/README.md +++ b/.devcontainer/README.md @@ -1 +1,43 @@ -https://code.visualstudio.com/docs/devcontainers/tutorial +# Development Container + +This is **Devcontainer** configuration to provide a consistent development environment for all contributors. + +## Features + +- [x] Pre-configured **Python environment** +- [x] Automatic installation of **pre-commit hooks** +- [x] **Ruff** linter ready to check your code +- [x] **Oh My Zsh** with plugins: +- `zsh-autosuggestions` +- `zsh-syntax-highlighting` + +## Usage + +1. Install [**Docker**](https://www.docker.com/get-started/) and [**Visual Studio Code**](https://code.visualstudio.com/) +2. Install the **Remote - Containers** extension in VS Code + + - Do `CTRL+P`, paste this command and press `Enter` + + ```shell + ext install ms-vscode-remote.remote-containers + ``` + +3. Open this repository in VS Code +4. When prompted, click **"Reopen in Container"** +5. Wait for the environment to build and initialize + +After setup: + +- `pre-commit` hooks are installed +- `ruff` and other tools are available +- The shell uses Zsh by default + +## Tips + +To manually run checks on all files: + +```bash +pre-commit run --all-files +``` + +> For further information here's [Microsoft tutorial about devcontainers.](https://code.visualstudio.com/docs/devcontainers/tutorial) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index ae1d4fb7494d..96691bc86fe4 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,15 +1,25 @@ { "name": "Python 3", - "build": { - "dockerfile": "Dockerfile", - "context": "..", - "args": { - // Update 'VARIANT' to pick a Python version: 3, 3.11, 3.10, 3.9, 3.8 - // Append -bullseye or -buster to pin to an OS version. - // Use -bullseye variants on local on arm64/Apple Silicon. - "VARIANT": "3.12-bookworm", - } - }, + + // Use a prebuilt dev container image instead of building from a local + // Dockerfile. The repo migrated its dependencies to pyproject.toml, so the + // old Dockerfile's `COPY requirements.txt` step no longer had a file to copy + // and the image build failed. The upstream images already ship Python + a + // full toolchain, so pulling one is both faster and less to maintain. + // + // This repo tracks the latest-and-greatest CPython on the newest stable + // Debian. Images are published per CPython minor version on Debian 13 + // "Trixie" (3.11-trixie ... 3.15-trixie); bump this to the newest available + // when a new stable CPython ships. + // NOTE: these images do not publish free-threaded (`t`) variants, so 3.15t + // cannot be selected via the tag alone -- but the repo's `.python-version` + // pins 3.15t, and `uv run`/`uv sync` in the container honor it, so uv gives + // contributors free-threaded 3.15t regardless of the base tag. + "image": "mcr.microsoft.com/devcontainers/python:latest", + + // Install the tools post_install and CI expect (pre-commit + ruff), plus uv + // for the free-threaded workflow above, then run the existing setup script. + "postCreateCommand": "pipx install pre-commit ruff uv && zsh .devcontainer/post_install", // Configure tool-specific properties. "customizations": { @@ -18,15 +28,23 @@ // 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" + // Formatting/linting is handled by Ruff (matches pre-commit and CI). + "editor.formatOnSave": true, + "[python]": { + "editor.defaultFormatter": "charliermarsh.ruff", + "editor.codeActionsOnSave": { + "source.fixAll": "explicit", + "source.organizeImports": "explicit" + } + }, + "terminal.integrated.defaultProfile.linux": "zsh" }, // Add the IDs of extensions you want installed when the container is created. "extensions": [ "ms-python.python", - "ms-python.vscode-pylance" + "ms-python.vscode-pylance", + "charliermarsh.ruff" ] } }, @@ -34,9 +52,6 @@ // 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" } diff --git a/.devcontainer/post_install b/.devcontainer/post_install new file mode 100755 index 000000000000..589ee361f5cb --- /dev/null +++ b/.devcontainer/post_install @@ -0,0 +1,29 @@ +#!/usr/bin/env bash + +echo "Begin post-installation steps..." + +set -e + +echo "Installing pre-commit hooks..." +pre-commit install + +echo "Installing Oh My Zsh plugins..." + +# Install zsh-autosuggestions if not present +if [ ! -d "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-autosuggestions" ]; then + echo "Cloning zsh-autosuggestions..." + git clone https://github.com/zsh-users/zsh-autosuggestions \ + "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-autosuggestions" +fi + +# Install zsh-syntax-highlighting if not present +if [ ! -d "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting" ]; then + echo "Cloning zsh-syntax-highlighting..." + git clone https://github.com/zsh-users/zsh-syntax-highlighting.git \ + "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting" +fi + +echo "Configuring plugins in ~/.zshrc..." +sed -i '/^plugins=/c\plugins=(git zsh-autosuggestions zsh-syntax-highlighting)' ~/.zshrc + +echo "Post-installation steps completed successfully. Enjoy!" diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index d2ac43c7df31..3cc25d1bae1c 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -9,8 +9,6 @@ /.* @cclauss -# /arithmetic_analysis/ - # /backtracking/ # /bit_manipulation/ diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 15e494ec867e..0b7f161181df 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -6,3 +6,5 @@ updates: directory: "/" schedule: interval: "daily" + cooldown: + default-days: 7 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e2ae0966cda5..9b7eb5bca370 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,21 +1,20 @@ -### Describe your change: - - +### Describe your change * [ ] Add an algorithm? * [ ] Fix a bug or typo in an existing algorithm? * [ ] Add or change doctests? -- Note: Please avoid changing both code and tests in a single pull request. * [ ] Documentation change? -### Checklist: +### Checklist + * [ ] I have read [CONTRIBUTING.md](https://github.com/TheAlgorithms/Python/blob/master/CONTRIBUTING.md). * [ ] This pull request is all my own work -- I have not plagiarized. * [ ] I know that pull requests will not be merged if they fail the automated tests. -* [ ] This PR only changes one algorithm file. To ease review, please open separate PRs for separate algorithms. +* [ ] This PR only changes one algorithm file. To ease review, please open separate PRs for separate algorithms. * [ ] All new Python files are placed inside an existing directory. * [ ] All filenames are in all lowercase characters with no spaces or dashes. * [ ] All functions and variable names follow Python naming conventions. * [ ] 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 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". +* [ ] 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". diff --git a/.github/skills/code-review/SKILL.md b/.github/skills/code-review/SKILL.md new file mode 100644 index 000000000000..f6b9689acfb2 --- /dev/null +++ b/.github/skills/code-review/SKILL.md @@ -0,0 +1,95 @@ +# Skill: Code review for TheAlgorithms/Python + +Review a pull request against the rules already written in +[`CONTRIBUTING.md`](../../../CONTRIBUTING.md). The goal is a review that any +reviewer (human or AI) can run the same way every time, and that produces a clear, +kind, actionable verdict. + +## How to run this skill + +Read the PR diff, then work through the four `CONTRIBUTING.md` sections in order +and emit the fixed output shape below. Cite the exact rule you are applying and +suggest the fix — never just "rejected". + +### 1. Before contributing / Is this an algorithm? + +- [ ] The change adds, fixes, or documents **one algorithm** — not multiple, and + not both code and doctest changes in the same PR. +- [ ] It is a genuine algorithm or data structure (see the *What is an Algorithm?* + section), not a script, snippet, how-to-use for an existing API, or exercise + dump. +- [ ] It is **not already in the repository** (search the existing directories). +- [ ] **No earlier open PR** already does the same thing — link it if one exists. +- [ ] Properly attributed — no plagiarism; prior sources credited. + +### 2. Coding Style + +- [ ] `from __future__ import annotations` is not needed because this repo only uses + the latest version of CPython. +- [ ] File and directory names are lowercase, use underscores, and land inside an + existing directory. +- [ ] Public functions/classes have **type hints**. +- [ ] Public functions have **doctests that actually pass**. +- [ ] Descriptive variable and function names (no single letters where a word helps). +- [ ] Code is formatted and lint-clean (`ruff`, `pre-commit`). + +> **Optional hint:** When a PR hand-writes a simple class that is mostly a +> bundle of fields (a manual `__init__` plus `__repr__`/`__eq__`), it is worth +> **suggesting** `from typing import NamedTuple` or +> `from dataclasses import dataclass` where they would simplify the code. These +> are underutilized tools that our contributors would benefit from using where +> they make sense. Offer it as an optional improvement, not a blocker — do not +> request changes solely because a class was written the longhand way. + +#### When a PR fails `ruff check` + +Don't just report the failure — try the mechanical fixes and recommend the one +that works, in this order: + +1. Run `ruff check --fix file_path.py`. If that makes the file pass, recommend + that solution — these are the fixes `ruff` considers **safe**. +2. If it still fails, run `ruff check --fix --unsafe-fixes file_path.py`. If that + makes the file pass **and** the resulting diff is genuinely safe (it preserves + behavior — review it, don't trust it blindly), recommend that solution and note + that it required `--unsafe-fixes`. +3. If neither passes, or the unsafe fix would change behavior, describe the + remaining rule violations and the manual change the author needs to make. + +Always quote the exact rule code(s) `ruff` reports (e.g., `ruff rule UP047`, +`ruff rule RUF100`) so the author can run those commands to read the rules being +flagged. Also, paste the concrete command you ran. + +### 3. Other Requirements for Submissions + +- [ ] At least one **Wikipedia (or equivalent) URL** documenting the algorithm. +- [ ] Docstring explains what the function does and its parameters/returns. +- [ ] No unnecessary third-party dependencies. + +### 4. Verdict — fixed output shape + +Emit exactly these headings so reviews are comparable and easy to automate: + +```text +### Is this an algorithm? — +### Duplicate / prior-art check — <#NNNN | none found> +### Coding style — +### Other requirements (doctests, type hints, descriptive names, Wikipedia URL) — +### Verdict — + one-line reason +``` + +## Tone + +Be specific and kind. Point at the exact `CONTRIBUTING.md` rule and offer the fix +rather than a bare rejection — first-time and Hacktoberfest contributors are more +likely to come back and improve the PR when the path forward is clear. + +## Map findings to labels + +Where a finding matches an existing label, name it so the review lines up with the +maintenance/cleanup tooling: + +- missing/failing doctests → `require tests` +- missing type hints → `require type hints` +- non-descriptive names → `require descriptive names` +- CI red → `tests are failing` +- otherwise ready for a maintainer → `awaiting reviews` diff --git a/.github/skills/new-pull-request/SKILL.md b/.github/skills/new-pull-request/SKILL.md new file mode 100644 index 000000000000..ca6a0dda5fb2 --- /dev/null +++ b/.github/skills/new-pull-request/SKILL.md @@ -0,0 +1,75 @@ +# Skill: New pull request for TheAlgorithms/Python + +Create a new pull request using the rules already written in +[`CONTRIBUTING.md`](../../../CONTRIBUTING.md). The goal is that creating a new +pull request (human or AI) can run the same way every time, and that produces a +clear, kind, tested, type-hinted, mergeable contribution. + +## How to run this skill + +Make sure that the local `master` branch is synced with `upstream/master` before +creating a new pull request. + +Create a new clearly named branch for the pull request. Pull request changes must +not be made or submitted on the `master` branch. + +Never hand-edit or revert the `uv.lock` file. If you add a legitimate +dependency, let the `uv-lock` pre-commit hook regenerate it — do not touch it by +hand. A hand-modified `uv.lock` makes the `algorithms-keeper` bot close the pull +request as invalid, and even a repo maintainer cannot undo that. + +Always check at least one Markdown checkbox in the pull request description (the "Describe your change" section), or the +`algorithms-keeper` bot will close the pull request as invalid — and it does +this *before* a human reads the PR, so a genuinely good change gets closed for a +formatting reason. This applies to **every** pull request, including CI, docs, +and tooling changes that are not algorithms: tick the boxes that genuinely apply +so the body is never submitted with all boxes empty. Any repo maintainer can +undo this if you @mention them on the closed pull request, but re-opening is +often unreliable, so it is far better to get it right the first time. + +### 1. Before contributing / Is this an algorithm? + +- [ ] The change adds, fixes, or documents **one algorithm** — not multiple, and + not both code and doctest changes in the same PR. +- [ ] It is a genuine algorithm or data structure (see the *What is an Algorithm?* + section), not a script, snippet, how-to-use for an existing API, or exercise + dump. +- [ ] It is **not already in the repository** (search the existing directories). +- [ ] **No earlier open PR** already does the same thing — link it if one exists. +- [ ] Properly attributed — no plagiarism; prior sources credited. + +### 2. Coding Style + +- [ ] `from __future__ import annotations` is not needed because this repo only uses + the latest version of CPython. +- [ ] File and directory names are lowercase, use underscores, and land inside an + existing directory. +- [ ] Public functions/classes have **type hints**. +- [ ] Public functions have **doctests that actually pass**. +- [ ] Descriptive variable and function names (no single letters where a word helps). +- [ ] For a simple class that is mostly a bundle of fields, **consider** + `from typing import NamedTuple` or `from dataclasses import dataclass` + instead of a hand-written `__init__`/`__repr__`/`__eq__`. These are + underutilized tools that make simple classes shorter and clearer — use + them where they genuinely simplify the code, not everywhere. +- [ ] Code is formatted and lint-clean (`ruff`, `pre-commit`). +- [ ] `DIRECTORY.md` and `README.md` are **not hand-edited** — the + `algorithms-keeper` bot regenerates them automatically after merge. + +### 3. Other Requirements for Submissions + +- [ ] At least one **Wikipedia (or equivalent) URL** documenting the algorithm. +- [ ] Docstring explains what the function does and its parameters/returns. +- [ ] No unnecessary third-party dependencies. + +## Before you click "Create pull request" + +This is the final gate. Do not open the pull request until every item here is true: + +- [ ] At least one Markdown checkbox in the PR description is checked. **Verify + this by re-reading the rendered body** — if every box is still `- [ ]`, the + `algorithms-keeper` bot will auto-close the PR before any human sees it. + Check the boxes that genuinely apply to this change; never submit an + all-empty checklist, even for a CI, docs, or tooling PR. +- [ ] The branch is not `master`, and `master` is synced with `upstream/master`. +- [ ] `uv.lock` was not hand-edited. diff --git a/.github/skills/review-open-issue/SKILL.md b/.github/skills/review-open-issue/SKILL.md new file mode 100644 index 000000000000..7603f38fdbff --- /dev/null +++ b/.github/skills/review-open-issue/SKILL.md @@ -0,0 +1,110 @@ +# Skill: Review an open issue for TheAlgorithms/Python + +Triage an open issue — most often one carrying the `bug` label — **together with +every pull request attached to it**, and produce a verdict a maintainer can act on +without re-doing the work. The goal is a review that any triager (human or AI) can +run the same way every time, and that ends in an explicit list of `Closes #NNNNN` +lines the maintainer can paste into a merge commit. + +This repo exists to **teach visitors to fix bugs by doing**. So the default is to +merge adequate existing contributor work, not to open a fresh PR that races them. +Only open your own PR when no attached PR adequately solves the issue. + +## How to run this skill + +### 1. Reproduce before you trust the report + +- Check out current `master` and actually **run the failing case** from the issue. +- If it reproduces, say so and paste the minimal reproducer (inputs → observed + output, e.g. `nan` + a `RuntimeWarning`). +- If you **cannot** confirm it locally — an optional dependency isn't installed, + the failure needs an external service, the report is too vague — **say that + explicitly rather than guessing.** "Not reproducible in a vanilla checkout" + is a real, useful verdict. + +### 2. Classify the issue + +Sort each issue into one bucket and act accordingly: + +- **Confirmed bug with an adequate open PR** → recommend the specific PR to merge. +- **Confirmed bug, no adequate PR** → open a new PR yourself (see step 5). +- **Not a bug / working-as-intended** → recommend closing, and explain why (e.g. + binary search returning *an* index of a duplicate is correct, not a defect). +- **Feature request mislabeled as a bug** → recommend dropping the `bug` label; do + **not** close it as a bug. +- **Too vague / needs reporter info** → comment **on the issue itself** asking for + the one concrete thing missing (a file path, a traceback, a reproducer), and note + it should be closed if no answer arrives. +- **Environment / optional-dependency, not an algorithm defect** → note it needs + someone with that environment; it is not fixable in a vanilla checkout. + +### 3. Examine every attached PR — pick one, name the duplicates + +For a bug with several open PRs: + +- **Verify each fix's doctest values numerically** against a trusted reference + (`scipy`, `numpy.linalg`, `geopy`, or a brute-force check over random inputs). + Don't take a doctest's word for it — confirm the number. +- Prefer the **first-in PR with the smallest correct diff** that follows repo + convention (doctests over new test files, `raise` over `assert`, no unrelated + reindentation or churn of clean doctests into floating-point noise). +- **Reject out-of-scope "fixes"** — e.g. swapping a real divide-by-zero for a + `1e-15` magic constant makes results implementation-defined. Fix the issue, not + more. +- Identify the byte-for-byte **duplicates** so the maintainer can close them with + thanks in the same action. + +### 4. Emit the verdict — fixed output shape + +Post one comment that a maintainer can act on directly. For each issue give a +one-line rationale and the exact autoclose line. Two formatting rules matter a lot +to human maintainers scanning the thread: + +- **Start every line that references an issue or PR with a Markdown list marker + (`-` or `* `).** GitHub-flavored Markdown only autolinks `#NNNNN` inside a list, + and those autolinks are colored — **purple = merged, red = closed, green = open** — + so the maintainer can see merge/close progress at a glance. A bare `#14813` at the + start of a line does not autolink. +- **Merging a PR that closes an issue also closes the issue's other open PRs**, so + fold the duplicates into one autoclose statement rather than listing the winner + alone: + + ```text + * #14813 — 3x3 inverse returns the transpose → merge #14821 + (Closes #14813, Closes #14840, Closes #15045) + ``` + +Recommended shape: + +```text +## Confirmed bugs with an adequate open PR — merge +* # — → merge # (Closes #, Closes #, …) + +## Not a bug / not merge-ready +* # — + +## Summary — lines to add +* Closes # → # +``` + +### 5. When you must open your own PR + +If no attached PR is adequate, open one — but let the contributors keep the credit +where their work was close. Use autoclose keywords in the **commit message body** +so the merge closes the issue *and* the superseded PRs: + +```text +Fixes #12233 +Fixes #12262 +Fixes #13635 +``` + +Follow the [`new-pull-request`](../new-pull-request/SKILL.md) skill for the +mechanics (synced `master`, named branch, checked description box, untouched +`uv.lock`). + +## Tone + +Be specific and kind. Name the exact PR and the exact reason, credit the +contributor by handle, and offer runners-up detailed feedback so they learn — the +point of the repo is that people come back and fix the next one. diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index a113b4608678..3dfe13d80c65 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -9,25 +9,40 @@ jobs: build: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 + - uses: actions/checkout@v7 with: - python-version: 3.12 - allow-prereleases: true - - uses: actions/cache@v4 + persist-credentials: false + - uses: astral-sh/setup-uv@v7 + with: + enable-cache: true + cache-dependency-glob: uv.lock + - uses: actions/setup-python@v7 with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }} - - name: Install dependencies - run: | - python -m pip install --upgrade pip setuptools six wheel - python -m pip install pytest-cov -r requirements.txt + python-version-file: .python-version + allow-prereleases: true + - run: uv sync --group=test - name: Run tests - # TODO: #8818 Re-enable quantum tests - run: pytest - --ignore=quantum/q_fourier_transform.py + # opencv-python is gated out on 3.15t (no cp315t wheel yet), so skip the + # files that import cv2. Pure-Python algorithms in computer_vision/ and + # data_compression/ still run; digital_image_processing/ is almost entirely + # cv2-based so it is skipped as a tree. Re-enable when a cp315t wheel ships. + # --ignore-gil-enabled: some compiled deps (sklearn, xgboost, ...) don't + # yet ship the Py_mod_gil slot, so importing them re-enables the GIL under + # 3.15t. That's an upstream-wheel gap, not our code; the flag lets the suite + # run anyway and pytest-run-parallel still reports which tests are not + # thread-safe. Drop the flag once the scientific stack ships free-threaded wheels. + run: uv run --with=pytest-run-parallel pytest + --iterations=8 --parallel-threads=auto --ignore-gil-enabled + --ignore=computer_vision/flip_augmentation.py + --ignore=computer_vision/harris_corner.py + --ignore=computer_vision/mosaic_augmentation.py + --ignore=data_compression/peak_signal_to_noise_ratio.py + --ignore=digital_image_processing/ + --ignore=docs/conf.py --ignore=project_euler/ --ignore=scripts/validate_solutions.py + --ignore=web_programming/current_stock_price.py + --ignore=web_programming/fetch_anime_and_play.py --cov-report=term-missing:skip-covered --cov=. . - if: ${{ success() }} diff --git a/.github/workflows/devcontainer_ci.yml b/.github/workflows/devcontainer_ci.yml new file mode 100644 index 000000000000..946df0446c57 --- /dev/null +++ b/.github/workflows/devcontainer_ci.yml @@ -0,0 +1,29 @@ +name: Test DevContainer Build + +on: + push: + paths: + - ".devcontainer/**" + - ".github/workflows/devcontainer_ci.yml" + - ".python-version" + - "pyproject.toml" + - "uv.lock" + pull_request: + paths: + - ".devcontainer/**" + - ".github/workflows/devcontainer_ci.yml" + - ".python-version" + - "pyproject.toml" + - "uv.lock" + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: devcontainers/ci@v0.3 + with: + push: never + runCmd: "uv --version" diff --git a/.github/workflows/directory_writer.yml b/.github/workflows/directory_writer.yml index 55d89f455a25..b58e0727801c 100644 --- a/.github/workflows/directory_writer.yml +++ b/.github/workflows/directory_writer.yml @@ -3,15 +3,17 @@ name: directory_writer on: [push] jobs: - build: + directory_writer: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v7 with: fetch-depth: 0 - - uses: actions/setup-python@v5 + persist-credentials: false + - uses: actions/setup-python@v7 with: - python-version: 3.x + python-version-file: .python-version + allow-prereleases: true - name: Write DIRECTORY.md run: | scripts/build_directory_md.py 2>&1 | tee DIRECTORY.md diff --git a/.github/workflows/hacktoberfest_prep.yml b/.github/workflows/hacktoberfest_prep.yml new file mode 100644 index 000000000000..fc78d9b059b8 --- /dev/null +++ b/.github/workflows/hacktoberfest_prep.yml @@ -0,0 +1,109 @@ +# Daily refresh of the Hacktoberfest 2026 open-PR cleanup tracker. +# Ticks off any tracked pull request that has since been merged/closed, and +# rewrites the "Automated statistics" section (open issue/PR counts + the top +# three `awaiting reviews` directories). The job fails on purpose once +# Hacktoberfest 2026 has begun (>= 2026-10-01), which is the signal to retire it. +name: hacktoberfest_prep + +on: + push: + paths: + - ".github/workflows/hacktoberfest_prep.yml" + - "scripts/hacktoberfest_prep_update.py" + pull_request: + paths: + - ".github/workflows/hacktoberfest_prep.yml" + - "scripts/hacktoberfest_prep_update.py" + # schedule: + # - cron: "50 11 * * *" # 11:50 UTC every day + workflow_dispatch: # allow a manual run while testing + +permissions: + contents: write + pull-requests: write + +jobs: + hacktoberfest-prep: + # No point running on forks — this pushes to the repo's own docs file. + if: github.repository == 'TheAlgorithms/Python' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: actions/setup-python@v7 + with: + python-version-file: .python-version + allow-prereleases: true + - name: Install dependencies + run: python -m pip install --upgrade "httpx2>=2.0.1" + - name: Update the tracker + id: update + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITHUB_REPOSITORY: ${{ github.repository }} + # Don't let the intentional post-Oct-1 failure stop the commit step; + # capture the exit code and re-raise it after pushing any changes. + run: | + set +e + python scripts/hacktoberfest_prep_update.py + echo "exit_code=$?" >> "$GITHUB_OUTPUT" + # Dry run on push / pull_request: show the diff the script produced but + # do NOT commit or push. This lets a PR prove the tracker still gathers + # its data and rewrites docs/hacktober_2026_prep.md correctly without + # leaving a permanent commit. Only the schedule/manual runs persist. + - name: Show changes (dry run) + if: github.event_name == 'push' || github.event_name == 'pull_request' + run: | + echo "Dry run (${{ github.event_name }}): showing git diff, not committing." + git --no-pager diff -- docs/hacktober_2026_prep.md + if git diff --quiet -- docs/hacktober_2026_prep.md; then + echo "No changes to docs/hacktober_2026_prep.md." + fi + # `master` is a protected branch: direct pushes are rejected with + # `GH006: Protected branch update failed ... Changes must be made through + # a pull request`. So instead of committing straight to master, persist + # the refreshed tracker on a single rolling branch and open — or, since + # re-pushing the branch updates the existing PR in place, leave open — one + # pull request. Uses the bundled `gh` CLI rather than a third-party + # action (see zizmor's "superfluous actions" audit). + - name: Open or update the tracker pull request + if: github.event_name != 'push' && github.event_name != 'pull_request' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + BRANCH: chore/hacktoberfest-2026-prep-refresh + run: | + set -euo pipefail + if git diff --quiet -- docs/hacktober_2026_prep.md; then + echo "No changes to docs/hacktober_2026_prep.md; nothing to persist." + exit 0 + fi + git config --global user.name "$GITHUB_ACTOR" + git config --global user.email "$GITHUB_ACTOR@users.noreply.github.com" + # `actions/checkout` runs with `persist-credentials: false`, so git has + # no token to authenticate the push below (it fails with + # `fatal: could not read Username for 'https://github.com'`). Wire the + # bundled `gh` in as git's credential helper so `git push` reuses + # GH_TOKEN — no third-party action and no token baked into the remote URL. + gh auth setup-git + git switch -c "$BRANCH" + git add docs/hacktober_2026_prep.md + git commit -m "chore: refresh Hacktoberfest 2026 prep tracker" + # Force-push so the rolling branch always carries just the latest + # snapshot on top of master; this also updates any open PR in place. + git push --force origin "$BRANCH" + if [ -z "$(gh pr list --head "$BRANCH" --state open --json number --jq '.[].number')" ]; then + gh pr create \ + --base master \ + --head "$BRANCH" \ + --title "chore: refresh Hacktoberfest 2026 prep tracker" \ + --body "Automated daily refresh of the Hacktoberfest 2026 open-PR cleanup tracker (\`docs/hacktober_2026_prep.md\`): ticks off any tracked pull request that has since been merged/closed and rewrites the **Automated statistics** section. + + This PR is updated in place by the \`hacktoberfest_prep\` workflow, so it always reflects the latest scheduled run. Merge it whenever you want to capture the current snapshot." + else + echo "Open tracker PR already exists; force-push updated it in place." + fi + - name: Propagate the script's exit code + env: + UPDATE_EXIT_CODE: ${{ steps.update.outputs.exit_code }} + run: exit ${UPDATE_EXIT_CODE} diff --git a/.github/workflows/project_euler.yml b/.github/workflows/project_euler.yml index 59e1208a650d..bbbeaa048943 100644 --- a/.github/workflows/project_euler.yml +++ b/.github/workflows/project_euler.yml @@ -14,26 +14,28 @@ jobs: project-euler: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 + - uses: actions/checkout@v7 with: - python-version: 3.x - - name: Install pytest and pytest-cov - run: | - python -m pip install --upgrade pip - python -m pip install --upgrade numpy pytest pytest-cov - - run: pytest --doctest-modules --cov-report=term-missing:skip-covered --cov=project_euler/ project_euler/ + persist-credentials: false + - uses: astral-sh/setup-uv@v7 + - uses: actions/setup-python@v7 + with: + python-version-file: .python-version + allow-prereleases: true + - run: uv sync --group=euler-validate --group=test + - run: uv run pytest --doctest-modules --cov-report=term-missing:skip-covered --cov=project_euler/ project_euler/ validate-solutions: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: astral-sh/setup-uv@v7 + - uses: actions/setup-python@v7 with: - python-version: 3.x - - name: Install pytest and requests - run: | - python -m pip install --upgrade pip - python -m pip install --upgrade numpy pytest requests - - run: pytest scripts/validate_solutions.py + python-version-file: .python-version + allow-prereleases: true + - run: uv sync --group=euler-validate --group=test + - run: uv run pytest scripts/validate_solutions.py env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/ruff.yml b/.github/workflows/ruff.yml index d354eba672ae..338bae8d6470 100644 --- a/.github/workflows/ruff.yml +++ b/.github/workflows/ruff.yml @@ -11,6 +11,8 @@ jobs: ruff: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - run: pip install --user ruff - - run: ruff check --output-format=github . + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: astral-sh/setup-uv@v7 + - run: uvx ruff check --output-format=github . diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml new file mode 100644 index 000000000000..1672bf69407f --- /dev/null +++ b/.github/workflows/sphinx.yml @@ -0,0 +1,52 @@ +name: sphinx + +on: + # Triggers the workflow on push or pull request events but only for the "master" branch + push: + branches: ["master"] + pull_request: + branches: ["master"] + # Or manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build_docs: + runs-on: ubuntu-24.04-arm + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: astral-sh/setup-uv@v7 + - uses: actions/setup-python@v7 + with: + python-version-file: .python-version + allow-prereleases: true + - run: uv sync --group=docs + - uses: actions/configure-pages@v6 + - run: uv run sphinx-build -c docs . docs/_build/html + - uses: actions/upload-pages-artifact@v5 + with: + path: docs/_build/html + + deploy_docs: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + if: github.event_name != 'pull_request' + needs: build_docs + runs-on: ubuntu-latest + steps: + - uses: actions/deploy-pages@v5 + id: deployment diff --git a/.github/workflows/ty.yml b/.github/workflows/ty.yml new file mode 100644 index 000000000000..15aface62dea --- /dev/null +++ b/.github/workflows/ty.yml @@ -0,0 +1,53 @@ +# https://docs.astral.sh/ty/ +name: ty +on: + push: + branches: + - master + pull_request: + branches: + - master +jobs: + ty: + runs-on: ubuntu-latest + # Informational only: ty is not yet a required gate. This job surfaces + # type-check findings in the logs so they can be triaged into gradual + # [tool.ty] rules without blocking merges. Flip `continue-on-error` to + # false once the baseline is clean. + continue-on-error: true + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: astral-sh/setup-uv@v7 + with: + enable-cache: true + cache-dependency-glob: uv.lock + # Mirror the `build` job: `uv sync` installs the dependencies without + # building this flat-layout repo as a wheel. pyproject.toml has no + # [build-system], so uv treats the project as virtual and installs only + # its dependencies -- no "Multiple top-level packages discovered in a + # flat-layout" error and no need for a src-layout. (`uv pip install .` + # would force that wheel build and fail.) Pin a regular GIL 3.15 so typed + # third-party dependencies resolve; the free-threaded 3.15t interpreter the + # test matrix uses lacks wheels for several of them. ty itself is pulled in + # ephemerally with `--with` so it needn't be added to the lockfile. + - run: uv sync --python 3.15 + # Pin the *run* to the same regular-GIL 3.15 too. Without `--python 3.15` + # here, `uv run` re-resolved the project's default interpreter -- the + # free-threaded 3.15t used by the test matrix -- so ty type-checked against + # an env where many third-party stubs don't resolve, drowning real findings + # in `unresolved-import` / `unresolved-attribute` noise. Pinning 3.15 lets + # ty see the synced dependencies, so the `[tool.ty.rules]` severities in + # pyproject.toml apply to a meaningful baseline. + # + # `--exit-zero` is ty's native advisory switch (the analog of ruff's + # `ruff check --exit-zero`): the step always exits 0, yet with + # `--output-format=github` ty still emits ::error annotations that render + # inline on the diff, so findings stay visible without a red X. Promotion + # path: `--exit-zero` (informational, always green) -> `--exit-zero-on-warning` + # (fail only on error-severity, tolerate warnings) -> drop the flag entirely + # to make ty a required gate once the [tool.ty] baseline is clean. + # `continue-on-error: true` above stays as a belt-and-suspenders guard so a + # ty *crash* (not a diagnostic) can never block a merge either. + - run: uv run --python 3.15 --with ty ty check --output-format=github --exit-zero diff --git a/.github/zizmor.yml b/.github/zizmor.yml new file mode 100644 index 000000000000..75a55f63776d --- /dev/null +++ b/.github/zizmor.yml @@ -0,0 +1,7 @@ +rules: + excessive-permissions: + disable: true + unpinned-uses: + config: + policies: + "*": ref-pin diff --git a/.gitignore b/.gitignore index baea84b8d1f1..192f37798f5d 100644 --- a/.gitignore +++ b/.gitignore @@ -73,7 +73,6 @@ target/ .ipynb_checkpoints # pyenv -.python-version # celery beat schedule file celerybeat-schedule diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 7b219597f7b6..9b4488f78310 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,6 +1,12 @@ +ci: + autoupdate_schedule: monthly + # uv-lock resolves dependencies from PyPI, but pre-commit.ci runs hooks with no + # network access, so it fails there. Skip it on pre-commit.ci; it still runs locally. + skip: [uv-lock] + repos: - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.6.0 + rev: v6.0.0 hooks: - id: check-executables-have-shebangs - id: check-toml @@ -11,28 +17,35 @@ repos: - id: requirements-txt-fixer - repo: https://github.com/MarcoGorelli/auto-walrus - rev: 0.3.4 + rev: 0.4.1 hooks: - id: auto-walrus - - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.6.7 - hooks: - - id: ruff - - id: ruff-format - - repo: https://github.com/codespell-project/codespell - rev: v2.3.0 + rev: v2.4.3 hooks: - id: codespell additional_dependencies: - tomli - repo: https://github.com/tox-dev/pyproject-fmt - rev: "2.2.4" + rev: v2.30.3 hooks: - id: pyproject-fmt + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.17.3 + hooks: + - id: ruff-check + - id: ruff-format + + - repo: https://github.com/rvben/rumdl-pre-commit + rev: v0.3.2 + hooks: + - id: rumdl-fmt + - id: rumdl + args: [--fix] + - repo: local hooks: - id: validate-filenames @@ -41,24 +54,18 @@ repos: language: script pass_filenames: false - - repo: https://github.com/abravalheri/validate-pyproject - rev: v0.19 + - repo: https://github.com/astral-sh/uv-pre-commit + rev: 0.13.6 hooks: - - id: validate-pyproject + - id: uv-lock - - repo: https://github.com/pre-commit/mirrors-mypy - rev: v1.11.2 + - repo: https://github.com/abravalheri/validate-pyproject + rev: "v0.27" hooks: - - id: mypy - args: - - --explicit-package-bases - - --ignore-missing-imports - - --install-types # See mirrors-mypy README.md - - --non-interactive - additional_dependencies: [types-requests] + - id: validate-pyproject - - repo: https://github.com/pre-commit/mirrors-prettier - rev: "v4.0.0-alpha.8" + - repo: https://github.com/15r10nk/matchify + rev: v0.3.0 hooks: - - id: prettier - types_or: [toml, yaml] + - id: matchify + exclude: ^data_structures/linked_list/doubly_linked_list\.py$ diff --git a/.python-version b/.python-version new file mode 100644 index 000000000000..d5629d4841ea --- /dev/null +++ b/.python-version @@ -0,0 +1 @@ +3.15t diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index ef16fa1aa7ac..000000000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "githubPullRequests.ignoredPullRequestBranches": [ - "master" - ] -} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000000..1846b12d0efd --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,62 @@ +# AGENTS.md + +Guidance for AI coding agents (and their humans) contributing to +**TheAlgorithms/Python**. This complements — and never overrides — +[`CONTRIBUTING.md`](CONTRIBUTING.md). Read that first. + +This repository is educational: implementations should be clear and correct +rather than maximally optimized. Every change goes through CI and the +`algorithms-keeper` bot, both of which reject non-conforming PRs automatically. + +## Before opening a pull request + +- **Check at least one box in the PR description.** The `algorithms-keeper` + bot **closes any PR whose "Describe your change" section has no checked + box** (`* [x]`). Fill in the template that ships in + `.github/pull_request_template.md` and tick every item that applies before + you submit — this is the single most common reason automated PRs get closed. +- **One algorithm file per PR.** Split unrelated changes into separate PRs to + keep review focused. +- **Don't change code and its doctests in the same PR.** If you're only + updating tests, say so and touch nothing else. + +## Code conventions (enforced by CI) + +- **Formatting & linting:** `ruff` (`uvx ruff check .` and `uvx ruff format .`). + Run `uvx pre-commit run --all-files` locally to catch everything CI will. +- **Type hints:** annotate every function parameter and return value with + [type hints](https://docs.python.org/3/library/typing.html). +- **Doctests:** every function needs at least one + [doctest](https://docs.python.org/3/library/doctest.html) that passes under + `python -m doctest -v your_file.py` (and `pytest`). +- **Naming:** filenames are all-lowercase with underscores (no spaces or + dashes); functions and variables follow standard Python naming. +- **Placement:** new files go inside an existing directory. +- **References:** new algorithms include a URL to Wikipedia or a comparable + explanation. + +## Running the suite locally + +This project is managed with [`uv`](https://docs.astral.sh/uv/) — there is no +`requirements.txt`. Dependencies live in `pyproject.toml`/`uv.lock`, and `uvx` +runs a tool in a throwaway environment without polluting yours: + +```bash +uvx pre-commit run --all-files # ruff, formatting, hooks +uvx pytest your_module/your_file.py --doctest-modules +``` + +(`uv run pytest ...` works too if you'd rather use the project's locked +environment.) + +Some directories are intentionally skipped in CI (`--ignore` entries in +`.github/workflows/build.yml`), usually because a heavy dependency lacks a +wheel for the CPython version the repo currently targets. Check that list +before assuming a file is untested. + +## Good agent behavior + +- Keep diffs minimal and scoped to the stated change. +- Preserve existing style and structure; prefer clarity over cleverness. +- Never fabricate doctest output — run it and paste the real result. +- If CI is red, read the log and fix the cause rather than re-running blindly. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 096582e45afa..2c66950b8a7c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,8 @@ -# Contributing guidelines +# Contributing Guidelines -## Before contributing +## Before Contributing -Welcome to [TheAlgorithms/Python](https://github.com/TheAlgorithms/Python)! Before submitting your pull requests, please ensure that you __read the whole guidelines__. If you have any doubts about the contributing guide, please feel free to [state it clearly in an issue](https://github.com/TheAlgorithms/Python/issues/new) or ask the community on [Gitter](https://gitter.im/TheAlgorithms/community). +Welcome to [TheAlgorithms/Python](https://github.com/TheAlgorithms/Python)! Before submitting your pull requests, please ensure that you __read the entire guidelines__. If you have any doubts about the contributing guide, please feel free to [state them clearly in an issue](https://github.com/TheAlgorithms/Python/issues/new) or ask the community on [Gitter](https://gitter.im/TheAlgorithms/community). ## Contributing @@ -10,64 +10,87 @@ Welcome to [TheAlgorithms/Python](https://github.com/TheAlgorithms/Python)! Befo We are delighted that you are considering implementing algorithms and data structures for others! This repository is referenced and used by learners from all over the globe. By being one of our contributors, you agree and confirm that: -- You did your work - no plagiarism allowed. +- You did your work — no plagiarism allowed. - Any plagiarized work will not be merged. -- Your work will be distributed under [MIT License](LICENSE.md) once your pull request is merged. +- Your work will be distributed under the [MIT License](LICENSE.md) once your pull request is merged. - Your submitted work fulfills or mostly fulfills our styles and standards. -__New implementation__ is welcome! For example, new solutions for a problem, different representations for a graph data structure or algorithm designs with different complexity, but __identical implementation__ of an existing implementation is not allowed. Please check whether the solution is already implemented or not before submitting your pull request. +__New implementations__ are welcome! For example, new solutions for a problem, different representations for a graph data structure, or algorithm designs with different complexities. However, __identical implementations__ of an existing one are not allowed. Please check whether the solution is already implemented before submitting your pull request. __Improving comments__ and __writing proper tests__ are also highly welcome. ### Contribution -We appreciate any contribution, from fixing a grammar mistake in a comment to implementing complex algorithms. Please read this section if you are contributing your work. +We appreciate any contribution — from fixing a grammar mistake in a comment to implementing complex algorithms. Please read this section if you are contributing your work. -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 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. +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 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. #### Issues -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. +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. __Do not__ create an issue to contribute an algorithm. Please submit a pull request instead. 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: -``` + +```text 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? -An Algorithm is one or more functions (or classes) that: -* take one or more inputs, -* perform some internal calculations or data manipulations, -* return one or more outputs, -* have minimal side effects (Ex. `print()`, `plot()`, `read()`, `write()`). +An algorithm is one or more functions (or classes) that: + +- take one or more inputs, +- perform some internal calculations or data manipulations, +- return one or more outputs, +- have minimal side effects (e.g., `print()`, `plot()`, `read()`, `write()`). -Algorithms should be packaged in a way that would make it easy for readers to put them into larger programs. +Algorithms should be packaged in a way that would make it easy for readers to integrate them into larger programs. Algorithms should: -* have intuitive class and function names that make their purpose clear to readers -* use Python naming conventions and intuitive variable names to ease comprehension -* be flexible to take different input values -* have Python type hints for their input parameters and return values -* raise Python exceptions (`ValueError`, etc.) on erroneous input values -* have docstrings with clear explanations and/or URLs to source materials -* contain doctests that test both valid and erroneous input values -* return all calculation results instead of printing or plotting them - -Algorithms in this repo should not be how-to examples for existing Python packages. Instead, they should perform internal calculations or manipulations to convert input values into different output values. Those calculations or manipulations can use data types, classes, or functions of existing Python packages but each algorithm in this repo should add unique value. - -#### Pre-commit plugin + +- have intuitive class and function names that make their purpose clear to readers, +- use Python naming conventions and intuitive variable names to ease comprehension, +- be flexible to take different input values, +- have Python type hints for their input parameters and return values, +- raise Python exceptions (`ValueError`, etc.) on erroneous input values, +- have docstrings with clear explanations and/or URLs to source materials, +- contain doctests that test both valid and erroneous input values, +- return all calculation results instead of printing or plotting them. + +Algorithms in this repo should not be simple how-to examples for existing Python packages. Instead, they should perform internal calculations or manipulations to convert input values into different output values. +These calculations or manipulations can use data types, classes, or functions of existing Python packages, but each algorithm in this repo should add unique value. + +#### Pre-Commit Plugin + +- have intuitive class and function names that make their purpose clear to readers +- use Python naming conventions and intuitive variable names to ease comprehension +- be flexible to take different input values +- have Python type hints for their input parameters and return values +- raise Python exceptions (`ValueError`, etc.) on erroneous input values +- have docstrings with clear explanations and/or URLs to source materials +- contain doctests that test both valid and erroneous input values +- return all calculation results instead of printing or plotting them + +Algorithms in this repo should not be how-to examples for existing Python packages. Instead, they should perform internal calculations or manipulations to convert input values into different output values. +Those calculations or manipulations can use data types, classes, or functions of existing Python packages, but each algorithm in this repo should add unique value. + +#### Pre-commit + Use [pre-commit](https://pre-commit.com/#installation) to automatically format your code to match our coding style: ```bash python3 -m pip install pre-commit # only required the first time pre-commit install ``` -That's it! The plugin will run every time you commit any changes. If there are any errors found during the run, fix them and commit those changes. You can even run the plugin manually on all files: + +That's it! Pre-commit will run every time you commit any changes. If any errors are found during the run, fix them and commit those changes. You can even run the plugin manually on all files: ```bash pre-commit run --all-files --show-diff-on-failure @@ -77,43 +100,45 @@ pre-commit run --all-files --show-diff-on-failure We want your work to be readable by others; therefore, we encourage you to note the following: -- Please write in Python 3.12+. For instance: `print()` is a function in Python 3 so `print "Hello"` will *not* work but `print("Hello")` will. -- Please focus hard on the naming of functions, classes, and variables. Help your reader by using __descriptive names__ that can help you to remove redundant comments. - - Single letter variable names are *old school* so please avoid them unless their life only spans a few lines. +- Please write in free-threaded Python 3.15t+. For instance: `print()` is a function in Python 3, so `print "Hello"` will *not* work, but `print("Hello")` will. + +- Please focus hard on the naming of functions, classes, and variables. Help your reader by using __descriptive names__ that can help you to remove redundant comments. + - Single-letter variable names are *old school*, so please avoid them unless their life only spans a few lines. - Expand acronyms because `gcd()` is hard to understand but `greatest_common_divisor()` is not. - Please follow the [Python Naming Conventions](https://pep8.org/#prescriptive-naming-conventions) so variable_names and function_names should be lower_case, CONSTANTS in UPPERCASE, ClassNames should be CamelCase, etc. - We encourage the use of Python [f-strings](https://realpython.com/python-f-strings/#f-strings-a-new-and-improved-way-to-format-strings-in-python) where they make the code easier to read. -- Please consider running [__psf/black__](https://github.com/python/black) on your Python file(s) before submitting your pull request. This is not yet a requirement but it does make your code more readable and automatically aligns it with much of [PEP 8](https://www.python.org/dev/peps/pep-0008/). There are other code formatters (autopep8, yapf) but the __black__ formatter is now hosted by the Python Software Foundation. To use it, +- Please consider running [__ruff format__](https://docs.astral.sh/ruff/formatter/) on your Python file(s) before submitting your pull request. This is not yet a requirement, but it does make your code more readable and automatically aligns it with much of [PEP 8](https://peps.python.org/pep-0008/). To use it, ```bash - python3 -m pip install black # only required the first time - black . + python3 -m pip install ruff # only required the first time + ruff format ``` -- All submissions will need to pass the test `ruff .` before they will be accepted so if possible, try this test locally on your Python file(s) before submitting your pull request. +- All submissions will need to pass the test `ruff check` before they will be accepted, so if possible, try this test locally on your Python file(s) before submitting your pull request. ```bash python3 -m pip install ruff # only required the first time - ruff . + ruff check ``` -- Original code submission require docstrings or comments to describe your work. +- Original code submissions require docstrings or comments to describe your work. - More on docstrings and comments: - If you used a Wikipedia article or some other source material to create your algorithm, please add the URL in a docstring or comment to help your reader. + If you used a Wikipedia article or other source material to create your algorithm, please add the URL in a docstring or comment to help your reader. The following are considered to be bad and may be requested to be improved: ```python - x = x + 2 # increased by 2 + x += 2 # increased by 2 ``` - This is too trivial. Comments are expected to be explanatory. For comments, you can write them above, on or below a line of code, as long as you are consistent within the same piece of code. + This is too trivial. Comments should not merely repeat what the code already says. Comments should explain ___why___ we are doing things. Comments on the same line as code should never cause the line to wrap (> 88 characters per line). +Comments which are not on the same line as code should appear ___before___ the code they describe. "First tell the reader ___why___ with comments and then show them ___how___ with code." - We encourage you to put docstrings inside your functions but please pay attention to the indentation of docstrings. The following is a good example: + We require you to put docstrings inside your functions, but please pay attention to the indentation of docstrings. The following is a good example: ```python def sum_ab(a, b): @@ -123,7 +148,7 @@ We want your work to be readable by others; therefore, we encourage you to note return a + b ``` -- Write tests (especially [__doctests__](https://docs.python.org/3/library/doctest.html)) to illustrate and verify your work. We highly encourage the use of _doctests on all functions_. +- Write tests (especially [__doctests__](https://docs.python.org/3/library/doctest.html)) to illustrate and verify your work. We highly encourage the use of *doctests on all functions*. ```python def sum_ab(a, b): @@ -139,7 +164,7 @@ We want your work to be readable by others; therefore, we encourage you to note return a + b ``` - These doctests will be run by pytest as part of our automated testing so please try to run your doctests locally and make sure that they are found and pass: + These doctests will be run by pytest as part of our automated testing, so please try to run your doctests locally and make sure that they are found and pass: ```bash python3 -m doctest -v my_submission.py @@ -148,7 +173,7 @@ We want your work to be readable by others; therefore, we encourage you to note The use of the Python built-in `input()` function is __not__ encouraged: ```python - input('Enter your input:') + input("Enter your input:") # Or even worse... input = eval(input("Enter your input: ")) ``` @@ -159,32 +184,38 @@ We want your work to be readable by others; therefore, we encourage you to note starting_value = int(input("Please enter a starting value: ").strip()) ``` - The use of [Python type hints](https://docs.python.org/3/library/typing.html) is encouraged for function parameters and return values. Our automated testing will run [mypy](http://mypy-lang.org) so run that locally before making your submission. + The use of [Python type hints](https://docs.python.org/3/library/typing.html) is encouraged for function parameters and return values. Our CI runs [ty](https://docs.astral.sh/ty/) as an informational check that does not block merges yet, so you may want to run it locally before making your submission. + + ```bash + python3 -m pip install ty # only required the first time + ty check my_file_path.py + ``` ```python def sum_ab(a: int, b: int) -> int: return a + b ``` - Instructions on how to install mypy can be found [here](https://github.com/python/mypy). Please use the command `mypy --ignore-missing-imports .` to test all files or `mypy --ignore-missing-imports path/to/file.py` to test a specific file. + [Install ty](https://docs.astral.sh/ty/installation/) and then please use the command `ty check` to test all files or `ty check path/to/file.py` to test a specific file. - [__List comprehensions and generators__](https://docs.python.org/3/tutorial/datastructures.html#list-comprehensions) are preferred over the use of `lambda`, `map`, `filter`, `reduce` but the important thing is to demonstrate the power of Python in code that is easy to read and maintain. - Avoid importing external libraries for basic algorithms. Only use those libraries for complicated algorithms. -- If you need a third-party module that is not in the file __requirements.txt__, please add it to that file as part of your submission. + +- If you need a third-party module that is not already listed in __pyproject.toml__, please add it to the `dependencies` there as part of your submission. The `uv-lock` pre-commit hook will update `uv.lock` to match. #### Other Requirements for Submissions + - If you are submitting code in the `project_euler/` directory, please also read [the dedicated Guideline](https://github.com/TheAlgorithms/Python/blob/master/project_euler/README.md) before contributing to our Project Euler library. - The file extension for code files should be `.py`. Jupyter Notebooks should be submitted to [TheAlgorithms/Jupyter](https://github.com/TheAlgorithms/Jupyter). -- Strictly use snake_case (underscore_separated) in your file_name, as it will be easy to parse in future using scripts. +- Strictly use snake_case (underscore_separated) in your file_name, as it will be easy to parse in the future using scripts. - Please avoid creating new directories if at all possible. Try to fit your work into the existing directory structure. - If possible, follow the standard *within* the folder you are submitting to. -- If you have modified/added code work, make sure the code compiles before submitting. +- If you have modified/added code, make sure the code compiles before submitting. - If you have modified/added documentation work, ensure your language is concise and contains no grammar errors. -- Do not update the README.md or DIRECTORY.md file which will be periodically autogenerated by our GitHub Actions processes. +- Do not update the README.md or DIRECTORY.md file, which will be periodically autogenerated by our GitHub Actions processes. - Add a corresponding explanation to [Algorithms-Explanation](https://github.com/TheAlgorithms/Algorithms-Explanation) (Optional but recommended). -- All submissions will be tested with [__mypy__](http://www.mypy-lang.org) so we encourage you to add [__Python type hints__](https://docs.python.org/3/library/typing.html) where it makes sense to do so. - +- Our CI runs [__ty__](https://docs.astral.sh/ty/) on every pull request as an informational check that does not block merges yet, so we encourage you to add [__Python type hints__](https://docs.python.org/3/library/typing.html) where `ty` recommends to do so. - Most importantly, - __Be consistent in the use of these guidelines when submitting.__ - __Join__ us on [Discord](https://discord.com/invite/c7MnfGFGa6) and [Gitter](https://gitter.im/TheAlgorithms/community) __now!__ diff --git a/DIRECTORY.md b/DIRECTORY.md index 955001e2aa23..52b15110f236 100644 --- a/DIRECTORY.md +++ b/DIRECTORY.md @@ -1,10 +1,57 @@ +## Table of Contents +1. [Audio Filters](#audio-filters) +2. [Backtracking](#backtracking) +3. [Bit Manipulation](#bit-manipulation) +4. [Blockchain](#blockchain) +5. [Boolean Algebra](#boolean-algebra) +6. [Cellular Automata](#cellular-automata) +7. [Ciphers](#ciphers) +8. [Computer Vision](#computer-vision) +9. [Conversions](#conversions) +10. [Data Compression](#data-compression) +11. [Data Structures](#data-structures) +12. [Digital Image Processing](#digital-image-processing) +13. [Divide And Conquer](#divide-and-conquer) +14. [Docs](#docs) +15. [Dynamic Programming](#dynamic-programming) +16. [Electronics](#electronics) +17. [File Transfer](#file-transfer) +18. [Financial](#financial) +19. [Fractals](#fractals) +20. [Fuzzy Logic](#fuzzy-logic) +21. [Genetic Algorithm](#genetic-algorithm) +22. [Geodesy](#geodesy) +23. [Geometry](#geometry) +24. [Graphics](#graphics) +25. [Graphs](#graphs) +26. [Greedy Methods](#greedy-methods) +27. [Hashes](#hashes) +28. [Knapsack](#knapsack) +29. [Linear Algebra](#linear-algebra) +30. [Linear Programming](#linear-programming) +31. [Machine Learning](#machine-learning) +32. [Maths](#maths) +33. [Matrix](#matrix) +34. [Networking Flow](#networking-flow) +35. [Neural Network](#neural-network) +36. [Other](#other) +37. [Physics](#physics) +38. [Project Euler](#project-euler) +39. [Quantum](#quantum) +40. [Scheduling](#scheduling) +41. [Searches](#searches) +42. [Sorts](#sorts) +43. [Strings](#strings) +44. [Tests](#tests) +45. [Web Programming](#web-programming) -## Audio Filters +## [Audio Filters](audio_filters) * [Butterworth Filter](audio_filters/butterworth_filter.py) + * [Equal Loudness Filter](audio_filters/equal_loudness_filter.py) * [Iir Filter](audio_filters/iir_filter.py) * [Show Response](audio_filters/show_response.py) -## Backtracking +## [Backtracking](backtracking) * [All Combinations](backtracking/all_combinations.py) * [All Permutations](backtracking/all_permutations.py) * [All Subsequences](backtracking/all_subsequences.py) @@ -12,8 +59,10 @@ * [Combination Sum](backtracking/combination_sum.py) * [Crossword Puzzle Solver](backtracking/crossword_puzzle_solver.py) * [Generate Parentheses](backtracking/generate_parentheses.py) + * [Generate Parentheses Iterative](backtracking/generate_parentheses_iterative.py) * [Hamiltonian Cycle](backtracking/hamiltonian_cycle.py) * [Knight Tour](backtracking/knight_tour.py) + * [M Coloring Problem](backtracking/m_coloring_problem.py) * [Match Word Pattern](backtracking/match_word_pattern.py) * [Minimax](backtracking/minimax.py) * [N Queens](backtracking/n_queens.py) @@ -22,9 +71,11 @@ * [Rat In Maze](backtracking/rat_in_maze.py) * [Sudoku](backtracking/sudoku.py) * [Sum Of Subsets](backtracking/sum_of_subsets.py) + * [Word Break](backtracking/word_break.py) + * [Word Ladder](backtracking/word_ladder.py) * [Word Search](backtracking/word_search.py) -## Bit Manipulation +## [Bit Manipulation](bit_manipulation) * [Binary And Operator](bit_manipulation/binary_and_operator.py) * [Binary Coded Decimal](bit_manipulation/binary_coded_decimal.py) * [Binary Count Setbits](bit_manipulation/binary_count_setbits.py) @@ -37,7 +88,9 @@ * [Count 1S Brian Kernighan Method](bit_manipulation/count_1s_brian_kernighan_method.py) * [Count Number Of One Bits](bit_manipulation/count_number_of_one_bits.py) * [Excess 3 Code](bit_manipulation/excess_3_code.py) + * [Fast Walsh Hadamard Transform](bit_manipulation/fast_walsh_hadamard_transform.py) * [Find Previous Power Of Two](bit_manipulation/find_previous_power_of_two.py) + * [Find Unique Number](bit_manipulation/find_unique_number.py) * [Gray Code Sequence](bit_manipulation/gray_code_sequence.py) * [Highest Set Bit](bit_manipulation/highest_set_bit.py) * [Index Of Rightmost Set Bit](bit_manipulation/index_of_rightmost_set_bit.py) @@ -45,16 +98,25 @@ * [Is Power Of Two](bit_manipulation/is_power_of_two.py) * [Largest Pow Of Two Le Num](bit_manipulation/largest_pow_of_two_le_num.py) * [Missing Number](bit_manipulation/missing_number.py) + * [Next Power Of Two](bit_manipulation/next_power_of_two.py) * [Numbers Different Signs](bit_manipulation/numbers_different_signs.py) + * [Parity](bit_manipulation/parity.py) * [Power Of 4](bit_manipulation/power_of_4.py) * [Reverse Bits](bit_manipulation/reverse_bits.py) + * [Rotate Bits](bit_manipulation/rotate_bits.py) * [Single Bit Manipulation Operations](bit_manipulation/single_bit_manipulation_operations.py) * [Swap All Odd And Even Bits](bit_manipulation/swap_all_odd_and_even_bits.py) + * [Xor Swap Two Integers](bit_manipulation/xor_swap_two_integers.py) -## Blockchain +## [Blockchain](blockchain) * [Diophantine Equation](blockchain/diophantine_equation.py) + * [Merkle Tree](blockchain/merkle_tree.py) + * [Proof Of Stake](blockchain/proof_of_stake.py) + * [Proof Of Work](blockchain/proof_of_work.py) + * [Simple Blockchain](blockchain/simple_blockchain.py) + * [Simple Proof Of Work](blockchain/simple_proof_of_work.py) -## Boolean Algebra +## [Boolean Algebra](boolean_algebra) * [And Gate](boolean_algebra/and_gate.py) * [Imply Gate](boolean_algebra/imply_gate.py) * [Karnaugh Map Simplification](boolean_algebra/karnaugh_map_simplification.py) @@ -68,15 +130,16 @@ * [Xnor Gate](boolean_algebra/xnor_gate.py) * [Xor Gate](boolean_algebra/xor_gate.py) -## Cellular Automata +## [Cellular Automata](cellular_automata) * [Conways Game Of Life](cellular_automata/conways_game_of_life.py) + * [Elementary Cellular Automaton](cellular_automata/elementary_cellular_automaton.py) * [Game Of Life](cellular_automata/game_of_life.py) * [Langtons Ant](cellular_automata/langtons_ant.py) * [Nagel Schrekenberg](cellular_automata/nagel_schrekenberg.py) * [One Dimensional](cellular_automata/one_dimensional.py) * [Wa Tor](cellular_automata/wa_tor.py) -## Ciphers +## [Ciphers](ciphers) * [A1Z26](ciphers/a1z26.py) * [Affine Cipher](ciphers/affine_cipher.py) * [Atbash](ciphers/atbash.py) @@ -84,20 +147,24 @@ * [Baconian Cipher](ciphers/baconian_cipher.py) * [Base16](ciphers/base16.py) * [Base32](ciphers/base32.py) - * [Base64](ciphers/base64.py) + * [Base58](ciphers/base58.py) + * [Base64 Cipher](ciphers/base64_cipher.py) * [Base85](ciphers/base85.py) * [Beaufort Cipher](ciphers/beaufort_cipher.py) * [Bifid](ciphers/bifid.py) * [Brute Force Caesar Cipher](ciphers/brute_force_caesar_cipher.py) * [Caesar Cipher](ciphers/caesar_cipher.py) + * [Columnar Transposition](ciphers/columnar_transposition.py) * [Cryptomath Module](ciphers/cryptomath_module.py) * [Decrypt Caesar With Chi Squared](ciphers/decrypt_caesar_with_chi_squared.py) + * [Des Ecb](ciphers/des_ecb.py) * [Deterministic Miller Rabin](ciphers/deterministic_miller_rabin.py) * [Diffie](ciphers/diffie.py) * [Diffie Hellman](ciphers/diffie_hellman.py) * [Elgamal Key Generator](ciphers/elgamal_key_generator.py) * [Enigma Machine2](ciphers/enigma_machine2.py) * [Fractionated Morse Cipher](ciphers/fractionated_morse_cipher.py) + * [Gronsfeld Cipher](ciphers/gronsfeld_cipher.py) * [Hill Cipher](ciphers/hill_cipher.py) * [Mixed Keyword Cypher](ciphers/mixed_keyword_cypher.py) * [Mono Alphabetic Ciphers](ciphers/mono_alphabetic_ciphers.py) @@ -109,6 +176,7 @@ * [Porta Cipher](ciphers/porta_cipher.py) * [Rabin Miller](ciphers/rabin_miller.py) * [Rail Fence Cipher](ciphers/rail_fence_cipher.py) + * [Rc4](ciphers/rc4.py) * [Rot13](ciphers/rot13.py) * [Rsa Cipher](ciphers/rsa_cipher.py) * [Rsa Factorization](ciphers/rsa_factorization.py) @@ -117,35 +185,36 @@ * [Shuffled Shift Cipher](ciphers/shuffled_shift_cipher.py) * [Simple Keyword Cypher](ciphers/simple_keyword_cypher.py) * [Simple Substitution Cipher](ciphers/simple_substitution_cipher.py) + * [Skytale Cipher](ciphers/skytale_cipher.py) * [Transposition Cipher](ciphers/transposition_cipher.py) * [Transposition Cipher Encrypt Decrypt File](ciphers/transposition_cipher_encrypt_decrypt_file.py) * [Trifid Cipher](ciphers/trifid_cipher.py) * [Vernam Cipher](ciphers/vernam_cipher.py) * [Vigenere Cipher](ciphers/vigenere_cipher.py) * [Xor Cipher](ciphers/xor_cipher.py) + * [Xtea](ciphers/xtea.py) -## Compression - * [Burrows Wheeler](compression/burrows_wheeler.py) - * [Huffman](compression/huffman.py) - * [Lempel Ziv](compression/lempel_ziv.py) - * [Lempel Ziv Decompress](compression/lempel_ziv_decompress.py) - * [Lz77](compression/lz77.py) - * [Peak Signal To Noise Ratio](compression/peak_signal_to_noise_ratio.py) - * [Run Length Encoding](compression/run_length_encoding.py) - -## Computer Vision - * [Cnn Classification](computer_vision/cnn_classification.py) +## [Computer Vision](computer_vision) * [Flip Augmentation](computer_vision/flip_augmentation.py) + * [Gramian](computer_vision/gramian.py) * [Haralick Descriptors](computer_vision/haralick_descriptors.py) * [Harris Corner](computer_vision/harris_corner.py) * [Horn Schunck](computer_vision/horn_schunck.py) + * [Intensity Based Segmentation](computer_vision/intensity_based_segmentation.py) * [Mean Threshold](computer_vision/mean_threshold.py) * [Mosaic Augmentation](computer_vision/mosaic_augmentation.py) + * [Otsu Threshold](computer_vision/otsu_threshold.py) * [Pooling Functions](computer_vision/pooling_functions.py) + * [Vision Transformer](computer_vision/vision_transformer.py) -## Conversions +## [Conversions](conversions) * [Astronomical Length Scale Conversion](conversions/astronomical_length_scale_conversion.py) + * [Base64 To Binary](conversions/base64_to_binary.py) + * [Binary To Base64](conversions/binary_to_base64.py) * [Binary To Decimal](conversions/binary_to_decimal.py) + * [Binary To Excess3](conversions/binary_to_excess3.py) + * [Binary To Gray](conversions/binary_to_gray.py) + * [Binary To Gray Code](conversions/binary_to_gray_code.py) * [Binary To Hexadecimal](conversions/binary_to_hexadecimal.py) * [Binary To Octal](conversions/binary_to_octal.py) * [Convert Number To Words](conversions/convert_number_to_words.py) @@ -153,19 +222,24 @@ * [Decimal To Binary](conversions/decimal_to_binary.py) * [Decimal To Hexadecimal](conversions/decimal_to_hexadecimal.py) * [Decimal To Octal](conversions/decimal_to_octal.py) + * [Endianness](conversions/endianness.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) + * [Hex To Rgb](conversions/hex_to_rgb.py) * [Hexadecimal To Decimal](conversions/hexadecimal_to_decimal.py) + * [Int To Negative Binary Base](conversions/int_to_negative_binary_base.py) * [Ipv4 Conversion](conversions/ipv4_conversion.py) * [Length Conversion](conversions/length_conversion.py) * [Molecular Chemistry](conversions/molecular_chemistry.py) + * [Negative Binary Base To Int](conversions/negative_binary_base_to_int.py) * [Octal To Binary](conversions/octal_to_binary.py) * [Octal To Decimal](conversions/octal_to_decimal.py) * [Octal To Hexadecimal](conversions/octal_to_hexadecimal.py) * [Prefix Conversions](conversions/prefix_conversions.py) * [Prefix Conversions String](conversions/prefix_conversions_string.py) * [Pressure Conversions](conversions/pressure_conversions.py) + * [Rectangular To Polar](conversions/rectangular_to_polar.py) * [Rgb Cmyk Conversion](conversions/rgb_cmyk_conversion.py) * [Rgb Hsv Conversion](conversions/rgb_hsv_conversion.py) * [Roman Numerals](conversions/roman_numerals.py) @@ -175,18 +249,37 @@ * [Volume Conversions](conversions/volume_conversions.py) * [Weight Conversion](conversions/weight_conversion.py) -## Data Structures +## [Data Compression](data_compression) + * [Burrows Wheeler](data_compression/burrows_wheeler.py) + * [Coordinate Compression](data_compression/coordinate_compression.py) + * [Huffman](data_compression/huffman.py) + * [Lempel Ziv](data_compression/lempel_ziv.py) + * [Lempel Ziv Decompress](data_compression/lempel_ziv_decompress.py) + * [Lz77](data_compression/lz77.py) + * [Move To Front](data_compression/move_to_front.py) + * [Peak Signal To Noise Ratio](data_compression/peak_signal_to_noise_ratio.py) + * [Run Length Encoding](data_compression/run_length_encoding.py) + +## [Data Structures](data_structures) * Arrays + * [Dynamic Array](data_structures/arrays/dynamic_array.py) * [Equilibrium Index In Array](data_structures/arrays/equilibrium_index_in_array.py) * [Find Triplets With 0 Sum](data_structures/arrays/find_triplets_with_0_sum.py) + * [Gas Station](data_structures/arrays/gas_station.py) * [Index 2D Array In 1D](data_structures/arrays/index_2d_array_in_1d.py) * [Kth Largest Element](data_structures/arrays/kth_largest_element.py) * [Median Two Array](data_structures/arrays/median_two_array.py) + * [Merge Intervals](data_structures/arrays/merge_intervals.py) + * [Merge Sorted](data_structures/arrays/merge_sorted.py) * [Monotonic Array](data_structures/arrays/monotonic_array.py) * [Pairs With Given Sum](data_structures/arrays/pairs_with_given_sum.py) + * [Pairwise Iteration](data_structures/arrays/pairwise_iteration.py) * [Permutations](data_structures/arrays/permutations.py) * [Prefix Sum](data_structures/arrays/prefix_sum.py) * [Product Sum](data_structures/arrays/product_sum.py) + * [Reverse Array](data_structures/arrays/reverse_array.py) + * [Rotate Array](data_structures/arrays/rotate_array.py) + * [Set Matrix Zeroes](data_structures/arrays/set_matrix_zeroes.py) * [Sparse Table](data_structures/arrays/sparse_table.py) * [Sudoku Solver](data_structures/arrays/sudoku_solver.py) * Binary Tree @@ -194,6 +287,7 @@ * [Basic Binary Tree](data_structures/binary_tree/basic_binary_tree.py) * [Binary Search Tree](data_structures/binary_tree/binary_search_tree.py) * [Binary Search Tree Recursive](data_structures/binary_tree/binary_search_tree_recursive.py) + * [Binary Tree Maximum Path Sum](data_structures/binary_tree/binary_tree_maximum_path_sum.py) * [Binary Tree Mirror](data_structures/binary_tree/binary_tree_mirror.py) * [Binary Tree Node Sum](data_structures/binary_tree/binary_tree_node_sum.py) * [Binary Tree Path Sum](data_structures/binary_tree/binary_tree_path_sum.py) @@ -210,14 +304,17 @@ * [Lazy Segment Tree](data_structures/binary_tree/lazy_segment_tree.py) * [Lowest Common Ancestor](data_structures/binary_tree/lowest_common_ancestor.py) * [Maximum Fenwick Tree](data_structures/binary_tree/maximum_fenwick_tree.py) + * [Maximum Sum Bst](data_structures/binary_tree/maximum_sum_bst.py) * [Merge Two Binary Trees](data_structures/binary_tree/merge_two_binary_trees.py) * [Mirror Binary Tree](data_structures/binary_tree/mirror_binary_tree.py) * [Non Recursive Segment Tree](data_structures/binary_tree/non_recursive_segment_tree.py) * [Number Of Possible Binary Trees](data_structures/binary_tree/number_of_possible_binary_trees.py) + * [Persistent Segment Tree](data_structures/binary_tree/persistent_segment_tree.py) * [Red Black Tree](data_structures/binary_tree/red_black_tree.py) * [Segment Tree](data_structures/binary_tree/segment_tree.py) * [Segment Tree Other](data_structures/binary_tree/segment_tree_other.py) * [Serialize Deserialize Binary Tree](data_structures/binary_tree/serialize_deserialize_binary_tree.py) + * [Splay Tree](data_structures/binary_tree/splay_tree.py) * [Symmetric Tree](data_structures/binary_tree/symmetric_tree.py) * [Treap](data_structures/binary_tree/treap.py) * [Wavelet Tree](data_structures/binary_tree/wavelet_tree.py) @@ -261,32 +358,44 @@ * [From Sequence](data_structures/linked_list/from_sequence.py) * [Has Loop](data_structures/linked_list/has_loop.py) * [Is Palindrome](data_structures/linked_list/is_palindrome.py) + * [Kth Element From End](data_structures/linked_list/kth_element_from_end.py) + * [Merge Sort Linked List](data_structures/linked_list/merge_sort_linked_list.py) * [Merge Two Lists](data_structures/linked_list/merge_two_lists.py) * [Middle Element Of Linked List](data_structures/linked_list/middle_element_of_linked_list.py) + * [Partition Linked List](data_structures/linked_list/partition_linked_list.py) * [Print Reverse](data_structures/linked_list/print_reverse.py) + * [Remove Nth Node From End Of List](data_structures/linked_list/remove_nth_node_from_end_of_list.py) * [Reverse K Group](data_structures/linked_list/reverse_k_group.py) * [Rotate To The Right](data_structures/linked_list/rotate_to_the_right.py) * [Singly Linked List](data_structures/linked_list/singly_linked_list.py) * [Skip List](data_structures/linked_list/skip_list.py) + * [Sorted Linked List](data_structures/linked_list/sorted_linked_list.py) * [Swap Nodes](data_structures/linked_list/swap_nodes.py) - * Queue - * [Circular Queue](data_structures/queue/circular_queue.py) - * [Circular Queue Linked List](data_structures/queue/circular_queue_linked_list.py) - * [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 Pseudo Stack](data_structures/queue/queue_on_pseudo_stack.py) + * [Xor Linked List](data_structures/linked_list/xor_linked_list.py) + * Queues + * [Circular Queue](data_structures/queues/circular_queue.py) + * [Circular Queue Linked List](data_structures/queues/circular_queue_linked_list.py) + * [Double Ended Queue](data_structures/queues/double_ended_queue.py) + * [Linked Queue](data_structures/queues/linked_queue.py) + * [Monotonic Queue](data_structures/queues/monotonic_queue.py) + * [Priority Queue Using List](data_structures/queues/priority_queue_using_list.py) + * [Queue By List](data_structures/queues/queue_by_list.py) + * [Queue By Two Stacks](data_structures/queues/queue_by_two_stacks.py) + * [Queue On Pseudo Stack](data_structures/queues/queue_on_pseudo_stack.py) * Stacks * [Balanced Parentheses](data_structures/stacks/balanced_parentheses.py) * [Dijkstras Two Stack Algorithm](data_structures/stacks/dijkstras_two_stack_algorithm.py) * [Infix To Postfix Conversion](data_structures/stacks/infix_to_postfix_conversion.py) * [Infix To Prefix Conversion](data_structures/stacks/infix_to_prefix_conversion.py) + * [Kth Next Greater Element](data_structures/stacks/kth_next_greater_element.py) + * [Largest Rectangle Histogram](data_structures/stacks/largest_rectangle_histogram.py) + * [Lexicographical Numbers](data_structures/stacks/lexicographical_numbers.py) * [Next Greater Element](data_structures/stacks/next_greater_element.py) * [Postfix Evaluation](data_structures/stacks/postfix_evaluation.py) + * [Postfix To Infix Conversion](data_structures/stacks/postfix_to_infix_conversion.py) * [Prefix Evaluation](data_structures/stacks/prefix_evaluation.py) * [Stack](data_structures/stacks/stack.py) + * [Stack Tracking Min Max](data_structures/stacks/stack_tracking_min_max.py) * [Stack Using Two Queues](data_structures/stacks/stack_using_two_queues.py) * [Stack With Doubly Linked List](data_structures/stacks/stack_with_doubly_linked_list.py) * [Stack With Singly Linked List](data_structures/stacks/stack_with_singly_linked_list.py) @@ -302,7 +411,7 @@ * [Radix Tree](data_structures/trie/radix_tree.py) * [Trie](data_structures/trie/trie.py) -## Digital Image Processing +## [Digital Image Processing](digital_image_processing) * [Change Brightness](digital_image_processing/change_brightness.py) * [Change Contrast](digital_image_processing/change_contrast.py) * [Convert To Negative](digital_image_processing/convert_to_negative.py) @@ -332,7 +441,7 @@ * [Sepia](digital_image_processing/sepia.py) * [Test Digital Image Processing](digital_image_processing/test_digital_image_processing.py) -## Divide And Conquer +## [Divide And Conquer](divide_and_conquer) * [Closest Pair Of Points](divide_and_conquer/closest_pair_of_points.py) * [Convex Hull](divide_and_conquer/convex_hull.py) * [Heaps Algorithm](divide_and_conquer/heaps_algorithm.py) @@ -342,11 +451,17 @@ * [Max Difference Pair](divide_and_conquer/max_difference_pair.py) * [Max Subarray](divide_and_conquer/max_subarray.py) * [Mergesort](divide_and_conquer/mergesort.py) + * [Minimum Element Of Array](divide_and_conquer/minimum_element_of_array.py) * [Peak](divide_and_conquer/peak.py) * [Power](divide_and_conquer/power.py) * [Strassen Matrix Multiplication](divide_and_conquer/strassen_matrix_multiplication.py) + * Tests + * [Test Strassen Matrix Multiplication](divide_and_conquer/tests/test_strassen_matrix_multiplication.py) -## Dynamic Programming +## [Docs](docs) + * [Conf](docs/conf.py) + +## [Dynamic Programming](dynamic_programming) * [Abbreviation](dynamic_programming/abbreviation.py) * [All Construct](dynamic_programming/all_construct.py) * [Bitmask](dynamic_programming/bitmask.py) @@ -354,6 +469,7 @@ * [Climbing Stairs](dynamic_programming/climbing_stairs.py) * [Combination Sum Iv](dynamic_programming/combination_sum_iv.py) * [Edit Distance](dynamic_programming/edit_distance.py) + * [Egg Dropping](dynamic_programming/egg_dropping.py) * [Factorial](dynamic_programming/factorial.py) * [Fast Fibonacci](dynamic_programming/fast_fibonacci.py) * [Fibonacci](dynamic_programming/fibonacci.py) @@ -361,14 +477,15 @@ * [Floyd Warshall](dynamic_programming/floyd_warshall.py) * [Integer Partition](dynamic_programming/integer_partition.py) * [Iterating Through Submasks](dynamic_programming/iterating_through_submasks.py) - * [K Means Clustering Tensorflow](dynamic_programming/k_means_clustering_tensorflow.py) * [Knapsack](dynamic_programming/knapsack.py) * [Largest Divisible Subset](dynamic_programming/largest_divisible_subset.py) * [Longest Common Subsequence](dynamic_programming/longest_common_subsequence.py) * [Longest Common Substring](dynamic_programming/longest_common_substring.py) * [Longest Increasing Subsequence](dynamic_programming/longest_increasing_subsequence.py) + * [Longest Increasing Subsequence Iterative](dynamic_programming/longest_increasing_subsequence_iterative.py) * [Longest Increasing Subsequence O Nlogn](dynamic_programming/longest_increasing_subsequence_o_nlogn.py) * [Longest Palindromic Subsequence](dynamic_programming/longest_palindromic_subsequence.py) + * [Longest Repeating Subsequence](dynamic_programming/longest_repeating_subsequence.py) * [Matrix Chain Multiplication](dynamic_programming/matrix_chain_multiplication.py) * [Matrix Chain Order](dynamic_programming/matrix_chain_order.py) * [Max Non Adjacent Sum](dynamic_programming/max_non_adjacent_sum.py) @@ -382,8 +499,11 @@ * [Minimum Squares To Represent A Number](dynamic_programming/minimum_squares_to_represent_a_number.py) * [Minimum Steps To One](dynamic_programming/minimum_steps_to_one.py) * [Minimum Tickets Cost](dynamic_programming/minimum_tickets_cost.py) + * [Narcissistic Number](dynamic_programming/narcissistic_number.py) + * [Needleman Wunsch](dynamic_programming/needleman_wunsch.py) * [Optimal Binary Search Tree](dynamic_programming/optimal_binary_search_tree.py) * [Palindrome Partitioning](dynamic_programming/palindrome_partitioning.py) + * [Range Sum Query](dynamic_programming/range_sum_query.py) * [Regex Match](dynamic_programming/regex_match.py) * [Rod Cutting](dynamic_programming/rod_cutting.py) * [Smith Waterman](dynamic_programming/smith_waterman.py) @@ -395,7 +515,7 @@ * [Wildcard Matching](dynamic_programming/wildcard_matching.py) * [Word Break](dynamic_programming/word_break.py) -## Electronics +## [Electronics](electronics) * [Apparent Power](electronics/apparent_power.py) * [Builtin Voltage](electronics/builtin_voltage.py) * [Capacitor Equivalence](electronics/capacitor_equivalence.py) @@ -407,54 +527,91 @@ * [Electric Conductivity](electronics/electric_conductivity.py) * [Electric Power](electronics/electric_power.py) * [Electrical Impedance](electronics/electrical_impedance.py) + * [Full Wave Rectifier](electronics/full_wave_rectifier.py) + * [Half Wave Rectifier](electronics/half_wave_rectifier.py) * [Ic 555 Timer](electronics/ic_555_timer.py) * [Ind Reactance](electronics/ind_reactance.py) * [Ohms Law](electronics/ohms_law.py) + * [Power Factor Correction](electronics/power_factor_correction.py) * [Real And Reactive Power](electronics/real_and_reactive_power.py) * [Resistor Color Code](electronics/resistor_color_code.py) * [Resistor Equivalence](electronics/resistor_equivalence.py) * [Resonant Frequency](electronics/resonant_frequency.py) + * [Star Delta Conversions](electronics/star_delta_conversions.py) * [Wheatstone Bridge](electronics/wheatstone_bridge.py) -## File Transfer +## [File Transfer](file_transfer) * [Receive File](file_transfer/receive_file.py) * [Send File](file_transfer/send_file.py) * Tests * [Test Send File](file_transfer/tests/test_send_file.py) -## Financial +## [Financial](financial) + * [Annuity Due Future Value](financial/annuity_due_future_value.py) * [Equated Monthly Installments](financial/equated_monthly_installments.py) + * [Expected Shortfall](financial/expected_shortfall.py) * [Exponential Moving Average](financial/exponential_moving_average.py) + * [Fractional Differentiation](financial/fractional_differentiation.py) * [Interest](financial/interest.py) + * [Kelly Criterion](financial/kelly_criterion.py) + * [Macaulay Duration](financial/macaulay_duration.py) + * [Ordinary Annuity Future Value](financial/ordinary_annuity_future_value.py) * [Present Value](financial/present_value.py) * [Price Plus Tax](financial/price_plus_tax.py) + * [Sharpe Ratio](financial/sharpe_ratio.py) * [Simple Moving Average](financial/simple_moving_average.py) + * [Straight Line Depreciation](financial/straight_line_depreciation.py) + * [Streaming Moving Average](financial/streaming_moving_average.py) + * [Time And Half Pay](financial/time_and_half_pay.py) + * [Value At Risk](financial/value_at_risk.py) -## Fractals +## [Fractals](fractals) + * [Barnsley Fern](fractals/barnsley_fern.py) + * [Hilbert Curve](fractals/hilbert_curve.py) * [Julia Sets](fractals/julia_sets.py) * [Koch Snowflake](fractals/koch_snowflake.py) * [Mandelbrot](fractals/mandelbrot.py) + * [Sierpinski Carpet](fractals/sierpinski_carpet.py) * [Sierpinski Triangle](fractals/sierpinski_triangle.py) * [Vicsek](fractals/vicsek.py) -## Fuzzy Logic +## [Fuzzy Logic](fuzzy_logic) * [Fuzzy Operations](fuzzy_logic/fuzzy_operations.py) + * [Fuzzy Set Operations](fuzzy_logic/fuzzy_set_operations.py) -## Genetic Algorithm +## [Genetic Algorithm](genetic_algorithm) * [Basic String](genetic_algorithm/basic_string.py) + * [Travelling Salesman Problem](genetic_algorithm/travelling_salesman_problem.py) -## Geodesy +## [Geodesy](geodesy) * [Haversine Distance](geodesy/haversine_distance.py) * [Lamberts Ellipsoidal Distance](geodesy/lamberts_ellipsoidal_distance.py) + * [Radar Target Calculation](geodesy/radar_target_calculation.py) -## Geometry +## [Geometry](geometry) + * [Braik Mac Construction](geometry/braik_mac_construction.py) * [Geometry](geometry/geometry.py) + * [Graham Scan](geometry/graham_scan.py) + * [Jarvis March](geometry/jarvis_march.py) + * [Monotone Chain](geometry/monotone_chain.py) + * [Ramer Douglas Peucker](geometry/ramer_douglas_peucker.py) + * [Rotating Calipers](geometry/rotating_calipers.py) + * [Segment Intersection](geometry/segment_intersection.py) + * [Shoelace](geometry/shoelace.py) + * Tests + * [Test Graham Scan](geometry/tests/test_graham_scan.py) + * [Test Jarvis March](geometry/tests/test_jarvis_march.py) + * [Triangle](geometry/triangle.py) -## Graphics +## [Graphics](graphics) * [Bezier Curve](graphics/bezier_curve.py) + * [Bresenham Line Basic](graphics/bresenham_line_basic.py) + * [Bresenham Line Generalized](graphics/bresenham_line_generalized.py) + * [Butterfly Pattern](graphics/butterfly_pattern.py) + * [Digital Differential Analyzer Line](graphics/digital_differential_analyzer_line.py) * [Vector3 For 2D Rendering](graphics/vector3_for_2d_rendering.py) -## Graphs +## [Graphs](graphs) * [A Star](graphs/a_star.py) * [Ant Colony Optimization Algorithms](graphs/ant_colony_optimization_algorithms.py) * [Articulation Points](graphs/articulation_points.py) @@ -463,6 +620,7 @@ * [Bi Directional Dijkstra](graphs/bi_directional_dijkstra.py) * [Bidirectional A Star](graphs/bidirectional_a_star.py) * [Bidirectional Breadth First Search](graphs/bidirectional_breadth_first_search.py) + * [Bidirectional Search](graphs/bidirectional_search.py) * [Boruvka](graphs/boruvka.py) * [Breadth First Search](graphs/breadth_first_search.py) * [Breadth First Search 2](graphs/breadth_first_search_2.py) @@ -482,6 +640,7 @@ * [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 Blossom Algorithm](graphs/edmonds_blossom_algorithm.py) * [Edmonds Karp Multiple Source And Sink](graphs/edmonds_karp_multiple_source_and_sink.py) * [Eulerian Path And Circuit For Undirected Graph](graphs/eulerian_path_and_circuit_for_undirected_graph.py) * [Even Tree](graphs/even_tree.py) @@ -491,13 +650,18 @@ * [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 Centrality](graphs/graph_centrality.py) * [Graph List](graphs/graph_list.py) + * [Graph Peripherality](graphs/graph_peripherality.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) + * [Hopcroft Karp](graphs/hopcroft_karp.py) + * [Johnson](graphs/johnson.py) * [Kahns Algorithm Long](graphs/kahns_algorithm_long.py) * [Kahns Algorithm Topo](graphs/kahns_algorithm_topo.py) * [Karger](graphs/karger.py) + * [Lanczos Eigenvectors](graphs/lanczos_eigenvectors.py) * [Markov Chain](graphs/markov_chain.py) * [Matching Min Vertex Cover](graphs/matching_min_vertex_cover.py) * [Minimum Path Sum](graphs/minimum_path_sum.py) @@ -514,35 +678,44 @@ * [Strongly Connected Components](graphs/strongly_connected_components.py) * [Tarjans Scc](graphs/tarjans_scc.py) * Tests + * [Test Edmonds Blossom Algorithm](graphs/tests/test_edmonds_blossom_algorithm.py) + * [Test Graphs Floyd Warshall](graphs/tests/test_graphs_floyd_warshall.py) + * [Test Johnson](graphs/tests/test_johnson.py) * [Test Min Spanning Tree Kruskal](graphs/tests/test_min_spanning_tree_kruskal.py) * [Test Min Spanning Tree Prim](graphs/tests/test_min_spanning_tree_prim.py) + * [Travelling Salesman Problem](graphs/travelling_salesman_problem.py) -## Greedy Methods +## [Greedy Methods](greedy_methods) + * [Activity Selection](greedy_methods/activity_selection.py) * [Best Time To Buy And Sell Stock](greedy_methods/best_time_to_buy_and_sell_stock.py) * [Fractional Cover Problem](greedy_methods/fractional_cover_problem.py) * [Fractional Knapsack](greedy_methods/fractional_knapsack.py) * [Fractional Knapsack 2](greedy_methods/fractional_knapsack_2.py) * [Gas Station](greedy_methods/gas_station.py) + * [Minimize Deviation In Array](greedy_methods/minimize_deviation_in_array.py) * [Minimum Coin Change](greedy_methods/minimum_coin_change.py) * [Minimum Waiting Time](greedy_methods/minimum_waiting_time.py) * [Optimal Merge Pattern](greedy_methods/optimal_merge_pattern.py) + * [Sliding Window](greedy_methods/sliding_window.py) * [Smallest Range](greedy_methods/smallest_range.py) -## Hashes +## [Hashes](hashes) * [Adler32](hashes/adler32.py) * [Chaos Machine](hashes/chaos_machine.py) + * [Crc32](hashes/crc32.py) * [Djb2](hashes/djb2.py) * [Elf](hashes/elf.py) * [Enigma Machine](hashes/enigma_machine.py) * [Fletcher16](hashes/fletcher16.py) * [Hamming Code](hashes/hamming_code.py) + * [Jenkins One At A Time](hashes/jenkins_one_at_a_time.py) * [Luhn](hashes/luhn.py) * [Md5](hashes/md5.py) * [Sdbm](hashes/sdbm.py) * [Sha1](hashes/sha1.py) * [Sha256](hashes/sha256.py) -## Knapsack +## [Knapsack](knapsack) * [Greedy Knapsack](knapsack/greedy_knapsack.py) * [Knapsack](knapsack/knapsack.py) * [Recursive Approach Knapsack](knapsack/recursive_approach_knapsack.py) @@ -550,10 +723,12 @@ * [Test Greedy Knapsack](knapsack/tests/test_greedy_knapsack.py) * [Test Knapsack](knapsack/tests/test_knapsack.py) -## Linear Algebra +## [Linear Algebra](linear_algebra) + * [Gauss Jordan](linear_algebra/gauss_jordan.py) * [Gaussian Elimination](linear_algebra/gaussian_elimination.py) * [Jacobi Iteration Method](linear_algebra/jacobi_iteration_method.py) * [Lu Decomposition](linear_algebra/lu_decomposition.py) + * [Matrix Inversion](linear_algebra/matrix_inversion.py) * Src * [Conjugate Gradient](linear_algebra/src/conjugate_gradient.py) * [Gaussian Elimination Pivoting](linear_algebra/src/gaussian_elimination_pivoting.py) @@ -566,44 +741,59 @@ * [Test Linear Algebra](linear_algebra/src/test_linear_algebra.py) * [Transformations 2D](linear_algebra/src/transformations_2d.py) -## Linear Programming +## [Linear Programming](linear_programming) * [Simplex](linear_programming/simplex.py) -## Machine Learning +## [Machine Learning](machine_learning) * [Apriori Algorithm](machine_learning/apriori_algorithm.py) * [Astar](machine_learning/astar.py) * [Automatic Differentiation](machine_learning/automatic_differentiation.py) * [Data Transformations](machine_learning/data_transformations.py) + * [Dbscan](machine_learning/dbscan.py) * [Decision Tree](machine_learning/decision_tree.py) * [Dimensionality Reduction](machine_learning/dimensionality_reduction.py) + * [Federated Averaging](machine_learning/federated_averaging.py) * Forecasting * [Run](machine_learning/forecasting/run.py) * [Frequent Pattern Growth](machine_learning/frequent_pattern_growth.py) + * [Gaussian Mixture Model](machine_learning/gaussian_mixture_model.py) + * [Gaussian Naive Bayes](machine_learning/gaussian_naive_bayes.py) * [Gradient Boosting Classifier](machine_learning/gradient_boosting_classifier.py) + * [Gradient Boosting Regressor](machine_learning/gradient_boosting_regressor.py) * [Gradient Descent](machine_learning/gradient_descent.py) * [K Means Clust](machine_learning/k_means_clust.py) - * [K Nearest Neighbours](machine_learning/k_nearest_neighbours.py) + * [K Medoids](machine_learning/k_medoids.py) + * [K Nearest Neighbors](machine_learning/k_nearest_neighbors.py) * [Linear Discriminant Analysis](machine_learning/linear_discriminant_analysis.py) * [Linear Regression](machine_learning/linear_regression.py) + * [Linear Regression Vectorized](machine_learning/linear_regression_vectorized.py) * Local Weighted Learning * [Local Weighted Learning](machine_learning/local_weighted_learning/local_weighted_learning.py) * [Logistic Regression](machine_learning/logistic_regression.py) * [Loss Functions](machine_learning/loss_functions.py) - * Lstm - * [Lstm Prediction](machine_learning/lstm/lstm_prediction.py) + * [Mab](machine_learning/mab.py) + * [Mean Shift](machine_learning/mean_shift.py) * [Mfcc](machine_learning/mfcc.py) + * [Mini Batch Gradient Descent](machine_learning/mini_batch_gradient_descent.py) * [Multilayer Perceptron Classifier](machine_learning/multilayer_perceptron_classifier.py) + * [Naive Bayes Text Classification](machine_learning/naive_bayes_text_classification.py) + * [Ordinary Least Squares Regression](machine_learning/ordinary_least_squares_regression.py) * [Polynomial Regression](machine_learning/polynomial_regression.py) + * [Principle Component Analysis](machine_learning/principle_component_analysis.py) + * [Q Learning](machine_learning/q_learning.py) + * [Random Forest Classifier](machine_learning/random_forest_classifier.py) + * [Random Forest Regressor](machine_learning/random_forest_regressor.py) + * [Ridge Regression](machine_learning/ridge_regression.py) + * [Rmsprop](machine_learning/rmsprop.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) * [Similarity Search](machine_learning/similarity_search.py) * [Support Vector Machines](machine_learning/support_vector_machines.py) + * [T Stochastic Neighbour Embedding](machine_learning/t_stochastic_neighbour_embedding.py) * [Word Frequency Functions](machine_learning/word_frequency_functions.py) - * [Xgboost Classifier](machine_learning/xgboost_classifier.py) - * [Xgboost Regressor](machine_learning/xgboost_regressor.py) -## Maths +## [Maths](maths) * [Abs](maths/abs.py) * [Addition Without Arithmetic](maths/addition_without_arithmetic.py) * [Aliquot Sum](maths/aliquot_sum.py) @@ -611,6 +801,7 @@ * [Arc Length](maths/arc_length.py) * [Area](maths/area.py) * [Area Under Curve](maths/area_under_curve.py) + * [Autocorrelation](maths/autocorrelation.py) * [Average Absolute Deviation](maths/average_absolute_deviation.py) * [Average Mean](maths/average_mean.py) * [Average Median](maths/average_median.py) @@ -618,23 +809,31 @@ * [Bailey Borwein Plouffe](maths/bailey_borwein_plouffe.py) * [Base Neg2 Conversion](maths/base_neg2_conversion.py) * [Basic Maths](maths/basic_maths.py) + * [Bearing](maths/bearing.py) * [Binary Exponentiation](maths/binary_exponentiation.py) * [Binary Multiplication](maths/binary_multiplication.py) * [Binomial Coefficient](maths/binomial_coefficient.py) * [Binomial Distribution](maths/binomial_distribution.py) + * [Binomial Expansion](maths/binomial_expansion.py) * [Ceil](maths/ceil.py) * [Chebyshev Distance](maths/chebyshev_distance.py) * [Check Polygon](maths/check_polygon.py) * [Chinese Remainder Theorem](maths/chinese_remainder_theorem.py) + * [Cholesky Decomposition](maths/cholesky_decomposition.py) * [Chudnovsky Algorithm](maths/chudnovsky_algorithm.py) * [Collatz Sequence](maths/collatz_sequence.py) * [Combinations](maths/combinations.py) * [Continued Fraction](maths/continued_fraction.py) + * [Convolve 1D](maths/convolve_1d.py) * [Decimal Isolate](maths/decimal_isolate.py) * [Decimal To Fraction](maths/decimal_to_fraction.py) + * [Derangement](maths/derangement.py) + * [Digital Root](maths/digital_root.py) + * [Disarium](maths/disarium.py) * [Dodecahedron](maths/dodecahedron.py) * [Double Factorial](maths/double_factorial.py) * [Dual Number Automatic Differentiation](maths/dual_number_automatic_differentiation.py) + * [Ear Clipping Polygon Triangulation](maths/ear_clipping_polygon_triangulation.py) * [Entropy](maths/entropy.py) * [Euclidean Distance](maths/euclidean_distance.py) * [Euler Method](maths/euler_method.py) @@ -648,10 +847,12 @@ * [Fibonacci](maths/fibonacci.py) * [Find Max](maths/find_max.py) * [Find Min](maths/find_min.py) + * [First Fundamental Form](maths/first_fundamental_form.py) * [Floor](maths/floor.py) * [Gamma](maths/gamma.py) * [Gaussian](maths/gaussian.py) * [Gcd Of N Numbers](maths/gcd_of_n_numbers.py) + * [Geometric Mean](maths/geometric_mean.py) * [Germain Primes](maths/germain_primes.py) * [Greatest Common Divisor](maths/greatest_common_divisor.py) * [Hardy Ramanujanalgo](maths/hardy_ramanujanalgo.py) @@ -659,15 +860,19 @@ * [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 Ipv6 Address Valid](maths/is_ipv6_address_valid.py) * [Is Square Free](maths/is_square_free.py) * [Jaccard Similarity](maths/jaccard_similarity.py) * [Joint Probability Distribution](maths/joint_probability_distribution.py) * [Josephus Problem](maths/josephus_problem.py) * [Juggler Sequence](maths/juggler_sequence.py) * [Karatsuba](maths/karatsuba.py) + * [Keith Number](maths/keith_number.py) * [Kth Lexicographic Permutation](maths/kth_lexicographic_permutation.py) + * [Laplace Transformation](maths/laplace_transformation.py) * [Largest Of Very Large Numbers](maths/largest_of_very_large_numbers.py) * [Least Common Multiple](maths/least_common_multiple.py) + * [Line Intersection](maths/line_intersection.py) * [Line Length](maths/line_length.py) * [Liouville Lambda](maths/liouville_lambda.py) * [Lucas Lehmer Primality Test](maths/lucas_lehmer_primality_test.py) @@ -682,16 +887,21 @@ * [Modular Exponential](maths/modular_exponential.py) * [Monte Carlo](maths/monte_carlo.py) * [Monte Carlo Dice](maths/monte_carlo_dice.py) + * [Ncr Combinations](maths/ncr_combinations.py) + * [Next Prime Number](maths/next_prime_number.py) * [Number Of Digits](maths/number_of_digits.py) * Numerical Analysis * [Adams Bashforth](maths/numerical_analysis/adams_bashforth.py) * [Bisection](maths/numerical_analysis/bisection.py) * [Bisection 2](maths/numerical_analysis/bisection_2.py) + * [Brent Method](maths/numerical_analysis/brent_method.py) + * [Gauss Seidel Method](maths/numerical_analysis/gauss_seidel_method.py) * [Integration By Simpson Approx](maths/numerical_analysis/integration_by_simpson_approx.py) * [Intersection](maths/numerical_analysis/intersection.py) * [Nevilles Method](maths/numerical_analysis/nevilles_method.py) * [Newton Forward Interpolation](maths/numerical_analysis/newton_forward_interpolation.py) * [Newton Raphson](maths/numerical_analysis/newton_raphson.py) + * [Nth Root](maths/numerical_analysis/nth_root.py) * [Numerical Integration](maths/numerical_analysis/numerical_integration.py) * [Proper Fractions](maths/numerical_analysis/proper_fractions.py) * [Runge Kutta](maths/numerical_analysis/runge_kutta.py) @@ -700,7 +910,10 @@ * [Secant Method](maths/numerical_analysis/secant_method.py) * [Simpson Rule](maths/numerical_analysis/simpson_rule.py) * [Square Root](maths/numerical_analysis/square_root.py) + * [Weierstrass Method](maths/numerical_analysis/weierstrass_method.py) * [Odd Sieve](maths/odd_sieve.py) + * [Padovan Sequence](maths/padovan_sequence.py) + * [Pell Number](maths/pell_number.py) * [Perfect Cube](maths/perfect_cube.py) * [Perfect Number](maths/perfect_number.py) * [Perfect Square](maths/perfect_square.py) @@ -724,16 +937,23 @@ * [Quadratic Equations Complex Numbers](maths/quadratic_equations_complex_numbers.py) * [Radians](maths/radians.py) * [Radix2 Fft](maths/radix2_fft.py) + * [Recursive Digit Sum](maths/recursive_digit_sum.py) * [Remove Digit](maths/remove_digit.py) + * [Reverse Factorial Recursive](maths/reverse_factorial_recursive.py) * [Segmented Sieve](maths/segmented_sieve.py) * Series + * [Alternate Harmonic Series](maths/series/alternate_harmonic_series.py) + * [Alternating Harmonic Series](maths/series/alternating_harmonic_series.py) * [Arithmetic](maths/series/arithmetic.py) * [Geometric](maths/series/geometric.py) * [Geometric Series](maths/series/geometric_series.py) * [Harmonic](maths/series/harmonic.py) * [Harmonic Series](maths/series/harmonic_series.py) * [Hexagonal Numbers](maths/series/hexagonal_numbers.py) + * [Logarithmic Series](maths/series/logarithmic_series.py) * [P Series](maths/series/p_series.py) + * [Shoelace Area](maths/shoelace_area.py) + * [Sieve Of Atkin](maths/sieve_of_atkin.py) * [Sieve Of Eratosthenes](maths/sieve_of_eratosthenes.py) * [Sigmoid](maths/sigmoid.py) * [Signum](maths/signum.py) @@ -744,21 +964,30 @@ * [Solovay Strassen Primality Test](maths/solovay_strassen_primality_test.py) * [Spearman Rank Correlation Coefficient](maths/spearman_rank_correlation_coefficient.py) * Special Numbers + * [Abundant Numbers](maths/special_numbers/abundant_numbers.py) * [Armstrong Numbers](maths/special_numbers/armstrong_numbers.py) * [Automorphic Number](maths/special_numbers/automorphic_number.py) * [Bell Numbers](maths/special_numbers/bell_numbers.py) * [Carmichael Number](maths/special_numbers/carmichael_number.py) * [Catalan Number](maths/special_numbers/catalan_number.py) + * [Deficient Numbers](maths/special_numbers/deficient_numbers.py) + * [Disarum Number](maths/special_numbers/disarum_number.py) + * [Evil Number](maths/special_numbers/evil_number.py) * [Hamming Numbers](maths/special_numbers/hamming_numbers.py) * [Happy Number](maths/special_numbers/happy_number.py) * [Harshad Numbers](maths/special_numbers/harshad_numbers.py) * [Hexagonal Number](maths/special_numbers/hexagonal_number.py) + * [Jacobsthal Number](maths/special_numbers/jacobsthal_number.py) + * [Kaprekar Constant](maths/special_numbers/kaprekar_constant.py) + * [Kaprekar Number](maths/special_numbers/kaprekar_number.py) * [Krishnamurthy Number](maths/special_numbers/krishnamurthy_number.py) * [Perfect Number](maths/special_numbers/perfect_number.py) * [Polygonal Numbers](maths/special_numbers/polygonal_numbers.py) * [Pronic Number](maths/special_numbers/pronic_number.py) * [Proth Number](maths/special_numbers/proth_number.py) + * [Spy Number](maths/special_numbers/spy_number.py) * [Triangular Numbers](maths/special_numbers/triangular_numbers.py) + * [Trimorphic Number](maths/special_numbers/trimorphic_number.py) * [Ugly Numbers](maths/special_numbers/ugly_numbers.py) * [Weird Number](maths/special_numbers/weird_number.py) * [Sum Of Arithmetic Series](maths/sum_of_arithmetic_series.py) @@ -768,24 +997,32 @@ * [Sumset](maths/sumset.py) * [Sylvester Sequence](maths/sylvester_sequence.py) * [Tanh](maths/tanh.py) + * [Test Abs](maths/test_abs.py) + * [Test Factorial](maths/test_factorial.py) * [Test Prime Check](maths/test_prime_check.py) * [Three Sum](maths/three_sum.py) + * [Tonelli Shanks](maths/tonelli_shanks.py) + * [Trailing Zeroes](maths/trailing_zeroes.py) * [Trapezoidal Rule](maths/trapezoidal_rule.py) * [Triplet Sum](maths/triplet_sum.py) * [Twin Prime](maths/twin_prime.py) * [Two Pointer](maths/two_pointer.py) * [Two Sum](maths/two_sum.py) * [Volume](maths/volume.py) + * [Weddles Rule](maths/weddles_rule.py) + * [Weighted Average](maths/weighted_average.py) * [Zellers Congruence](maths/zellers_congruence.py) -## Matrix +## [Matrix](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) + * [Kronecker Product](matrix/kronecker_product.py) * [Largest Square Area In Matrix](matrix/largest_square_area_in_matrix.py) + * [Matrix Based Game](matrix/matrix_based_game.py) * [Matrix Class](matrix/matrix_class.py) * [Matrix Equalization](matrix/matrix_equalization.py) * [Matrix Multiplication Recursion](matrix/matrix_multiplication_recursion.py) @@ -797,16 +1034,20 @@ * [Rotate Matrix](matrix/rotate_matrix.py) * [Searching In Sorted Matrix](matrix/searching_in_sorted_matrix.py) * [Sherman Morrison](matrix/sherman_morrison.py) + * [Similar Matrices](matrix/similar_matrices.py) * [Spiral Print](matrix/spiral_print.py) * Tests * [Test Matrix Operation](matrix/tests/test_matrix_operation.py) + * [Transitive Closure](matrix/transitive_closure.py) * [Validate Sudoku Board](matrix/validate_sudoku_board.py) -## Networking Flow +## [Networking Flow](networking_flow) + * [Dinic](networking_flow/dinic.py) * [Ford Fulkerson](networking_flow/ford_fulkerson.py) * [Minimum Cut](networking_flow/minimum_cut.py) + * [Push Relabel](networking_flow/push_relabel.py) -## Neural Network +## [Neural Network](neural_network) * Activation Functions * [Binary Step](neural_network/activation_functions/binary_step.py) * [Exponential Linear Unit](neural_network/activation_functions/exponential_linear_unit.py) @@ -817,18 +1058,29 @@ * [Scaled Exponential Linear Unit](neural_network/activation_functions/scaled_exponential_linear_unit.py) * [Soboleva Modified Hyperbolic Tangent](neural_network/activation_functions/soboleva_modified_hyperbolic_tangent.py) * [Softplus](neural_network/activation_functions/softplus.py) + * [Softsign](neural_network/activation_functions/softsign.py) * [Squareplus](neural_network/activation_functions/squareplus.py) * [Swish](neural_network/activation_functions/swish.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) + * [Lstm](neural_network/lstm.py) + * Optimizers + * [Adagrad](neural_network/optimizers/adagrad.py) + * [Adam Optimizer](neural_network/optimizers/adam_optimizer.py) + * [Momentum Sgd](neural_network/optimizers/momentum_sgd.py) + * [Muon Optimizer](neural_network/optimizers/muon_optimizer.py) + * [Nesterov Accelerated Sgd](neural_network/optimizers/nesterov_accelerated_sgd.py) + * [Perceptron](neural_network/perceptron.py) * [Simple Neural Network](neural_network/simple_neural_network.py) + * [Sliding Window Attention](neural_network/sliding_window_attention.py) * [Two Hidden Layers Neural Network](neural_network/two_hidden_layers_neural_network.py) -## Other +## [Other](other) * [Activity Selection](other/activity_selection.py) * [Alternative List Arrange](other/alternative_list_arrange.py) * [Bankers Algorithm](other/bankers_algorithm.py) + * [Cheap Progress](other/cheap_progress.py) + * [Dancing Links](other/dancing_links.py) * [Davis Putnam Logemann Loveland](other/davis_putnam_logemann_loveland.py) * [Doomsday](other/doomsday.py) * [Fischer Yates Shuffle](other/fischer_yates_shuffle.py) @@ -847,46 +1099,65 @@ * [Nested Brackets](other/nested_brackets.py) * [Number Container System](other/number_container_system.py) * [Password](other/password.py) + * [Pipeline](other/pipeline.py) * [Quine](other/quine.py) * [Scoring Algorithm](other/scoring_algorithm.py) * [Sdes](other/sdes.py) + * [Sliding Window Maximum](other/sliding_window_maximum.py) + * [Token Bucket](other/token_bucket.py) * [Tower Of Hanoi](other/tower_of_hanoi.py) * [Word Search](other/word_search.py) -## Physics +## [Physics](physics) * [Altitude Pressure](physics/altitude_pressure.py) * [Archimedes Principle Of Buoyant Force](physics/archimedes_principle_of_buoyant_force.py) * [Basic Orbital Capture](physics/basic_orbital_capture.py) + * [Boyles Law](physics/boyles_law.py) + * [Bragg Angle](physics/bragg_angle.py) * [Casimir Effect](physics/casimir_effect.py) * [Center Of Mass](physics/center_of_mass.py) * [Centripetal Force](physics/centripetal_force.py) * [Coulombs Law](physics/coulombs_law.py) * [Doppler Frequency](physics/doppler_frequency.py) + * [Escape Velocity](physics/escape_velocity.py) + * [Faraday Lenz Law](physics/faraday_lenz_law.py) + * [First Law Of Thermodynamics](physics/first_law_of_thermodynamics.py) + * [Fresnel Diffract](physics/fresnel_diffract.py) * [Grahams Law](physics/grahams_law.py) + * [Hamiltonian](physics/hamiltonian.py) + * [Hookes Law](physics/hookes_law.py) * [Horizontal Projectile Motion](physics/horizontal_projectile_motion.py) * [Hubble Parameter](physics/hubble_parameter.py) * [Ideal Gas Law](physics/ideal_gas_law.py) * [In Static Equilibrium](physics/in_static_equilibrium.py) * [Kinetic Energy](physics/kinetic_energy.py) * [Lens Formulae](physics/lens_formulae.py) + * [Light Aberration](physics/light_aberration.py) * [Lorentz Transformation Four Vector](physics/lorentz_transformation_four_vector.py) + * [Magnetic Flux](physics/magnetic_flux.py) * [Malus Law](physics/malus_law.py) * [Mass Energy Equivalence](physics/mass_energy_equivalence.py) + * [Maxwells Equations](physics/maxwells_equations.py) * [Mirror Formulae](physics/mirror_formulae.py) * [N Body Simulation](physics/n_body_simulation.py) * [Newtons Law Of Gravitation](physics/newtons_law_of_gravitation.py) * [Newtons Second Law Of Motion](physics/newtons_second_law_of_motion.py) + * [Orbital Transfer Work](physics/orbital_transfer_work.py) + * [Period Of Pendulum](physics/period_of_pendulum.py) * [Photoelectric Effect](physics/photoelectric_effect.py) * [Potential Energy](physics/potential_energy.py) * [Rainfall Intensity](physics/rainfall_intensity.py) + * [Relativistic Kinetic Energy](physics/relativistic_kinetic_energy.py) + * [Relativistic Velocity Summation](physics/relativistic_velocity_summation.py) * [Reynolds Number](physics/reynolds_number.py) * [Rms Speed Of Molecule](physics/rms_speed_of_molecule.py) * [Shear Stress](physics/shear_stress.py) + * [Snells Law](physics/snells_law.py) * [Speed Of Sound](physics/speed_of_sound.py) * [Speeds Of Gas Molecules](physics/speeds_of_gas_molecules.py) * [Terminal Velocity](physics/terminal_velocity.py) -## Project Euler +## [Project Euler](project_euler) * Problem 001 * [Sol1](project_euler/problem_001/sol1.py) * [Sol2](project_euler/problem_001/sol2.py) @@ -928,6 +1199,7 @@ * [Sol1](project_euler/problem_009/sol1.py) * [Sol2](project_euler/problem_009/sol2.py) * [Sol3](project_euler/problem_009/sol3.py) + * [Sol4](project_euler/problem_009/sol4.py) * Problem 010 * [Sol1](project_euler/problem_010/sol1.py) * [Sol2](project_euler/problem_010/sol2.py) @@ -940,11 +1212,13 @@ * [Sol2](project_euler/problem_012/sol2.py) * Problem 013 * [Sol1](project_euler/problem_013/sol1.py) + * [Sol2](project_euler/problem_013/sol2.py) * Problem 014 * [Sol1](project_euler/problem_014/sol1.py) * [Sol2](project_euler/problem_014/sol2.py) * Problem 015 * [Sol1](project_euler/problem_015/sol1.py) + * [Sol2](project_euler/problem_015/sol2.py) * Problem 016 * [Sol1](project_euler/problem_016/sol1.py) * [Sol2](project_euler/problem_016/sol2.py) @@ -1042,6 +1316,8 @@ * [Sol1](project_euler/problem_058/sol1.py) * Problem 059 * [Sol1](project_euler/problem_059/sol1.py) + * Problem 060 + * [Sol1](project_euler/problem_060/sol1.py) * Problem 062 * [Sol1](project_euler/problem_062/sol1.py) * Problem 063 @@ -1099,6 +1375,8 @@ * [Sol1](project_euler/problem_092/sol1.py) * Problem 094 * [Sol1](project_euler/problem_094/sol1.py) + * Problem 095 + * [Sol1](project_euler/problem_095/sol1.py) * Problem 097 * [Sol1](project_euler/problem_097/sol1.py) * Problem 099 @@ -1115,6 +1393,8 @@ * [Sol1](project_euler/problem_107/sol1.py) * Problem 109 * [Sol1](project_euler/problem_109/sol1.py) + * Problem 111 + * [Sol1](project_euler/problem_111/sol1.py) * Problem 112 * [Sol1](project_euler/problem_112/sol1.py) * Problem 113 @@ -1133,8 +1413,12 @@ * [Sol1](project_euler/problem_120/sol1.py) * Problem 121 * [Sol1](project_euler/problem_121/sol1.py) + * Problem 122 + * [Sol1](project_euler/problem_122/sol1.py) * Problem 123 * [Sol1](project_euler/problem_123/sol1.py) + * Problem 124 + * [Sol1](project_euler/problem_124/sol1.py) * Problem 125 * [Sol1](project_euler/problem_125/sol1.py) * Problem 129 @@ -1143,10 +1427,20 @@ * [Sol1](project_euler/problem_131/sol1.py) * Problem 135 * [Sol1](project_euler/problem_135/sol1.py) + * Problem 136 + * [Sol1](project_euler/problem_136/sol1.py) + * Problem 137 + * [Sol1](project_euler/problem_137/sol1.py) + * Problem 138 + * [Sol1](project_euler/problem_138/sol1.py) + * Problem 142 + * [Sol1](project_euler/problem_142/sol1.py) * Problem 144 * [Sol1](project_euler/problem_144/sol1.py) * Problem 145 * [Sol1](project_euler/problem_145/sol1.py) + * Problem 164 + * [Sol1](project_euler/problem_164/sol1.py) * Problem 173 * [Sol1](project_euler/problem_173/sol1.py) * Problem 174 @@ -1157,6 +1451,8 @@ * [Sol1](project_euler/problem_187/sol1.py) * Problem 188 * [Sol1](project_euler/problem_188/sol1.py) + * Problem 190 + * [Sol1](project_euler/problem_190/sol1.py) * Problem 191 * [Sol1](project_euler/problem_191/sol1.py) * Problem 203 @@ -1171,6 +1467,8 @@ * [Sol1](project_euler/problem_234/sol1.py) * Problem 301 * [Sol1](project_euler/problem_301/sol1.py) + * Problem 345 + * [Sol1](project_euler/problem_345/sol1.py) * Problem 493 * [Sol1](project_euler/problem_493/sol1.py) * Problem 551 @@ -1182,10 +1480,11 @@ * Problem 800 * [Sol1](project_euler/problem_800/sol1.py) -## Quantum - * [Q Fourier Transform](quantum/q_fourier_transform.py) +## [Quantum](quantum) + * [Shor Algorithm](quantum/shor_algorithm.py) -## Scheduling +## [Scheduling](scheduling) + * [Cpuschedulingalgorithms](scheduling/cpuschedulingalgorithms.py) * [First Come First Served](scheduling/first_come_first_served.py) * [Highest Response Ratio Next](scheduling/highest_response_ratio_next.py) * [Job Sequence With Deadline](scheduling/job_sequence_with_deadline.py) @@ -1194,12 +1493,14 @@ * [Non Preemptive Shortest Job First](scheduling/non_preemptive_shortest_job_first.py) * [Round Robin](scheduling/round_robin.py) * [Shortest Job First](scheduling/shortest_job_first.py) + * [Weighted Interval Scheduling](scheduling/weighted_interval_scheduling.py) -## Searches +## [Searches](searches) * [Binary Search](searches/binary_search.py) * [Binary Tree Traversal](searches/binary_tree_traversal.py) * [Double Linear Search](searches/double_linear_search.py) * [Double Linear Search Recursion](searches/double_linear_search_recursion.py) + * [Exponential Search](searches/exponential_search.py) * [Fibonacci Search](searches/fibonacci_search.py) * [Hill Climbing](searches/hill_climbing.py) * [Interpolation Search](searches/interpolation_search.py) @@ -1213,27 +1514,33 @@ * [Tabu Search](searches/tabu_search.py) * [Ternary Search](searches/ternary_search.py) -## Sorts +## [Sorts](sorts) + * [Adaptive Merge Sort](sorts/adaptive_merge_sort.py) * [Bead Sort](sorts/bead_sort.py) + * [Benchmark Sorts](sorts/benchmark_sorts.py) * [Binary Insertion Sort](sorts/binary_insertion_sort.py) * [Bitonic Sort](sorts/bitonic_sort.py) * [Bogo Sort](sorts/bogo_sort.py) * [Bubble Sort](sorts/bubble_sort.py) + * [Bubble Sort Recursive](sorts/bubble_sort_recursive.py) * [Bucket Sort](sorts/bucket_sort.py) * [Circle Sort](sorts/circle_sort.py) * [Cocktail Shaker Sort](sorts/cocktail_shaker_sort.py) * [Comb Sort](sorts/comb_sort.py) * [Counting Sort](sorts/counting_sort.py) * [Cycle Sort](sorts/cycle_sort.py) + * [Cyclic Sort](sorts/cyclic_sort.py) * [Double Sort](sorts/double_sort.py) * [Dutch National Flag Sort](sorts/dutch_national_flag_sort.py) * [Exchange Sort](sorts/exchange_sort.py) * [External Sort](sorts/external_sort.py) + * [Flash Sort](sorts/flash_sort.py) * [Gnome Sort](sorts/gnome_sort.py) * [Heap Sort](sorts/heap_sort.py) * [Insertion Sort](sorts/insertion_sort.py) * [Intro Sort](sorts/intro_sort.py) * [Iterative Merge Sort](sorts/iterative_merge_sort.py) + * [Kirkpatrick Reisch Sort](sorts/kirkpatrick_reisch_sort.py) * [Merge Insertion Sort](sorts/merge_insertion_sort.py) * [Merge Sort](sorts/merge_sort.py) * [Msd Radix Sort](sorts/msd_radix_sort.py) @@ -1245,16 +1552,21 @@ * [Patience Sort](sorts/patience_sort.py) * [Pigeon Sort](sorts/pigeon_sort.py) * [Pigeonhole Sort](sorts/pigeonhole_sort.py) + * [Power Sort](sorts/power_sort.py) * [Quick Sort](sorts/quick_sort.py) * [Quick Sort 3 Partition](sorts/quick_sort_3_partition.py) * [Radix Sort](sorts/radix_sort.py) * [Recursive Insertion Sort](sorts/recursive_insertion_sort.py) * [Recursive Mergesort Array](sorts/recursive_mergesort_array.py) * [Recursive Quick Sort](sorts/recursive_quick_sort.py) + * [Reverse Selection](sorts/reverse_selection.py) + * [Reversort](sorts/reversort.py) * [Selection Sort](sorts/selection_sort.py) * [Shell Sort](sorts/shell_sort.py) * [Shrink Shell Sort](sorts/shrink_shell_sort.py) * [Slowsort](sorts/slowsort.py) + * [Smoothsort](sorts/smoothsort.py) + * [Stalin Sort](sorts/stalin_sort.py) * [Stooge Sort](sorts/stooge_sort.py) * [Strand Sort](sorts/strand_sort.py) * [Tim Sort](sorts/tim_sort.py) @@ -1263,19 +1575,23 @@ * [Unknown Sort](sorts/unknown_sort.py) * [Wiggle Sort](sorts/wiggle_sort.py) -## Strings +## [Strings](strings) * [Aho Corasick](strings/aho_corasick.py) * [Alternative String Arrange](strings/alternative_string_arrange.py) * [Anagrams](strings/anagrams.py) * [Autocomplete Using Trie](strings/autocomplete_using_trie.py) * [Barcode Validator](strings/barcode_validator.py) * [Bitap String Match](strings/bitap_string_match.py) + * [Booths Algorithm](strings/booths_algorithm.py) + * [Boyer Moore Horspool](strings/boyer_moore_horspool.py) * [Boyer Moore Search](strings/boyer_moore_search.py) + * [Bpe Tokenizer](strings/bpe_tokenizer.py) * [Camel Case To Snake Case](strings/camel_case_to_snake_case.py) * [Can String Be Rearranged As Palindrome](strings/can_string_be_rearranged_as_palindrome.py) * [Capitalize](strings/capitalize.py) * [Check Anagrams](strings/check_anagrams.py) * [Count Vowels](strings/count_vowels.py) + * [Count Vowels Consonants](strings/count_vowels_consonants.py) * [Credit Card Validator](strings/credit_card_validator.py) * [Damerau Levenshtein Distance](strings/damerau_levenshtein_distance.py) * [Detecting English Programmatically](strings/detecting_english_programmatically.py) @@ -1286,6 +1602,7 @@ * [Indian Phone Validator](strings/indian_phone_validator.py) * [Is Contains Unique Chars](strings/is_contains_unique_chars.py) * [Is Isogram](strings/is_isogram.py) + * [Is Isomorphic](strings/is_isomorphic.py) * [Is Pangram](strings/is_pangram.py) * [Is Polish National Id](strings/is_polish_national_id.py) * [Is Spain National Id](strings/is_spain_national_id.py) @@ -1294,10 +1611,13 @@ * [Jaro Winkler](strings/jaro_winkler.py) * [Join](strings/join.py) * [Knuth Morris Pratt](strings/knuth_morris_pratt.py) + * [Largest Smallest Words](strings/largest_smallest_words.py) * [Levenshtein Distance](strings/levenshtein_distance.py) + * [Longest Word In Sentence](strings/longest_word_in_sentence.py) * [Lower](strings/lower.py) * [Manacher](strings/manacher.py) * [Min Cost String Conversion](strings/min_cost_string_conversion.py) + * [Min Window Substring](strings/min_window_substring.py) * [Naive String Search](strings/naive_string_search.py) * [Ngram](strings/ngram.py) * [Palindrome](strings/palindrome.py) @@ -1309,23 +1629,31 @@ * [Reverse Words](strings/reverse_words.py) * [Snake Case To Camel Pascal Case](strings/snake_case_to_camel_pascal_case.py) * [Split](strings/split.py) + * [String Is Valid Number](strings/string_is_valid_number.py) * [String Switch Case](strings/string_switch_case.py) * [Strip](strings/strip.py) + * [Suffix Automaton](strings/suffix_automaton.py) * [Text Justification](strings/text_justification.py) * [Title](strings/title.py) * [Top K Frequent Words](strings/top_k_frequent_words.py) * [Upper](strings/upper.py) - * [Wave](strings/wave.py) + * [Wave String](strings/wave_string.py) * [Wildcard Pattern Matching](strings/wildcard_pattern_matching.py) * [Word Occurrence](strings/word_occurrence.py) * [Word Patterns](strings/word_patterns.py) * [Z Function](strings/z_function.py) -## Web Programming +## [Tests](tests) + * [Test Find And Fix Pep798](tests/test_find_and_fix_pep798.py) + * [Test Sorts](tests/test_sorts.py) + +## [Web Programming](web_programming) * [Co2 Emission](web_programming/co2_emission.py) * [Covid Stats Via Xpath](web_programming/covid_stats_via_xpath.py) * [Crawl Google Results](web_programming/crawl_google_results.py) * [Crawl Google Scholar Citation](web_programming/crawl_google_scholar_citation.py) + * [Crypto Price](web_programming/crypto_price.py) + * [Crypto Price Tracker](web_programming/crypto_price_tracker.py) * [Currency Converter](web_programming/currency_converter.py) * [Current Stock Price](web_programming/current_stock_price.py) * [Current Weather](web_programming/current_weather.py) @@ -1343,7 +1671,6 @@ * [Get Ip Geolocation](web_programming/get_ip_geolocation.py) * [Get Top Billionaires](web_programming/get_top_billionaires.py) * [Get Top Hn Posts](web_programming/get_top_hn_posts.py) - * [Get User Tweets](web_programming/get_user_tweets.py) * [Giphy](web_programming/giphy.py) * [Instagram Crawler](web_programming/instagram_crawler.py) * [Instagram Pic](web_programming/instagram_pic.py) diff --git a/LICENSE.md b/LICENSE.md index 2897d02e2a01..de631c3ef333 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,4 +1,4 @@ -MIT License +## MIT License Copyright (c) 2016-2022 TheAlgorithms and contributors diff --git a/README.md b/README.md index d8eba4e016fa..e9a19fa15499 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@

The Algorithms - Python

+ @@ -16,9 +17,7 @@ Discord chat - - Gitter chat - +
@@ -27,23 +26,24 @@ pre-commit - - code style: black + + code style: black + -

All algorithms implemented in Python - for education

+

All algorithms implemented in Python - for education 📚

Implementations are for learning purposes only. They may be less efficient than the implementations in the Python standard library. Use them at your discretion. -## Getting Started +## 🚀 Getting Started -Read through our [Contribution Guidelines](CONTRIBUTING.md) before you contribute. +📋 Read through our [Contribution Guidelines](CONTRIBUTING.md) before you contribute. -## Community Channels +## 🌐 Community Channels -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! +We are on [Discord](https://the-algorithms.com/discord)! Community channels are a great way for you to ask questions and get help. Please join us! -## List of Algorithms +## 📜 List of Algorithms See our [directory](DIRECTORY.md) for easier navigation and a better overview of the project. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000000..f4ad026e4c71 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,41 @@ +# Security Policy + +## Supported Versions + +| Version | Supported | +| ------- | ------------------ | +| latest | :white_check_mark: | + +## Reporting a Vulnerability + +If you discover a security vulnerability in this project, please report it responsibly. + +**Please do NOT open a public issue for security vulnerabilities.** + +Instead, please send an email to the project maintainers or use GitHub's private vulnerability reporting feature. + +### What to include + +- A description of the vulnerability +- Steps to reproduce the issue +- Possible impact of the vulnerability +- Any suggested fixes (if applicable) + +### Response Timeline + +- **Acknowledgment**: Within 48 hours +- **Initial assessment**: Within 1 week +- **Fix or mitigation**: Depends on severity, typically within 2-4 weeks + +### After Reporting + +- The security team will validate the vulnerability +- We will work on a fix and coordinate disclosure +- Credit will be given to the reporter (unless anonymity is requested) + +## Security Best Practices for Contributors + +- Keep dependencies up to date +- Avoid committing sensitive information (API keys, passwords, tokens) +- Follow secure coding practices +- Review code changes for potential security implications diff --git a/audio_filters/README.md b/audio_filters/README.md index 4419bd8bdbf9..a28f2d6a9949 100644 --- a/audio_filters/README.md +++ b/audio_filters/README.md @@ -1,9 +1,58 @@ -# Audio Filter +# Audio Filters -Audio filters work on the frequency of an audio signal to attenuate unwanted frequency and amplify wanted ones. -They are used within anything related to sound, whether it is radio communication or a hi-fi system. +Audio filters work on the frequency of an audio signal to attenuate unwanted +frequencies and amplify wanted ones. They are used within anything related to +sound, whether it is radio communication or a hi-fi system. If you have ever +turned up the bass or cut the treble on a stereo, tuned a radio to a station, or +removed the background hum from a recording, you have used an audio filter. + +Curious to learn more? These are great starting points: * * * * +* + +## What's in this directory + +| File | Description | +| ---- | ----------- | +| [`iir_filter.py`](iir_filter.py) | A generic N-order [Infinite Impulse Response (IIR)](https://en.wikipedia.org/wiki/Infinite_impulse_response) filter. This is the engine every filter below runs on: give it a set of coefficients and it processes a stream of samples one at a time. | +| [`butterworth_filter.py`](butterworth_filter.py) | A collection of second-order [Butterworth](https://en.wikipedia.org/wiki/Butterworth_filter) / biquad filter designs from the RBJ Audio EQ Cookbook. Each function returns a ready-to-use `IIRFilter`. | +| [`equal_loudness_filter.py`](equal_loudness_filter.py) | An [equal-loudness](https://en.wikipedia.org/wiki/Equal-loudness_contour) filter that compensates for the human ear's non-linear response to sound by cascading a Yule-Walker filter and a Butterworth high-pass filter. Includes a dependency-free `yulewalk` implementation. | +| [`show_response.py`](show_response.py) | Helpers to plot the [magnitude and phase response](https://en.wikipedia.org/wiki/Frequency_response) of any filter so you can *see* what it does. | +| [`loudness_curve.json`](loudness_curve.json) | The Robinson-Dadson equal-loudness contour data used by the equal-loudness filter. | + +## Filter designs in `butterworth_filter.py` + +| Function | Effect | +| -------- | ------ | +| `make_lowpass` | Passes frequencies below the cutoff, attenuates those above it. | +| `make_highpass` | Passes frequencies above the cutoff, attenuates those below it. | +| `make_bandpass` | Passes a band of frequencies around the center (constant skirt gain). | +| `make_bandpass_peak` | Passes a band of frequencies around the center (constant 0 dB peak gain). | +| `make_notch` | Rejects a narrow band around the center — great for removing mains hum. | +| `make_allpass` | Passes all frequencies but changes their phase relationship. | +| `make_peak` | Boosts or cuts a band around the center by a given gain (parametric EQ). | +| `make_lowshelf` | Boosts or cuts everything below the cutoff. | +| `make_highshelf` | Boosts or cuts everything above the cutoff. | + +## Try it out + +```python +from audio_filters.butterworth_filter import make_lowpass +from audio_filters.show_response import show_frequency_response + +# A 5 kHz low-pass filter for CD-quality audio (44.1 kHz sample rate) +filt = make_lowpass(5000, 44100) + +# Process samples one at a time... +filtered = [filt.process(sample) for sample in my_audio_samples] + +# ...or visualise what the filter does to the spectrum: +show_frequency_response(make_lowpass(5000, 44100), 44100) +``` + +Every module has runnable doctests — read them for concrete, copy-pasteable +examples of each filter in action. diff --git a/audio_filters/butterworth_filter.py b/audio_filters/butterworth_filter.py index 4e6ea1b18fb4..1830b74e6b89 100644 --- a/audio_filters/butterworth_filter.py +++ b/audio_filters/butterworth_filter.py @@ -7,9 +7,51 @@ Code based on https://webaudio.github.io/Audio-EQ-Cookbook/audio-eq-cookbook.html Alternatively you can use scipy.signal.butter, which should yield the same results. + +https://en.wikipedia.org/wiki/Butterworth_filter + +Notation used throughout this module (from the RBJ Audio EQ Cookbook): + w0 -- normalised angular frequency, ``2 * pi * frequency / samplerate`` + alpha -- bandwidth parameter, ``sin(w0) / (2 * q_factor)`` + b0..b2 -- feed-forward (numerator) coefficients of the biquad + a0..a2 -- feed-back (denominator) coefficients of the biquad +The a/b coefficient names match ``IIRFilter.set_coefficients`` and the standard +biquad transfer function, so they are kept consistent across every filter here. """ +def _validate_frequency(frequency: int, samplerate: int, q_factor: float) -> None: + """ + Validate arguments shared by the Butterworth filter factories. + + >>> _validate_frequency(1000, 48000, 1 / sqrt(2)) + >>> _validate_frequency(0, 48000, 1 / sqrt(2)) + Traceback (most recent call last): + ... + ValueError: frequency must be a positive integer + >>> _validate_frequency(24000, 48000, 1 / sqrt(2)) + Traceback (most recent call last): + ... + ValueError: frequency must be less than half the samplerate + >>> _validate_frequency(1000, 0, 1 / sqrt(2)) + Traceback (most recent call last): + ... + ValueError: samplerate must be a positive integer + >>> _validate_frequency(1000, 48000, 0) + Traceback (most recent call last): + ... + ValueError: q_factor must be positive + """ + if not isinstance(frequency, int) or frequency <= 0: + raise ValueError("frequency must be a positive integer") + if not isinstance(samplerate, int) or samplerate <= 0: + raise ValueError("samplerate must be a positive integer") + if frequency >= samplerate / 2: + raise ValueError("frequency must be less than half the samplerate") + if q_factor <= 0: + raise ValueError("q_factor must be positive") + + def make_lowpass( frequency: int, samplerate: int, @@ -23,6 +65,7 @@ def make_lowpass( [1.0922959556412573, -1.9828897227476208, 0.9077040443587427, 0.004277569313094809, 0.008555138626189618, 0.004277569313094809] """ + _validate_frequency(frequency, samplerate, q_factor) w0 = tau * frequency / samplerate _sin = sin(w0) _cos = cos(w0) @@ -53,6 +96,7 @@ def make_highpass( [1.0922959556412573, -1.9828897227476208, 0.9077040443587427, 0.9957224306869052, -1.9914448613738105, 0.9957224306869052] """ + _validate_frequency(frequency, samplerate, q_factor) w0 = tau * frequency / samplerate _sin = sin(w0) _cos = cos(w0) @@ -83,6 +127,7 @@ def make_bandpass( [1.0922959556412573, -1.9828897227476208, 0.9077040443587427, 0.06526309611002579, 0, -0.06526309611002579] """ + _validate_frequency(frequency, samplerate, q_factor) w0 = tau * frequency / samplerate _sin = sin(w0) _cos = cos(w0) @@ -114,6 +159,7 @@ def make_allpass( [1.0922959556412573, -1.9828897227476208, 0.9077040443587427, 0.9077040443587427, -1.9828897227476208, 1.0922959556412573] """ + _validate_frequency(frequency, samplerate, q_factor) w0 = tau * frequency / samplerate _sin = sin(w0) _cos = cos(w0) @@ -142,6 +188,7 @@ def make_peak( [1.0653405327119334, -1.9828897227476208, 0.9346594672880666, 1.1303715025601122, -1.9828897227476208, 0.8696284974398878] """ + _validate_frequency(frequency, samplerate, q_factor) w0 = tau * frequency / samplerate _sin = sin(w0) _cos = cos(w0) @@ -174,6 +221,7 @@ def make_lowshelf( [3.0409336710888786, -5.608870992220748, 2.602157875636628, 3.139954022810743, -5.591841778072785, 2.5201667380627257] """ + _validate_frequency(frequency, samplerate, q_factor) w0 = tau * frequency / samplerate _sin = sin(w0) _cos = cos(w0) @@ -211,6 +259,7 @@ def make_highshelf( [2.2229172136088806, -3.9587208137297303, 1.7841414181566304, 4.295432981120543, -7.922740859457287, 3.6756456963725253] """ + _validate_frequency(frequency, samplerate, q_factor) w0 = tau * frequency / samplerate _sin = sin(w0) _cos = cos(w0) @@ -232,3 +281,81 @@ def make_highshelf( filt = IIRFilter(2) filt.set_coefficients([a0, a1, a2], [b0, b1, b2]) return filt + + +def make_notch( + frequency: int, + samplerate: int, + q_factor: float = 1 / sqrt(2), +) -> IIRFilter: + """ + Creates a notch (band-reject) filter that strongly attenuates a narrow band + of frequencies around ``frequency`` while leaving the rest of the spectrum + unchanged. It is the complement of the band-pass filter and is commonly used + to remove a single tone such as 50/60 Hz mains hum. + + https://en.wikipedia.org/wiki/Band-stop_filter + + >>> filter = make_notch(1000, 48000) + >>> filter.a_coeffs + filter.b_coeffs # doctest: +NORMALIZE_WHITESPACE + [1.0922959556412573, -1.9828897227476208, 0.9077040443587427, 1.0, + -1.9828897227476208, 1.0] + """ + w0 = tau * frequency / samplerate # centre frequency, in radians/sample + _sin = sin(w0) + _cos = cos(w0) + alpha = _sin / (2 * q_factor) # controls how narrow the rejected band is + + # Feed-forward: a pair of zeros placed exactly on the notch frequency, so + # that frequency is fully cancelled while the rest of the spectrum passes. + b0 = 1.0 + b1 = -2 * _cos + b2 = 1.0 + + # Feed-back: matching poles just inside the unit circle keep the notch + # narrow and the surrounding gain flat. + a0 = 1 + alpha + a1 = -2 * _cos + a2 = 1 - alpha + + filt = IIRFilter(2) + filt.set_coefficients([a0, a1, a2], [b0, b1, b2]) + return filt + + +def make_bandpass_peak( + frequency: int, + samplerate: int, + q_factor: float = 1 / sqrt(2), +) -> IIRFilter: + """ + Creates a band-pass filter with constant 0 dB peak gain. + + Unlike :func:`make_bandpass`, whose skirt (edge) gain is held constant so the + peak gain grows with ``q_factor``, this variant normalises the response so + the peak always reaches 0 dB regardless of the chosen ``q_factor``. Both + forms come from the RBJ Audio EQ Cookbook. + + https://en.wikipedia.org/wiki/Band-pass_filter + + >>> filter = make_bandpass_peak(1000, 48000) + >>> filter.a_coeffs + filter.b_coeffs # doctest: +NORMALIZE_WHITESPACE + [1.0922959556412573, -1.9828897227476208, 0.9077040443587427, + 0.09229595564125725, 0, -0.09229595564125725] + """ + w0 = tau * frequency / samplerate + _sin = sin(w0) + _cos = cos(w0) + alpha = _sin / (2 * q_factor) + + b0 = alpha + b1 = 0 + b2 = -alpha + + a0 = 1 + alpha + a1 = -2 * _cos + a2 = 1 - alpha + + filt = IIRFilter(2) + filt.set_coefficients([a0, a1, a2], [b0, b1, b2]) + return filt diff --git a/audio_filters/equal_loudness_filter.py b/audio_filters/equal_loudness_filter.py new file mode 100644 index 000000000000..387772aa1f50 --- /dev/null +++ b/audio_filters/equal_loudness_filter.py @@ -0,0 +1,198 @@ +from __future__ import annotations + +from json import loads +from pathlib import Path + +import numpy as np +from scipy.linalg import toeplitz +from scipy.signal import lfilter, unit_impulse + +from audio_filters.butterworth_filter import make_highpass +from audio_filters.iir_filter import IIRFilter + +data = loads((Path(__file__).resolve().parent / "loudness_curve.json").read_text()) + + +def _polystab(poly: np.ndarray) -> np.ndarray: + """ + Stabilize a polynomial by reflecting any roots that lie outside the unit + circle back inside it. This keeps the resulting IIR filter stable without + changing its magnitude response. + + https://en.wikipedia.org/wiki/Minimum_phase + + >>> np.round(_polystab(np.array([1.0, 2.0, 1.0])), 6) + array([1., 2., 1.]) + >>> np.round(_polystab(np.array([1.0, 2.0, 1.01])), 6) + array([1. , 1.980198, 0.990099]) + """ + if poly.size <= 1: + return poly + roots = np.roots(poly) + nonzero = np.where(roots != 0)[0] + outside = 0.5 * (np.sign(np.abs(roots[nonzero]) - 1) + 1) + roots[nonzero] = (1 - outside) * roots[nonzero] + outside / np.conj(roots[nonzero]) + stabilized = np.poly(roots) + if not np.imag(poly).any(): + stabilized = np.real(stabilized) + return stabilized + + +def _numerator( + impulse_response: np.ndarray, denominator: np.ndarray, numerator_order: int +) -> np.ndarray: + """ + Least-squares estimate of the numerator polynomial of a transfer function + given its impulse response and (already known) denominator polynomial. + + >>> num = _numerator(np.array([1.0, 0.0, 0.0]), np.array([1.0, 0.0, 0.0]), 1) + >>> np.round(num, 6) + array([1., 0.]) + """ + length = impulse_response.size + impulse = lfilter([1.0], denominator.ravel(), unit_impulse(length)) + toep = toeplitz(impulse, unit_impulse(numerator_order + 1)) + return np.linalg.lstsq(toep.conj(), impulse_response.ravel().conj(), rcond=None)[ + 0 + ].conj() + + +def yulewalk( + order: int, frequencies: np.ndarray, magnitudes: np.ndarray, npt: int = 512 +) -> tuple[np.ndarray, np.ndarray]: + """ + Design a recursive (IIR) digital filter that approximates an arbitrary + frequency response using the modified Yule-Walker method. This is a + dependency-free re-implementation of MATLAB/Octave's ``yulewalk`` so that + the equal-loudness filter below no longer relies on a third-party package. + + https://en.wikipedia.org/wiki/Autoregressive_model#Yule%E2%80%93Walker_equations + + :param order: order of the filter to design + :param frequencies: sample points on ``[0, 1]`` where 1 is the Nyquist + frequency, in increasing order and starting at 0 + :param magnitudes: desired (linear) magnitude at each point in ``frequencies`` + :param npt: number of points used to estimate the frequency response + :return: ``(a_coeffs, b_coeffs)``, the denominator and numerator polynomials + + >>> a, b = yulewalk(4, np.array([0.0, 0.5, 1.0]), np.array([1.0, 0.5, 0.0])) + >>> len(a), len(b) + (5, 5) + >>> bool(np.all(np.abs(np.roots(a)) < 1)) # the designed filter is stable + True + + Mismatched inputs and non-increasing frequencies are rejected: + + >>> yulewalk(4, np.array([0.0, 1.0]), np.array([1.0])) + Traceback (most recent call last): + ... + ValueError: frequencies and magnitudes must have the same length + >>> yulewalk(4, np.array([0.0, 1.0, 0.5]), np.array([1.0, 0.5, 0.0])) + Traceback (most recent call last): + ... + ValueError: frequencies must be in increasing order + """ + frequencies = np.asarray(frequencies, dtype=float).ravel() + magnitudes = np.asarray(magnitudes, dtype=float).ravel() + if frequencies.size != magnitudes.size: + msg = "frequencies and magnitudes must have the same length" + raise ValueError(msg) + if np.any(np.diff(frequencies) < 0): + msg = "frequencies must be in increasing order" + raise ValueError(msg) + + npt = npt + 1 + # Linearly interpolate the target response onto a dense grid, then mirror it + # to build the full (symmetric) magnitude spectrum. + response = np.interp(np.linspace(0, 1, npt), frequencies, magnitudes) + response = np.concatenate([response, response[-2:0:-1]]) + + total = response.size + half = (total + 1) // 2 + window_len = 4 * order + index = np.arange(window_len) + + # Autocorrelation from the power spectrum, tapered with a Hamming window. + correlation = np.real(np.fft.ifft(response * response)) + correlation = correlation[:window_len] * ( + 0.54 + 0.46 * np.cos(np.pi * index / (window_len - 1)) + ) + cepstral_window = np.concatenate([[0.5], np.ones(half - 1), np.zeros(total - half)]) + + # Solve the Yule-Walker normal equations for the denominator coefficients. + rmat = toeplitz(correlation[order : window_len - 1], correlation[order:0:-1]) + rhs = -correlation[order + 1 : window_len] + denominator = np.concatenate([[1.0], np.linalg.lstsq(rmat, rhs, rcond=None)[0]]) + denominator = _polystab(denominator) + + half_correlation = correlation.copy() + half_correlation[0] = correlation[0] / 2 + numerator = _numerator(half_correlation, denominator, order) + + padded_num = np.zeros(total) + padded_num[: numerator.size] = numerator + padded_den = np.zeros(total) + padded_den[: denominator.size] = denominator + + spectrum = 2 * np.real(np.fft.fft(padded_num) / np.fft.fft(padded_den)) + complex_log = np.log(np.abs(spectrum)) + 1j * np.angle(spectrum) + cepstrum = np.fft.ifft( + np.exp(np.fft.fft(cepstral_window * np.fft.ifft(complex_log))) + ) + numerator = np.real(_numerator(cepstrum[:window_len], denominator, order)) + return denominator, numerator + + +class EqualLoudnessFilter: + r""" + An equal-loudness filter which compensates for the human ear's non-linear + response to sound. This filter corrects this by cascading a Yule-Walker + filter and a Butterworth filter. + + Designed for use with samplerate of 44.1kHz and above. If you're using a + lower samplerate, use with caution. + + Code based on the matlab implementation at https://bit.ly/3eqh2HU + (url shortened for ruff) + + Target curve: https://i.imgur.com/3g2VfaM.png + Yulewalk response: https://i.imgur.com/J9LnJ4C.png + Butterworth and overall response: https://i.imgur.com/3g2VfaM.png + + Images and original matlab implementation by David Robinson, 2001 + + https://en.wikipedia.org/wiki/Equal-loudness_contour + + >>> filt = EqualLoudnessFilter() + >>> isinstance(filt.yulewalk_filter, IIRFilter) + True + """ + + def __init__(self, samplerate: int = 44100) -> None: + self.yulewalk_filter = IIRFilter(10) + self.butterworth_filter = make_highpass(150, samplerate) + + # pad the data to nyquist + curve_freqs = np.array(data["frequencies"] + [max(20000.0, samplerate / 2)]) + curve_gains = np.array(data["gains"] + [140]) + + # Convert to angular frequency + freqs_normalized = curve_freqs / samplerate * 2 + # Invert the curve and normalize to 0dB + gains_normalized = np.power(10, (np.min(curve_gains) - curve_gains) / 20) + + # Compute the coefficients using a least-squares fit to the curve with + # the built-in ``yulewalk`` implementation above (no third-party deps). + ya, yb = yulewalk(10, freqs_normalized, gains_normalized) + self.yulewalk_filter.set_coefficients(ya.tolist(), yb.tolist()) + + def process(self, sample: float) -> float: + """ + Process a single sample through both filters + + >>> filt = EqualLoudnessFilter() + >>> filt.process(0.0) + 0.0 + """ + tmp = self.yulewalk_filter.process(sample) + return self.butterworth_filter.process(tmp) diff --git a/audio_filters/equal_loudness_filter.py.broken.txt b/audio_filters/equal_loudness_filter.py.broken.txt deleted file mode 100644 index 88cba8533cf7..000000000000 --- a/audio_filters/equal_loudness_filter.py.broken.txt +++ /dev/null @@ -1,61 +0,0 @@ -from json import loads -from pathlib import Path - -import numpy as np -from yulewalker import yulewalk - -from audio_filters.butterworth_filter import make_highpass -from audio_filters.iir_filter import IIRFilter - -data = loads((Path(__file__).resolve().parent / "loudness_curve.json").read_text()) - - -class EqualLoudnessFilter: - r""" - An equal-loudness filter which compensates for the human ear's non-linear response - to sound. - This filter corrects this by cascading a yulewalk filter and a butterworth filter. - - Designed for use with samplerate of 44.1kHz and above. If you're using a lower - samplerate, use with caution. - - Code based on matlab implementation at https://bit.ly/3eqh2HU - (url shortened for ruff) - - Target curve: https://i.imgur.com/3g2VfaM.png - Yulewalk response: https://i.imgur.com/J9LnJ4C.png - Butterworth and overall response: https://i.imgur.com/3g2VfaM.png - - Images and original matlab implementation by David Robinson, 2001 - """ - - def __init__(self, samplerate: int = 44100) -> None: - self.yulewalk_filter = IIRFilter(10) - self.butterworth_filter = make_highpass(150, samplerate) - - # pad the data to nyquist - curve_freqs = np.array(data["frequencies"] + [max(20000.0, samplerate / 2)]) - curve_gains = np.array(data["gains"] + [140]) - - # Convert to angular frequency - freqs_normalized = curve_freqs / samplerate * 2 - # Invert the curve and normalize to 0dB - gains_normalized = np.power(10, (np.min(curve_gains) - curve_gains) / 20) - - # Scipy's `yulewalk` function is a stub, so we're using the - # `yulewalker` library instead. - # This function computes the coefficients using a least-squares - # fit to the specified curve. - ya, yb = yulewalk(10, freqs_normalized, gains_normalized) - self.yulewalk_filter.set_coefficients(ya, yb) - - def process(self, sample: float) -> float: - """ - Process a single sample through both filters - - >>> filt = EqualLoudnessFilter() - >>> filt.process(0.0) - 0.0 - """ - tmp = self.yulewalk_filter.process(sample) - return self.butterworth_filter.process(tmp) diff --git a/audio_filters/iir_filter.py b/audio_filters/iir_filter.py index f3c1ad43b001..2144e6bd4c7a 100644 --- a/audio_filters/iir_filter.py +++ b/audio_filters/iir_filter.py @@ -10,13 +10,17 @@ class IIRFilter: Implementation details: Based on the 2nd-order function from - https://en.wikipedia.org/wiki/Digital_biquad_filter, + https://en.wikipedia.org/wiki/Digital_biquad_filter, this generalized N-order function was made. Using the following transfer function - H(z)=\frac{b_{0}+b_{1}z^{-1}+b_{2}z^{-2}+...+b_{k}z^{-k}}{a_{0}+a_{1}z^{-1}+a_{2}z^{-2}+...+a_{k}z^{-k}} + .. math:: H(z)=\frac{b_{0}+b_{1}z^{-1}+b_{2}z^{-2}+...+b_{k}z^{-k}} + {a_{0}+a_{1}z^{-1}+a_{2}z^{-2}+...+a_{k}z^{-k}} + we can rewrite this to - y[n]={\frac{1}{a_{0}}}\left(\left(b_{0}x[n]+b_{1}x[n-1]+b_{2}x[n-2]+...+b_{k}x[n-k]\right)-\left(a_{1}y[n-1]+a_{2}y[n-2]+...+a_{k}y[n-k]\right)\right) + .. math:: y[n]={\frac{1}{a_{0}}} + \left(\left(b_{0}x[n]+b_{1}x[n-1]+b_{2}x[n-2]+...+b_{k}x[n-k]\right)- + \left(a_{1}y[n-1]+a_{2}y[n-2]+...+a_{k}y[n-k]\right)\right) """ def __init__(self, order: int) -> None: @@ -34,19 +38,50 @@ def __init__(self, order: int) -> None: def set_coefficients(self, a_coeffs: list[float], b_coeffs: list[float]) -> None: """ - Set the coefficients for the IIR filter. These should both be of size order + 1. - a_0 may be left out, and it will use 1.0 as default value. + Set the coefficients for the IIR filter. + These should both be of size `order` + 1. + :math:`a_0` may be left out, and it will use 1.0 as default value. This method works well with scipy's filter design functions - >>> # Make a 2nd-order 1000Hz butterworth lowpass filter - >>> import scipy.signal - >>> b_coeffs, a_coeffs = scipy.signal.butter(2, 1000, - ... btype='lowpass', - ... fs=48000) - >>> filt = IIRFilter(2) - >>> filt.set_coefficients(a_coeffs, b_coeffs) + + >>> # Make a 2nd-order 1000Hz butterworth lowpass filter + >>> import scipy.signal + >>> b_coeffs, a_coeffs = scipy.signal.butter(2, 1000, + ... btype='lowpass', + ... fs=48000) + >>> filt = IIRFilter(2) + >>> filt.set_coefficients(a_coeffs, b_coeffs) + + The leading :math:`a_0` coefficient may be omitted and defaults to 1.0: + + >>> filt = IIRFilter(2) + >>> filt.set_coefficients([-1.9, 0.9], [1.0, -2.0, 1.0]) + >>> filt.a_coeffs + [1.0, -1.9, 0.9] + + Passing the wrong number of coefficients raises a ``ValueError``: + + >>> IIRFilter(2).set_coefficients([1.0, 2.0, 3.0, 4.0], [1.0, 2.0, 3.0]) + Traceback (most recent call last): + ... + ValueError: Expected a_coeffs to have 3 elements for 2-order filter, got 4 + >>> IIRFilter(2).set_coefficients([1.0, 2.0, 3.0], [1.0, 2.0]) + Traceback (most recent call last): + ... + ValueError: Expected b_coeffs to have 3 elements for 2-order filter, got 2 + + A genuinely too-short ``a_coeffs`` is reported with its real length + rather than after the optional ``a_0`` has been filled in: + + >>> IIRFilter(2).set_coefficients([1.0], [1.0, 2.0, 3.0]) + Traceback (most recent call last): + ... + ValueError: Expected a_coeffs to have 3 elements for 2-order filter, got 1 """ - if len(a_coeffs) < self.order: + if len(a_coeffs) == self.order: + # The leading a_0 coefficient is optional; default it to 1.0. + # Only a single missing coefficient is filled in this way, so that + # genuinely too-short inputs are reported with their real length. a_coeffs = [1.0, *a_coeffs] if len(a_coeffs) != self.order + 1: @@ -59,7 +94,7 @@ def set_coefficients(self, a_coeffs: list[float], b_coeffs: list[float]) -> None if len(b_coeffs) != self.order + 1: msg = ( f"Expected b_coeffs to have {self.order + 1} elements " - f"for {self.order}-order filter, got {len(a_coeffs)}" + f"for {self.order}-order filter, got {len(b_coeffs)}" ) raise ValueError(msg) @@ -68,7 +103,7 @@ def set_coefficients(self, a_coeffs: list[float], b_coeffs: list[float]) -> None def process(self, sample: float) -> float: """ - Calculate y[n] + Calculate :math:`y[n]` >>> filt = IIRFilter(2) >>> filt.process(0) diff --git a/audio_filters/show_response.py b/audio_filters/show_response.py index f9c9537c047c..5830db0a2a38 100644 --- a/audio_filters/show_response.py +++ b/audio_filters/show_response.py @@ -1,3 +1,9 @@ +""" +Plot the magnitude and phase response of an audio filter. + +https://en.wikipedia.org/wiki/Frequency_response +""" + from __future__ import annotations from abc import abstractmethod diff --git a/backtracking/all_combinations.py b/backtracking/all_combinations.py index 390decf3a05b..1d15c6263e14 100644 --- a/backtracking/all_combinations.py +++ b/backtracking/all_combinations.py @@ -12,6 +12,8 @@ def combination_lists(n: int, k: int) -> list[list[int]]: """ + Generates all possible combinations of k numbers out of 1 ... n using itertools. + >>> combination_lists(n=4, k=2) [[1, 2], [1, 3], [1, 4], [2, 3], [2, 4], [3, 4]] """ @@ -20,6 +22,8 @@ def combination_lists(n: int, k: int) -> list[list[int]]: def generate_all_combinations(n: int, k: int) -> list[list[int]]: """ + Generates all possible combinations of k numbers out of 1 ... n using backtracking. + >>> generate_all_combinations(n=4, k=2) [[1, 2], [1, 3], [1, 4], [2, 3], [2, 4], [3, 4]] >>> generate_all_combinations(n=0, k=0) @@ -34,6 +38,14 @@ def generate_all_combinations(n: int, k: int) -> list[list[int]]: ValueError: n must not be negative >>> generate_all_combinations(n=5, k=4) [[1, 2, 3, 4], [1, 2, 3, 5], [1, 2, 4, 5], [1, 3, 4, 5], [2, 3, 4, 5]] + >>> generate_all_combinations(n=3, k=3) + [[1, 2, 3]] + >>> generate_all_combinations(n=3, k=1) + [[1], [2], [3]] + >>> generate_all_combinations(n=1, k=0) + [[]] + >>> generate_all_combinations(n=1, k=1) + [[1]] >>> from itertools import combinations >>> all(generate_all_combinations(n, k) == combination_lists(n, k) ... for n in range(1, 6) for k in range(1, 6)) @@ -56,6 +68,28 @@ def create_all_state( current_list: list[int], total_list: list[list[int]], ) -> None: + """ + Helper function to recursively build all combinations. + + >>> create_all_state(1, 4, 2, [], result := []) + >>> result + [[1, 2], [1, 3], [1, 4], [2, 3], [2, 4], [3, 4]] + >>> create_all_state(1, 3, 3, [], result := []) + >>> result + [[1, 2, 3]] + >>> create_all_state(2, 2, 1, [1], result := []) + >>> result + [[1, 2]] + >>> create_all_state(1, 0, 0, [], result := []) + >>> result + [[]] + >>> create_all_state(1, 4, 0, [1, 2], result := []) + >>> result + [[1, 2]] + >>> create_all_state(5, 4, 2, [1, 2], result := []) + >>> result + [] + """ if level == 0: total_list.append(current_list[:]) return diff --git a/backtracking/all_permutations.py b/backtracking/all_permutations.py index f376e6fa0945..691b2a2b7592 100644 --- a/backtracking/all_permutations.py +++ b/backtracking/all_permutations.py @@ -10,6 +10,16 @@ def generate_all_permutations(sequence: list[int | str]) -> None: + """ + Generate and print all possible permutations of the given sequence. + + >>> generate_all_permutations([1, 2]) + [1, 2] + [2, 1] + >>> generate_all_permutations(["A", "B"]) + ['A', 'B'] + ['B', 'A'] + """ create_state_space_tree(sequence, [], 0, [0 for i in range(len(sequence))]) diff --git a/backtracking/all_subsequences.py b/backtracking/all_subsequences.py index 18696054eb7e..43ae4fed747c 100644 --- a/backtracking/all_subsequences.py +++ b/backtracking/all_subsequences.py @@ -12,6 +12,21 @@ def generate_all_subsequences(sequence: list[Any]) -> None: + """ + Generate and print all possible subsequences of the given sequence. + + >>> generate_all_subsequences([1, 2]) + [] + [2] + [1] + [1, 2] + >>> generate_all_subsequences(["A", "B"]) + [] + ['B'] + ['A'] + ['A', 'B'] + """ + create_state_space_tree(sequence, [], 0) diff --git a/backtracking/coloring.py b/backtracking/coloring.py index f10cdbcf9d26..923f8bb65927 100644 --- a/backtracking/coloring.py +++ b/backtracking/coloring.py @@ -1,7 +1,7 @@ """ -Graph Coloring also called "m coloring problem" -consists of coloring a given graph with at most m colors -such that no adjacent vertices are assigned the same color +Graph Coloring (also called the "m coloring problem") is the problem of +assigning at most 'm' colors to the vertices of a graph such that +no two adjacent vertices share the same color. Wikipedia: https://en.wikipedia.org/wiki/Graph_coloring """ @@ -11,13 +11,31 @@ def valid_coloring( neighbours: list[int], colored_vertices: list[int], color: int ) -> bool: """ + Check if a given vertex can be assigned the specified color + without violating the graph coloring constraints (i.e., no two adjacent vertices + have the same color). + + Procedure: For each neighbour check if the coloring constraint is satisfied If any of the neighbours fail the constraint return False If all neighbours validate the constraint return True - >>> neighbours = [0,1,0,1,0] + Parameters: + neighbours: The list representing which vertices + are adjacent to the current vertex. + 1 indicates an edge between the current vertex + and the neighbour. + colored_vertices: List of current color assignments for all vertices + (-1 means uncolored). + color: The color we are trying to assign to the current vertex. + + Returns: + True if the vertex can be safely colored with the given color, + otherwise False. + + Examples: + >>> neighbours = [0, 1, 0, 1, 0] >>> colored_vertices = [0, 2, 1, 2, 0] - >>> color = 1 >>> valid_coloring(neighbours, colored_vertices, color) True @@ -25,8 +43,14 @@ def valid_coloring( >>> color = 2 >>> valid_coloring(neighbours, colored_vertices, color) False + + >>> neighbors = [1, 0, 1, 0] + >>> colored_vertices = [-1, -1, -1, -1] + >>> color = 0 + >>> valid_coloring(neighbors, colored_vertices, color) + True """ - # Does any neighbour not satisfy the constraints + # Check if any adjacent vertex has already been colored with the same color return not any( neighbour == 1 and colored_vertices[i] == color for i, neighbour in enumerate(neighbours) @@ -37,7 +61,7 @@ def util_color( graph: list[list[int]], max_colors: int, colored_vertices: list[int], index: int ) -> bool: """ - Pseudo-Code + Recursive function to try and color the graph using backtracking. Base Case: 1. Check if coloring is complete @@ -51,6 +75,20 @@ def util_color( 2.4. if current coloring leads to a solution return 2.5. Uncolor given vertex + Parameters: + graph: Adjacency matrix representing the graph. + graph[i][j] is 1 if there is an edge + between vertex i and j. + max_colors: Maximum number of colors allowed (m in the m-coloring problem). + colored_vertices: Current color assignments for each vertex. + -1 indicates that the vertex has not been colored + yet. + index: The current vertex index being processed. + + Returns: + True if the graph can be colored using at most max_colors, otherwise False. + + Examples: >>> graph = [[0, 1, 0, 0, 0], ... [1, 0, 1, 0, 1], ... [0, 1, 0, 1, 0], @@ -67,36 +105,47 @@ def util_color( >>> util_color(graph, max_colors, colored_vertices, index) False """ - - # Base Case + # Base Case: If all vertices have been assigned a color, we have a valid solution if index == len(graph): return True - # Recursive Step - for i in range(max_colors): - if valid_coloring(graph[index], colored_vertices, i): - # Color current vertex - colored_vertices[index] = i - # Validate coloring + # Try each color for the current vertex + for color in range(max_colors): + # Check if it's valid to color the current vertex with 'color' + if valid_coloring(graph[index], colored_vertices, color): + colored_vertices[index] = color # Assign color + # Recur to color the rest of the vertices if util_color(graph, max_colors, colored_vertices, index + 1): return True - # Backtrack + # Backtrack if no solution found with the current assignment colored_vertices[index] = -1 - return False + + return False # Return False if no valid coloring is possible def color(graph: list[list[int]], max_colors: int) -> list[int]: """ - Wrapper function to call subroutine called util_color - which will either return True or False. - If True is returned colored_vertices list is filled with correct colorings - + Attempt to color the graph with at most max_colors colors such that no two adjacent + vertices have the same color. + If it is possible, returns the list of color assignments; + otherwise, returns an empty list. + + Parameters: + graph: Adjacency matrix representing the graph. + max_colors: Maximum number of colors allowed. + + Returns: + List of color assignments if the graph can be colored using max_colors. + Each index in the list represents the color assigned + to the corresponding vertex. + If coloring is not possible, returns an empty list. + + Examples: >>> graph = [[0, 1, 0, 0, 0], ... [1, 0, 1, 0, 1], ... [0, 1, 0, 1, 0], ... [0, 1, 1, 0, 0], ... [0, 1, 0, 0, 0]] - >>> max_colors = 3 >>> color(graph, max_colors) [0, 1, 0, 2, 0] @@ -104,10 +153,34 @@ def color(graph: list[list[int]], max_colors: int) -> list[int]: >>> max_colors = 2 >>> color(graph, max_colors) [] + + >>> graph = [[0, 1], [1, 0]] # Simple 2-node graph + >>> max_colors = 2 + >>> color(graph, max_colors) + [0, 1] + + >>> graph = [[0, 1, 1], [1, 0, 1], [1, 1, 0]] # Complete graph of 3 vertices + >>> max_colors = 2 + >>> color(graph, max_colors) + [] + + >>> max_colors = 3 + >>> color(graph, max_colors) + [0, 1, 2] + >>> color([], 2) # empty graph + [] + >>> color([[0]], 1) # single node, 1 color + [0] + >>> color([[0, 1], [1, 0]], 1) # 2 nodes, 1 color (impossible) + [] + >>> color([[0, 1], [1, 0]], 2) # 2 nodes, 2 colors (possible) + [0, 1] """ + # Initialize all vertices as uncolored (-1) colored_vertices = [-1] * len(graph) + # Use the utility function to try and color the graph starting from vertex 0 if util_color(graph, max_colors, colored_vertices, 0): - return colored_vertices + return colored_vertices # The successful color assignment - return [] + return [] # No valid coloring is possible diff --git a/backtracking/combination_sum.py b/backtracking/combination_sum.py index 3c6ed81f44f0..3d954f11d2c5 100644 --- a/backtracking/combination_sum.py +++ b/backtracking/combination_sum.py @@ -47,8 +47,18 @@ def combination_sum(candidates: list, target: int) -> list: >>> combination_sum([-8, 2.3, 0], 1) Traceback (most recent call last): ... - RecursionError: maximum recursion depth exceeded + ValueError: All elements in candidates must be non-negative + >>> combination_sum([], 1) + Traceback (most recent call last): + ... + ValueError: Candidates list should not be empty """ + if not candidates: + raise ValueError("Candidates list should not be empty") + + if any(x < 0 for x in candidates): + raise ValueError("All elements in candidates must be non-negative") + path = [] # type: list[int] answer = [] # type: list[int] backtrack(candidates, path, answer, target, 0) diff --git a/backtracking/crossword_puzzle_solver.py b/backtracking/crossword_puzzle_solver.py index e702c7e52153..e510909cfc41 100644 --- a/backtracking/crossword_puzzle_solver.py +++ b/backtracking/crossword_puzzle_solver.py @@ -6,29 +6,28 @@ def is_valid( ) -> bool: """ Check if a word can be placed at the given position. + A cell is valid if it is empty or already contains the correct letter + (enabling crossing/intersection between words). - >>> puzzle = [ - ... ['', '', '', ''], - ... ['', '', '', ''], - ... ['', '', '', ''], - ... ['', '', '', ''] - ... ] + >>> puzzle = [['', '', '', ''], ['', '', '', ''], + ... ['', '', '', ''], ['', '', '', '']] >>> is_valid(puzzle, 'word', 0, 0, True) True - >>> puzzle = [ - ... ['', '', '', ''], - ... ['', '', '', ''], - ... ['', '', '', ''], - ... ['', '', '', ''] - ... ] >>> is_valid(puzzle, 'word', 0, 0, False) True + >>> puzzle2 = [['w', '', ''], ['o', '', ''], ['r', '', ''], ['d', '', '']] + >>> is_valid(puzzle2, 'word', 0, 0, True) + True + >>> is_valid(puzzle2, 'cat', 0, 0, True) + False """ - for i in range(len(word)): - if vertical: - if row + i >= len(puzzle) or puzzle[row + i][col] != "": - return False - elif col + i >= len(puzzle[0]) or puzzle[row][col + i] != "": + rows, cols = len(puzzle), len(puzzle[0]) + for i, ch in enumerate(word): + r, c = (row + i, col) if vertical else (row, col + i) + if r >= rows or c >= cols: + return False + cell = puzzle[r][c] + if cell not in ("", ch): return False return True @@ -37,95 +36,87 @@ def place_word( puzzle: list[list[str]], word: str, row: int, col: int, vertical: bool ) -> None: """ - Place a word at the given position. - - >>> puzzle = [ - ... ['', '', '', ''], - ... ['', '', '', ''], - ... ['', '', '', ''], - ... ['', '', '', ''] - ... ] + Place a word at the given position in the puzzle. + + >>> puzzle = [['', '', '', ''], ['', '', '', ''], + ... ['', '', '', ''], ['', '', '', '']] >>> place_word(puzzle, 'word', 0, 0, True) >>> puzzle [['w', '', '', ''], ['o', '', '', ''], ['r', '', '', ''], ['d', '', '', '']] """ - for i, char in enumerate(word): + for i, ch in enumerate(word): if vertical: - puzzle[row + i][col] = char + puzzle[row + i][col] = ch else: - puzzle[row][col + i] = char + puzzle[row][col + i] = ch def remove_word( - puzzle: list[list[str]], word: str, row: int, col: int, vertical: bool + puzzle: list[list[str]], + word: str, + row: int, + col: int, + vertical: bool, + snapshot: list[list[str]], ) -> None: """ - Remove a word from the given position. - - >>> puzzle = [ - ... ['w', '', '', ''], - ... ['o', '', '', ''], - ... ['r', '', '', ''], - ... ['d', '', '', ''] - ... ] - >>> remove_word(puzzle, 'word', 0, 0, True) + Remove a word from the puzzle, restoring only cells that were empty + before placement. Cells shared with crossing words are preserved. + + >>> puzzle = [['w', 'o', 'r', 'd'], ['', '', '', ''], + ... ['', '', '', ''], ['', '', '', '']] + >>> snap = [['', 'o', 'r', 'd'], ['', '', '', ''], + ... ['', '', '', ''], ['', '', '', '']] + >>> remove_word(puzzle, 'word', 0, 0, False, snap) >>> puzzle - [['', '', '', ''], ['', '', '', ''], ['', '', '', ''], ['', '', '', '']] + [['', 'o', 'r', 'd'], ['', '', '', ''], ['', '', '', ''], ['', '', '', '']] """ for i in range(len(word)): - if vertical: - puzzle[row + i][col] = "" - else: - puzzle[row][col + i] = "" + r, c = (row + i, col) if vertical else (row, col + i) + if snapshot[r][c] == "": + puzzle[r][c] = "" def solve_crossword(puzzle: list[list[str]], words: list[str]) -> bool: """ Solve the crossword puzzle using backtracking. + Words are tried longest-first to prune the search space early. + Intersections between words (shared letters) are supported. - >>> puzzle = [ - ... ['', '', '', ''], - ... ['', '', '', ''], - ... ['', '', '', ''], - ... ['', '', '', ''] - ... ] - - >>> words = ['word', 'four', 'more', 'last'] - >>> solve_crossword(puzzle, words) + >>> puzzle = [['', '', '', ''], ['', '', '', ''], + ... ['', '', '', ''], ['', '', '', '']] + >>> solve_crossword(puzzle, ['word', 'four', 'more', 'last']) True - >>> puzzle = [ - ... ['', '', '', ''], - ... ['', '', '', ''], - ... ['', '', '', ''], - ... ['', '', '', ''] - ... ] - >>> words = ['word', 'four', 'more', 'paragraphs'] - >>> solve_crossword(puzzle, words) + >>> puzzle2 = [['', '', '', ''], ['', '', '', ''], + ... ['', '', '', ''], ['', '', '', '']] + >>> solve_crossword(puzzle2, ['word', 'four', 'more', 'paragraphs']) False """ + if not words: + return True + + remaining = sorted(words, key=len, reverse=True) + word, rest = remaining[0], remaining[1:] + for row in range(len(puzzle)): for col in range(len(puzzle[0])): - if puzzle[row][col] == "": - for word in words: - for vertical in [True, False]: - if is_valid(puzzle, word, row, col, vertical): - place_word(puzzle, word, row, col, vertical) - words.remove(word) - if solve_crossword(puzzle, words): - return True - words.append(word) - remove_word(puzzle, word, row, col, vertical) - return False - return True + for vertical in (True, False): + if is_valid(puzzle, word, row, col, vertical): + snapshot = [r[:] for r in puzzle] + place_word(puzzle, word, row, col, vertical) + if solve_crossword(puzzle, rest): + return True + remove_word(puzzle, word, row, col, vertical, snapshot) + + return False if __name__ == "__main__": PUZZLE = [[""] * 3 for _ in range(3)] WORDS = ["cat", "dog", "car"] - if solve_crossword(PUZZLE, WORDS): print("Solution found:") for row in PUZZLE: - print(" ".join(row)) + print(" ".join(cell or "." for cell in row)) else: - print("No solution found:") + print("No solution found.") diff --git a/backtracking/generate_parentheses.py b/backtracking/generate_parentheses.py index 18c21e2a9b51..5094f4b08619 100644 --- a/backtracking/generate_parentheses.py +++ b/backtracking/generate_parentheses.py @@ -64,6 +64,10 @@ def generate_parenthesis(n: int) -> list[str]: Example 2: >>> generate_parenthesis(1) ['()'] + + Example 3: + >>> generate_parenthesis(0) + [''] """ result: list[str] = [] diff --git a/backtracking/generate_parentheses_iterative.py b/backtracking/generate_parentheses_iterative.py new file mode 100644 index 000000000000..84c032f52dc4 --- /dev/null +++ b/backtracking/generate_parentheses_iterative.py @@ -0,0 +1,67 @@ +def generate_parentheses_iterative(length: int) -> list[str]: + """ + Generate all valid combinations of parentheses (Iterative Approach). + + The algorithm works as follows: + 1. Initialize an empty list to store the combinations. + 2. Initialize a stack to keep track of partial combinations. + 3. Start with empty string and push it on stack along with + the counts of '(' and ')'. + 4. While the stack is not empty: + a. Pop a partial combination and its open and close counts from the stack. + b. If the combination length is equal to 2*length, add it to the result. + c. If open count < length, push new combination with added '(' on stack. + d. If close count < open count, push new combination with added ')' on stack. + 5. Return the result containing all valid combinations. + + Args: + length: The desired length of the parentheses combinations + + Returns: + A list of strings representing valid combinations of parentheses + + Time Complexity: + O(2^(2*length)) + + Space Complexity: + O(2^(2*length)) + + >>> generate_parentheses_iterative(3) + ['()()()', '()(())', '(())()', '(()())', '((()))'] + >>> generate_parentheses_iterative(2) + ['()()', '(())'] + >>> generate_parentheses_iterative(1) + ['()'] + >>> generate_parentheses_iterative(0) + [''] + """ + if length == 0: + return [""] + + result: list[str] = [] + stack: list[tuple[str, int, int]] = [] + + # Each element in stack is a tuple (current_combination, open_count, close_count) + stack.append(("", 0, 0)) + + while stack: + current_combination, open_count, close_count = stack.pop() + + if len(current_combination) == 2 * length: + result.append(current_combination) + continue + + if open_count < length: + stack.append((current_combination + "(", open_count + 1, close_count)) + + if close_count < open_count: + stack.append((current_combination + ")", open_count, close_count + 1)) + + return result + + +if __name__ == "__main__": + import doctest + + doctest.testmod() + print(generate_parentheses_iterative(3)) diff --git a/backtracking/m_coloring_problem.py b/backtracking/m_coloring_problem.py new file mode 100644 index 000000000000..89de4c09e10b --- /dev/null +++ b/backtracking/m_coloring_problem.py @@ -0,0 +1,86 @@ +def is_safe( + node: int, + color: int, + graph: list[list[int]], + num_vertices: int, + col: list[int], +) -> bool: + """ + Check if it is safe to assign a color to a node. + + >>> is_safe(0, 1, [[0,1],[1,0]], 2, [0,1]) + False + >>> is_safe(0, 2, [[0,1],[1,0]], 2, [0,1]) + True + """ + return all( + not (graph[node][k] == 1 and col[k] == color) for k in range(num_vertices) + ) + + +def solve( + node: int, + col: list[int], + max_colors: int, + num_vertices: int, + graph: list[list[int]], +) -> bool: + """ + Recursively try to color the graph using at most max_colors. + + >>> solve(0, [0]*3, 3, 3, [[0,1,0],[1,0,1],[0,1,0]]) + True + >>> solve(0, [0]*3, 2, 3, [[0,1,0],[1,0,1],[0,1,0]]) + True + """ + if node == num_vertices: + return True + for c in range(1, max_colors + 1): + if is_safe(node, c, graph, num_vertices, col): + col[node] = c + if solve(node + 1, col, max_colors, num_vertices, graph): + return True + col[node] = 0 + return False + + +def graph_coloring(graph: list[list[int]], max_colors: int, num_vertices: int) -> bool: + """ + Determine if the graph can be colored with at most max_colors. + + >>> graph_coloring([[0,1,1],[1,0,1],[1,1,0]], 3, 3) + True + >>> graph_coloring([[0,1,1],[1,0,1],[1,1,0]], 2, 3) + False + """ + col = [0] * num_vertices + return solve(0, col, max_colors, num_vertices, graph) + + +if __name__ == "__main__": + import doctest + + doctest.testmod() + + num_vertices = int(input("Enter vertices: ")) + num_edges = int(input("Enter edges: ")) + graph = [[0] * num_vertices for _ in range(num_vertices)] + + print("Enter edges (u v):") + for _ in range(num_edges): + try: + u, v = map(int, input().split()) + if 0 <= u < num_vertices and 0 <= v < num_vertices: + graph[u][v] = 1 + graph[v][u] = 1 + else: + print("Invalid edge.") + except ValueError: + print("Invalid input.") + + max_colors = int(input("Enter max colors: ")) + + if graph_coloring(graph, max_colors, num_vertices): + print("Coloring possible.") + else: + print("Coloring not possible.") diff --git a/backtracking/minimax.py b/backtracking/minimax.py index 4eef90b75483..96fd88cd5afa 100644 --- a/backtracking/minimax.py +++ b/backtracking/minimax.py @@ -46,6 +46,10 @@ def minimax( Traceback (most recent call last): ... ValueError: Scores cannot be empty + >>> minimax(0, 0, True, [1, 2, 3], 2) + Traceback (most recent call last): + ... + ValueError: Number of scores must be a power of 2 >>> scores = [3, 5, 2, 9, 12, 5, 23, 23] >>> height = math.log(len(scores), 2) >>> minimax(0, 0, True, scores, height) @@ -56,6 +60,8 @@ def minimax( raise ValueError("Depth cannot be less than 0") if len(scores) == 0: raise ValueError("Scores cannot be empty") + if len(scores) & (len(scores) - 1) != 0: + raise ValueError("Number of scores must be a power of 2") # Base case: If the current depth equals the height of the tree, # return the score of the current node. diff --git a/backtracking/n_queens.py b/backtracking/n_queens.py index 81668b17a0ac..6fac93aa77d6 100644 --- a/backtracking/n_queens.py +++ b/backtracking/n_queens.py @@ -27,21 +27,36 @@ def is_safe(board: list[list[int]], row: int, column: int) -> bool: >>> is_safe([[0, 0, 0], [0, 0, 0], [0, 0, 0]], 1, 1) True + >>> is_safe([[0, 1, 0], [0, 0, 0], [0, 0, 0]], 1, 1) + False >>> is_safe([[1, 0, 0], [0, 0, 0], [0, 0, 0]], 1, 1) False + >>> is_safe([[0, 0, 1], [0, 0, 0], [0, 0, 0]], 1, 1) + False + >>> is_safe([[1, 0, 0], [0, 0, 0], [0, 0, 0]], 1, 2) + True + >>> is_safe([[1, 0, 0], [0, 0, 0], [0, 0, 0]], 2, 1) + True + >>> is_safe([[0, 0, 0], [1, 0, 0], [0, 0, 0]], 0, 2) + True + >>> is_safe([[0, 0, 0], [1, 0, 0], [0, 0, 0]], 2, 2) + True """ n = len(board) # Size of the board - # Check if there is any queen in the same row, column, - # left upper diagonal, and right upper diagonal + # Check if there is any queen in the same upper column, + # left upper diagonal and right upper diagonal return ( - all(board[i][j] != 1 for i, j in zip(range(row, -1, -1), range(column, n))) + all(board[i][j] != 1 for i, j in zip(range(row), [column] * row)) + and all( + board[i][j] != 1 + for i, j in zip(range(row - 1, -1, -1), range(column - 1, -1, -1)) + ) and all( - board[i][j] != 1 for i, j in zip(range(row, -1, -1), range(column, -1, -1)) + board[i][j] != 1 + for i, j in zip(range(row - 1, -1, -1), range(column + 1, n)) ) - and all(board[i][j] != 1 for i, j in zip(range(row, n), range(column, n))) - and all(board[i][j] != 1 for i, j in zip(range(row, n), range(column, -1, -1))) ) diff --git a/backtracking/sum_of_subsets.py b/backtracking/sum_of_subsets.py index f34d3ca34339..f26f179f8725 100644 --- a/backtracking/sum_of_subsets.py +++ b/backtracking/sum_of_subsets.py @@ -1,5 +1,5 @@ """ -The sum-of-subsetsproblem states that a set of non-negative integers, and a +The sum-of-subsets problem states that a set of non-negative integers, and a value M, determine all possible subsets of the given set whose summation sum equal to given M. @@ -7,10 +7,20 @@ can be used only once. """ -from __future__ import annotations +def generate_sum_of_subsets_solutions(nums: list[int], max_sum: int) -> list[list[int]]: + """ + The main function. For list of numbers 'nums' find the subsets with sum + equal to 'max_sum' + + >>> generate_sum_of_subsets_solutions(nums=[3, 34, 4, 12, 5, 2], max_sum=9) + [[3, 4, 2], [4, 5]] + >>> generate_sum_of_subsets_solutions(nums=[3, 34, 4, 12, 5, 2], max_sum=3) + [[3]] + >>> generate_sum_of_subsets_solutions(nums=[3, 34, 4, 12, 5, 2], max_sum=1) + [] + """ -def generate_sum_of_subsets_soln(nums: list[int], max_sum: int) -> list[list[int]]: result: list[list[int]] = [] path: list[int] = [] num_index = 0 @@ -34,7 +44,21 @@ def create_state_space_tree( This algorithm follows depth-fist-search and backtracks when the node is not branchable. + >>> path = [] + >>> result = [] + >>> create_state_space_tree( + ... nums=[1], + ... max_sum=1, + ... num_index=0, + ... path=path, + ... result=result, + ... remaining_nums_sum=1) + >>> path + [] + >>> result + [[1]] """ + if sum(path) > max_sum or (remaining_nums_sum + sum(path)) < max_sum: return if sum(path) == max_sum: @@ -51,16 +75,7 @@ def create_state_space_tree( ) -""" -remove the comment to take an input from the user - -print("Enter the elements") -nums = list(map(int, input().split())) -print("Enter max_sum sum") -max_sum = int(input()) +if __name__ == "__main__": + import doctest -""" -nums = [3, 34, 4, 12, 5, 2] -max_sum = 9 -result = generate_sum_of_subsets_soln(nums, max_sum) -print(*result) + doctest.testmod() diff --git a/backtracking/word_break.py b/backtracking/word_break.py new file mode 100644 index 000000000000..2e874a02b61c --- /dev/null +++ b/backtracking/word_break.py @@ -0,0 +1,74 @@ +""" +Word Break Problem is a well-known problem in computer science. +Given a string and a dictionary of words, the task is to determine if +the string can be segmented into a sequence of one or more dictionary words. + +Wikipedia: https://en.wikipedia.org/wiki/Word_break_problem +""" + + +def backtrack(input_string: str, word_dict: set[str], start: int) -> bool: + """ + Helper function that uses backtracking to determine if a valid + word segmentation is possible starting from index 'start'. + + Parameters: + input_string (str): The input string to be segmented. + word_dict (set[str]): A set of valid dictionary words. + start (int): The starting index of the substring to be checked. + + Returns: + bool: True if a valid segmentation is possible, otherwise False. + + Example: + >>> backtrack("leetcode", {"leet", "code"}, 0) + True + + >>> backtrack("applepenapple", {"apple", "pen"}, 0) + True + + >>> backtrack("catsandog", {"cats", "dog", "sand", "and", "cat"}, 0) + False + """ + + # Base case: if the starting index has reached the end of the string + if start == len(input_string): + return True + + # Try every possible substring from 'start' to 'end' + for end in range(start + 1, len(input_string) + 1): + if input_string[start:end] in word_dict and backtrack( + input_string, word_dict, end + ): + return True + + return False + + +def word_break(input_string: str, word_dict: set[str]) -> bool: + """ + Determines if the input string can be segmented into a sequence of + valid dictionary words using backtracking. + + Parameters: + input_string (str): The input string to segment. + word_dict (set[str]): The set of valid words. + + Returns: + bool: True if the string can be segmented into valid words, otherwise False. + + Example: + >>> word_break("leetcode", {"leet", "code"}) + True + + >>> word_break("applepenapple", {"apple", "pen"}) + True + + >>> word_break("catsandog", {"cats", "dog", "sand", "and", "cat"}) + False + + >>> word_break("applepenapple", {}) + False + """ + + return backtrack(input_string, word_dict, 0) diff --git a/backtracking/word_ladder.py b/backtracking/word_ladder.py new file mode 100644 index 000000000000..7d9fd00f6669 --- /dev/null +++ b/backtracking/word_ladder.py @@ -0,0 +1,100 @@ +""" +Word Ladder is a classic problem in computer science. +The problem is to transform a start word into an end word +by changing one letter at a time. +Each intermediate word must be a valid word from a given list of words. +The goal is to find a transformation sequence +from the start word to the end word. + +Wikipedia: https://en.wikipedia.org/wiki/Word_ladder +""" + +import string + + +def backtrack( + current_word: str, path: list[str], end_word: str, word_set: set[str] +) -> list[str]: + """ + Helper function to perform backtracking to find the transformation + from the current_word to the end_word. + + Parameters: + current_word (str): The current word in the transformation sequence. + path (list[str]): The list of transformations from begin_word to current_word. + end_word (str): The target word for transformation. + word_set (set[str]): The set of valid words for transformation. + + Returns: + list[str]: The list of transformations from begin_word to end_word. + Returns an empty list if there is no valid + transformation from current_word to end_word. + + Example: + >>> backtrack("hit", ["hit"], "cog", {"hot", "dot", "dog", "lot", "log", "cog"}) + ['hit', 'hot', 'dot', 'lot', 'log', 'cog'] + + >>> backtrack("hit", ["hit"], "cog", {"hot", "dot", "dog", "lot", "log"}) + [] + + >>> backtrack("lead", ["lead"], "gold", {"load", "goad", "gold", "lead", "lord"}) + ['lead', 'lead', 'load', 'goad', 'gold'] + + >>> backtrack("game", ["game"], "code", {"came", "cage", "code", "cade", "gave"}) + ['game', 'came', 'cade', 'code'] + """ + + # Base case: If the current word is the end word, return the path + if current_word == end_word: + return path + + # Try all possible single-letter transformations + for i in range(len(current_word)): + for c in string.ascii_lowercase: # Try changing each letter + transformed_word = current_word[:i] + c + current_word[i + 1 :] + if transformed_word in word_set: + word_set.remove(transformed_word) + # Recur with the new word added to the path + result = backtrack( + transformed_word, [*path, transformed_word], end_word, word_set + ) + if result: # valid transformation found + return result + word_set.add(transformed_word) # backtrack + + return [] # No valid transformation found + + +def word_ladder(begin_word: str, end_word: str, word_set: set[str]) -> list[str]: + """ + Solve the Word Ladder problem using Backtracking and return + the list of transformations from begin_word to end_word. + + Parameters: + begin_word (str): The word from which the transformation starts. + end_word (str): The target word for transformation. + word_list (list[str]): The list of valid words for transformation. + + Returns: + list[str]: The list of transformations from begin_word to end_word. + Returns an empty list if there is no valid transformation. + + Example: + >>> word_ladder("hit", "cog", ["hot", "dot", "dog", "lot", "log", "cog"]) + ['hit', 'hot', 'dot', 'lot', 'log', 'cog'] + + >>> word_ladder("hit", "cog", ["hot", "dot", "dog", "lot", "log"]) + [] + + >>> word_ladder("lead", "gold", ["load", "goad", "gold", "lead", "lord"]) + ['lead', 'lead', 'load', 'goad', 'gold'] + + >>> word_ladder("game", "code", ["came", "cage", "code", "cade", "gave"]) + ['game', 'came', 'cade', 'code'] + """ + + if end_word not in word_set: # no valid transformation possible + return [] + + # Perform backtracking starting from the begin_word + return backtrack(begin_word, [begin_word], end_word, word_set) diff --git a/backtracking/word_search.py b/backtracking/word_search.py index 8a9b2f1b5359..b6ee1211eb07 100644 --- a/backtracking/word_search.py +++ b/backtracking/word_search.py @@ -25,7 +25,7 @@ Result: True -Implementation notes: Use backtracking approach. +Implementation notes: Use a backtracking approach. At each point, check all neighbors to try to find the next letter of the word. leetcode: https://leetcode.com/problems/word-search/ @@ -53,7 +53,7 @@ def exits_word( visited_points_set: set[int], ) -> bool: """ - Return True if it's possible to search the word suffix + Return True if it's possible to search for the word suffix starting from the word_index. >>> exits_word([["A"]], "B", 0, 0, 0, set()) @@ -88,13 +88,122 @@ def exits_word( return False +def validate_board_and_word(board: list[list[str]], word: str) -> None: + """ + >>> board = [["A","B","C","E"],["S","F","C","S"],["A","D","E","E"]] + >>> validate_board_and_word(board, "ABCCED") + >>> validate_board_and_word(board, "SEE") + >>> validate_board_and_word(board, "ABCB") + >>> validate_board_and_word([["A"]], "A") + >>> validate_board_and_word( + ... [["B", "A", "A"], ["A", "A", "A"], ["A", "B", "A"]], "ABB" + ... ) + >>> validate_board_and_word([["A"]], 123) + Traceback (most recent call last): + ... + ValueError: The word parameter should be a string of length greater than 0. + >>> validate_board_and_word([["A"]], "") + Traceback (most recent call last): + ... + ValueError: The word parameter should be a string of length greater than 0. + >>> validate_board_and_word([[]], "AB") + Traceback (most recent call last): + ... + ValueError: The board should be a non-empty matrix of single-character strings. + >>> validate_board_and_word([], "AB") + Traceback (most recent call last): + ... + ValueError: The board should be a non-empty matrix of single-character strings. + >>> validate_board_and_word([["A"], [21]], "AB") + Traceback (most recent call last): + ... + ValueError: The board should be a non-empty matrix of single-character strings. + """ + + # Validate board + msg = "The board should be a non-empty matrix of single-character strings." + if not board or not isinstance(board, list): + raise ValueError(msg) + + for row in board: + if not row or not isinstance(row, list): + raise ValueError(msg) + + for item in row: + if not item or not isinstance(item, str): + raise ValueError(msg) + + # Validate word + if not isinstance(word, str) or len(word) == 0: + msg = "The word parameter should be a string of length greater than 0." + raise ValueError(msg) + + +def get_word_path(board: list[list[str]], word: str) -> list[tuple[int, int]] | None: + """ + Return the path of the word in the board if it exists; otherwise, return None. + + >>> board = [["A","B","C","E"],["S","F","C","S"],["A","D","E","E"]] + >>> get_word_path(board, "ABCCED") + [(0, 0), (0, 1), (0, 2), (1, 2), (2, 2), (2, 1)] + >>> get_word_path(board, "SEE") + [(1, 3), (2, 3), (2, 2)] + >>> get_word_path(board, "ABCB") is None + True + >>> get_word_path([["A"]], 123) + Traceback (most recent call last): + ... + ValueError: The word parameter should be a string of length greater than 0. + """ + validate_board_and_word(board, word) + rows, cols = len(board), len(board[0]) + + def backtrack( + r: int, + c: int, + index: int, + path: list[tuple[int, int]], + visited: set[tuple[int, int]], + ) -> list[tuple[int, int]] | None: + if board[r][c] != word[index]: + return None + + path.append((r, c)) + visited.add((r, c)) + + if index == len(word) - 1: + return path.copy() + + directions = [(0, 1), (0, -1), (1, 0), (-1, 0)] + + for dr, dc in directions: + nr, nc = r + dr, c + dc + if 0 <= nr < rows and 0 <= nc < cols and (nr, nc) not in visited: + result = backtrack(nr, nc, index + 1, path, visited) + if result: + return result + + path.pop() + visited.remove((r, c)) + return None + + for i in range(rows): + for j in range(cols): + result = backtrack(i, j, 0, [], set()) + if result: + return result + + return None + + def word_exists(board: list[list[str]], word: str) -> bool: """ - >>> word_exists([["A","B","C","E"],["S","F","C","S"],["A","D","E","E"]], "ABCCED") + >>> board = [["A","B","C","E"],["S","F","C","S"],["A","D","E","E"]] + >>> word_exists(board, "ABCCED") True - >>> word_exists([["A","B","C","E"],["S","F","C","S"],["A","D","E","E"]], "SEE") + >>> word_exists(board, "SEE") True - >>> word_exists([["A","B","C","E"],["S","F","C","S"],["A","D","E","E"]], "ABCB") + >>> word_exists(board, "ABCB") False >>> word_exists([["A"]], "A") True @@ -111,40 +220,18 @@ def word_exists(board: list[list[str]], word: str) -> bool: >>> word_exists([[]], "AB") Traceback (most recent call last): ... - ValueError: The board should be a non empty matrix of single chars strings. + ValueError: The board should be a non-empty matrix of single-character strings. >>> word_exists([], "AB") Traceback (most recent call last): ... - ValueError: The board should be a non empty matrix of single chars strings. + ValueError: The board should be a non-empty matrix of single-character strings. >>> word_exists([["A"], [21]], "AB") Traceback (most recent call last): ... - ValueError: The board should be a non empty matrix of single chars strings. + ValueError: The board should be a non-empty matrix of single-character strings. """ - - # Validate board - board_error_message = ( - "The board should be a non empty matrix of single chars strings." - ) - + validate_board_and_word(board, word) len_board = len(board) - if not isinstance(board, list) or len(board) == 0: - raise ValueError(board_error_message) - - for row in board: - if not isinstance(row, list) or len(row) == 0: - raise ValueError(board_error_message) - - for item in row: - if not isinstance(item, str) or len(item) != 1: - raise ValueError(board_error_message) - - # Validate word - if not isinstance(word, str) or len(word) == 0: - raise ValueError( - "The word parameter should be a string of length greater than 0." - ) - len_board_column = len(board[0]) for i in range(len_board): for j in range(len_board_column): diff --git a/bit_manipulation/binary_and_operator.py b/bit_manipulation/binary_and_operator.py index f33b8b1c0ab4..18761424c9b4 100644 --- a/bit_manipulation/binary_and_operator.py +++ b/bit_manipulation/binary_and_operator.py @@ -1,3 +1,37 @@ +"""Bitwise AND helper. + +Return a zero-padded binary string representing ``a & b`` where the width is the +maximum bit length of the inputs. Only non-negative integers are accepted. + +>>> binary_and(25, 32) +'0b000000' +>>> binary_and(37, 50) +'0b100000' +>>> binary_and(21, 30) +'0b10100' +>>> binary_and(58, 73) +'0b0001000' +>>> binary_and(0, 255) +'0b00000000' +>>> binary_and(256, 256) +'0b100000000' + +Invalid inputs raise clear exceptions: + +>>> binary_and(0, -1) +Traceback (most recent call last): + ... +ValueError: inputs must be non-negative integers +>>> binary_and(0, 1.1) +Traceback (most recent call last): + ... +TypeError: inputs must be integers +>>> binary_and("0", "1") +Traceback (most recent call last): + ... +TypeError: inputs must be integers +""" + # https://www.tutorialspoint.com/python3/bitwise_operators_example.htm @@ -22,28 +56,32 @@ def binary_and(a: int, b: int) -> str: >>> binary_and(0, -1) Traceback (most recent call last): ... - ValueError: the value of both inputs must be positive + ValueError: inputs must be non-negative integers >>> binary_and(0, 1.1) Traceback (most recent call last): ... - ValueError: Unknown format code 'b' for object of type 'float' + TypeError: inputs must be integers >>> binary_and("0", "1") Traceback (most recent call last): ... - TypeError: '<' not supported between instances of 'str' and 'int' + TypeError: inputs must be integers + >>> binary_and(10, "1") + Traceback (most recent call last): + ... + TypeError: inputs must be integers """ + if not isinstance(a, int) or not isinstance(b, int): + raise TypeError("inputs must be integers") if a < 0 or b < 0: - raise ValueError("the value of both inputs must be positive") + raise ValueError("inputs must be non-negative integers") a_binary = format(a, "b") b_binary = format(b, "b") max_len = max(len(a_binary), len(b_binary)) - return "0b" + "".join( - str(int(char_a == "1" and char_b == "1")) - for char_a, char_b in zip(a_binary.zfill(max_len), b_binary.zfill(max_len)) - ) + max_len = max(a.bit_length(), b.bit_length()) + return f"0b{(a & b):0{max_len}b}" if __name__ == "__main__": diff --git a/bit_manipulation/binary_count_setbits.py b/bit_manipulation/binary_count_setbits.py index 3c92694533aa..0244853e740b 100644 --- a/bit_manipulation/binary_count_setbits.py +++ b/bit_manipulation/binary_count_setbits.py @@ -30,7 +30,7 @@ def binary_count_setbits(a: int) -> int: """ if a < 0: raise ValueError("Input value must be a positive integer") - elif isinstance(a, float): + if isinstance(a, float): raise TypeError("Input value must be a 'int' type") return bin(a).count("1") diff --git a/bit_manipulation/binary_count_trailing_zeros.py b/bit_manipulation/binary_count_trailing_zeros.py index f401c4ab9266..e989d5086c8d 100644 --- a/bit_manipulation/binary_count_trailing_zeros.py +++ b/bit_manipulation/binary_count_trailing_zeros.py @@ -3,8 +3,7 @@ def binary_count_trailing_zeros(a: int) -> int: """ - Take in 1 integer, return a number that is - the number of trailing zeros in binary representation of that number. + Take in 1 integer, return the number of trailing zeros in binary representation. >>> binary_count_trailing_zeros(25) 0 @@ -17,7 +16,9 @@ def binary_count_trailing_zeros(a: int) -> int: >>> binary_count_trailing_zeros(4294967296) 32 >>> binary_count_trailing_zeros(0) - 0 + Traceback (most recent call last): + ... + ValueError: Trailing zeros for 0 are undefined >>> binary_count_trailing_zeros(-10) Traceback (most recent call last): ... @@ -25,17 +26,27 @@ def binary_count_trailing_zeros(a: int) -> int: >>> binary_count_trailing_zeros(0.8) Traceback (most recent call last): ... - TypeError: Input value must be a 'int' type + TypeError: Input value must be an integer >>> binary_count_trailing_zeros("0") Traceback (most recent call last): ... - TypeError: '<' not supported between instances of 'str' and 'int' + TypeError: Input value must be an integer """ + + # Type check + if not isinstance(a, int): + raise TypeError("Input value must be an integer") + + # Edge case: zero + if a == 0: + raise ValueError("Trailing zeros for 0 are undefined") + + # Negative numbers not allowed if a < 0: raise ValueError("Input value must be a positive integer") - elif isinstance(a, float): - raise TypeError("Input value must be a 'int' type") - return 0 if (a == 0) else int(log2(a & -a)) + + # Core logic + return int(log2(a & -a)) if __name__ == "__main__": diff --git a/bit_manipulation/binary_or_operator.py b/bit_manipulation/binary_or_operator.py index 95f61f1da64e..ced9e4d2d4a4 100644 --- a/bit_manipulation/binary_or_operator.py +++ b/bit_manipulation/binary_or_operator.py @@ -1,45 +1,47 @@ +"""Bitwise OR helper. + +Return a zero-padded binary string representing ``a | b`` where the width is the +maximum bit length of the inputs. Only non-negative integers are accepted. + +>>> binary_or(25, 32) +'0b111001' +>>> binary_or(37, 50) +'0b110111' +>>> binary_or(21, 30) +'0b11111' +>>> binary_or(58, 73) +'0b1111011' +>>> binary_or(0, 255) +'0b11111111' +>>> binary_or(0, 256) +'0b100000000' + +Invalid inputs raise clear exceptions: + +>>> binary_or(0, -1) +Traceback (most recent call last): + ... +ValueError: inputs must be non-negative integers +>>> binary_or(0, 1.1) +Traceback (most recent call last): + ... +TypeError: inputs must be integers +>>> binary_or("0", "1") +Traceback (most recent call last): + ... +TypeError: inputs must be integers +""" + # https://www.tutorialspoint.com/python3/bitwise_operators_example.htm def binary_or(a: int, b: int) -> str: - """ - Take in 2 integers, convert them to binary, and return a binary number that is the - result of a binary or operation on the integers provided. - - >>> binary_or(25, 32) - '0b111001' - >>> binary_or(37, 50) - '0b110111' - >>> binary_or(21, 30) - '0b11111' - >>> binary_or(58, 73) - '0b1111011' - >>> binary_or(0, 255) - '0b11111111' - >>> binary_or(0, 256) - '0b100000000' - >>> binary_or(0, -1) - Traceback (most recent call last): - ... - ValueError: the value of both inputs must be positive - >>> binary_or(0, 1.1) - Traceback (most recent call last): - ... - TypeError: 'float' object cannot be interpreted as an integer - >>> binary_or("0", "1") - Traceback (most recent call last): - ... - TypeError: '<' not supported between instances of 'str' and 'int' - """ + if not isinstance(a, int) or not isinstance(b, int): + raise TypeError("inputs must be integers") if a < 0 or b < 0: - raise ValueError("the value of both inputs must be positive") - a_binary = str(bin(a))[2:] # remove the leading "0b" - b_binary = str(bin(b))[2:] - max_len = max(len(a_binary), len(b_binary)) - return "0b" + "".join( - str(int("1" in (char_a, char_b))) - for char_a, char_b in zip(a_binary.zfill(max_len), b_binary.zfill(max_len)) - ) + raise ValueError("inputs must be non-negative integers") + max_len = max(a.bit_length(), b.bit_length()) + return f"0b{(a | b):0{max_len}b}" if __name__ == "__main__": diff --git a/bit_manipulation/binary_xor_operator.py b/bit_manipulation/binary_xor_operator.py index 6206c70a99f6..3c69fdb135c0 100644 --- a/bit_manipulation/binary_xor_operator.py +++ b/bit_manipulation/binary_xor_operator.py @@ -1,49 +1,48 @@ +"""Bitwise XOR helper. + +Return a zero-padded binary string representing ``a ^ b`` where the width is the +maximum bit length of the inputs. Only non-negative integers are accepted. + +>>> binary_xor(25, 32) +'0b111001' +>>> binary_xor(37, 50) +'0b010111' +>>> binary_xor(21, 30) +'0b01011' +>>> binary_xor(58, 73) +'0b1110011' +>>> binary_xor(0, 255) +'0b11111111' +>>> binary_xor(256, 256) +'0b000000000' + +Invalid inputs raise clear exceptions: + +>>> binary_xor(0, -1) +Traceback (most recent call last): + ... +ValueError: inputs must be non-negative integers +>>> binary_xor(0, 1.1) +Traceback (most recent call last): + ... +TypeError: inputs must be integers +>>> binary_xor("0", "1") +Traceback (most recent call last): + ... +TypeError: inputs must be integers +""" + # https://www.tutorialspoint.com/python3/bitwise_operators_example.htm def binary_xor(a: int, b: int) -> str: - """ - Take in 2 integers, convert them to binary, - return a binary number that is the - result of a binary xor operation on the integers provided. - - >>> binary_xor(25, 32) - '0b111001' - >>> binary_xor(37, 50) - '0b010111' - >>> binary_xor(21, 30) - '0b01011' - >>> binary_xor(58, 73) - '0b1110011' - >>> binary_xor(0, 255) - '0b11111111' - >>> binary_xor(256, 256) - '0b000000000' - >>> binary_xor(0, -1) - Traceback (most recent call last): - ... - ValueError: the value of both inputs must be positive - >>> binary_xor(0, 1.1) - Traceback (most recent call last): - ... - TypeError: 'float' object cannot be interpreted as an integer - >>> binary_xor("0", "1") - Traceback (most recent call last): - ... - TypeError: '<' not supported between instances of 'str' and 'int' - """ + if not isinstance(a, int) or not isinstance(b, int): + raise TypeError("inputs must be integers") if a < 0 or b < 0: - raise ValueError("the value of both inputs must be positive") - - a_binary = str(bin(a))[2:] # remove the leading "0b" - b_binary = str(bin(b))[2:] # remove the leading "0b" - - max_len = max(len(a_binary), len(b_binary)) + raise ValueError("inputs must be non-negative integers") - return "0b" + "".join( - str(int(char_a != char_b)) - for char_a, char_b in zip(a_binary.zfill(max_len), b_binary.zfill(max_len)) - ) + max_len = max(a.bit_length(), b.bit_length()) + return f"0b{(a ^ b):0{max_len}b}" if __name__ == "__main__": diff --git a/bit_manipulation/count_number_of_one_bits.py b/bit_manipulation/count_number_of_one_bits.py index f0c9f927620a..e9064c2745c7 100644 --- a/bit_manipulation/count_number_of_one_bits.py +++ b/bit_manipulation/count_number_of_one_bits.py @@ -20,6 +20,8 @@ def get_set_bits_count_using_brian_kernighans_algorithm(number: int) -> int: Traceback (most recent call last): ... ValueError: the value of input must not be negative + >>> get_set_bits_count_using_brian_kernighans_algorithm(1023) + 10 """ if number < 0: raise ValueError("the value of input must not be negative") @@ -49,6 +51,8 @@ def get_set_bits_count_using_modulo_operator(number: int) -> int: Traceback (most recent call last): ... ValueError: the value of input must not be negative + >>> get_set_bits_count_using_modulo_operator(1024) + 1 """ if number < 0: raise ValueError("the value of input must not be negative") @@ -60,20 +64,62 @@ def get_set_bits_count_using_modulo_operator(number: int) -> int: return result +def get_set_bits_count_using_lookup_table(number: int) -> int: + """ + Count the number of set bits in a 32-bit integer using a precomputed lookup table. + + I see similar approach in GeeksforGeeks, but the implementation is different. + Link to Code: + https://www.geeksforgeeks.org/dsa/count-set-bits-integer-using-lookup-table/ + + >>> get_set_bits_count_using_lookup_table(25) + 3 + >>> get_set_bits_count_using_lookup_table(37) + 3 + >>> get_set_bits_count_using_lookup_table(21) + 3 + >>> get_set_bits_count_using_lookup_table(58) + 4 + >>> get_set_bits_count_using_lookup_table(0) + 0 + >>> get_set_bits_count_using_lookup_table(256) + 1 + >>> get_set_bits_count_using_lookup_table(-1) + Traceback (most recent call last): + ... + ValueError: the value of input must not be negative + """ + _lookup_table = [bin(i).count("1") for i in range(256)] + + if number < 0: + raise ValueError("the value of input must not be negative") + + # Split 32-bit number into four 8-bit chunks and use lookup table + return ( + _lookup_table[number & 0xFF] + + _lookup_table[(number >> 8) & 0xFF] + + _lookup_table[(number >> 16) & 0xFF] + + _lookup_table[(number >> 24) & 0xFF] + ) + + def benchmark() -> None: """ - Benchmark code for comparing 2 functions, with different length int values. - Brian Kernighan's algorithm is consistently faster than using modulo_operator. + Benchmark code for comparing 3 functions, with different length int values. + Brian Kernighan's algorithm is consistently faster than using modulo_operator, + and the lookup table method is often the fastest for repeated calls. """ def do_benchmark(number: int) -> None: setup = "import __main__ as z" print(f"Benchmark when {number = }:") + print(f"{get_set_bits_count_using_modulo_operator(number) = }") timing = timeit( f"z.get_set_bits_count_using_modulo_operator({number})", setup=setup ) print(f"timeit() runs in {timing} seconds") + print(f"{get_set_bits_count_using_brian_kernighans_algorithm(number) = }") timing = timeit( f"z.get_set_bits_count_using_brian_kernighans_algorithm({number})", @@ -81,6 +127,13 @@ def do_benchmark(number: int) -> None: ) print(f"timeit() runs in {timing} seconds") + print(f"{get_set_bits_count_using_lookup_table(number) = }") + timing = timeit( + f"z.get_set_bits_count_using_lookup_table({number})", + setup=setup, + ) + print(f"timeit() runs in {timing} seconds") + for number in (25, 37, 58, 0): do_benchmark(number) print() diff --git a/bit_manipulation/fast_walsh_hadamard_transform.py b/bit_manipulation/fast_walsh_hadamard_transform.py new file mode 100644 index 000000000000..1c7d447e3c0a --- /dev/null +++ b/bit_manipulation/fast_walsh_hadamard_transform.py @@ -0,0 +1,209 @@ +""" +Fast Walsh-Hadamard Transform (FWHT) for Bitwise Convolutions. + +Reference: https://en.wikipedia.org/wiki/Fast_Walsh%E2%80%93Hadamard_transform +Reference: https://cp-algorithms.com/algebra/walsh-hadamard-transform.html + +Computes bitwise XOR, AND, and OR convolutions of two numeric sequences in O(N log N) +time, where N is a positive power of 2. +""" + + +def fwht_xor(sequence: list[int], inverse: bool = False) -> list[int]: + """ + Perform Fast Walsh-Hadamard Transform (or inverse) for XOR operation. + + Time Complexity: O(N log N) + + >>> fwht_xor([1, 2, 3, 4]) + [10, -2, -4, 0] + >>> fwht_xor([10, -2, -4, 0], inverse=True) + [1, 2, 3, 4] + >>> fwht_xor([1, 2, 3]) + Traceback (most recent call last): + ... + ValueError: Length of sequence must be a positive power of 2. + >>> fwht_xor([]) + Traceback (most recent call last): + ... + ValueError: Length of sequence must be a positive power of 2. + >>> fwht_xor([1, 2, 3, 5], inverse=True) + Traceback (most recent call last): + ... + ValueError: Inverse XOR transform requires elements divisible by sequence length. + """ + sequence_length = len(sequence) + if sequence_length == 0 or (sequence_length & (sequence_length - 1)) != 0: + raise ValueError("Length of sequence must be a positive power of 2.") + + result = list(sequence) + half_block = 1 + while half_block < sequence_length: + block_size = half_block * 2 + for block_start in range(0, sequence_length, block_size): + for offset in range(half_block): + left_index = block_start + offset + right_index = left_index + half_block + left_val = result[left_index] + right_val = result[right_index] + result[left_index] = left_val + right_val + result[right_index] = left_val - right_val + half_block *= 2 + + if inverse: + if any(element % sequence_length != 0 for element in result): + raise ValueError( + "Inverse XOR transform requires elements divisible by sequence length." + ) + result = [element // sequence_length for element in result] + return result + + +def xor_convolution(sequence_a: list[int], sequence_b: list[int]) -> list[int]: + """ + Compute bitwise XOR convolution C[k] = sum_{i ^ j = k} (A[i] * B[j]). + + Time Complexity: O(N log N) + + >>> xor_convolution([1, 2], [3, 4]) + [11, 10] + >>> xor_convolution([1, 2], [3]) + Traceback (most recent call last): + ... + ValueError: Input sequences must have equal length. + """ + if len(sequence_a) != len(sequence_b): + raise ValueError("Input sequences must have equal length.") + + transformed_a = fwht_xor(sequence_a) + transformed_b = fwht_xor(sequence_b) + pointwise_product = [ + transformed_a[index] * transformed_b[index] for index in range(len(sequence_a)) + ] + return fwht_xor(pointwise_product, inverse=True) + + +def fwht_or(sequence: list[int], inverse: bool = False) -> list[int]: + """ + Perform Fast Walsh-Hadamard Transform for OR operation. + + Time Complexity: O(N log N) + + >>> fwht_or([1, 2]) + [1, 3] + >>> fwht_or([1, 3], inverse=True) + [1, 2] + >>> fwht_or([1, 2, 3]) + Traceback (most recent call last): + ... + ValueError: Length of sequence must be a positive power of 2. + """ + sequence_length = len(sequence) + if sequence_length == 0 or (sequence_length & (sequence_length - 1)) != 0: + raise ValueError("Length of sequence must be a positive power of 2.") + + result = list(sequence) + half_block = 1 + while half_block < sequence_length: + block_size = half_block * 2 + for block_start in range(0, sequence_length, block_size): + for offset in range(half_block): + left_index = block_start + offset + right_index = left_index + half_block + if not inverse: + result[right_index] += result[left_index] + else: + result[right_index] -= result[left_index] + half_block *= 2 + + return result + + +def or_convolution(sequence_a: list[int], sequence_b: list[int]) -> list[int]: + """ + Compute bitwise OR convolution C[k] = sum_{i | j = k} (A[i] * B[j]). + + Time Complexity: O(N log N) + + >>> or_convolution([1, 2], [3, 4]) + [3, 18] + >>> or_convolution([1, 2], [3]) + Traceback (most recent call last): + ... + ValueError: Input sequences must have equal length. + """ + if len(sequence_a) != len(sequence_b): + raise ValueError("Input sequences must have equal length.") + + transformed_a = fwht_or(sequence_a) + transformed_b = fwht_or(sequence_b) + pointwise_product = [ + transformed_a[index] * transformed_b[index] for index in range(len(sequence_a)) + ] + return fwht_or(pointwise_product, inverse=True) + + +def fwht_and(sequence: list[int], inverse: bool = False) -> list[int]: + """ + Perform Fast Walsh-Hadamard Transform for AND operation. + + Time Complexity: O(N log N) + + >>> fwht_and([1, 2]) + [3, 2] + >>> fwht_and([3, 2], inverse=True) + [1, 2] + >>> fwht_and([1, 2, 3]) + Traceback (most recent call last): + ... + ValueError: Length of sequence must be a positive power of 2. + """ + sequence_length = len(sequence) + if sequence_length == 0 or (sequence_length & (sequence_length - 1)) != 0: + raise ValueError("Length of sequence must be a positive power of 2.") + + result = list(sequence) + half_block = 1 + while half_block < sequence_length: + block_size = half_block * 2 + for block_start in range(0, sequence_length, block_size): + for offset in range(half_block): + left_index = block_start + offset + right_index = left_index + half_block + if not inverse: + result[left_index] += result[right_index] + else: + result[left_index] -= result[right_index] + half_block *= 2 + + return result + + +def and_convolution(sequence_a: list[int], sequence_b: list[int]) -> list[int]: + """ + Compute bitwise AND convolution C[k] = sum_{i & j = k} (A[i] * B[j]). + + Time Complexity: O(N log N) + + >>> and_convolution([1, 2], [3, 4]) + [13, 8] + >>> and_convolution([1, 2], [3]) + Traceback (most recent call last): + ... + ValueError: Input sequences must have equal length. + """ + if len(sequence_a) != len(sequence_b): + raise ValueError("Input sequences must have equal length.") + + transformed_a = fwht_and(sequence_a) + transformed_b = fwht_and(sequence_b) + pointwise_product = [ + transformed_a[index] * transformed_b[index] for index in range(len(sequence_a)) + ] + return fwht_and(pointwise_product, inverse=True) + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/bit_manipulation/find_unique_number.py b/bit_manipulation/find_unique_number.py new file mode 100644 index 000000000000..77970b4865d1 --- /dev/null +++ b/bit_manipulation/find_unique_number.py @@ -0,0 +1,37 @@ +def find_unique_number(arr: list[int]) -> int: + """ + Given a list of integers where every element appears twice except for one, + this function returns the element that appears only once using bitwise XOR. + + >>> find_unique_number([1, 1, 2, 2, 3]) + 3 + >>> find_unique_number([4, 5, 4, 6, 6]) + 5 + >>> find_unique_number([7]) + 7 + >>> find_unique_number([10, 20, 10]) + 20 + >>> find_unique_number([]) + Traceback (most recent call last): + ... + ValueError: input list must not be empty + >>> find_unique_number([1, 'a', 1]) + Traceback (most recent call last): + ... + TypeError: all elements must be integers + """ + if not arr: + raise ValueError("input list must not be empty") + if not all(isinstance(x, int) for x in arr): + raise TypeError("all elements must be integers") + + result = 0 + for num in arr: + result ^= num + return result + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/bit_manipulation/gray_code_sequence.py b/bit_manipulation/gray_code_sequence.py index 636578d89754..ab66eb7b1e7c 100644 --- a/bit_manipulation/gray_code_sequence.py +++ b/bit_manipulation/gray_code_sequence.py @@ -1,4 +1,4 @@ -def gray_code(bit_count: int) -> list: +def gray_code(bit_count: int) -> list[int]: """ Takes in an integer n and returns a n-bit gray code sequence @@ -7,12 +7,15 @@ def gray_code(bit_count: int) -> list: a) Every integer is between [0,2^n -1] inclusive b) The sequence begins with 0 - c) An integer appears at most one times in the sequence - d)The binary representation of every pair of integers differ + c) An integer appears at most one time in the sequence + d) The binary representation of every pair of integers differ by exactly one bit e) The binary representation of first and last bit also differ by exactly one bit + >>> gray_code(0) + [0] + >>> gray_code(2) [0, 1, 3, 2] @@ -37,21 +40,19 @@ def gray_code(bit_count: int) -> list: if bit_count < 0: raise ValueError("The given input must be positive") - # get the generated string sequence + # get the generated string sequence and convert them to integers sequence = gray_code_sequence_string(bit_count) - # - # convert them to integers - for i in range(len(sequence)): - sequence[i] = int(sequence[i], 2) - - return sequence + return [int(code, 2) for code in sequence] -def gray_code_sequence_string(bit_count: int) -> list: +def gray_code_sequence_string(bit_count: int) -> list[str]: """ - Will output the n-bit grey sequence as a + Will output the n-bit Gray code sequence as a string of bits + >>> gray_code_sequence_string(0) + ['0'] + >>> gray_code_sequence_string(2) ['00', '01', '11', '10'] @@ -73,7 +74,7 @@ def gray_code_sequence_string(bit_count: int) -> list: # recursive answer will generate answer for n-1 bits smaller_sequence = gray_code_sequence_string(bit_count - 1) - sequence = [] + sequence: list[str] = [] # append 0 to first half of the smaller sequence generated for i in range(seq_len // 2): diff --git a/bit_manipulation/is_even.py b/bit_manipulation/is_even.py index 6f95a1160797..a87988a2c3f8 100644 --- a/bit_manipulation/is_even.py +++ b/bit_manipulation/is_even.py @@ -1,17 +1,9 @@ def is_even(number: int) -> bool: - """ - return true if the input integer is even - Explanation: Lets take a look at the following decimal to binary conversions - 2 => 10 - 14 => 1110 - 100 => 1100100 - 3 => 11 - 13 => 1101 - 101 => 1100101 - from the above examples we can observe that - for all the odd integers there is always 1 set bit at the end - also, 1 in binary can be represented as 001, 00001, or 0000001 - so for any odd integer n => n&1 is always equals 1 else the integer is even + """Return True if the input integer is even using a bitwise check. + + Explanation: + In binary, even numbers always have the least significant bit cleared (0), + while odd numbers have it set (1). Therefore, ``n & 1 == 0`` implies even. >>> is_even(1) False @@ -27,8 +19,54 @@ def is_even(number: int) -> bool: True >>> is_even(101) False + >>> is_even(True) + Traceback (most recent call last): + ... + TypeError: input must be an integer + >>> is_even(3.14) + Traceback (most recent call last): + ... + TypeError: input must be an integer + """ + if not isinstance(number, int) or isinstance(number, bool): + # bool is a subclass of int; explicitly disallow it as a number here. + raise TypeError("input must be an integer") + return (number & 1) == 0 + + +def is_even_using_shift_operator(number: int) -> bool: + """ + Returns True if the input integer is even. + + Explanation: + In binary, even numbers end with 0, odd numbers end with 1. + Examples: + 2 -> 10 + 3 -> 11 + 4 -> 100 + 5 -> 101 + + For odd numbers, the last bit is always 1. + Using shift: + (n >> 1) << 1 removes the last bit. + If result equals n, n is even. + + >>> is_even_using_shift_operator(1) + False + >>> is_even_using_shift_operator(4) + True + >>> is_even_using_shift_operator(9) + False + >>> is_even_using_shift_operator(15) + False + >>> is_even_using_shift_operator(40) + True + >>> is_even_using_shift_operator(100) + True + >>> is_even_using_shift_operator(101) + False """ - return number & 1 == 0 + return (number >> 1) << 1 == number if __name__ == "__main__": diff --git a/bit_manipulation/is_power_of_two.py b/bit_manipulation/is_power_of_two.py index 023e979fe51c..3dd8df3540bc 100644 --- a/bit_manipulation/is_power_of_two.py +++ b/bit_manipulation/is_power_of_two.py @@ -33,6 +33,10 @@ def is_power_of_two(number: int) -> bool: True >>> is_power_of_two(17) False + >>> is_power_of_two(1024) + True + >>> is_power_of_two(1023) + False >>> is_power_of_two(-1) Traceback (most recent call last): ... diff --git a/bit_manipulation/next_power_of_two.py b/bit_manipulation/next_power_of_two.py new file mode 100644 index 000000000000..4b523c17b130 --- /dev/null +++ b/bit_manipulation/next_power_of_two.py @@ -0,0 +1,55 @@ +""" +Author : Basuki Nath +Date : 2025-10-04 + +Utility to compute the next power of two greater than or equal to n. +""" + + +def next_power_of_two(n: int) -> int: + """ + Return the smallest power of two >= n for positive integers. + + >>> next_power_of_two(1) + 1 + >>> next_power_of_two(2) + 2 + >>> next_power_of_two(3) + 4 + >>> next_power_of_two(5) + 8 + >>> next_power_of_two(1025) + 2048 + >>> next_power_of_two(0) + Traceback (most recent call last): + ... + ValueError: n must be positive + >>> next_power_of_two(-3) + Traceback (most recent call last): + ... + ValueError: n must be positive + """ + if n <= 0: + raise ValueError("n must be positive") + # If already a power of two, return it + if n & (n - 1) == 0: + return n + # Otherwise, fill bits to the right + v = n - 1 + v |= v >> 1 + v |= v >> 2 + v |= v >> 4 + v |= v >> 8 + v |= v >> 16 + # for very large ints, continue shifting using Python's arbitrary precision + shift = 32 + while (1 << shift) <= v: + v |= v >> shift + shift <<= 1 + return v + 1 + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/bit_manipulation/parity.py b/bit_manipulation/parity.py new file mode 100644 index 000000000000..019c88deea30 --- /dev/null +++ b/bit_manipulation/parity.py @@ -0,0 +1,43 @@ +""" +Author : Basuki Nath +Date : 2025-10-04 + +Simple parity utility for integers. + +The parity is 1 when the number of set bits is odd, otherwise 0. +""" + + +def parity(number: int) -> int: + """ + Return 1 if `number` has an odd number of set bits, otherwise 0. + + >>> parity(0) + 0 + >>> parity(1) + 1 + >>> parity(2) # 10b -> one set bit + 1 + >>> parity(3) # 11b -> two set bits + 0 + >>> parity(1023) # 10 ones -> even + 0 + >>> parity(-1) + Traceback (most recent call last): + ... + ValueError: number must not be negative + """ + if number < 0: + raise ValueError("number must not be negative") + # Kernighan's algorithm toggling parity + p = 0 + while number: + p ^= 1 + number &= number - 1 + return p + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/bit_manipulation/reverse_bits.py b/bit_manipulation/reverse_bits.py index 74b4f2563234..4a0b2ff7047a 100644 --- a/bit_manipulation/reverse_bits.py +++ b/bit_manipulation/reverse_bits.py @@ -1,6 +1,6 @@ def get_reverse_bit_string(number: int) -> str: """ - return the bit string of an integer + Return the reverse bit string of a 32 bit integer >>> get_reverse_bit_string(9) '10010000000000000000000000000000' @@ -8,76 +8,76 @@ def get_reverse_bit_string(number: int) -> str: '11010100000000000000000000000000' >>> get_reverse_bit_string(2873) '10011100110100000000000000000000' + >>> get_reverse_bit_string(2550136832) + '00000000000000000000000000011001' >>> get_reverse_bit_string("this is not a number") Traceback (most recent call last): ... - TypeError: operation can not be conducted on a object of type str + TypeError: operation can not be conducted on an object of type str """ if not isinstance(number, int): msg = ( - "operation can not be conducted on a object of type " + "operation can not be conducted on an object of type " f"{type(number).__name__}" ) raise TypeError(msg) bit_string = "" for _ in range(32): bit_string += str(number % 2) - number = number >> 1 + number >>= 1 return bit_string -def reverse_bit(number: int) -> str: +def reverse_bit(number: int) -> int: """ - Take in an 32 bit integer, reverse its bits, - return a string of reverse bits - - result of a reverse_bit and operation on the integer provided. + Take in a 32 bit integer, reverse its bits, return a 32 bit integer result >>> reverse_bit(25) - '00000000000000000000000000011001' + 2550136832 >>> reverse_bit(37) - '00000000000000000000000000100101' + 2751463424 >>> reverse_bit(21) - '00000000000000000000000000010101' + 2818572288 >>> reverse_bit(58) - '00000000000000000000000000111010' + 1543503872 >>> reverse_bit(0) - '00000000000000000000000000000000' + 0 >>> reverse_bit(256) - '00000000000000000000000100000000' + 8388608 + >>> reverse_bit(2550136832) + 25 >>> reverse_bit(-1) Traceback (most recent call last): ... - ValueError: the value of input must be positive + ValueError: The value of input must be non-negative >>> reverse_bit(1.1) Traceback (most recent call last): ... - TypeError: Input value must be a 'int' type + TypeError: Input value must be an 'int' type >>> reverse_bit("0") Traceback (most recent call last): ... - TypeError: '<' not supported between instances of 'str' and 'int' + TypeError: Input value must be an 'int' type """ + if not isinstance(number, int): + raise TypeError("Input value must be an 'int' type") if number < 0: - raise ValueError("the value of input must be positive") - elif isinstance(number, float): - raise TypeError("Input value must be a 'int' type") - elif isinstance(number, str): - raise TypeError("'<' not supported between instances of 'str' and 'int'") + raise ValueError("The value of input must be non-negative") + result = 0 - # iterator over [1 to 32],since we are dealing with 32 bit integer - for _ in range(1, 33): + # iterator over [0 to 31], since we are dealing with a 32 bit integer + for _ in range(32): # left shift the bits by unity - result = result << 1 + result <<= 1 # get the end bit - end_bit = number % 2 + end_bit = number & 1 # right shift the bits by unity - number = number >> 1 - # add that bit to our ans - result = result | end_bit - return get_reverse_bit_string(result) + number >>= 1 + # add that bit to our answer + result |= end_bit + return result if __name__ == "__main__": diff --git a/bit_manipulation/rotate_bits.py b/bit_manipulation/rotate_bits.py new file mode 100644 index 000000000000..521ab8de203f --- /dev/null +++ b/bit_manipulation/rotate_bits.py @@ -0,0 +1,70 @@ +""" +Author : Basuki Nath +Date : 2025-10-04 + +Bit rotation helpers for 32-bit unsigned integers. +""" + + +def rotate_left32(x: int, k: int) -> int: + """ + Rotate the lower 32 bits of x left by k and return result in 0..2**32-1. + + >>> rotate_left32(1, 1) + 2 + >>> rotate_left32(1, 31) + 2147483648 + >>> rotate_left32(0x80000000, 1) + 1 + >>> rotate_left32(0x12345678, 4) + 591751041 + >>> rotate_left32(-1, 3) + Traceback (most recent call last): + ... + ValueError: x must be a non-negative integer + >>> rotate_left32(1, -1) + Traceback (most recent call last): + ... + ValueError: k must be non-negative + """ + if not isinstance(x, int) or x < 0: + raise ValueError("x must be a non-negative integer") + if not isinstance(k, int) or k < 0: + raise ValueError("k must be non-negative") + mask = (1 << 32) - 1 + k &= 31 + return ((x << k) & mask) | ((x & mask) >> (32 - k)) + + +def rotate_right32(x: int, k: int) -> int: + """ + Rotate the lower 32 bits of x right by k and return result in 0..2**32-1. + + >>> rotate_right32(2, 1) + 1 + >>> rotate_right32(1, 1) + 2147483648 + >>> rotate_right32(0x12345678, 4) + 2166572391 + >>> rotate_right32(-1, 1) + Traceback (most recent call last): + ... + ValueError: x must be a non-negative integer + >>> rotate_right32(1, -3) + Traceback (most recent call last): + ... + ValueError: k must be non-negative + """ + if not isinstance(x, int) or x < 0: + raise ValueError("x must be a non-negative integer") + if not isinstance(k, int) or k < 0: + raise ValueError("k must be non-negative") + mask = (1 << 32) - 1 + k &= 31 + return ((x & mask) >> k) | ((x << (32 - k)) & mask) + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/bit_manipulation/single_bit_manipulation_operations.py b/bit_manipulation/single_bit_manipulation_operations.py index fcbf033ccb24..95be4be976d8 100644 --- a/bit_manipulation/single_bit_manipulation_operations.py +++ b/bit_manipulation/single_bit_manipulation_operations.py @@ -94,6 +94,29 @@ def get_bit(number: int, position: int) -> int: return int((number & (1 << position)) != 0) +def clear_least_significant_set_bit(number: int) -> int: + """ + Clear the least significant set bit (rightmost 1 bit). + + Subtracting 1 changes the rightmost 1 to 0 and the 0 bits to its right to 1. + ANDing the result with the original number therefore clears that set bit. + For negative integers, Python's infinite sign extension is used. + https://graphics.stanford.edu/~seander/bithacks.html#CountBitsSetKernighan + + >>> clear_least_significant_set_bit(0b101100) # 0b101000 + 40 + >>> clear_least_significant_set_bit(0b1000) # 0b0 + 0 + >>> clear_least_significant_set_bit(0) + 0 + >>> clear_least_significant_set_bit(0b1111) # 0b1110 + 14 + >>> clear_least_significant_set_bit(-5) + -6 + """ + return number & (number - 1) + + if __name__ == "__main__": import doctest diff --git a/bit_manipulation/xor_swap_two_integers.py b/bit_manipulation/xor_swap_two_integers.py new file mode 100644 index 000000000000..3c558eb9a0f9 --- /dev/null +++ b/bit_manipulation/xor_swap_two_integers.py @@ -0,0 +1,40 @@ +# Information on XOR swap: https://en.wikipedia.org/wiki/Bitwise_operation#XOR + +# Algorithm: +# 1. Take two integers a and b. +# 2. Apply XOR between a and b and store the result in a: +# a = a ^ b +# 3. XOR the new value of a with b to get the original value of a and store it in b: +# b = a ^ b +# 4. XOR the new value of a with the new value of b. +# This gives the original value of b, which we store in a: +# a = a ^ b +# 5. Return the swapped values (a, b). +# This method swaps two numbers without using a temporary variable. + + +def xor_swap(a: int, b: int) -> tuple[int, int]: + """ + Swap two integers using bitwise XOR operation and return the swapped values. + + >>> xor_swap(5, 10) + (10, 5) + >>> xor_swap(0, 0) + (0, 0) + >>> xor_swap(-1, 1) + (1, -1) + >>> xor_swap(123, 456) + (456, 123) + >>> xor_swap(12345, 54321) + (54321, 12345) + """ + a = a ^ b + b = a ^ b + a = a ^ b + return a, b + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/blockchain/README.md b/blockchain/README.md index b5fab7b36eaa..47d2a6e62b1f 100644 --- a/blockchain/README.md +++ b/blockchain/README.md @@ -1,45 +1,160 @@ -# Blockchain +# Blockchain Technology -A Blockchain is a type of **distributed ledger** technology (DLT) that consists of growing list of records, called **blocks**, that are securely linked together using **cryptography**. +

+ +

-Let's breakdown the terminologies in the above definition. We find below terminologies, +A Blockchain is a type of **distributed ledger** technology (DLT) that consists of a growing list of records, called **blocks**, that are securely linked together using **cryptography**. + +Let's break down the terminologies in the above definition. We find below terminologies, - Digital Ledger Technology (DLT) - Blocks - Cryptography -## Digital Ledger Technology +## Distributed Ledger Technology (DLT) + +First of all, a **ledger** is a book or collection of accounts that keeps track of account transactions. Usually, ledgers are **centralised**, meaning that they're controlled by a sole influence. +These ledgers are physical records maintained by banks, governments, and other establishments to track financial transactions, ownership records, and any other essential information. +However, this approach only serves as a hotbed for inefficiency and over-reliance on a sole entity. + +This is where Distributed Ledger Technology comes in. DLT represents a massive shift from centralised data management. + +Instead of one single entity managing data, the ledger, which in this case is **digital**, is shared among multiple **nodes**(computers) in a network. Each node is responsible for maintaining an **identical** copy of the main ledger, and all these nodes must consent before any new information is added to the main ledger. + +*Key Characteristics of DLT:* + +- Decentralisation: No single point of control, management or failure +- Transparency: All network participants can see transactions, although personal details may be encrypted +- Immutability: Once data is recorded and confirmed, it becomes extremely hard to change +- Consensus Mechanisms: Network participants must agree on the credibility of new transactions + +*To further conceptualise Distributed Ledger Technology, imagine the scenario below:* + +- Four roommates live in an apartment together. +- They all contribute towards groceries, utilities, and rent. +- In the spirit of accountability, they use a **shared Google Sheet** where every expense is tracked. +- Everyone can **see**, **add**, and **validate** expenses, but **no one can delete past expense entries** — they're only allowed to append new rows with reasons for any corrections. - It is otherwise called as distributed ledger technology. It is simply the opposite of centralized database. Firstly, what is a **ledger**? A ledger is a book or collection of accounts that records account transactions. +This is exactly how a Distributed Ledger works. - *Why is Blockchain addressed as digital ledger if it can record more than account transactions? What other transaction details and information can it hold?* +| Google Sheet Feature | DLT Concept Equivalent | +|---------------------------------------------------|---------------------------------------------------| +| Everyone has access to the same document | **Distributed ledger** — everyone has a synchronised copy | +| Changes are visible to all in real time | **Transparency and consensus** | +| No one can erase old entries; only new ones can be added with explanations | **Immutability** of records | +| Each entry includes a timestamp and who added it | **Timestamped transactions** and **identity** (like digital signatures) | +| Everyone can verify what’s been entered | **Decentralised verification** | +| Any disputes are resolved by checking the shared record | **Consensus mechanism** (though manual here) | -Digital Ledger Technology is just a ledger which is shared among multiple nodes. This way there exist no need for central authority to hold the info. Okay, how is it differentiated from central database and what are their benefits? +## Centralised vs. Distributed Management -There is an organization which has 4 branches whose data are stored in a centralized database. So even if one branch needs any data from ledger they need an approval from database in charge. And if one hacks the central database he gets to tamper and control all the data. +**Centralised approach:** Here, an organisation with 4 branches stores all its data in one central database. This database is managed by the Chief Administrator at the headquarters. Each branch needs approval from the Chief Administrator to view and access information. +If a bad actor gains access to the central database, they can unduly alter all the data, and if the central database fails, all the branches lose their access to vital data. -Now lets assume every branch has a copy of the ledger and then once anything is added to the ledger by anyone branch it is gonna automatically reflect in all other ledgers available in other branch. This is done using Peer-to-peer network. +**Distributed approach:** In this case, each organisational branch maintains a complete **carbon copy** of the original ledger. For one branch to add information, all branches must reach a consensus. +When one branch adds information, it's broadcast to the entire network and systematically synchronised across all other ledgers through a peer-to-peer network after verification. -So this means even if information is tampered in one branch we can find out. If one branch is hacked we can be alerted ,so we can safeguard other branches. Now, assume these branches as computers or nodes and the ledger is a transaction record or digital receipt. If one ledger is hacked in a node we can detect since there will be a mismatch in comparison with other node information. So this is the concept of Digital Ledger Technology. +In summary, a distributed approach offers: -*Is it required for all nodes to have access to all information in other nodes? Wouldn't this require enormous storage space in each node?* +- Fault tolerance: If information is altered in one branch, other branches can detect the change through consensus algorithms +- Security: If one branch is compromised, other branches remain secure and can identify the bad actor +- Availability: No single point of failure — if one computer goes down, the network is still highly functional +- Verification: Any member of the network can independently verify the integrity of the complete transaction history ## Blocks -In short a block is nothing but collections of records with a labelled header. These are connected cryptographically. Once a new block is added to a chain, the previous block is connected, more precisely said as locked and hence, will remain unaltered. We can understand this concept once we get a clear understanding of working mechanism of blockchain. +A **block** is a cluster of transactions grouped together with metadata in a structured manner. +Imagine a block as a page in a digital ledger. This page consists of multiple transaction entries, including important information about when and how that page was created. +Cryptography is the practice and study of secure communication techniques amid adversarial behavior. More broadly, cryptography is the creation and analysis of protocols that prevent third parties or the general public from accessing private messages. + +*Structure of a Block:* + +1. Block Header: + +- Previous Block Hash: A unique fingerprint of the previous block, creating the *chain* +- Merkle Root: A cryptographic summary of all transactions in the block +- Timestamp: The time the block was created +- Nonce: A number used in the Proof-of-Work (PoW) mining process +- Difficulty Target: The complexity level required to mine this block + +2. Block Body: + +- Transaction Data: The actual transaction records (transfers, smart contract executions, etc.) +- Transaction Count: Number of transactions confirmed in the block + +## The Chain Formation + +Blocks are connected cryptographically using hash functions, in order to create an **immutable** chain: + +1. Genesis Block: The first block in the chain, which is hardcoded into the blockchain protocol +2. Subsequent Blocks: Each new block contains the hash function of the preceding block +3. Chain Integrity: If someone tries to modify a previous block, its hash function changes, breaking the chain and notifying the entire network + +With cryptographic linking, once a block is added to the chain and verified by the network, modifying any preceding block is computationally impractical. The deeper a block is in the chain (the more blocks built on top of it), the more secure it becomes. ## Cryptography -It is the practice and study of secure communication techniques in the midst of adversarial behavior. More broadly, cryptography is the creation and analysis of protocols that prevent third parties or the general public from accessing private messages. +Cryptography is the practice and study of secure communication strategies that safeguard information from unwanted access. In the context of blockchain, cryptography is the backbone of security, privacy, and trust, in a decentralised network where participants don't know, or even trust each other. + +*Key Cryptographic Concepts in Blockchain:* + +1. Hash Functions: + +- Generate fixed-size output (hash) from variable-size input +- The SHA-256 function is typically used in Bitcoin +- Properties: Deterministic (giving input to a hash function will always produce the same output), avalanche effect, irreversible +- Used for: Block linking, transaction verification, mining puzzles + +2. Digital Signatures: + +- Prove ownership and authorise transactions without revealing private keys +- Based on public-key cryptography (asymmetric encryption) +- Each user has a pair: private key (secret) and public key (shareable) +- Process: Sign with private key and verify with public key + +3. Merkle Trees: + +- Binary tree structure that effectively outlines all transactions in a block +- Enables quick verification of transaction inclusion without having to download the entire block +- Provides evidence for altered transaction data + +*Cryptographic Security in Practice:* + +1. Transaction Security: +When person A wants to send **cryptocurrency** to person B: + +- Person A creates a transaction using person B's **public address** +- Person A signs the transaction with their **private key** +- Network nodes verify the signature using person A's **public key** +- Once verified, the transaction is added to a block + +2. Block Integrity: + +- Each block contains the hash of the previous block +- Any change to a previous block changes its hash +- This breaks the chain and immediately notifies the entire network +- Makes altering historical data unfeasible + +3. Privacy vs. Transparency: + +- **Transparency** means amounts and addresses are public. +- **Privacy** ensures that real-world identities behind addresses are undisclosed. +- This balance allows for accountability and anonymity in transactions. -*Which cryptography technology is most widely used in blockchain and why?* +> In summary, **Blockchain technology** represents a pioneering shift in how we store, verify, and transfer value in digital systems. It's a distributed, immutable, non-physical ledger that records transactions and tracks assets across a decentralised network, without requiring **trust** in a sole entity. +Blockchain networks can track and trade virtually any **asset** of value, from tangible assets like real estate, commodities, and vehicles, to intangible assets such as cryptocurrencies, intellectual property, digital art (NFTs), and carbon credits. +A blockchain network can track and sell almost anything of value, lowering risk and costs for everyone involved. -So, in general, blockchain technology is a distributed record holder which records the information about ownership of an asset. To define precisely, -> Blockchain is a distributed, immutable ledger that makes it easier to record transactions and track assets in a corporate network. -An asset could be tangible (such as a house, car, cash, or land) or intangible (such as a business) (intellectual property, patents, copyrights, branding). A blockchain network can track and sell almost anything of value, lowering risk and costs for everyone involved. +This is just a brief introduction to blockchain technology. +To find out more about this technology, check out the links below: -So this is all about introduction to blockchain technology. To learn more about the topic refer below links.... -* -* -* -* +- - Comprehensive overview of blockchain technology +- - The original document by Satoshi Nakamoto +- - Introduction to programmable blockchain +- - Understanding the math behind blockchain security +- - Data structure for efficient verification +- - JavaScript library for blockchain interaction +- +- +- diff --git a/blockchain/diophantine_equation.py b/blockchain/diophantine_equation.py index ae6a145d2922..5fc3777c431e 100644 --- a/blockchain/diophantine_equation.py +++ b/blockchain/diophantine_equation.py @@ -100,6 +100,64 @@ def extended_gcd(a: int, b: int) -> tuple[int, int, int]: return (d, x, y) +def all_diophantine_solutions( + a: int, + b: int, + c: int, + n: int = 2, +) -> list[tuple[int, int]]: + """ + Return up to `n` integer solutions (x, y) to the linear Diophantine equation + a*x + b*y = c using the extended Euclidean algorithm. + + Raises + ------ + ValueError + If no integer solutions exist. + + Time complexity + --------------- + O(log(max(|a|, |b|))) to compute a base solution using extended_gcd; + plus O(n) to enumerate `n` solutions. + + Space complexity + ---------------- + O(1) beyond the returned list. + + Examples + -------- + >>> all_diophantine_solutions(10, 6, 14, n=2) + [(-7, 14), (-4, 9)] + >>> all_diophantine_solutions(10, 6, 14, n=4) + [(-7, 14), (-4, 9), (-1, 4), (2, -1)] + >>> all_diophantine_solutions(3, 6, 10, n=1) + Traceback (most recent call last): + ... + ValueError: No integer solutions exist for a=3, b=6, c=10 + """ + if a == 0 and b == 0: + if c == 0: + # Infinite solutions; return one canonical solution. + return [(0, 0)][: min(1, n)] + raise ValueError("No integer solutions exist for a=0, b=0, c!=0") + + g, xg, yg = extended_gcd(abs(a), abs(b)) + if c % g != 0: + msg = f"No integer solutions exist for a={a}, b={b}, c={c}" + raise ValueError(msg) + + # Scale a particular solution to ax + by = c + x0, y0 = xg * (c // g), yg * (c // g) + if a < 0: + x0 = -x0 + if b < 0: + y0 = -y0 + + # General solution: x = x0 + t*(b/g), y = y0 - t*(a/g) + dx, dy = b // g, a // g + return [(x0 + t * dx, y0 - t * dy) for t in range(n)] + + if __name__ == "__main__": from doctest import testmod diff --git a/blockchain/merkle_tree.py b/blockchain/merkle_tree.py new file mode 100644 index 000000000000..627937fdd54a --- /dev/null +++ b/blockchain/merkle_tree.py @@ -0,0 +1,107 @@ +""" +Merkle Tree Construction and Verification + +This module implements the construction of a Merkle Tree and +verification of inclusion proofs for blockchain data integrity. + +Each leaf is a SHA-256 hash of a transaction, and internal nodes are +computed by hashing the concatenation of their child nodes. + +References: +https://en.wikipedia.org/wiki/Merkle_tree +""" + +import hashlib + + +def sha256(data: str) -> str: + """ + Compute the SHA-256 hash of the given string. + + Args: + data (str): Input string. + + Returns: + str: Hexadecimal SHA-256 hash of the input. + + Example: + >>> sha256("abc") + 'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad' + """ + return hashlib.sha256(data.encode()).hexdigest() + + +def build_merkle_tree(leaves: list[str]) -> list[list[str]]: + """ + Build a Merkle Tree from the given leaf nodes. + + Args: + leaves: List of data strings (transactions). + + Returns: + A list of lists representing tree levels, + with the last level containing the Merkle root. + + >>> len(build_merkle_tree(["a", "b", "c", "d"])[-1][0]) + 64 + """ + if not leaves: + raise ValueError("Leaf list cannot be empty.") + + current_level = [sha256(x) for x in leaves] + tree = [current_level] + + while len(current_level) > 1: + next_level = [] + for i in range(0, len(current_level), 2): + left = current_level[i] + right = current_level[i + 1] if i + 1 < len(current_level) else left + next_level.append(sha256(left + right)) + current_level = next_level + tree.append(current_level) + + return tree + + +def merkle_root(leaves: list[str]) -> str: + """ + Return the Merkle root hash for a given list of data. + + >>> r = merkle_root(["tx1", "tx2", "tx3"]) + >>> isinstance(r, str) + True + """ + return build_merkle_tree(leaves)[-1][0] + + +def verify_proof(leaf: str, proof: list[str], root: str) -> bool: + """ + Verify inclusion of a leaf using a Merkle proof. + + Args: + leaf: Original data string. + proof: List of sibling hashes up the path. + root: Expected Merkle root hash. + + Returns: + True if proof is valid, else False. + + >>> data = ["a", "b", "c", "d"] + >>> tree = build_merkle_tree(data) + >>> root = tree[-1][0] + >>> leaf = "a" + >>> proof = [sha256("b"), sha256(sha256("c") + sha256("d"))] + >>> verify_proof(leaf, proof, root) + True + """ + computed_hash = sha256(leaf) + for sibling in proof: + combined = sha256(computed_hash + sibling) + computed_hash = combined + return computed_hash == root + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/blockchain/proof_of_stake.py b/blockchain/proof_of_stake.py new file mode 100644 index 000000000000..7eea9ded21e5 --- /dev/null +++ b/blockchain/proof_of_stake.py @@ -0,0 +1,40 @@ +import random + + +class Validator: + def __init__(self, name: str, stake: int) -> None: + """ + Initializes a new validator with a given name and stake. + + Args: + name (str): The name of the validator. + stake (int): The amount of stake the validator has. + """ + self.name = name + self.stake = stake + + +def choose_validator(validators: list[Validator]) -> Validator: + """ + Selects a validator to create the next block based on the weight of their stake. + + The higher the stake, the greater the chance to be selected. + + Args: + validators (list[Validator]): A list of Validator objects. + + Returns: + Validator: The selected validator based on weighted random selection. + + Example: + >>> validators = [Validator("Alice", 50), Validator("Bob", 30)] + >>> chosen = choose_validator(validators) + >>> isinstance(chosen, Validator) + True + """ + total_stake = sum(v.stake for v in validators) + weighted_validators = [(v, v.stake / total_stake) for v in validators] + selected = random.choices( + [v[0] for v in weighted_validators], weights=[v[1] for v in weighted_validators] + ) + return selected[0] diff --git a/blockchain/proof_of_work.py b/blockchain/proof_of_work.py new file mode 100644 index 000000000000..8ad2b4b88c42 --- /dev/null +++ b/blockchain/proof_of_work.py @@ -0,0 +1,189 @@ +# Title: Proof of Work Algorithm for Blockchain + +## Algorithm Statement: +# The algorithm implements the Proof of Work (PoW) consensus mechanism used in +# blockchain to validate blocks. PoW ensures participants (miners) perform a +# computational task to create a valid block and add it to the blockchain. The +# difficulty is defined by the number of leading zeros required in the block hash. + +import hashlib +import time + + +class Block: + def __init__( + self, + index: int, + previous_hash: str, + transactions: str, + timestamp: float, + difficulty: int, + ) -> None: + """ + Initializes a Block object with the specified parameters. + + Parameters: + - index (int): The index of the block in the blockchain. + - previous_hash (str): The hash of the previous block. + - transactions (str): The list of transactions in the block. + - timestamp (float): The time when the block was created + (in Unix timestamp format). + - difficulty (int): The difficulty level for mining this block. + """ + self.index = index + self.previous_hash = previous_hash + self.transactions = transactions + self.timestamp = timestamp + self.nonce = 0 # Start with nonce 0 + self.difficulty = difficulty + self.hash = self.compute_hash() + + def compute_hash(self) -> str: + """ + Generates the hash of the block content. + Combines index, previous hash, transactions, timestamp, and nonce into + a string, which is then hashed using SHA-256. + + Returns: + - str: The hash of the block. + """ + block_string = ( + f"{self.index}{self.previous_hash}{self.transactions}{self.timestamp}" + f"{self.nonce}" + ) + return hashlib.sha256(block_string.encode()).hexdigest() + + def mine_block(self) -> None: + """ + Performs Proof of Work by adjusting the nonce until a valid hash is found. + A valid hash has the required number of leading zeros based on the + difficulty level. + + Returns: + - None + """ + target = ( + "0" * self.difficulty + ) # Target hash should start with 'difficulty' zeros + while self.hash[: self.difficulty] != target: + self.nonce += 1 + self.hash = self.compute_hash() + + print(f"Block mined with nonce {self.nonce}, hash: {self.hash}") + + +class Blockchain: + def __init__(self, difficulty: int) -> None: + """ + Initializes the blockchain with a given difficulty level. + + Parameters: + - difficulty (int): The difficulty level for mining blocks in this blockchain. + + Returns: + - None + """ + self.chain: list[Block] = [] # Adding type hint for the list of blocks + self.difficulty = difficulty + self.create_genesis_block() + + def create_genesis_block(self) -> None: + """ + Creates the first block in the blockchain (the Genesis block). + + Returns: + - None + """ + genesis_block = Block(0, "0", "Genesis Block", time.time(), self.difficulty) + genesis_block.mine_block() + self.chain.append(genesis_block) + + def add_block(self, transactions: str) -> None: + """ + Adds a new block to the blockchain after performing Proof of Work. + + Parameters: + - transactions (str): The list of transactions to be added in the new block. + + Returns: + - None + """ + previous_block = self.chain[-1] + new_block = Block( + len(self.chain), + previous_block.hash, + transactions, + time.time(), + self.difficulty, + ) + new_block.mine_block() + self.chain.append(new_block) + + def is_chain_valid(self) -> bool: + """ + Verifies the integrity of the blockchain by ensuring each block's previous + hash matches and that all blocks meet the Proof of Work requirement. + + Returns: + - bool: True if the blockchain is valid, False otherwise. + """ + for i in range(1, len(self.chain)): + current_block = self.chain[i] + previous_block = self.chain[i - 1] + + if current_block.hash != current_block.compute_hash(): + print(f"Invalid block at index {i}. Hash mismatch.") + return False + + if current_block.previous_hash != previous_block.hash: + print(f"Invalid chain at index {i}. Previous hash mismatch.") + return False + + return True + + +# Test cases + + +## Test Case 1: Blockchain Initialization and Genesis Block +# This test verifies if the blockchain is correctly initialized with a Genesis block +# and if the block is successfully mined. +def test_blockchain() -> None: + """ + Test cases for the Blockchain proof of work algorithm. + + Returns: + - None + """ + # Create blockchain with difficulty level of 4 (hash should start with 4 zeros) + blockchain = Blockchain(difficulty=4) + + ## Test Case 2: Add a block and verify the block is mined + # This test adds a new block with transactions and ensures it's mined according + # to the proof of work mechanism. + blockchain.add_block("Transaction 1: Alice pays Bob 5 BTC") + blockchain.add_block("Transaction 2: Bob pays Charlie 3 BTC") + + ## Test Case 3: Verify blockchain integrity + # This test checks that the blockchain remains valid after adding new blocks + assert blockchain.is_chain_valid(), "Blockchain should be valid" + + ## Test Case 4: Tampering with the blockchain + # This test simulates tampering with the blockchain and checks that the validation + # correctly detects the tampering. + blockchain.chain[ + 1 + ].transactions = "Transaction 1: Alice pays Bob 50 BTC" # Tampering + assert not blockchain.is_chain_valid(), ( + "Blockchain should be invalid due to tampering" + ) + + ## Test Case 5: Correct blockchain validation + # This test checks if the blockchain becomes invalid after tampering and verifies + # if the PoW still holds after tampering is done. + + print("All test cases passed.") + + +if __name__ == "__main__": + test_blockchain() diff --git a/blockchain/simple_blockchain.py b/blockchain/simple_blockchain.py new file mode 100644 index 000000000000..6adaeb9883d4 --- /dev/null +++ b/blockchain/simple_blockchain.py @@ -0,0 +1,168 @@ +""" +A simple blockchain implementation with Proof-of-Work (PoW). + +This educational example demonstrates: +- Block structure with index, timestamp, data, previous hash, nonce, and hash +- Mining via Proof-of-Work +- Chain integrity verification + +Author: Letitia Gilbert +""" + +import hashlib +from time import time + + +class Block: + """ + Represents a single block in a blockchain. + + Attributes: + index (int): Position of the block in the chain. + timestamp (float): Creation time of the block. + data (str): Data stored in the block. + previous_hash (str): Hash of the previous block. + nonce (int): Number used for mining. + hash (str): SHA256 hash of the block's content. + """ + + def __init__( + self, index: int, data: str, previous_hash: str, difficulty: int = 2 + ) -> None: + self.index = index + self.timestamp = time() + self.data = data + self.previous_hash = previous_hash + self.nonce, self.hash = self.mine_block(difficulty) + + def compute_hash(self, nonce: int) -> str: + """ + Compute SHA256 hash of the block with given nonce. + + Args: + nonce (int): Nonce to include in the hash. + + Returns: + str: Hexadecimal hash string. + + >>> block = Block(0, "Genesis", "0", difficulty=2) + >>> len(block.compute_hash(0)) == 64 + True + >>> isinstance(block.compute_hash(0), str) + True + """ + block_string = ( + f"{self.index}{self.timestamp}{self.data}{self.previous_hash}{nonce}" + ) + return hashlib.sha256(block_string.encode()).hexdigest() + + def mine_block(self, difficulty: int) -> tuple[int, str]: + """ + Simple Proof-of-Work mining algorithm. + + Args: + difficulty (int): Number of leading zeros required in the hash. + + Returns: + Tuple[int, str]: Valid nonce and resulting hash that satisfies difficulty. + + >>> block = Block(0, "Genesis", "0", difficulty=2) + >>> block.hash.startswith('00') + True + """ + if difficulty < 1: + raise ValueError("Difficulty must be at least 1") + nonce = 0 + target = "0" * difficulty + while True: + hash_result = self.compute_hash(nonce) + if hash_result.startswith(target): + return nonce, hash_result + nonce += 1 + + +class Blockchain: + """ + Simple blockchain class maintaining a list of blocks. + + Attributes: + chain (List[Block]): List of blocks forming the chain. + """ + + def __init__(self, difficulty: int = 2) -> None: + self.difficulty = difficulty + self.chain: list[Block] = [self.create_genesis_block()] + + def create_genesis_block(self) -> Block: + """ + Create the first block in the blockchain. + + Returns: + Block: Genesis block. + + >>> bc = Blockchain() + >>> bc.chain[0].index + 0 + >>> bc.chain[0].hash.startswith('00') + True + """ + return Block(0, "Genesis Block", "0", self.difficulty) + + def add_block(self, data: str) -> Block: + """ + Add a new block to the blockchain with given data. + + Args: + data (str): Data to store in the block. + + Returns: + Block: Newly added block. + + >>> bc = Blockchain() + >>> new_block = bc.add_block("Test Data") + >>> new_block.index + 1 + >>> new_block.previous_hash == bc.chain[0].hash + True + >>> new_block.hash.startswith('00') + True + >>> bc.is_valid() + True + """ + prev_hash = self.chain[-1].hash + new_block = Block(len(self.chain), data, prev_hash, self.difficulty) + self.chain.append(new_block) + return new_block + + def is_valid(self) -> bool: + """ + Verify the integrity of the blockchain. + + Returns: + bool: True if chain is valid, False otherwise. + + >>> bc = Blockchain() + >>> new_block = bc.add_block("Test") + >>> new_block.index + 1 + >>> new_block.previous_hash == bc.chain[0].hash + True + >>> new_block.hash.startswith('00') + True + >>> bc.is_valid() + True + >>> bc.chain[1].previous_hash = "tampered" + >>> bc.is_valid() + False + + """ + for i in range(1, len(self.chain)): + current = self.chain[i] + prev = self.chain[i - 1] + if current.previous_hash != prev.hash: + return False + if not current.hash.startswith("0" * self.difficulty): + return False + if current.hash != current.compute_hash(current.nonce): + return False + return True diff --git a/blockchain/simple_proof_of_work.py b/blockchain/simple_proof_of_work.py new file mode 100644 index 000000000000..abcd591b8a10 --- /dev/null +++ b/blockchain/simple_proof_of_work.py @@ -0,0 +1,62 @@ +""" +Proof of Work (PoW) implementation. +This algorithm is used in blockchain technology +to reach consensus and secure the network +""" + +import hashlib + + +def proof_of_work( + block_number: int, transactions: str, previous_hash: str, difficulty: int +) -> tuple[int, str]: + """ + Finds a nonce such that the SHA-256 hash of the block starts with + a specific number of zeros (difficulty). + + >>> proof_of_work(1, "test", "abc", 1)[1].startswith("0") + True + >>> # Consistency check: same input must produce same output + >>> res1 = proof_of_work(1, "data", "hash", 2) + >>> res2 = proof_of_work(1, "data", "hash", 2) + >>> res1 == res2 + True + >>> # Difficulty 0 should return nonce 0 immediately + >>> proof_of_work(1, "data", "hash", 0)[0] + 0 + """ + if difficulty < 0: + raise ValueError("difficulty must be a non-negative integer") + + prefix = "0" * difficulty + nonce = 0 + + while True: + # Create a single string representing all block data + text = f"{block_number}{transactions}{previous_hash}{nonce}" + + # Calculate the SHA-256 hash + current_hash = hashlib.sha256(text.encode()).hexdigest() + + # Check if the hash meets the difficulty requirement + if current_hash.startswith(prefix): + return nonce, current_hash + + nonce += 1 + + +if __name__ == "__main__": + import doctest + + doctest.testmod() + + # Example usage: + example_tx = "Alice sends 1 BTC to Bob" + prev_h = "00000abcdef1234567890" + diff = 4 + + print(f"Mining block... (Difficulty: {diff})") + nonce, hash_found = proof_of_work(1, example_tx, prev_h, diff) + + print(f"Success! Nonce: {nonce}") + print(f"Hash: {hash_found}") diff --git a/boolean_algebra/and_gate.py b/boolean_algebra/and_gate.py index 6ae66b5b0a77..2f012f779b08 100644 --- a/boolean_algebra/and_gate.py +++ b/boolean_algebra/and_gate.py @@ -1,8 +1,8 @@ """ -An AND Gate is a logic gate in boolean algebra which results to 1 (True) if both the -inputs are 1, and 0 (False) otherwise. +An AND Gate is a logic gate in boolean algebra which results to 1 (True) if all the +inputs are 1 (True), and 0 (False) otherwise. -Following is the truth table of an AND Gate: +Following is the truth table of a Two Input AND Gate: ------------------------------ | Input 1 | Input 2 | Output | ------------------------------ @@ -12,13 +12,13 @@ | 1 | 1 | 1 | ------------------------------ -Refer - https://www.geeksforgeeks.org/logic-gates-in-python/ +Refer - https://www.geeksforgeeks.org/logic-gates/ """ def and_gate(input_1: int, input_2: int) -> int: """ - Calculate AND of the input values + Calculate AND of two binary input values. >>> and_gate(0, 0) 0 @@ -28,8 +28,65 @@ def and_gate(input_1: int, input_2: int) -> int: 0 >>> and_gate(1, 1) 1 + >>> and_gate(2, 1) + Traceback (most recent call last): + ... + ValueError: Both inputs must be 0 or 1 + >>> and_gate(0, "1") + Traceback (most recent call last): + ... + TypeError: Both inputs must be integers """ - return int(input_1 and input_2) + # Type validation + if not isinstance(input_1, int) or not isinstance(input_2, int): + raise TypeError("Both inputs must be integers") + + # Value validation + if input_1 not in (0, 1) or input_2 not in (0, 1): + raise ValueError("Both inputs must be 0 or 1") + + return input_1 & input_2 + + +def n_input_and_gate(inputs: list[int]) -> int: + """ + Calculate AND of a list of binary input values. + + >>> n_input_and_gate([1, 0, 1, 1, 0]) + 0 + >>> n_input_and_gate([1, 1, 1, 1, 1]) + 1 + >>> n_input_and_gate([1, 0, 1, 1, 0]) + 0 + >>> n_input_and_gate([]) + Traceback (most recent call last): + ... + ValueError: Input list cannot be empty + >>> n_input_and_gate([1, 2, 1]) + Traceback (most recent call last): + ... + ValueError: All inputs in the list must be 0 or 1 + >>> n_input_and_gate([1, "1"]) + Traceback (most recent call last): + ... + TypeError: All inputs in the list must be integers + """ + # Type validation for the list itself + if not isinstance(inputs, list): + raise TypeError("Input must be a list") + + # Edge case validation for an empty list + if not inputs: + raise ValueError("Input list cannot be empty") + + # Type and value validation for items within the list + for item in inputs: + if not isinstance(item, int): + raise TypeError("All inputs in the list must be integers") + if item not in (0, 1): + raise ValueError("All inputs in the list must be 0 or 1") + + return int(all(inputs)) if __name__ == "__main__": diff --git a/boolean_algebra/imply_gate.py b/boolean_algebra/imply_gate.py index b64ebaceb306..3d71ff12f8d9 100644 --- a/boolean_algebra/imply_gate.py +++ b/boolean_algebra/imply_gate.py @@ -33,6 +33,58 @@ def imply_gate(input_1: int, input_2: int) -> int: return int(input_1 == 0 or input_2 == 1) +def recursive_imply_list(input_list: list[int]) -> int: + """ + Recursively calculates the implication of a list. + Strictly the implication is applied consecutively left to right: + ( (a -> b) -> c ) -> d ... + + >>> recursive_imply_list([]) + Traceback (most recent call last): + ... + ValueError: Input list must contain at least two elements + >>> recursive_imply_list([0]) + Traceback (most recent call last): + ... + ValueError: Input list must contain at least two elements + >>> recursive_imply_list([1]) + Traceback (most recent call last): + ... + ValueError: Input list must contain at least two elements + >>> recursive_imply_list([0, 0]) + 1 + >>> recursive_imply_list([0, 1]) + 1 + >>> recursive_imply_list([1, 0]) + 0 + >>> recursive_imply_list([1, 1]) + 1 + >>> recursive_imply_list([0, 0, 0]) + 0 + >>> recursive_imply_list([0, 0, 1]) + 1 + >>> recursive_imply_list([0, 1, 0]) + 0 + >>> recursive_imply_list([0, 1, 1]) + 1 + >>> recursive_imply_list([1, 0, 0]) + 1 + >>> recursive_imply_list([1, 0, 1]) + 1 + >>> recursive_imply_list([1, 1, 0]) + 0 + >>> recursive_imply_list([1, 1, 1]) + 1 + """ + if len(input_list) < 2: + raise ValueError("Input list must contain at least two elements") + first_implication = imply_gate(input_list[0], input_list[1]) + if len(input_list) == 2: + return first_implication + new_list = [first_implication, *input_list[2:]] + return recursive_imply_list(new_list) + + if __name__ == "__main__": import doctest diff --git a/cellular_automata/conways_game_of_life.py b/cellular_automata/conways_game_of_life.py index 364a34c3aba6..4009d0e1b7ae 100644 --- a/cellular_automata/conways_game_of_life.py +++ b/cellular_automata/conways_game_of_life.py @@ -58,10 +58,8 @@ def new_generation(cells: list[list[int]]) -> list[list[int]]: # 3. All other live cells die in the next generation. # Similarly, all other dead cells stay dead. alive = cells[i][j] == 1 - if ( - (alive and 2 <= neighbour_count <= 3) - or not alive - and neighbour_count == 3 + if (alive and 2 <= neighbour_count <= 3) or ( + not alive and neighbour_count == 3 ): next_generation_row.append(1) else: @@ -80,6 +78,7 @@ def generate_images(cells: list[list[int]], frames: int) -> list[Image.Image]: # Create output image img = Image.new("RGB", (len(cells[0]), len(cells))) pixels = img.load() + assert pixels is not None # Save cells to image for x in range(len(cells)): diff --git a/cellular_automata/elementary_cellular_automaton.py b/cellular_automata/elementary_cellular_automaton.py new file mode 100644 index 000000000000..582ef1736438 --- /dev/null +++ b/cellular_automata/elementary_cellular_automaton.py @@ -0,0 +1,74 @@ +""" +Elementary Cellular Automaton - Rule 30 +--------------------------------------- + +A one-dimensional cellular automaton introduced by Stephen Wolfram. +Each cell's next state depends on its current state and its two immediate neighbors. + +Reference: + https://en.wikipedia.org/wiki/Rule_30 +""" + + +def rule_30_step(current: list[int]) -> list[int]: + """ + Compute the next generation of a one-dimensional cellular automaton + following Wolfram's Rule 30. + + Each cell's next state is determined by its left, center, and right neighbors. + + Args: + current (list[int]): The current generation as a list of 0s (dead) + and 1s (alive). + + Returns: + list[int]: The next generation as a list of 0s and 1s. + + Example: + >>> rule_30_step([0, 0, 1, 0, 0]) + [0, 1, 1, 1, 0] + """ + next_gen = [] + for i in range(len(current)): + left = current[i - 1] if i > 0 else 0 + center = current[i] + right = current[i + 1] if i < len(current) - 1 else 0 + + # Combine neighbors into a 3-bit pattern + pattern = (left << 2) | (center << 1) | right + + # Rule 30 binary: 00011110 (bitwise representation of 30) + next_gen.append((30 >> pattern) & 1) + + return next_gen + + +def generate_rule_30(size: int = 31, generations: int = 15) -> list[list[int]]: + """ + Generate multiple generations of Rule 30 automaton. + + Args: + size (int): Number of cells in one generation. Default is 31. + generations (int): Number of generations to evolve. Default is 15. + + Returns: + list[list[int]]: A list of generations (each a list of 0s and 1s). + + Example: + >>> len(generate_rule_30(15, 5)) + 5 + """ + grid = [[0] * size for _ in range(generations)] + grid[0][size // 2] = 1 # Start with a single live cell in the middle + + for i in range(1, generations): + grid[i] = rule_30_step(grid[i - 1]) + + return grid + + +if __name__ == "__main__": + # Run an example simulation + generations = generate_rule_30(31, 15) + for row in generations: + print("".join("█" if cell else " " for cell in row)) diff --git a/cellular_automata/game_of_life.py b/cellular_automata/game_of_life.py index 76276b272d65..8fef54add69a 100644 --- a/cellular_automata/game_of_life.py +++ b/cellular_automata/game_of_life.py @@ -42,6 +42,27 @@ def create_canvas(size: int) -> list[list[bool]]: + """ + Create a square canvas of given size filled with False (dead cells). + + Args: + size: The dimension of the square canvas + + Returns: + A size x size 2D list of boolean values, all initialized to False + + >>> canvas = create_canvas(3) + >>> len(canvas) + 3 + >>> len(canvas[0]) + 3 + >>> all(all(not cell for cell in row) for row in canvas) + True + >>> create_canvas(1) + [[False]] + >>> create_canvas(0) + [] + """ canvas = [[False for i in range(size)] for j in range(size)] return canvas @@ -54,15 +75,33 @@ 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 - status accordingly.(in the same canvas) - @Args: - -- - canvas : canvas of population to run the rules on. - - @returns: - -- - canvas of population after one step + Run one generation of Conway's Game of Life on the canvas. + + Applies the Game of Life rules to all cells simultaneously to produce + the next generation. + + Args: + canvas: 2D list representing current state of cells + + Returns: + 2D list representing the next generation state + + >>> blinker = [[False, False, False, False, False], + ... [False, False, True, False, False], + ... [False, False, True, False, False], + ... [False, False, True, False, False], + ... [False, False, False, False, False]] + >>> result = run(blinker) + >>> result[2] + [False, True, True, True, False] + >>> run([[False, False, False], [False, False, False], [False, False, False]]) + [[False, False, False], [False, False, False], [False, False, False]] + >>> block = [[False, False, False, False], + ... [False, True, True, False], + ... [False, True, True, False], + ... [False, False, False, False]] + >>> run(block)[1] + [False, True, True, False] """ current_canvas = np.array(canvas) next_gen_canvas = np.array(create_canvas(current_canvas.shape[0])) @@ -76,6 +115,43 @@ def run(canvas: list[list[bool]]) -> list[list[bool]]: def __judge_point(pt: bool, neighbours: list[list[bool]]) -> bool: + """ + Apply Conway's Game of Life rules to determine the next state of a cell. + + Args: + pt: Current state of the cell (True=alive, False=dead) + neighbours: 3x3 grid including the cell and its 8 neighbors + + Returns: + The next state of the cell + + Rules: + 1. Live cell with <2 live neighbours dies (under-population) + 2. Live cell with 2-3 live neighbours survives + 3. Live cell with >3 live neighbours dies (over-population) + 4. Dead cell with exactly 3 live neighbours becomes alive + + >>> __judge_point( + ... True, [[True, True, False], [False, True, False], [False, False, False]] + ... ) + True + >>> __judge_point( + ... True, [[True, False, False], [False, True, False], [False, False, False]] + ... ) + False + >>> __judge_point( + ... True, [[True, True, True], [True, True, False], [False, False, False]] + ... ) + False + >>> __judge_point( + ... False, [[True, True, False], [True, False, False], [False, False, False]] + ... ) + True + >>> __judge_point( + ... False, [[True, False, False], [False, False, False], [False, False, False]] + ... ) + False + """ dead = 0 alive = 0 # finding dead or alive neighbours count. diff --git a/cellular_automata/one_dimensional.py b/cellular_automata/one_dimensional.py index da77e444502f..04d55c2473e8 100644 --- a/cellular_automata/one_dimensional.py +++ b/cellular_automata/one_dimensional.py @@ -55,6 +55,7 @@ def generate_image(cells: list[list[int]]) -> Image.Image: # Create the output image img = Image.new("RGB", (len(cells[0]), len(cells))) pixels = img.load() + assert pixels is not None # Generates image for w in range(img.width): for h in range(img.height): diff --git a/cellular_automata/wa_tor.py b/cellular_automata/wa_tor.py index e423d1595bdb..29f7ea510bfe 100644 --- a/cellular_automata/wa_tor.py +++ b/cellular_automata/wa_tor.py @@ -1,9 +1,9 @@ """ 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 +| @ 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. @@ -97,8 +97,8 @@ class WaTor: :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. + 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 @@ -216,7 +216,7 @@ 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. + Subtly different to the `move_and_reproduce`. >>> wt = WaTor(WIDTH, HEIGHT) >>> wt.set_planet([ @@ -260,7 +260,7 @@ def move_and_reproduce( """ 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 + 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. @@ -351,12 +351,12 @@ def perform_prey_actions( 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. + 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)) @@ -382,15 +382,15 @@ def perform_predator_actions( :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. + 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))]]) @@ -430,7 +430,7 @@ def perform_predator_actions( def run(self, *, iteration_count: int) -> None: """ - Emulate time passing by looping iteration_count times + Emulate time passing by looping `iteration_count` times >>> wt = WaTor(WIDTH, HEIGHT) >>> wt.run(iteration_count=PREDATOR_INITIAL_ENERGY_VALUE - 1) @@ -484,11 +484,9 @@ def visualise(wt: WaTor, iter_number: int, *, colour: bool = True) -> None: 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 + Uses ascii colour codes to colourfully display the predators and prey: + * (0x60f197) Prey = ``#`` + * (0xfffff) Predator = ``x`` >>> wt = WaTor(30, 30) >>> wt.set_planet([ diff --git a/ciphers/a1z26.py b/ciphers/a1z26.py index a1377ea6d397..d99efe186519 100644 --- a/ciphers/a1z26.py +++ b/ciphers/a1z26.py @@ -13,7 +13,21 @@ def encode(plain: str) -> list[int]: """ >>> encode("myname") [13, 25, 14, 1, 13, 5] + >>> encode("abCd") + Traceback (most recent call last): + ... + ValueError: plain must contain only lowercase letters (a-z) + >>> encode("n0w") + Traceback (most recent call last): + ... + ValueError: plain must contain only lowercase letters (a-z) + >>> encode("later!") + Traceback (most recent call last): + ... + ValueError: plain must contain only lowercase letters (a-z) """ + if not plain.islower() or not plain.isalpha(): + raise ValueError("plain must contain only lowercase letters (a-z)") return [ord(elem) - 96 for elem in plain] diff --git a/ciphers/autokey.py b/ciphers/autokey.py index 8683e6d37001..0b269dc0adad 100644 --- a/ciphers/autokey.py +++ b/ciphers/autokey.py @@ -1,5 +1,6 @@ """ https://en.wikipedia.org/wiki/Autokey_cipher + An autokey cipher (also known as the autoclave cipher) is a cipher that incorporates the message (the plaintext) into the key. The key is generated from the message in some automated fashion, @@ -10,8 +11,9 @@ def encrypt(plaintext: str, key: str) -> str: """ - Encrypt a given plaintext (string) and key (string), returning the + Encrypt a given `plaintext` (string) and `key` (string), returning the encrypted ciphertext. + >>> encrypt("hello world", "coffee") 'jsqqs avvwo' >>> encrypt("coffee is good as python", "TheAlgorithms") @@ -24,6 +26,14 @@ def encrypt(plaintext: str, key: str) -> str: Traceback (most recent call last): ... ValueError: plaintext is empty + >>> encrypt("coffee is good as python", "") + Traceback (most recent call last): + ... + ValueError: key is empty + >>> encrypt(527.26, "TheAlgorithms") + Traceback (most recent call last): + ... + TypeError: plaintext must be a string """ if not isinstance(plaintext, str): raise TypeError("plaintext must be a string") @@ -66,8 +76,9 @@ def encrypt(plaintext: str, key: str) -> str: def decrypt(ciphertext: str, key: str) -> str: """ - Decrypt a given ciphertext (string) and key (string), returning the decrypted + Decrypt a given `ciphertext` (string) and `key` (string), returning the decrypted ciphertext. + >>> decrypt("jsqqs avvwo", "coffee") 'hello world' >>> decrypt("vvjfpk wj ohvp su ddylsv", "TheAlgorithms") @@ -80,6 +91,14 @@ def decrypt(ciphertext: str, key: str) -> str: Traceback (most recent call last): ... TypeError: ciphertext must be a string + >>> decrypt("", "TheAlgorithms") + Traceback (most recent call last): + ... + ValueError: ciphertext is empty + >>> decrypt("vvjfpk wj ohvp su ddylsv", 2) + Traceback (most recent call last): + ... + TypeError: key must be a string """ if not isinstance(ciphertext, str): raise TypeError("ciphertext must be a string") @@ -120,12 +139,13 @@ def decrypt(ciphertext: str, key: str) -> str: doctest.testmod() operation = int(input("Type 1 to encrypt or 2 to decrypt:")) - if operation == 1: - plaintext = input("Typeplaintext to be encrypted:\n") - key = input("Type the key:\n") - print(encrypt(plaintext, key)) - elif operation == 2: - ciphertext = input("Type the ciphertext to be decrypted:\n") - key = input("Type the key:\n") - print(decrypt(ciphertext, key)) + match operation: + case 1: + plaintext = input("Typeplaintext to be encrypted:\n") + key = input("Type the key:\n") + print(encrypt(plaintext, key)) + case 2: + ciphertext = input("Type the ciphertext to be decrypted:\n") + key = input("Type the key:\n") + print(decrypt(ciphertext, key)) decrypt("jsqqs avvwo", "coffee") diff --git a/ciphers/base64.py b/ciphers/base58.py similarity index 94% rename from ciphers/base64.py rename to ciphers/base58.py index 2b950b1be37d..038d13963d95 100644 --- a/ciphers/base64.py +++ b/ciphers/base58.py @@ -105,13 +105,13 @@ def base64_decode(encoded_data: str) -> bytes: # Check if the encoded string contains non base64 characters if padding: - assert all( - char in B64_CHARSET for char in encoded_data[:-padding] - ), "Invalid base64 character(s) found." + assert all(char in B64_CHARSET for char in encoded_data[:-padding]), ( + "Invalid base64 character(s) found." + ) else: - assert all( - char in B64_CHARSET for char in encoded_data - ), "Invalid base64 character(s) found." + assert all(char in B64_CHARSET for char in encoded_data), ( + "Invalid base64 character(s) found." + ) # Check the padding assert len(encoded_data) % 4 == 0 and padding < 3, "Incorrect padding" diff --git a/ciphers/base64_cipher.py b/ciphers/base64_cipher.py new file mode 100644 index 000000000000..038d13963d95 --- /dev/null +++ b/ciphers/base64_cipher.py @@ -0,0 +1,142 @@ +B64_CHARSET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/" + + +def base64_encode(data: bytes) -> bytes: + """Encodes data according to RFC4648. + + The data is first transformed to binary and appended with binary digits so that its + length becomes a multiple of 6, then each 6 binary digits will match a character in + the B64_CHARSET string. The number of appended binary digits would later determine + how many "=" signs should be added, the padding. + For every 2 binary digits added, a "=" sign is added in the output. + We can add any binary digits to make it a multiple of 6, for instance, consider the + following example: + "AA" -> 0010100100101001 -> 001010 010010 1001 + As can be seen above, 2 more binary digits should be added, so there's 4 + possibilities here: 00, 01, 10 or 11. + That being said, Base64 encoding can be used in Steganography to hide data in these + appended digits. + + >>> from base64 import b64encode + >>> a = b"This pull request is part of Hacktoberfest20!" + >>> b = b"https://tools.ietf.org/html/rfc4648" + >>> c = b"A" + >>> base64_encode(a) == b64encode(a) + True + >>> base64_encode(b) == b64encode(b) + True + >>> base64_encode(c) == b64encode(c) + True + >>> base64_encode("abc") + Traceback (most recent call last): + ... + TypeError: a bytes-like object is required, not 'str' + """ + # Make sure the supplied data is a bytes-like object + if not isinstance(data, bytes): + msg = f"a bytes-like object is required, not '{data.__class__.__name__}'" + raise TypeError(msg) + + binary_stream = "".join(bin(byte)[2:].zfill(8) for byte in data) + + padding_needed = len(binary_stream) % 6 != 0 + + if padding_needed: + # The padding that will be added later + padding = b"=" * ((6 - len(binary_stream) % 6) // 2) + + # Append binary_stream with arbitrary binary digits (0's by default) to make its + # length a multiple of 6. + binary_stream += "0" * (6 - len(binary_stream) % 6) + else: + padding = b"" + + # Encode every 6 binary digits to their corresponding Base64 character + return ( + "".join( + B64_CHARSET[int(binary_stream[index : index + 6], 2)] + for index in range(0, len(binary_stream), 6) + ).encode() + + padding + ) + + +def base64_decode(encoded_data: str) -> bytes: + """Decodes data according to RFC4648. + + This does the reverse operation of base64_encode. + We first transform the encoded data back to a binary stream, take off the + previously appended binary digits according to the padding, at this point we + would have a binary stream whose length is multiple of 8, the last step is + to convert every 8 bits to a byte. + + >>> from base64 import b64decode + >>> a = "VGhpcyBwdWxsIHJlcXVlc3QgaXMgcGFydCBvZiBIYWNrdG9iZXJmZXN0MjAh" + >>> b = "aHR0cHM6Ly90b29scy5pZXRmLm9yZy9odG1sL3JmYzQ2NDg=" + >>> c = "QQ==" + >>> base64_decode(a) == b64decode(a) + True + >>> base64_decode(b) == b64decode(b) + True + >>> base64_decode(c) == b64decode(c) + True + >>> base64_decode("abc") + Traceback (most recent call last): + ... + AssertionError: Incorrect padding + """ + # Make sure encoded_data is either a string or a bytes-like object + if not isinstance(encoded_data, bytes) and not isinstance(encoded_data, str): + msg = ( + "argument should be a bytes-like object or ASCII string, " + f"not '{encoded_data.__class__.__name__}'" + ) + raise TypeError(msg) + + # In case encoded_data is a bytes-like object, make sure it contains only + # ASCII characters so we convert it to a string object + if isinstance(encoded_data, bytes): + try: + encoded_data = encoded_data.decode("utf-8") + except UnicodeDecodeError: + raise ValueError("base64 encoded data should only contain ASCII characters") + + padding = encoded_data.count("=") + + # Check if the encoded string contains non base64 characters + if padding: + assert all(char in B64_CHARSET for char in encoded_data[:-padding]), ( + "Invalid base64 character(s) found." + ) + else: + assert all(char in B64_CHARSET for char in encoded_data), ( + "Invalid base64 character(s) found." + ) + + # Check the padding + assert len(encoded_data) % 4 == 0 and padding < 3, "Incorrect padding" + + if padding: + # Remove padding if there is one + encoded_data = encoded_data[:-padding] + + binary_stream = "".join( + bin(B64_CHARSET.index(char))[2:].zfill(6) for char in encoded_data + )[: -padding * 2] + else: + binary_stream = "".join( + bin(B64_CHARSET.index(char))[2:].zfill(6) for char in encoded_data + ) + + data = [ + int(binary_stream[index : index + 8], 2) + for index in range(0, len(binary_stream), 8) + ] + + return bytes(data) + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/ciphers/caesar_cipher.py b/ciphers/caesar_cipher.py index d19b9a337221..ef5f49313ee7 100644 --- a/ciphers/caesar_cipher.py +++ b/ciphers/caesar_cipher.py @@ -7,24 +7,29 @@ def encrypt(input_string: str, key: int, alphabet: str | None = None) -> str: """ encrypt ======= + Encodes a given string with the caesar cipher and returns the encoded message Parameters: ----------- - * input_string: the plain-text that needs to be encoded - * key: the number of letters to shift the message by + + * `input_string`: the plain-text that needs to be encoded + * `key`: the number of letters to shift the message by Optional: - * alphabet (None): the alphabet used to encode the cipher, if not + + * `alphabet` (``None``): the alphabet used to encode the cipher, if not specified, the standard english alphabet with upper and lowercase letters is used Returns: + * A string containing the encoded cipher-text More on the caesar cipher ========================= + The caesar cipher is named after Julius Caesar who used it when sending secret military messages to his troops. This is a simple substitution cipher where every character in the plain-text is shifted by a certain number known @@ -32,26 +37,28 @@ def encrypt(input_string: str, key: int, alphabet: str | None = None) -> str: Example: Say we have the following message: - "Hello, captain" + ``Hello, captain`` And our alphabet is made up of lower and uppercase letters: - "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ" + ``abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ`` - And our shift is "2" + And our shift is ``2`` - We can then encode the message, one letter at a time. "H" would become "J", - since "J" is two letters away, and so on. If the shift is ever two large, or + We can then encode the message, one letter at a time. ``H`` would become ``J``, + since ``J`` is two letters away, and so on. If the shift is ever too large, or our letter is at the end of the alphabet, we just start at the beginning - ("Z" would shift to "a" then "b" and so on). + (``Z`` would shift to ``a`` then ``b`` and so on). - Our final message would be "Jgnnq, ecrvckp" + Our final message would be ``Jgnnq, ecrvckp`` Further reading =============== + * https://en.m.wikipedia.org/wiki/Caesar_cipher Doctests ======== + >>> encrypt('The quick brown fox jumps over the lazy dog', 8) 'bpm yCqks jzwEv nwF rCuxA wDmz Bpm tiHG lwo' @@ -85,23 +92,28 @@ def decrypt(input_string: str, key: int, alphabet: str | None = None) -> str: """ decrypt ======= + Decodes a given string of cipher-text and returns the decoded plain-text Parameters: ----------- - * input_string: the cipher-text that needs to be decoded - * key: the number of letters to shift the message backwards by to decode + + * `input_string`: the cipher-text that needs to be decoded + * `key`: the number of letters to shift the message backwards by to decode Optional: - * alphabet (None): the alphabet used to decode the cipher, if not + + * `alphabet` (``None``): the alphabet used to decode the cipher, if not specified, the standard english alphabet with upper and lowercase letters is used Returns: + * A string containing the decoded plain-text More on the caesar cipher ========================= + The caesar cipher is named after Julius Caesar who used it when sending secret military messages to his troops. This is a simple substitution cipher where very character in the plain-text is shifted by a certain number known @@ -110,27 +122,29 @@ def decrypt(input_string: str, key: int, alphabet: str | None = None) -> str: Example: Say we have the following cipher-text: - "Jgnnq, ecrvckp" + ``Jgnnq, ecrvckp`` And our alphabet is made up of lower and uppercase letters: - "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ" + ``abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ`` - And our shift is "2" + And our shift is ``2`` To decode the message, we would do the same thing as encoding, but in - reverse. The first letter, "J" would become "H" (remember: we are decoding) - because "H" is two letters in reverse (to the left) of "J". We would - continue doing this. A letter like "a" would shift back to the end of - the alphabet, and would become "Z" or "Y" and so on. + reverse. The first letter, ``J`` would become ``H`` (remember: we are decoding) + because ``H`` is two letters in reverse (to the left) of ``J``. We would + continue doing this. A letter like ``a`` would shift back to the end of + the alphabet, and would become ``Z`` or ``Y`` and so on. - Our final message would be "Hello, captain" + Our final message would be ``Hello, captain`` Further reading =============== + * https://en.m.wikipedia.org/wiki/Caesar_cipher Doctests ======== + >>> decrypt('bpm yCqks jzwEv nwF rCuxA wDmz Bpm tiHG lwo', 8) 'The quick brown fox jumps over the lazy dog' @@ -150,41 +164,44 @@ def brute_force(input_string: str, alphabet: str | None = None) -> dict[int, str """ brute_force =========== + Returns all the possible combinations of keys and the decoded strings in the form of a dictionary Parameters: ----------- - * input_string: the cipher-text that needs to be used during brute-force + + * `input_string`: the cipher-text that needs to be used during brute-force Optional: - * alphabet: (None): the alphabet used to decode the cipher, if not + + * `alphabet` (``None``): the alphabet used to decode the cipher, if not specified, the standard english alphabet with upper and lowercase letters is used More about brute force ====================== + Brute force is when a person intercepts a message or password, not knowing the key and tries every single combination. This is easy with the caesar cipher since there are only all the letters in the alphabet. The more complex the cipher, the larger amount of time it will take to do brute force Ex: - Say we have a 5 letter alphabet (abcde), for simplicity and we intercepted the - following message: - - "dbc" - + Say we have a ``5`` letter alphabet (``abcde``), for simplicity and we intercepted + the following message: ``dbc``, we could then just write out every combination: - ecd... and so on, until we reach a combination that makes sense: - "cab" + ``ecd``... and so on, until we reach a combination that makes sense: + ``cab`` Further reading =============== + * https://en.wikipedia.org/wiki/Brute_force Doctests ======== + >>> brute_force("jFyuMy xIH'N vLONy zILwy Gy!")[20] "Please don't brute force me!" @@ -208,7 +225,7 @@ def brute_force(input_string: str, alphabet: str | None = None) -> dict[int, str if __name__ == "__main__": while True: - print(f'\n{"-" * 10}\n Menu\n{"-" * 10}') + print(f"\n{'-' * 10}\n Menu\n{'-' * 10}") print(*["1.Encrypt", "2.Decrypt", "3.BruteForce", "4.Quit"], sep="\n") # get user input diff --git a/ciphers/columnar_transposition.py b/ciphers/columnar_transposition.py new file mode 100644 index 000000000000..d697db6e1176 --- /dev/null +++ b/ciphers/columnar_transposition.py @@ -0,0 +1,127 @@ +"""Columnar Transposition cipher. + +This classical cipher writes the plaintext in rows under a keyword and reads +columns in the order of the alphabetical rank of the keyword letters. + +Reference: https://en.wikipedia.org/wiki/Transposition_cipher#Columnar_transposition + +We keep spaces and punctuation. Key must be alphabetic (case-insensitive). + +>>> pt = "WE ARE DISCOVERED. FLEE AT ONCE" +>>> ct = encrypt(pt, "ZEBRAS") +>>> decrypt(ct, "ZEBRAS") == pt +True + +Edge cases: +>>> encrypt("HELLO", "A") +'HELLO' +>>> decrypt("HELLO", "A") +'HELLO' +>>> encrypt("HELLO", "HELLO") +'EHLLO' +>>> decrypt("EHLLO", "HELLO") +'HELLO' +>>> encrypt("HELLO", "") +Traceback (most recent call last): + ... +ValueError: Key must be a non-empty alphabetic string +""" + +from __future__ import annotations + + +def _normalize_key(key: str) -> str: + k = "".join(ch for ch in key.upper() if ch.isalpha()) + if not k: + raise ValueError("Key must be a non-empty alphabetic string") + return k + + +def _column_order(key: str) -> list[int]: + # Stable sort by character then original index to handle duplicates + indexed = list(enumerate(key)) + return [ + i + for i, _ in sorted( + indexed, key=lambda indexed_pair: (indexed_pair[1], indexed_pair[0]) + ) + ] + + +def encrypt(plaintext: str, key: str) -> str: + """Encrypt using columnar transposition. + + :param plaintext: Input text (any characters) + :param key: Alphabetic keyword + :return: Ciphertext + :raises ValueError: on invalid key + """ + k = _normalize_key(key) + cols = len(k) + if cols == 1: + return plaintext + + order = _column_order(k) + + # Build ragged rows without padding + rows = (len(plaintext) + cols - 1) // cols + grid: list[str] = [plaintext[i * cols : (i + 1) * cols] for i in range(rows)] + + # Read columns in sorted order, skipping missing cells + out: list[str] = [] + for col in order: + for r in range(rows): + if col < len(grid[r]): + out.append(grid[r][col]) + return "".join(out) + + +def decrypt(ciphertext: str, key: str) -> str: + """Decrypt columnar transposition ciphertext. + + :param ciphertext: Encrypted text + :param key: Alphabetic keyword + :return: Decrypted plaintext + :raises ValueError: on invalid key + """ + k = _normalize_key(key) + cols = len(k) + if cols == 1: + return ciphertext + + order = _column_order(k) + text_len = len(ciphertext) + rows = (text_len + cols - 1) // cols + r = text_len % cols + + # Column lengths based on ragged last row (no padding during encryption) + col_lengths: list[int] = [] + for c in range(cols): + if r == 0: + col_lengths.append(rows) + else: + col_lengths.append(rows if c < r else rows - 1) + + # Slice ciphertext into columns following the sorted order + columns: list[str] = [""] * cols + idx = 0 + for col in order: + ln = col_lengths[col] + columns[col] = ciphertext[idx : idx + ln] + idx += ln + + # Rebuild plaintext row-wise + out: list[str] = [] + pointers = [0] * cols + for _ in range(rows * cols): + c = len(out) % cols + if pointers[c] < len(columns[c]): + out.append(columns[c][pointers[c]]) + pointers[c] += 1 + return "".join(out) + + +if __name__ == "__main__": # pragma: no cover + import doctest + + doctest.testmod() diff --git a/ciphers/cryptomath_module.py b/ciphers/cryptomath_module.py index 02e94e4b9e92..bf813c8c0167 100644 --- a/ciphers/cryptomath_module.py +++ b/ciphers/cryptomath_module.py @@ -1,7 +1,76 @@ +""" +Cryptographic mathematics module for modular arithmetic operations. + +This module provides utilities for cryptographic computations, +particularly modular multiplicative inverse. +""" + from maths.greatest_common_divisor import gcd_by_iterative def find_mod_inverse(a: int, m: int) -> int: + """ + Find the modular multiplicative inverse of a modulo m. + + The modular multiplicative inverse of a modulo m is an integer x such that: + (a * x) % m = 1 + + This function uses the Extended Euclidean Algorithm to find the inverse. + An inverse exists if and only if a and m are coprime (gcd(a, m) = 1). + + Args: + a: The integer to find the inverse of + m: The modulus + + Returns: + The modular multiplicative inverse of a modulo m + + Raises: + ValueError: If gcd(a, m) != 1 (inverse does not exist) + + Reference: + https://en.wikipedia.org/wiki/Modular_multiplicative_inverse + + Examples: + >>> find_mod_inverse(3, 7) + 5 + >>> (3 * 5) % 7 # Verify: 3 * 5 ≡ 1 (mod 7) + 1 + >>> find_mod_inverse(3, 10) + 7 + >>> (3 * 7) % 10 # Verify: 3 * 7 ≡ 1 (mod 10) + 1 + >>> find_mod_inverse(4, 11) + 3 + >>> (4 * 3) % 11 # Verify: 4 * 3 ≡ 1 (mod 11) + 1 + >>> find_mod_inverse(7, 26) + 15 + >>> (7 * 15) % 26 # Verify: 7 * 15 ≡ 1 (mod 26) + 1 + >>> find_mod_inverse(1, 5) + 1 + >>> find_mod_inverse(2, 7) + 4 + >>> find_mod_inverse(3, 11) + 4 + >>> find_mod_inverse(5, 11) + 9 + >>> find_mod_inverse(5, 17) + 7 + >>> find_mod_inverse(2, 4) + Traceback (most recent call last): + ... + ValueError: mod inverse of 2 and 4 does not exist + >>> find_mod_inverse(6, 9) + Traceback (most recent call last): + ... + ValueError: mod inverse of 6 and 9 does not exist + >>> find_mod_inverse(10, 20) + Traceback (most recent call last): + ... + ValueError: mod inverse of 10 and 20 does not exist + """ if gcd_by_iterative(a, m) != 1: msg = f"mod inverse of {a!r} and {m!r} does not exist" raise ValueError(msg) diff --git a/ciphers/decrypt_caesar_with_chi_squared.py b/ciphers/decrypt_caesar_with_chi_squared.py index 10832203e531..fb95c0f90628 100644 --- a/ciphers/decrypt_caesar_with_chi_squared.py +++ b/ciphers/decrypt_caesar_with_chi_squared.py @@ -11,33 +11,31 @@ def decrypt_caesar_with_chi_squared( """ Basic Usage =========== + Arguments: - * ciphertext (str): the text to decode (encoded with the caesar cipher) + * `ciphertext` (str): the text to decode (encoded with the caesar cipher) Optional Arguments: - * cipher_alphabet (list): the alphabet used for the cipher (each letter is - a string separated by commas) - * frequencies_dict (dict): a dictionary of word frequencies where keys are - the letters and values are a percentage representation of the frequency as - a decimal/float - * case_sensitive (bool): a boolean value: True if the case matters during - decryption, False if it doesn't + * `cipher_alphabet` (list): the alphabet used for the cipher (each letter is + a string separated by commas) + * `frequencies_dict` (dict): a dictionary of word frequencies where keys are + the letters and values are a percentage representation of the frequency as + a decimal/float + * `case_sensitive` (bool): a boolean value: ``True`` if the case matters during + decryption, ``False`` if it doesn't Returns: - * A tuple in the form of: - ( - most_likely_cipher, - most_likely_cipher_chi_squared_value, - decoded_most_likely_cipher - ) + * A tuple in the form of: + (`most_likely_cipher`, `most_likely_cipher_chi_squared_value`, + `decoded_most_likely_cipher`) - where... - - most_likely_cipher is an integer representing the shift of the smallest - chi-squared statistic (most likely key) - - most_likely_cipher_chi_squared_value is a float representing the - chi-squared statistic of the most likely shift - - decoded_most_likely_cipher is a string with the decoded cipher - (decoded by the most_likely_cipher key) + where... + - `most_likely_cipher` is an integer representing the shift of the smallest + chi-squared statistic (most likely key) + - `most_likely_cipher_chi_squared_value` is a float representing the + chi-squared statistic of the most likely shift + - `decoded_most_likely_cipher` is a string with the decoded cipher + (decoded by the most_likely_cipher key) The Chi-squared test @@ -45,52 +43,57 @@ def decrypt_caesar_with_chi_squared( The caesar cipher ----------------- + The caesar cipher is a very insecure encryption algorithm, however it has been used since Julius Caesar. The cipher is a simple substitution cipher where each character in the plain text is replaced by a character in the alphabet a certain number of characters after the original character. The number of characters away is called the shift or key. For example: - Plain text: hello - Key: 1 - Cipher text: ifmmp - (each letter in hello has been shifted one to the right in the eng. alphabet) + | Plain text: ``hello`` + | Key: ``1`` + | Cipher text: ``ifmmp`` + | (each letter in ``hello`` has been shifted one to the right in the eng. alphabet) As you can imagine, this doesn't provide lots of security. In fact decrypting ciphertext by brute-force is extremely easy even by hand. However - one way to do that is the chi-squared test. + one way to do that is the chi-squared test. The chi-squared test - ------------------- + -------------------- + Each letter in the english alphabet has a frequency, or the amount of times it shows up compared to other letters (usually expressed as a decimal representing the percentage likelihood). The most common letter in the - english language is "e" with a frequency of 0.11162 or 11.162%. The test is - completed in the following fashion. + english language is ``e`` with a frequency of ``0.11162`` or ``11.162%``. + The test is completed in the following fashion. 1. The ciphertext is decoded in a brute force way (every combination of the - 26 possible combinations) + ``26`` possible combinations) 2. For every combination, for each letter in the combination, the average amount of times the letter should appear the message is calculated by - multiplying the total number of characters by the frequency of the letter + multiplying the total number of characters by the frequency of the letter. + + | For example: + | In a message of ``100`` characters, ``e`` should appear around ``11.162`` + times. - For example: - In a message of 100 characters, e should appear around 11.162 times. + 3. Then, to calculate the margin of error (the amount of times the letter + SHOULD appear with the amount of times the letter DOES appear), we use + the chi-squared test. The following formula is used: - 3. Then, to calculate the margin of error (the amount of times the letter - SHOULD appear with the amount of times the letter DOES appear), we use - the chi-squared test. The following formula is used: + Let: + - n be the number of times the letter actually appears + - p be the predicted value of the number of times the letter should + appear (see item ``2``) + - let v be the chi-squared test result (referred to here as chi-squared + value/statistic) - Let: - - n be the number of times the letter actually appears - - p be the predicted value of the number of times the letter should - appear (see #2) - - let v be the chi-squared test result (referred to here as chi-squared - value/statistic) + :: - (n - p)^2 - --------- = v - p + (n - p)^2 + --------- = v + p 4. Each chi squared value for each letter is then added up to the total. The total is the chi-squared statistic for that encryption key. @@ -98,16 +101,16 @@ def decrypt_caesar_with_chi_squared( to be the decoded answer. Further Reading - ================ + =============== - * http://practicalcryptography.com/cryptanalysis/text-characterisation/chi-squared- - statistic/ + * http://practicalcryptography.com/cryptanalysis/text-characterisation/chi-squared-statistic/ * https://en.wikipedia.org/wiki/Letter_frequency * https://en.wikipedia.org/wiki/Chi-squared_test * https://en.m.wikipedia.org/wiki/Caesar_cipher Doctests ======== + >>> decrypt_caesar_with_chi_squared( ... 'dof pz aol jhlzhy jpwoly zv wvwbshy? pa pz avv lhzf av jyhjr!' ... ) # doctest: +NORMALIZE_WHITESPACE diff --git a/ciphers/des_ecb.py b/ciphers/des_ecb.py new file mode 100644 index 000000000000..559aee9b764a --- /dev/null +++ b/ciphers/des_ecb.py @@ -0,0 +1,562 @@ +""" +Python program for DES (Data Encryption Standard) using Electronic Codebook (ECB) mode. + +DES is a symmetric-key block cipher that encrypts data in fixed-size blocks (64 bits). +In ECB mode, the plaintext is divided into 64-bit blocks, and each block is encrypted +independently using the same key. This makes ECB the simplest block cipher mode, but +also one of the least secure, as identical plaintext blocks will produce identical +ciphertext blocks. + +This implementation of DES includes key scheduling, encryption, and decryption. +It uses standard DES operations such as initial and final permutations, expansion, +permutation, and S-box lookups. Padding is applied to ensure the plaintext length is +a multiple of 64 bits. + +Warning: ECB mode is not secure for most use cases due to its vulnerability to block +repetition analysis. Consider using a more secure mode of operation, such as CBC +(Cipher Block Chaining), for sensitive data encryption. + +References: +- Handbook of Applied Cryptography (Algorithm 7.82) +- Handbook of Applied Cryptography (Algorithm 7.83) +- Handbook of Applied Cryptography (Algorithm 9.29) +- https://en.wikipedia.org/wiki/Data_Encryption_Standard +""" + +import random + +# fmt: off + +# Initial Permutation Table +IP = [58, 50, 42, 34, 26, 18, 10, 2, + 60, 52, 44, 36, 28, 20, 12, 4, + 62, 54, 46, 38, 30, 22, 14, 6, + 64, 56, 48, 40, 32, 24, 16, 8, + 57, 49, 41, 33, 25, 17, 9, 1, + 59, 51, 43, 35, 27, 19, 11, 3, + 61, 53, 45, 37, 29, 21, 13, 5, + 63, 55, 47, 39, 31, 23, 15, 7] + +# Final Permutation Table +IP_INV = [40, 8, 48, 16, 56, 24, 64, 32, + 39, 7, 47, 15, 55, 23, 63, 31, + 38, 6, 46, 14, 54, 22, 62, 30, + 37, 5, 45, 13, 53, 21, 61, 29, + 36, 4, 44, 12, 52, 20, 60, 28, + 35, 3, 43, 11, 51, 19, 59, 27, + 34, 2, 42, 10, 50, 18, 58, 26, + 33, 1, 41, 9, 49, 17, 57, 25] + +# Expansion Table +E = [32, 1, 2, 3, 4, 5, + 4, 5, 6, 7, 8, 9, + 8, 9, 10, 11, 12, 13, + 12, 13, 14, 15, 16, 17, + 16, 17, 18, 19, 20, 21, + 20, 21, 22, 23, 24, 25, + 24, 25, 26, 27, 28, 29, + 28, 29, 30, 31, 32, 1] + +# Permutation Table +P = [16, 7, 20, 21, 29, 12, 28, 17, + 1, 15, 23, 26, 5, 18, 31, 10, + 2, 8, 24, 14, 32, 27, 3, 9, + 19, 13, 30, 6, 22, 11, 4, 25] + +# S-boxes (Substitution Boxes) +S_BOXES = { + "S1": [[14, 4, 13, 1, 2, 15, 11, 8, 3, 10, 6, 12, 5, 9, 0, 7], + [0, 15, 7, 4, 14, 2, 13, 1, 10, 6, 12, 11, 9, 5, 3, 8], + [4, 1, 14, 8, 13, 6, 2, 11, 15, 12, 9, 7, 3, 10, 5, 0], + [15, 12, 8, 2, 4, 9, 1, 7, 5, 11, 3, 14, 10, 0, 6, 13]], + + "S2": [[15, 1, 8, 14, 6, 11, 3, 4, 9, 7, 2, 13, 12, 0, 5, 10], + [3, 13, 4, 7, 15, 2, 8, 14, 12, 0, 1, 10, 6, 9, 11, 5], + [0, 14, 7, 11, 10, 4, 13, 1, 5, 8, 12, 6, 9, 3, 2, 15], + [13, 8, 10, 1, 3, 15, 4, 2, 11, 6, 7, 12, 0, 5, 14, 9]], + + "S3": [[10, 0, 9, 14, 6, 3, 15, 5, 1, 13, 12, 7, 11, 4, 2, 8], + [13, 7, 0, 9, 3, 4, 6, 10, 2, 8, 5, 14, 12, 11, 15, 1], + [13, 6, 4, 9, 8, 15, 3, 0, 11, 1, 2, 12, 5, 10, 14, 7], + [1, 10, 13, 0, 6, 9, 8, 7, 4, 15, 14, 3, 11, 5, 2, 12]], + + "S4": [[7, 13, 14, 3, 0, 6, 9, 10, 1, 2, 8, 5, 11, 12, 4, 15], + [13, 8, 11, 5, 6, 15, 0, 3, 4, 7, 2, 12, 1, 10, 14, 9], + [10, 6, 9, 0, 12, 11, 7, 13, 15, 1, 3, 14, 5, 2, 8, 4], + [3, 15, 0, 6, 10, 1, 13, 8, 9, 4, 5, 11, 12, 7, 2, 14]], + + "S5": [[2, 12, 4, 1, 7, 10, 11, 6, 8, 5, 3, 15, 13, 0, 14, 9], + [14, 11, 2, 12, 4, 7, 13, 1, 5, 0, 15, 10, 3, 9, 8, 6], + [4, 2, 1, 11, 10, 13, 7, 8, 15, 9, 12, 5, 6, 3, 0, 14], + [11, 8, 12, 7, 1, 14, 2, 13, 6, 15, 0, 9, 10, 4, 5, 3]], + + "S6": [[12, 1, 10, 15, 9, 2, 6, 8, 0, 13, 3, 4, 14, 7, 5, 11], + [10, 15, 4, 2, 7, 12, 9, 5, 6, 1, 13, 14, 0, 11, 3, 8], + [9, 14, 15, 5, 2, 8, 12, 3, 7, 0, 4, 10, 1, 13, 11, 6], + [4, 3, 2, 12, 9, 5, 15, 10, 11, 14, 1, 7, 6, 0, 8, 13]], + + "S7": [[4, 11, 2, 14, 15, 0, 8, 13, 3, 12, 9, 7, 5, 10, 6, 1], + [13, 0, 11, 7, 4, 9, 1, 10, 14, 3, 5, 12, 2, 15, 8, 6], + [1, 4, 11, 13, 12, 3, 7, 14, 10, 15, 6, 8, 0, 5, 9, 2], + [6, 11, 13, 8, 1, 4, 10, 7, 9, 5, 0, 15, 14, 2, 3, 12]], + + "S8": [[13, 2, 8, 4, 6, 15, 11, 1, 10, 9, 3, 14, 5, 0, 12, 7], + [1, 15, 13, 8, 10, 3, 7, 4, 12, 5, 6, 11, 0, 14, 9, 2], + [7, 11, 4, 1, 9, 12, 14, 2, 0, 6, 10, 13, 15, 3, 5, 8], + [2, 1, 14, 7, 4, 10, 8, 13, 15, 12, 9, 0, 3, 5, 6, 11]] +} + +# Permuted Choice 1 Table +PC1 = [57, 49, 41, 33, 25, 17, 9, + 1, 58, 50, 42, 34, 26, 18, + 10, 2, 59, 51, 43, 35, 27, + 19, 11, 3, 60, 52, 44, 36, + 63, 55, 47, 39, 31, 23, 15, + 7, 62, 54, 46, 38, 30, 22, + 14, 6, 61, 53, 45, 37, 29, + 21, 13, 5, 28, 20, 12, 4] + +# Permuted Choice 2 Table +PC2 = [14, 17, 11, 24, 1, 5, + 3, 28, 15, 6, 21, 10, + 23, 19, 12, 4, 26, 8, + 16, 7, 27, 20, 13, 2, + 41, 52, 31, 37, 47, 55, + 30, 40, 51, 45, 33, 48, + 44, 49, 39, 56, 34, 53, + 46, 42, 50, 36, 29, 32] +# fmt: on + + +class Operations: + @staticmethod + def string_to_bitset(string: str) -> list: + """ + Converts a string into a list of binary digits (bitset). + + Args: + string (str): The input string to be converted. + + Returns: + list: A list of binary digits representing the string. + + Examples: + >>> Operations.string_to_bitset('A') + ['0', '1', '0', '0', '0', '0', '0', '1'] + >>> len(Operations.string_to_bitset('ab')) + 16 + >>> Operations.string_to_bitset(' ') + ['0', '0', '1', '0', '0', '0', '0', '0'] + """ + return list("".join(format(ord(char), "08b") for char in string)) + + @staticmethod + def pad_right_to_multiple_of_n(bitset: list, length: int) -> list: + """ + Pads the bitset with zeros on the right until + its length is a multiple of `length`. + + Args: + bitset (list): A list of binary digits (as strings) to be padded. + + Returns: + list: The padded bitset, with a length that is a multiple of n. + + Examples: + >>> Operations.pad_right_to_multiple_of_n(['1', '0', '1'], 4) + ['1', '0', '1', '0'] + >>> len(Operations.pad_right_to_multiple_of_n(['1'] * 64, 64)) % 64 + 0 + >>> len(Operations.pad_right_to_multiple_of_n(['0'] * 63, 64)) % 64 + 0 + """ + if len(bitset) % length != 0: + bitset += list("0" * (length - len(bitset) % length)) + return bitset + + @staticmethod + def pad_left_to_multiple_of_n(bitset: list, length: int) -> list: + """ + Pads the bitset with zeros on the left until + its length is a multiple of length. + + Args: + bitset (list): A list of binary digits (as strings) to be padded. + + Returns: + list: The padded bitset, with a length that is a multiple of n. + + Examples: + >>> Operations.pad_left_to_multiple_of_n(['1', '0', '1'], 4) + ['0', '1', '0', '1'] + >>> len(Operations.pad_left_to_multiple_of_n(['1'] * 64, 64)) % 64 + 0 + >>> len(Operations.pad_left_to_multiple_of_n(['0'] * 63, 64)) % 64 + 0 + """ + if len(bitset) % length != 0: + bitset = list("0" * (length - len(bitset) % length)) + bitset + return bitset + + @staticmethod + def bitset_to_hex(bitset: list) -> str: + """ + Converts a list of binary digits + into its 16 digit hexadecimal representation. + + Args: + bitset (list): A list of binary digits (as strings)\ + representing a binary number. + + Returns: + str: The 16 digit hexadecimal representation of the binary number. + + Examples: + >>> Operations.bitset_to_hex(['1', '0', '1', '0', '1', '1', '1', '0']) + '00000000000000ae' + >>> Operations.bitset_to_hex(['1', '1', '1', '1'] * 16) + 'ffffffffffffffff' + >>> Operations.bitset_to_hex(['0'] * 64) + '0000000000000000' + """ + return format(int("".join(bitset), 2), "016x") + + @staticmethod + def hex_to_bitset(hex_string: str, left_pad: int) -> list: + """ + Converts a hexadecimal string to a bitset + and pads the bitset to a specified length. + + Args: + hex_string (str): The hexadecimal string to convert. + left_pad (int): The length to pad the bitset on the left. + + Returns: + list: The padded bitset. + + Examples: + >>> Operations.hex_to_bitset('ae', 8) + ['1', '0', '1', '0', '1', '1', '1', '0'] + >>> Operations.hex_to_bitset('1f', 10) + ['0', '0', '0', '0', '0', '1', '1', '1', '1', '1'] + """ + return Operations.pad_left_to_multiple_of_n( + list(format(int(hex_string, 16), f"0{left_pad}b")), left_pad + ) + + @staticmethod + def bitset_to_string(bitset: list) -> str: + """ + Converts a bitset into a string by interpreting every 8 bits as a character. + + Args: + bitset (list): The list of binary digits (bitset). + + Returns: + str: The decoded string. + + Examples: + >>> Operations.bitset_to_string(['0', '1', '0', '0', '0', '0', '0', '1']) + 'A' + >>> Operations.bitset_to_string(['0', '1', '0', '0', '0', '1',\ +'0', '0', '0', '1', '0', '1', '0', '1', '1', '0']) + 'DV' + """ + return "".join( + chr(int("".join(bitset[i : i + 8]), 2)) for i in range(0, len(bitset), 8) + ) + + @staticmethod + def xor(bitset1: list, bitset2: list) -> list: + """ + Applies a bitwise XOR operation between two bitsets of the same length. + + Args: + bitset1 (list): The first bitset. + bitset2 (list): The second bitset. + + Returns: + list: The result of the XOR operation as a new bitset. + + Examples: + >>> Operations.xor(['0', '1', '0', '1'], ['1', '0', '1', '1']) + ['1', '1', '1', '0'] + >>> Operations.xor(['1', '0', '1', '0'], ['0', '0', '0', '1']) + ['1', '0', '1', '1'] + >>> Operations.xor(['1', '0', '1', '0', '1'], ['0', '0', '0', '1']) + Traceback (most recent call last): + ... + ValueError: Bitsets must be of the same length + >>> Operations.xor(['1', '0', '1', '0'], ['0', '0', '0', '1', '1']) + Traceback (most recent call last): + ... + ValueError: Bitsets must be of the same length + """ + if len(bitset1) != len(bitset2): + raise ValueError("Bitsets must be of the same length") + return [str(int(bitset1[i]) ^ int(bitset2[i])) for i in range(len(bitset1))] + + @staticmethod + def shift_left(bitset: list, position: int) -> list: + """ + Performs a rotated left shift on a bitset by `position` positions. + + Args: + bitset (list): The bitset to be shifted. + n (int): The number of positions to shift. + + Returns: + list: The left-shifted bitset. + + Examples: + >>> Operations.shift_left(['1', '0', '0', '1'], 2) + ['0', '1', '1', '0'] + >>> Operations.shift_left(['0', '1', '1', '1'], 1) + ['1', '1', '1', '0'] + >>> Operations.shift_left(['0', '1', '1', '1'], 7) + ['1', '0', '1', '1'] + """ + position = position % len(bitset) + return bitset[position:] + bitset[:position] + + @staticmethod + def permute(bitset: list, permutation: list) -> list: + """ + Permutes a bitset according to a given permutation table. + + Args: + bitset (list): The bitset to be permuted. + permutation (list): The permutation table specifying the new order. + + Returns: + list: The permuted bitset. + + Examples: + >>> Operations.permute(['1', '0', '1', '0', '1', '1'], [6, 5, 4, 3, 2, 1]) + ['1', '1', '0', '1', '0', '1'] + >>> Operations.permute(['0', '1', '1', '0', '1', '0'], [3, 1, 6, 5, 4, 2]) + ['1', '0', '0', '1', '0', '1'] + >>> Operations.permute(['0', '1', '1', '0', '1', '0'], \ +[3, 1, 6, 5, 4, 2, 7]) + Traceback (most recent call last): + ... + ValueError: Permutation values must be within the range of the bitset + """ + if not all(0 < i <= len(bitset) for i in permutation): + raise ValueError( + "Permutation values must be within the range of the bitset" + ) + return [bitset[i - 1] for i in permutation] + + +class Des: + @staticmethod + def generate_key() -> str: + """ + Generates a random hexadecimal key of 16 characters (64 bits). + + Returns: + str: A random hexadecimal key. + + Examples: + >>> key = Des.generate_key() + >>> len(key) # Check if the key length is correct + 16 + >>> # Ensure key only contains valid hex characters + >>> all(c in "0123456789abcdef" for c in key) + True + """ + return "".join(random.choice("0123456789abcdef") for i in range(16)) + + @staticmethod + def key_schedule(key: str) -> list: + """ + Generates 16 subkeys (round keys) from a given + 64-bit hexadecimal key using the DES key schedule. + + Args: + key (str): A 16-character hexadecimal string representing a 64-bit key. + + Returns: + list: A list of 16 subkeys, each of which is a permuted bitset. + + Examples: + >>> subkeys = Des.key_schedule('133457799BBCDFF1') + >>> len(subkeys) # Check that 16 subkeys are generated + 16 + >>> # Ensure each subkey is 48 bits long + >>> all(len(subkey) == 48 for subkey in subkeys) + True + """ + key_bitset = Operations.hex_to_bitset(key, 64) + key_permuted = Operations.permute(key_bitset, PC1) + + left_key = key_permuted[:28] + right_key = key_permuted[28:] + + keys = [] + + shift_list = [1, 2, 9, 16] + + for i in range(1, 17): + if i in shift_list: + left_key = Operations.shift_left(left_key, 1) + right_key = Operations.shift_left(right_key, 1) + else: + left_key = Operations.shift_left(left_key, 2) + right_key = Operations.shift_left(right_key, 2) + keys.append(Operations.permute(left_key + right_key, PC2)) + + return keys + + @staticmethod + def des(keys: list, plain_bitset: list) -> list: + """ + Encrypts a plain bitset using the provided + subkeys with DES encryption algorithm. + + Args: + keys (list): A list of 16 subkeys, each 48 bits long. + plain_bitset (list): A bitset representing the plain text,\ + which should be divisible into 64-bit blocks. + + Returns: + list: The encrypted bitset. + + Examples: + >>> plain_bitset = Operations.string_to_bitset("Test string") + >>> plain_bitset = Operations.pad_right_to_multiple_of_n(plain_bitset, 64) + >>> keys = Des.key_schedule(Des.generate_key()) + >>> cipher_bitset = Des.des(keys, plain_bitset) + >>> # The output length should be the same as the input + >>> len(cipher_bitset) == len(plain_bitset) + True + >>> # Decryption should be the inverse of encryption + >>> plain_bitset == Des.des(keys[::-1], cipher_bitset) + True + """ + + no_of_blocks = len(plain_bitset) // 64 + + cipher_bitset = [] + + for i in range(no_of_blocks): + block = plain_bitset[i * 64 : (i + 1) * 64] + initial_permutation = Operations.permute(block, IP) + + left_bits = initial_permutation[:32] + right_bits = initial_permutation[32:] + + for i in range(16): + right_expanded = Operations.permute(right_bits, E) + right_xor_key = Operations.xor(right_expanded, keys[i]) + right_s_box = [] + for j in range(8): + s_box_input = right_xor_key[j * 6 : (j + 1) * 6] + row = 2 * int(s_box_input[0]) + int(s_box_input[5]) + col = int("".join(s_box_input[1:5]), 2) + s_box_output = format(S_BOXES[f"S{j + 1}"][row][col], "04b") + right_s_box += list(s_box_output) + + right_permuted = Operations.permute(right_s_box, P) + + left_bits, right_bits = ( + right_bits, + Operations.xor(left_bits, right_permuted), + ) + + left_bits, right_bits = right_bits, left_bits + cipher_bitset += Operations.permute(left_bits + right_bits, IP_INV) + return cipher_bitset + + @staticmethod + def encrypt(key: str, input_string: str) -> str: + """ + Encrypts a given input string using the DES encryption algorithm. + + Args: + key (str): A 16-character hexadecimal string representing a 64-bit key. + input_string (str): The plain text string to be encrypted. + + Returns: + str: A hexadecimal string representing the encrypted data. + + Examples: + >>> key = '133457799BBCDFF1' + >>> input_string = 'Test string' + >>> encrypted = Des.encrypt(key, input_string) + >>> encrypted # Checking the cipher to ensure consistency + 'c84e3c8fb646872720b224896db4f60' + """ + plain_bitset = Operations.string_to_bitset(input_string) + padded_bitset = Operations.pad_right_to_multiple_of_n(plain_bitset, 64) + keys = Des.key_schedule(key) + cipher_bitset = Des.des(keys, padded_bitset) + return Operations.bitset_to_hex(cipher_bitset) + + @staticmethod + def decrypt(key: str, cipher_text: str) -> str: + """ + Decrypts the given cipher text using DES decryption. + + Args: + key (str): A 16-character hexadecimal string representing a 64-bit key. + cipher_text (str): A hexadecimal string representing the encrypted data. + + Returns: + str: The decrypted plain text string. + + Examples: + >>> key = '133457799BBCDFF1' + >>> encrypted_string = 'c84e3c8fb646872720b224896db4f60' + >>> decrypted = Des.decrypt(key, encrypted_string) + >>> decrypted # Checking the cipher to ensure consistency + 'Test string' + """ + cipher_bitset = Operations.hex_to_bitset(cipher_text, 64) + keys = Des.key_schedule(key)[::-1] + plain_bitset = Des.des(keys, cipher_bitset) + return Operations.bitset_to_string(plain_bitset).replace("\x00", "") + + +if __name__ == "__main__": + import doctest + + doctest.testmod() + + while True: + print() + print("################ DES Algorithm ################") + print() + print("Select an option:") + print("1. To encrypt a string, enter 'e'") + print("2. To decrypt a string, enter 'd'") + print("3. To generate a key, enter 'k'") + print("4. To Quit, enter 'q'") + mode = input("Enter the option: ").strip().lower() + if mode not in ["e", "d", "k", "q"]: + print("Invalid option. Please try again.") + continue + match mode: + case "q": + break + case "k": + print(f"Generated key: {Des.generate_key()}") + case "e": + key = input("Enter the key: ").strip() + if len(key) != 16 and not all( + char in "0123456789abcdef" for char in key + ): + print("Invalid key. Please try again.") + continue + input_string = input("Enter the string to encrypt: ").strip() + print(f"Encrypted string: {Des.encrypt(key, input_string)}") + case "d": + key = input("Enter the key: ").strip() + if len(key) != 16 and not all( + char in "0123456789abcdef" for char in key + ): + print("Invalid key. Please try again.") + continue + cipher_text = input("Enter the cipher text to decrypt: ").strip() + print(f"Decrypted string: {Des.decrypt(key, cipher_text)}") diff --git a/ciphers/enigma_machine2.py b/ciphers/enigma_machine2.py index 163aa7172c11..d94205e99ec1 100644 --- a/ciphers/enigma_machine2.py +++ b/ciphers/enigma_machine2.py @@ -1,14 +1,16 @@ """ -Wikipedia: https://en.wikipedia.org/wiki/Enigma_machine -Video explanation: https://youtu.be/QwQVMqfoB2E -Also check out Numberphile's and Computerphile's videos on this topic +| Wikipedia: https://en.wikipedia.org/wiki/Enigma_machine +| Video explanation: https://youtu.be/QwQVMqfoB2E +| Also check out Numberphile's and Computerphile's videos on this topic -This module contains function 'enigma' which emulates +This module contains function ``enigma`` which emulates the famous Enigma machine from WWII. + Module includes: -- enigma function + +- ``enigma`` function - showcase of function usage -- 9 randomly generated rotors +- ``9`` randomly generated rotors - reflector (aka static rotor) - original alphabet @@ -73,7 +75,7 @@ def _validator( rotpos: RotorPositionT, rotsel: RotorSelectionT, pb: str ) -> tuple[RotorPositionT, RotorSelectionT, dict[str, str]]: """ - Checks if the values can be used for the 'enigma' function + Checks if the values can be used for the ``enigma`` function >>> _validator((1,1,1), (rotor1, rotor2, rotor3), 'POLAND') ((1, 1, 1), ('EGZWVONAHDCLFQMSIPJBYUKXTR', 'FOBHMDKEXQNRAULPGSJVTYICZW', \ @@ -83,7 +85,7 @@ def _validator( :param rotpos: rotor_positon :param rotsel: rotor_selection :param pb: plugb -> validated and transformed - :return: (rotpos, rotsel, pb) + :return: (`rotpos`, `rotsel`, `pb`) """ # Checks if there are 3 unique rotors @@ -118,9 +120,10 @@ def _plugboard(pbstring: str) -> dict[str, str]: >>> _plugboard('POLAND') {'P': 'O', 'O': 'P', 'L': 'A', 'A': 'L', 'N': 'D', 'D': 'N'} - In the code, 'pb' stands for 'plugboard' + In the code, ``pb`` stands for ``plugboard`` Pairs can be separated by spaces + :param pbstring: string containing plugboard setting for the Enigma machine :return: dictionary containing converted pairs """ @@ -131,10 +134,10 @@ def _plugboard(pbstring: str) -> dict[str, str]: if not isinstance(pbstring, str): msg = f"Plugboard setting isn't type string ({type(pbstring)})" raise TypeError(msg) - elif len(pbstring) % 2 != 0: + if len(pbstring) % 2 != 0: msg = f"Odd number of symbols ({len(pbstring)})" raise Exception(msg) - elif pbstring == "": + if pbstring == "": return {} pbstring.replace(" ", "") @@ -145,11 +148,10 @@ def _plugboard(pbstring: str) -> dict[str, str]: if i not in abc: msg = f"'{i}' not in list of symbols" raise Exception(msg) - elif i in tmppbl: + if i in tmppbl: msg = f"Duplicate symbol ({i})" raise Exception(msg) - else: - tmppbl.add(i) + tmppbl.add(i) del tmppbl # Created the dictionary @@ -168,31 +170,34 @@ def enigma( plugb: str = "", ) -> str: """ - The only difference with real-world enigma is that I allowed string input. + The only difference with real-world enigma is that ``I`` allowed string input. All characters are converted to uppercase. (non-letter symbol are ignored) - How it works: - (for every letter in the message) + + | How it works: + | (for every letter in the message) - Input letter goes into the plugboard. - If it is connected to another one, switch it. + If it is connected to another one, switch it. + + - Letter goes through ``3`` rotors. + Each rotor can be represented as ``2`` sets of symbol, where one is shuffled. + Each symbol from the first set has corresponding symbol in + the second set and vice versa. - - Letter goes through 3 rotors. - Each rotor can be represented as 2 sets of symbol, where one is shuffled. - Each symbol from the first set has corresponding symbol in - the second set and vice versa. + example:: - example: - | ABCDEFGHIJKLMNOPQRSTUVWXYZ | e.g. F=D and D=F - | VKLEPDBGRNWTFCJOHQAMUZYIXS | + | ABCDEFGHIJKLMNOPQRSTUVWXYZ | e.g. F=D and D=F + | VKLEPDBGRNWTFCJOHQAMUZYIXS | - Symbol then goes through reflector (static rotor). - There it is switched with paired symbol - The reflector can be represented as2 sets, each with half of the alphanet. - There are usually 10 pairs of letters. + There it is switched with paired symbol. + The reflector can be represented as ``2`` sets, each with half of the alphanet. + There are usually ``10`` pairs of letters. + + Example:: - Example: - | ABCDEFGHIJKLM | e.g. E is paired to X - | ZYXWVUTSRQPON | so when E goes in X goes out and vice versa + | ABCDEFGHIJKLM | e.g. E is paired to X + | ZYXWVUTSRQPON | so when E goes in X goes out and vice versa - Letter then goes through the rotors again @@ -211,9 +216,9 @@ def enigma( :param text: input message - :param rotor_position: tuple with 3 values in range 1..26 - :param rotor_selection: tuple with 3 rotors () - :param plugb: string containing plugboard configuration (default '') + :param rotor_position: tuple with ``3`` values in range ``1``.. ``26`` + :param rotor_selection: tuple with ``3`` rotors + :param plugb: string containing plugboard configuration (default ``''``) :return: en/decrypted string """ diff --git a/ciphers/gronsfeld_cipher.py b/ciphers/gronsfeld_cipher.py new file mode 100644 index 000000000000..a72b141bd502 --- /dev/null +++ b/ciphers/gronsfeld_cipher.py @@ -0,0 +1,45 @@ +from string import ascii_uppercase + + +def gronsfeld(text: str, key: str) -> str: + """ + Encrypt plaintext with the Gronsfeld cipher + + >>> gronsfeld('hello', '412') + 'LFNPP' + >>> gronsfeld('hello', '123') + 'IGOMQ' + >>> gronsfeld('', '123') + '' + >>> gronsfeld('yes, ¥€$ - _!@#%?', '0') + 'YES, ¥€$ - _!@#%?' + >>> gronsfeld('yes, ¥€$ - _!@#%?', '01') + 'YFS, ¥€$ - _!@#%?' + >>> gronsfeld('yes, ¥€$ - _!@#%?', '012') + 'YFU, ¥€$ - _!@#%?' + >>> gronsfeld('yes, ¥€$ - _!@#%?', '') + Traceback (most recent call last): + ... + ZeroDivisionError: division by zero + """ + ascii_len = len(ascii_uppercase) + key_len = len(key) + encrypted_text = "" + keys = [int(char) for char in key] + upper_case_text = text.upper() + + for i, char in enumerate(upper_case_text): + if char in ascii_uppercase: + new_position = (ascii_uppercase.index(char) + keys[i % key_len]) % ascii_len + shifted_letter = ascii_uppercase[new_position] + encrypted_text += shifted_letter + else: + encrypted_text += char + + return encrypted_text + + +if __name__ == "__main__": + from doctest import testmod + + testmod() diff --git a/ciphers/hill_cipher.py b/ciphers/hill_cipher.py index 33b2529f017b..a6038e576c14 100644 --- a/ciphers/hill_cipher.py +++ b/ciphers/hill_cipher.py @@ -78,8 +78,10 @@ def replace_digits(self, num: int) -> str: 'T' >>> hill_cipher.replace_digits(26) '0' + >>> hill_cipher.replace_digits(26.1) + '0' """ - return self.key_string[round(num)] + return self.key_string[int(num)] def check_determinant(self) -> None: """ @@ -201,14 +203,15 @@ def main() -> None: print("Would you like to encrypt or decrypt some text? (1 or 2)") option = input("\n1. Encrypt\n2. Decrypt\n") - if option == "1": - text_e = input("What text would you like to encrypt?: ") - print("Your encrypted text is:") - print(hc.encrypt(text_e)) - elif option == "2": - text_d = input("What text would you like to decrypt?: ") - print("Your decrypted text is:") - print(hc.decrypt(text_d)) + match option: + case "1": + text_e = input("What text would you like to encrypt?: ") + print("Your encrypted text is:") + print(hc.encrypt(text_e)) + case "2": + text_d = input("What text would you like to decrypt?: ") + print("Your decrypted text is:") + print(hc.decrypt(text_d)) if __name__ == "__main__": diff --git a/ciphers/mono_alphabetic_ciphers.py b/ciphers/mono_alphabetic_ciphers.py index 46013f4936bc..f9594ca8af5f 100644 --- a/ciphers/mono_alphabetic_ciphers.py +++ b/ciphers/mono_alphabetic_ciphers.py @@ -49,10 +49,11 @@ def main() -> None: key = "QWERTYUIOPASDFGHJKLZXCVBNM" mode = "decrypt" # set to 'encrypt' or 'decrypt' - if mode == "encrypt": - translated = encrypt_message(key, message) - elif mode == "decrypt": - translated = decrypt_message(key, message) + match mode: + case "encrypt": + translated = encrypt_message(key, message) + case "decrypt": + translated = decrypt_message(key, message) print(f"Using the key {key}, the {mode}ed message is: {translated}") diff --git a/ciphers/playfair_cipher.py b/ciphers/playfair_cipher.py index 86b45bc4fb6a..d48f113f02e0 100644 --- a/ciphers/playfair_cipher.py +++ b/ciphers/playfair_cipher.py @@ -24,7 +24,7 @@ from collections.abc import Generator, Iterable -def chunker(seq: Iterable[str], size: int) -> Generator[tuple[str, ...], None, None]: +def chunker(seq: Iterable[str], size: int) -> Generator[tuple[str, ...]]: it = iter(seq) while True: chunk = tuple(itertools.islice(it, size)) diff --git a/ciphers/rc4.py b/ciphers/rc4.py new file mode 100644 index 000000000000..30cd4a7f16a7 --- /dev/null +++ b/ciphers/rc4.py @@ -0,0 +1,217 @@ +""" +RC4 (Rivest Cipher 4) Stream Cipher Algorithm +============================================= + +RC4 is a symmetric stream cipher designed by Ron Rivest in 1987 for RSA Security. +It is famous for its simplicity and speed in software. It operates on bytes, +encrypting and decrypting data one byte at a time by XORing the plaintext with +a pseudorandom keystream. + +How it works: +------------- +1. Key Scheduling Algorithm (KSA): + Initializes and permutes a 256-byte state array (the S-box) based on the secret key. +2. Pseudo-Random Generation Algorithm (PRGA): + Generates a continuous sequence of pseudorandom bytes (the keystream) + from the S-box. + With each byte generated, the state array is mutated to ensure unpredictability. +3. Encryption/Decryption: + The plaintext is XORed byte-by-byte with the keystream to produce the ciphertext. + Since XOR is its own inverse, decryption uses the exact same process (XORing + the ciphertext with the same keystream). + +Security Status: +---------------- +WARNING: RC4 is cryptographically broken and insecure. +It suffers from significant keystream biases, particularly in the initial bytes. +If the same key is reused, or if an attacker captures enough ciphertext, they +can reconstruct the plaintext or the key. The use of RC4 is prohibited in modern +protocols (such as TLS via RFC 7465). It is implemented here strictly for +educational purposes. + +Further reading: +---------------- +* https://en.wikipedia.org/wiki/RC4 +""" + +from collections.abc import Generator + + +def ksa(key: bytes) -> list[int]: + """ + Key Scheduling Algorithm (KSA) + ============================== + + The KSA initializes the permutation in the array S (S-box) of size 256 + with values from 0 to 255. Then, it shuffles the array using the secret key. + + Parameters: + ----------- + * `key`: The secret key used for encryption/decryption as a bytes object. + + Returns: + -------- + * A list of 256 integers representing the permuted S-box. + + Doctests: + ========= + >>> ksa(b"Key")[:5] + [75, 51, 132, 157, 192] + """ + s_box = list(range(256)) + j = 0 + key_length = len(key) + for i in range(256): + j = (j + s_box[i] + key[i % key_length]) % 256 + s_box[i], s_box[j] = s_box[j], s_box[i] + return s_box + + +def prga(s_box: list[int]) -> Generator[int]: + """ + Pseudo-Random Generation Algorithm (PRGA) + ========================================= + + The PRGA generates keystream bytes from the permuted S-box S. + For each iteration, it modifies the S-box and outputs one byte of the keystream. + + Parameters: + ----------- + * `s_box`: The permuted state array S-box. + + Yields: + ------- + * An integer representing the next byte of the pseudo-random keystream. + + Doctests: + ========= + >>> box = ksa(b"Key") + >>> stream = prga(box) + >>> [next(stream) for _ in range(5)] + [235, 159, 119, 129, 183] + """ + s = s_box.copy() + i = 0 + j = 0 + while True: + i = (i + 1) % 256 + j = (j + s[i]) % 256 + s[i], s[j] = s[j], s[i] + yield s[(s[i] + s[j]) % 256] + + +def encrypt(plaintext: bytes, key: bytes) -> bytes: + """ + Encrypts/Decrypts the plaintext bytes with a key using the RC4 stream cipher. + + Parameters: + ----------- + * `plaintext`: The input message to encrypt/decrypt (bytes). + * `key`: The secret key (bytes). + + Returns: + -------- + * The encrypted/decrypted result (bytes). + + More on RC4: + ============ + RC4 (Rivest Cipher 4) is a symmetric stream cipher. Because it is symmetric, + the encryption and decryption operations are identical. The cipher + generates a pseudorandom stream of bytes (keystream) which is combined with + the plaintext using bitwise exclusive-or (XOR). + + Warning: + -------- + RC4 is cryptographically insecure and vulnerable to several attacks (such + as keystream biases). It should not be used in secure systems today. It is + implemented here purely for educational purposes. + + Further reading: + ================ + * https://en.wikipedia.org/wiki/RC4 + + Doctests: + ========= + >>> encrypt(b"Plaintext", b"Key") + b'\\xbb\\xf3\\x16\\xe8\\xd9@\\xaf\\n\\xd3' + >>> encrypt(b"pedia", b"Wiki") + b'\\x10!\\xbf\\x04 ' + >>> encrypt(b"\\x10!\\xbf\\x04 ", b"Wiki") + b'pedia' + """ + if not key: + raise ValueError("Key must not be empty.") + + s_box = ksa(key) + keystream = prga(s_box) + return bytes(p ^ next(keystream) for p in plaintext) + + +def decrypt(ciphertext: bytes, key: bytes) -> bytes: + """ + Decrypts the ciphertext bytes with a key using the RC4 stream cipher. + + Since RC4 is symmetric, decryption is identical to encryption. + + Parameters: + ----------- + * `ciphertext`: The input cipher text to decrypt (bytes). + * `key`: The secret key (bytes). + + Returns: + -------- + * The decrypted plaintext (bytes). + + Doctests: + ========= + >>> decrypt(b'\\x10!\\xbf\\x04 ', b"Wiki") + b'pedia' + """ + return encrypt(ciphertext, key) + + +if __name__ == "__main__": + import sys + + # Check for doctests + if len(sys.argv) > 1 and sys.argv[1] == "--test": + import doctest + + doctest.testmod() + sys.exit(0) + + print(f"\n{'-' * 10}\n RC4 Cipher Menu\n{'-' * 10}") + print("1. Encrypt String") + print("2. Decrypt Hex String") + print("3. Quit") + + while True: + choice = input("\nWhat would you like to do?: ").strip() + if choice == "3" or not choice: + print("Goodbye.") + break + elif choice == "1": + plain_str = input("Enter plain text to encrypt: ") + key_str = input("Enter key: ") + if not key_str: + print("Key cannot be empty!") + continue + encrypted_bytes = encrypt( + plain_str.encode("utf-8"), key_str.encode("utf-8") + ) + print(f"Ciphertext (Hex): {encrypted_bytes.hex()}") + elif choice == "2": + hex_str = input("Enter hex ciphertext to decrypt: ") + key_str = input("Enter key: ") + if not key_str: + print("Key cannot be empty!") + continue + try: + cipher_bytes = bytes.fromhex(hex_str) + decrypted_bytes = decrypt(cipher_bytes, key_str.encode("utf-8")) + decrypted_text = decrypted_bytes.decode("utf-8", errors="replace") + print(f"Decrypted text: {decrypted_text}") + except ValueError as e: + print(f"Invalid input: {e}") + else: + print("Invalid choice, please enter 1, 2, or 3.") diff --git a/ciphers/rsa_cipher.py b/ciphers/rsa_cipher.py index ac9782a49fff..d974e0c8a176 100644 --- a/ciphers/rsa_cipher.py +++ b/ciphers/rsa_cipher.py @@ -121,28 +121,31 @@ def main() -> None: elif response.lower().startswith("d"): mode = "decrypt" - if mode == "encrypt": - if not os.path.exists("rsa_pubkey.txt"): - rkg.make_key_files("rsa", 1024) - - message = input("\nEnter message: ") - pubkey_filename = "rsa_pubkey.txt" - print(f"Encrypting and writing to {filename}...") - encrypted_text = encrypt_and_write_to_file(filename, pubkey_filename, message) - - print("\nEncrypted text:") - print(encrypted_text) - - elif mode == "decrypt": - privkey_filename = "rsa_privkey.txt" - print(f"Reading from {filename} and decrypting...") - decrypted_text = read_from_file_and_decrypt(filename, privkey_filename) - print("writing decryption to rsa_decryption.txt...") - with open("rsa_decryption.txt", "w") as dec: - dec.write(decrypted_text) - - print("\nDecryption:") - print(decrypted_text) + match mode: + case "encrypt": + if not os.path.exists("rsa_pubkey.txt"): + rkg.make_key_files("rsa", 1024) + + message = input("\nEnter message: ") + pubkey_filename = "rsa_pubkey.txt" + print(f"Encrypting and writing to {filename}...") + encrypted_text = encrypt_and_write_to_file( + filename, pubkey_filename, message + ) + + print("\nEncrypted text:") + print(encrypted_text) + + case "decrypt": + privkey_filename = "rsa_privkey.txt" + print(f"Reading from {filename} and decrypting...") + decrypted_text = read_from_file_and_decrypt(filename, privkey_filename) + print("writing decryption to rsa_decryption.txt...") + with open("rsa_decryption.txt", "w") as dec: + dec.write(decrypted_text) + + print("\nDecryption:") + print(decrypted_text) if __name__ == "__main__": diff --git a/ciphers/rsa_factorization.py b/ciphers/rsa_factorization.py index 0a358a4fc2d4..585b21fac856 100644 --- a/ciphers/rsa_factorization.py +++ b/ciphers/rsa_factorization.py @@ -3,8 +3,10 @@ The program can efficiently factor RSA prime number given the private key d and public key e. -Source: on page 3 of https://crypto.stanford.edu/~dabo/papers/RSA-survey.pdf -More readable source: https://www.di-mgt.com.au/rsa_factorize_n.html + +| Source: on page ``3`` of https://crypto.stanford.edu/~dabo/papers/RSA-survey.pdf +| More readable source: https://www.di-mgt.com.au/rsa_factorize_n.html + large number can take minutes to factor, therefore are not included in doctest. """ @@ -17,13 +19,14 @@ def rsafactor(d: int, e: int, n: int) -> list[int]: """ This function returns the factors of N, where p*q=N - Return: [p, q] + + Return: [p, q] We call N the RSA modulus, e the encryption exponent, and d the decryption exponent. The pair (N, e) is the public key. As its name suggests, it is public and is used to - encrypt messages. + encrypt messages. The pair (N, d) is the secret key or private key and is known only to the recipient - of encrypted messages. + of encrypted messages. >>> rsafactor(3, 16971, 25777) [149, 173] diff --git a/ciphers/simple_keyword_cypher.py b/ciphers/simple_keyword_cypher.py index 1635471aebd1..bde137d826c3 100644 --- a/ciphers/simple_keyword_cypher.py +++ b/ciphers/simple_keyword_cypher.py @@ -1,16 +1,18 @@ def remove_duplicates(key: str) -> str: """ Removes duplicate alphabetic characters in a keyword (letter is ignored after its - first appearance). + first appearance). + :param key: Keyword to use :return: String with duplicates removed + >>> remove_duplicates('Hello World!!') 'Helo Wrd' """ key_no_dups = "" for ch in key: - if ch == " " or ch not in key_no_dups and ch.isalpha(): + if ch == " " or (ch not in key_no_dups and ch.isalpha()): key_no_dups += ch return key_no_dups @@ -18,6 +20,7 @@ def remove_duplicates(key: str) -> str: def create_cipher_map(key: str) -> dict[str, str]: """ Returns a cipher map given a keyword. + :param key: keyword to use :return: dictionary cipher map """ @@ -43,9 +46,11 @@ def create_cipher_map(key: str) -> dict[str, str]: def encipher(message: str, cipher_map: dict[str, str]) -> str: """ Enciphers a message given a cipher map. + :param message: Message to encipher :param cipher_map: Cipher map :return: enciphered string + >>> encipher('Hello World!!', create_cipher_map('Goodbye!!')) 'CYJJM VMQJB!!' """ @@ -55,9 +60,11 @@ def encipher(message: str, cipher_map: dict[str, str]) -> str: def decipher(message: str, cipher_map: dict[str, str]) -> str: """ Deciphers a message given a cipher map + :param message: Message to decipher :param cipher_map: Dictionary mapping to use :return: Deciphered string + >>> cipher_map = create_cipher_map('Goodbye!!') >>> decipher(encipher('Hello World!!', cipher_map), cipher_map) 'HELLO WORLD!!' @@ -70,6 +77,7 @@ def decipher(message: str, cipher_map: dict[str, str]) -> str: def main() -> None: """ Handles I/O + :return: void """ message = input("Enter message to encode or decode: ").strip() diff --git a/ciphers/simple_substitution_cipher.py b/ciphers/simple_substitution_cipher.py index 291a9bccd771..3c6898c7b1ee 100644 --- a/ciphers/simple_substitution_cipher.py +++ b/ciphers/simple_substitution_cipher.py @@ -22,6 +22,16 @@ def main() -> None: def check_valid_key(key: str) -> None: + """ + Check if the key is valid (contains all 26 letters of the alphabet exactly once). + Exits the program if the key is invalid. + + >>> check_valid_key('LFWOAYUISVKMNXPBDCRJTQEGHZ') + >>> check_valid_key('INVALIDKEY') + Traceback (most recent call last): + ... + SystemExit: Error in the key or symbol set. + """ key_list = list(key) letters_list = list(LETTERS) key_list.sort() @@ -69,6 +79,13 @@ def translate_message(key: str, message: str, mode: str) -> str: def get_random_key() -> str: + """ + Generate a random substitution cipher key. + + >>> random.seed(0) + >>> get_random_key() + 'OAXSGFHKWUECVDRLTJZPQIBNYM' + """ key = list(LETTERS) random.shuffle(key) return "".join(key) diff --git a/ciphers/skytale_cipher.py b/ciphers/skytale_cipher.py new file mode 100644 index 000000000000..11fe83e5c45c --- /dev/null +++ b/ciphers/skytale_cipher.py @@ -0,0 +1,103 @@ +"""Scytale (Skytale) transposition cipher. + +A classical transposition cipher used in ancient Greece. The sender wraps a +strip of parchment around a rod (scytale) and writes the message along the rod. +The recipient with a rod of the same diameter can read the message. + +Reference: https://en.wikipedia.org/wiki/Scytale + +Functions here keep characters as-is (including spaces). The key is a positive +integer representing the circumference count (number of rows). + +>>> encrypt("WE ARE DISCOVERED FLEE AT ONCE", 3) +'WA SVEFETNERDCEDL C EIOR EAOE' +>>> decrypt('WA SVEFETNERDCEDL C EIOR EAOE', 3) +'WE ARE DISCOVERED FLEE AT ONCE' + +Edge cases: +>>> encrypt("HELLO", 1) +'HELLO' +>>> decrypt("HELLO", 1) +'HELLO' +>>> encrypt("HELLO", 5) # key equals length +'HELLO' +>>> decrypt("HELLO", 5) +'HELLO' +>>> encrypt("HELLO", 0) +Traceback (most recent call last): + ... +ValueError: Key must be a positive integer +>>> decrypt("HELLO", -2) +Traceback (most recent call last): + ... +ValueError: Key must be a positive integer +""" + +from __future__ import annotations + + +def encrypt(plaintext: str, key: int) -> str: + """Encrypt plaintext using Scytale transposition. + + Write characters around a rod with `key` rows, then read off by rows. + + :param plaintext: Input message to encrypt + :param key: Positive integer number of rows + :return: Ciphertext string + :raises ValueError: if key <= 0 + """ + if key <= 0: + raise ValueError("Key must be a positive integer") + if key == 1 or len(plaintext) <= key: + return plaintext + + # Read every key-th character starting from each row offset + return "".join(plaintext[row::key] for row in range(key)) + + +def decrypt(ciphertext: str, key: int) -> str: + """Decrypt Scytale ciphertext. + + Reconstruct rows by their lengths and interleave by columns. + + :param ciphertext: Encrypted string + :param key: Positive integer number of rows + :return: Decrypted plaintext + :raises ValueError: if key <= 0 + """ + if key <= 0: + raise ValueError("Key must be a positive integer") + if key == 1 or len(ciphertext) <= key: + return ciphertext + + length = len(ciphertext) + base = length // key + extra = length % key + + # Determine each row length + row_lengths: list[int] = [base + (1 if r < extra else 0) for r in range(key)] + + # Slice ciphertext into rows + rows: list[str] = [] + idx = 0 + for r_len in row_lengths: + rows.append(ciphertext[idx : idx + r_len]) + idx += r_len + + # Pointers to current index in each row + pointers = [0] * key + + # Reconstruct by taking characters column-wise across rows + result_chars: list[str] = [] + for i in range(length): + r = i % key + if pointers[r] < len(rows[r]): + result_chars.append(rows[r][pointers[r]]) + pointers[r] += 1 + return "".join(result_chars) + + +if __name__ == "__main__": # pragma: no cover + import doctest + + doctest.testmod() diff --git a/ciphers/transposition_cipher.py b/ciphers/transposition_cipher.py index f1f07ddc3f35..76178cb6a1bc 100644 --- a/ciphers/transposition_cipher.py +++ b/ciphers/transposition_cipher.py @@ -52,10 +52,8 @@ def decrypt_message(key: int, message: str) -> str: plain_text[col] += symbol col += 1 - if ( - (col == num_cols) - or (col == num_cols - 1) - and (row >= num_rows - num_shaded_boxes) + if (col == num_cols) or ( + (col == num_cols - 1) and (row >= num_rows - num_shaded_boxes) ): col = 0 row += 1 diff --git a/ciphers/trifid_cipher.py b/ciphers/trifid_cipher.py index 16b9faf67688..13a47e9dd03b 100644 --- a/ciphers/trifid_cipher.py +++ b/ciphers/trifid_cipher.py @@ -22,7 +22,7 @@ def __encrypt_part(message_part: str, character_to_number: dict[str, str]) -> str: """ - Arrange the triagram value of each letter of 'message_part' vertically and join + Arrange the triagram value of each letter of `message_part` vertically and join them horizontally. >>> __encrypt_part('ASK', TEST_CHARACTER_TO_NUMBER) @@ -65,8 +65,8 @@ def __prepare( """ A helper function that generates the triagrams and assigns each letter of the alphabet to its corresponding triagram and stores this in a dictionary - ("character_to_number" and "number_to_character") after confirming if the - alphabet's length is 27. + (`character_to_number` and `number_to_character`) after confirming if the + alphabet's length is ``27``. >>> test = __prepare('I aM a BOy','abCdeFghijkLmnopqrStuVwxYZ+') >>> expected = ('IAMABOY','ABCDEFGHIJKLMNOPQRSTUVWXYZ+', @@ -75,24 +75,28 @@ def __prepare( True Testing with incomplete alphabet + >>> __prepare('I aM a BOy','abCdeFghijkLmnopqrStuVw') Traceback (most recent call last): ... KeyError: 'Length of alphabet has to be 27.' Testing with extra long alphabets + >>> __prepare('I aM a BOy','abCdeFghijkLmnopqrStuVwxyzzwwtyyujjgfd') Traceback (most recent call last): ... KeyError: 'Length of alphabet has to be 27.' - Testing with punctuations that are not in the given alphabet + Testing with punctuation not in the given alphabet + >>> __prepare('am i a boy?','abCdeFghijkLmnopqrStuVwxYZ+') Traceback (most recent call last): ... ValueError: Each message character has to be included in alphabet! Testing with numbers + >>> __prepare(500,'abCdeFghijkLmnopqrStuVwxYZ+') Traceback (most recent call last): ... @@ -124,15 +128,15 @@ def encrypt_message( encrypt_message =============== - Encrypts a message using the trifid_cipher. Any punctuatuions that + Encrypts a message using the trifid_cipher. Any punctuatuion chars that would be used should be added to the alphabet. PARAMETERS ---------- - * message: The message you want to encrypt. - * alphabet (optional): The characters to be used for the cipher . - * period (optional): The number of characters you want in a group whilst + * `message`: The message you want to encrypt. + * `alphabet` (optional): The characters to be used for the cipher . + * `period` (optional): The number of characters you want in a group whilst encrypting. >>> encrypt_message('I am a boy') @@ -169,20 +173,21 @@ def decrypt_message( decrypt_message =============== - Decrypts a trifid_cipher encrypted message . + Decrypts a trifid_cipher encrypted message. PARAMETERS ---------- - * message: The message you want to decrypt . - * alphabet (optional): The characters used for the cipher. - * period (optional): The number of characters used in grouping when it + * `message`: The message you want to decrypt. + * `alphabet` (optional): The characters used for the cipher. + * `period` (optional): The number of characters used in grouping when it was encrypted. >>> decrypt_message('BCDGBQY') 'IAMABOY' Decrypting with your own alphabet and period + >>> decrypt_message('FMJFVOISSUFTFPUFEQQC','FELIXMARDSTBCGHJKNOPQUVWYZ+',5) 'AIDETOILECIELTAIDERA' """ diff --git a/ciphers/vigenere_cipher.py b/ciphers/vigenere_cipher.py index e76161351fb1..37b96ea14a46 100644 --- a/ciphers/vigenere_cipher.py +++ b/ciphers/vigenere_cipher.py @@ -41,10 +41,11 @@ def translate_message(key: str, message: str, mode: str) -> str: for symbol in message: num = LETTERS.find(symbol.upper()) if num != -1: - if mode == "encrypt": - num += LETTERS.find(key[key_index]) - elif mode == "decrypt": - num -= LETTERS.find(key[key_index]) + match mode: + case "encrypt": + num += LETTERS.find(key[key_index]) + case "decrypt": + num -= LETTERS.find(key[key_index]) num %= len(LETTERS) diff --git a/ciphers/xor_cipher.py b/ciphers/xor_cipher.py index 24d88a0fd588..2196775cf575 100644 --- a/ciphers/xor_cipher.py +++ b/ciphers/xor_cipher.py @@ -21,7 +21,7 @@ class XORCipher: - def __init__(self, key: int = 0): + def __init__(self, key: int = 0) -> None: """ simple constructor that receives a key or uses default key = 0 diff --git a/ciphers/xtea.py b/ciphers/xtea.py new file mode 100644 index 000000000000..4d2aedde6c31 --- /dev/null +++ b/ciphers/xtea.py @@ -0,0 +1,118 @@ +""" +XTEA (eXtended Tiny Encryption Algorithm) is a block cipher designed to +correct weaknesses in TEA. It was published by David Wheeler and Roger +Needham in 1997. XTEA operates on 64-bit blocks with a 128-bit key and +uses a Feistel network with a recommended 64 rounds. + +It's still found in embedded systems and game networking protocols due +to its simplicity and small code footprint. + +Reference: https://en.wikipedia.org/wiki/XTEA +""" + +import struct + +DELTA = 0x9E3779B9 +MASK = 0xFFFFFFFF + + +def xtea_encrypt(block: bytes, key: bytes, num_rounds: int = 64) -> bytes: + """ + Encrypt a single 64-bit block using XTEA. + + :param block: 8 bytes of plaintext + :param key: 16 bytes (128-bit key) + :param num_rounds: number of Feistel rounds (default 64) + :return: 8 bytes of ciphertext + + >>> key = b'\\x00' * 16 + >>> plaintext = b'\\x00' * 8 + >>> ciphertext = xtea_encrypt(plaintext, key) + >>> ciphertext.hex() + 'fc924d124ad0ed50' + + >>> xtea_encrypt(b'hello!!!', b'sixteenbyteskey!') + b'u\\x8d\\x00\\x17c\\xb8\\xf0*' + + >>> xtea_encrypt(b'short', key) + Traceback (most recent call last): + ... + ValueError: block must be 8 bytes + + >>> xtea_encrypt(plaintext, b'short') + Traceback (most recent call last): + ... + ValueError: key must be 16 bytes + """ + if len(block) != 8: + raise ValueError("block must be 8 bytes") + if len(key) != 16: + raise ValueError("key must be 16 bytes") + + v0, v1 = struct.unpack("!II", block) + k = struct.unpack("!4I", key) + + total = 0 + for _ in range(num_rounds): + v0 = (v0 + ((((v1 << 4) ^ (v1 >> 5)) + v1) ^ (total + k[total & 3]))) & MASK + total = (total + DELTA) & MASK + v1 = ( + v1 + ((((v0 << 4) ^ (v0 >> 5)) + v0) ^ (total + k[(total >> 11) & 3])) + ) & MASK + + return struct.pack("!II", v0, v1) + + +def xtea_decrypt(block: bytes, key: bytes, num_rounds: int = 64) -> bytes: + """ + Decrypt a single 64-bit block using XTEA. + + :param block: 8 bytes of ciphertext + :param key: 16 bytes (128-bit key) + :param num_rounds: number of Feistel rounds (default 64) + :return: 8 bytes of plaintext + + Roundtrip test -- encrypt then decrypt returns original plaintext: + >>> key = b'\\x00' * 16 + >>> plaintext = b'\\x00' * 8 + >>> xtea_decrypt(xtea_encrypt(plaintext, key), key) == plaintext + True + + >>> msg = b'hello!!!' + >>> k = b'sixteenbyteskey!' + >>> xtea_decrypt(xtea_encrypt(msg, k), k) == msg + True + + >>> xtea_decrypt(b'short', key) + Traceback (most recent call last): + ... + ValueError: block must be 8 bytes + + >>> xtea_decrypt(b'\\x00' * 8, b'short') + Traceback (most recent call last): + ... + ValueError: key must be 16 bytes + """ + if len(block) != 8: + raise ValueError("block must be 8 bytes") + if len(key) != 16: + raise ValueError("key must be 16 bytes") + + v0, v1 = struct.unpack("!II", block) + k = struct.unpack("!4I", key) + + total = (DELTA * num_rounds) & MASK + for _ in range(num_rounds): + v1 = ( + v1 - ((((v0 << 4) ^ (v0 >> 5)) + v0) ^ (total + k[(total >> 11) & 3])) + ) & MASK + total = (total - DELTA) & MASK + v0 = (v0 - ((((v1 << 4) ^ (v1 >> 5)) + v1) ^ (total + k[total & 3]))) & MASK + + return struct.pack("!II", v0, v1) + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/computer_vision/README.md b/computer_vision/README.md index 1657128fd25e..ba7ccf457097 100644 --- a/computer_vision/README.md +++ b/computer_vision/README.md @@ -1,11 +1,11 @@ # Computer Vision -Computer vision is a field of computer science that works on enabling computers to see, identify and process images in the same way that human does, and provide appropriate output. +Computer vision is an interdisciplinary field focused on enabling computers to gain high-level understanding from images and video—automatically extracting, analyzing, and interpreting visual information to produce outputs such as labels, measurements, 3D structure, or decisions. -It is like imparting human intelligence and instincts to a computer. -Image processing and computer vision are a little different from each other. Image processing means applying some algorithms for transforming image from one form to the other like smoothing, contrasting, stretching, etc. +In practice, computer vision methods combine geometry, physics, statistics, and machine learning to connect pixel data to semantic concepts like objects, actions, and scenes. -While computer vision comes from modelling image processing using the techniques of machine learning, computer vision applies machine learning to recognize patterns for interpretation of images (much like the process of visual reasoning of human vision). +## Image processing vs. computer vision -* -* +Image processing primarily transforms images (e.g., denoising, contrast enhancement, geometric warping) where the output is another image. + +Computer vision uses images/video as input but often outputs information about the scene (e.g., detections, segmentation masks, pose estimates, tracking results, or a decision), which may then drive downstream behavior in a larger system. diff --git a/computer_vision/cnn_classification.py b/computer_vision/cnn_classification.py deleted file mode 100644 index 115333eba0d1..000000000000 --- a/computer_vision/cnn_classification.py +++ /dev/null @@ -1,100 +0,0 @@ -""" -Convolutional Neural Network - -Objective : To train a CNN model detect if TB is present in Lung X-ray or not. - -Resources CNN Theory : - https://en.wikipedia.org/wiki/Convolutional_neural_network -Resources Tensorflow : https://www.tensorflow.org/tutorials/images/cnn - -Download dataset from : -https://lhncbc.nlm.nih.gov/LHC-publications/pubs/TuberculosisChestXrayImageDataSets.html - -1. Download the dataset folder and create two folder training set and test set -in the parent dataset folder -2. Move 30-40 image from both TB positive and TB Negative folder -in the test set folder -3. The labels of the images will be extracted from the folder name -the image is present in. - -""" - -# Part 1 - Building the CNN - -import numpy as np - -# Importing the Keras libraries and packages -import tensorflow as tf -from keras import layers, models - -if __name__ == "__main__": - # Initialising the CNN - # (Sequential- Building the model layer by layer) - classifier = models.Sequential() - - # Step 1 - Convolution - # Here 64,64 is the length & breadth of dataset images and 3 is for the RGB channel - # (3,3) is the kernel size (filter matrix) - classifier.add( - layers.Conv2D(32, (3, 3), input_shape=(64, 64, 3), activation="relu") - ) - - # Step 2 - Pooling - classifier.add(layers.MaxPooling2D(pool_size=(2, 2))) - - # Adding a second convolutional layer - classifier.add(layers.Conv2D(32, (3, 3), activation="relu")) - classifier.add(layers.MaxPooling2D(pool_size=(2, 2))) - - # Step 3 - Flattening - classifier.add(layers.Flatten()) - - # Step 4 - Full connection - classifier.add(layers.Dense(units=128, activation="relu")) - classifier.add(layers.Dense(units=1, activation="sigmoid")) - - # Compiling the CNN - classifier.compile( - optimizer="adam", loss="binary_crossentropy", metrics=["accuracy"] - ) - - # Part 2 - Fitting the CNN to the images - - # Load Trained model weights - - # from keras.models import load_model - # regressor=load_model('cnn.h5') - - train_datagen = tf.keras.preprocessing.image.ImageDataGenerator( - rescale=1.0 / 255, shear_range=0.2, zoom_range=0.2, horizontal_flip=True - ) - - test_datagen = tf.keras.preprocessing.image.ImageDataGenerator(rescale=1.0 / 255) - - training_set = train_datagen.flow_from_directory( - "dataset/training_set", target_size=(64, 64), batch_size=32, class_mode="binary" - ) - - test_set = test_datagen.flow_from_directory( - "dataset/test_set", target_size=(64, 64), batch_size=32, class_mode="binary" - ) - - classifier.fit_generator( - training_set, steps_per_epoch=5, epochs=30, validation_data=test_set - ) - - classifier.save("cnn.h5") - - # Part 3 - Making new predictions - - test_image = tf.keras.preprocessing.image.load_img( - "dataset/single_prediction/image.png", target_size=(64, 64) - ) - test_image = tf.keras.preprocessing.image.img_to_array(test_image) - test_image = np.expand_dims(test_image, axis=0) - result = classifier.predict(test_image) - # training_set.class_indices - if result[0][0] == 0: - prediction = "Normal" - if result[0][0] == 1: - prediction = "Abnormality detected" diff --git a/computer_vision/flip_augmentation.py b/computer_vision/flip_augmentation.py index 77a8cbd7b14f..1c4fad847471 100644 --- a/computer_vision/flip_augmentation.py +++ b/computer_vision/flip_augmentation.py @@ -33,7 +33,7 @@ def main() -> None: 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]) - print(f"Success {index+1}/{len(new_images)} with {file_name}") + 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]}" @@ -96,16 +96,17 @@ def update_image_and_anno( path_list.append(path) img_annos = anno_list[idx] img = cv2.imread(path) - if flip_type == 1: - new_img = cv2.flip(img, flip_type) - for bbox in img_annos: - x_center_new = 1 - bbox[1] - new_annos.append([bbox[0], x_center_new, bbox[2], bbox[3], bbox[4]]) - elif flip_type == 0: - new_img = cv2.flip(img, flip_type) - for bbox in img_annos: - y_center_new = 1 - bbox[2] - new_annos.append([bbox[0], bbox[1], y_center_new, bbox[3], bbox[4]]) + match flip_type: + case 1: + new_img = cv2.flip(img, flip_type) + for bbox in img_annos: + x_center_new = 1 - bbox[1] + new_annos.append([bbox[0], x_center_new, bbox[2], bbox[3], bbox[4]]) + case 0: + new_img = cv2.flip(img, flip_type) + for bbox in img_annos: + y_center_new = 1 - bbox[2] + new_annos.append([bbox[0], bbox[1], y_center_new, bbox[3], bbox[4]]) new_annos_lists.append(new_annos) new_imgs_list.append(new_img) return new_imgs_list, new_annos_lists, path_list diff --git a/computer_vision/gramian.py b/computer_vision/gramian.py new file mode 100644 index 000000000000..cc193867c9bf --- /dev/null +++ b/computer_vision/gramian.py @@ -0,0 +1,69 @@ +""" +Image style reconstruction with Gram matrices. + +https://en.wikipedia.org/wiki/Gram_matrix +https://en.wikipedia.org/wiki/Neural_style_transfer +https://arxiv.org/pdf/1603.08155#page=7&zoom=auto,-294,3 +""" + +import numpy as np + + +def gram_matrix(mat: np.ndarray) -> np.ndarray: + """ + Returns the Gram (Gramian) matrix of an image. + + :param mat: matrix of shape (C, H, W); C = color channels, H = height, W = width. + :type mat: np.ndarray + :return: matrix of shape (C, C). + :rtype: np.ndarray + + Examples + -------- + >>> gram_matrix(np.ones((2,5,5))) + array([[0.5, 0.5], + [0.5, 0.5]]) + >>> gram_matrix(np.ones((3,5,5))) + array([[0.33333333, 0.33333333, 0.33333333], + [0.33333333, 0.33333333, 0.33333333], + [0.33333333, 0.33333333, 0.33333333]]) + >>> gram_matrix(np.ones((3,5,5))).shape + (3, 3) + """ + color, height, width = mat.shape + vec = mat.reshape(color, height * width) + gram = vec @ vec.T + return gram / (color * height * width) + + +def gram_loss(input_features: np.ndarray, reference_features: np.ndarray) -> np.float64: + """ + Calculates the squared Frobenius norm of the difference between + the Gram matrices of the input and reference image. + + :param input_features: Feature map of shape (C, H, W) + :type input_features: np.ndarray + :param reference_features: Feature map of shape (C, H, W) + :type reference_features: np.ndarray + :return: Gram loss between the two feature maps. + :rtype: float64 + + Examples + -------- + >>> a = np.random.randn(3,5,5) + >>> gram_loss(a, a) + np.float64(0.0) + >>> a = np.zeros((3,5,5)) + >>> b = np.ones((3,5,5)) + >>> gram_loss(a, b) + np.float64(1.0) + """ + input_gram = gram_matrix(input_features) + reference_gram = gram_matrix(reference_features) + return np.sum(np.square(input_gram - reference_gram)).astype(np.float64) + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/computer_vision/haralick_descriptors.py b/computer_vision/haralick_descriptors.py index 634f0495797b..f2f5edb57b89 100644 --- a/computer_vision/haralick_descriptors.py +++ b/computer_vision/haralick_descriptors.py @@ -5,6 +5,7 @@ import imageio.v2 as imageio import numpy as np +import numpy.typing as npt def root_mean_square_error(original: np.ndarray, reference: np.ndarray) -> float: @@ -19,11 +20,11 @@ def root_mean_square_error(original: np.ndarray, reference: np.ndarray) -> float >>> root_mean_square_error(np.array([1, 2, 3]), np.array([6, 4, 2])) 3.1622776601683795 """ - return np.sqrt(((original - reference) ** 2).mean()) + return float(np.sqrt(((original - reference) ** 2).mean())) def normalize_image( - image: np.ndarray, cap: float = 255.0, data_type: np.dtype = np.uint8 + image: np.ndarray, cap: float = 255.0, data_type: npt.DTypeLike = np.uint8 ) -> np.ndarray: """ Normalizes image in Numpy 2D array format, between ranges 0-cap, @@ -273,7 +274,7 @@ def haralick_descriptors(matrix: np.ndarray) -> list[float]: >>> morphological = opening_filter(binary) >>> mask_1 = binary_mask(gray, morphological)[0] >>> concurrency = matrix_concurrency(mask_1, (0, 1)) - >>> haralick_descriptors(concurrency) + >>> [float(f) for f in haralick_descriptors(concurrency)] [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0] """ # Function np.indices could be used for bigger input types, @@ -335,7 +336,7 @@ def get_descriptors( return np.concatenate(descriptors, axis=None) -def euclidean(point_1: np.ndarray, point_2: np.ndarray) -> np.float32: +def euclidean(point_1: np.ndarray, point_2: np.ndarray) -> float: """ Simple method for calculating the euclidean distance between two points, with type np.ndarray. @@ -346,7 +347,7 @@ def euclidean(point_1: np.ndarray, point_2: np.ndarray) -> np.float32: >>> euclidean(a, b) 3.3166247903554 """ - return np.sqrt(np.sum(np.square(point_1 - point_2))) + return float(np.sqrt(np.sum(np.square(point_1 - point_2)))) def get_distances(descriptors: np.ndarray, base: int) -> list[tuple[int, float]]: diff --git a/computer_vision/harris_corner.py b/computer_vision/harris_corner.py index 0cc7522bc3af..c47ba2019c4f 100644 --- a/computer_vision/harris_corner.py +++ b/computer_vision/harris_corner.py @@ -8,7 +8,7 @@ class HarrisCorner: - def __init__(self, k: float, window_size: int): + def __init__(self, k: float, window_size: int) -> None: """ k : is an empirically determined constant in [0.04,0.06] window_size : neighbourhoods considered diff --git a/computer_vision/intensity_based_segmentation.py b/computer_vision/intensity_based_segmentation.py new file mode 100644 index 000000000000..7f2b1141acc4 --- /dev/null +++ b/computer_vision/intensity_based_segmentation.py @@ -0,0 +1,62 @@ +# Source: "https://www.ijcse.com/docs/IJCSE11-02-03-117.pdf" + +# Importing necessary libraries +import matplotlib.pyplot as plt +import numpy as np +from PIL import Image + + +def segment_image(image: np.ndarray, thresholds: list[int]) -> np.ndarray: + """ + Performs image segmentation based on intensity thresholds. + + Args: + image: Input grayscale image as a 2D array. + thresholds: Intensity thresholds to define segments. + + Returns: + A labeled 2D array where each region corresponds to a threshold range. + + Example: + >>> img = np.array([[80, 120, 180], [40, 90, 150], [20, 60, 100]]) + >>> segment_image(img, [50, 100, 150]) + array([[1, 2, 3], + [0, 1, 2], + [0, 1, 1]], dtype=int32) + """ + # Initialize segmented array with zeros + segmented = np.zeros_like(image, dtype=np.int32) + + # Assign labels based on thresholds + for i, threshold in enumerate(thresholds): + segmented[image > threshold] = i + 1 + + return segmented + + +if __name__ == "__main__": + # Load the image + image_path = "path_to_image" # Replace with your image path + original_image = Image.open(image_path).convert("L") + image_array = np.array(original_image) + + # Define thresholds + thresholds = [50, 100, 150, 200] + + # Perform segmentation + segmented_image = segment_image(image_array, thresholds) + + # Display the results + plt.figure(figsize=(10, 5)) + + plt.subplot(1, 2, 1) + plt.title("Original Image") + plt.imshow(image_array, cmap="gray") + plt.axis("off") + + plt.subplot(1, 2, 2) + plt.title("Segmented Image") + plt.imshow(segmented_image, cmap="tab20") + plt.axis("off") + + plt.show() diff --git a/computer_vision/mean_threshold.py b/computer_vision/mean_threshold.py index 76657933d6a9..47f9ebcb063b 100644 --- a/computer_vision/mean_threshold.py +++ b/computer_vision/mean_threshold.py @@ -6,7 +6,7 @@ """ -def mean_threshold(image: Image) -> Image: +def mean_threshold(image: Image.Image) -> Image.Image: """ image: is a grayscale PIL image object """ diff --git a/computer_vision/mosaic_augmentation.py b/computer_vision/mosaic_augmentation.py index cd923dfe095f..753b8bf012ef 100644 --- a/computer_vision/mosaic_augmentation.py +++ b/computer_vision/mosaic_augmentation.py @@ -41,7 +41,7 @@ def main() -> None: file_name = path.split(os.sep)[-1].rsplit(".", 1)[0] file_root = f"{OUTPUT_DIR}/{file_name}_MOSAIC_{letter_code}" cv2.imwrite(f"{file_root}.jpg", new_image, [cv2.IMWRITE_JPEG_QUALITY, 85]) - print(f"Succeeded {index+1}/{NUMBER_IMAGES} with {file_name}") + print(f"Succeeded {index + 1}/{NUMBER_IMAGES} with {file_name}") annos_list = [] for anno in new_annos: width = anno[3] - anno[1] @@ -117,46 +117,48 @@ def update_image_and_anno( path_list.append(path) img_annos = all_annos[index] img = cv2.imread(path) - if i == 0: # top-left - img = cv2.resize(img, (divid_point_x, divid_point_y)) - output_img[:divid_point_y, :divid_point_x, :] = img - for bbox in img_annos: - xmin = bbox[1] * scale_x - ymin = bbox[2] * scale_y - xmax = bbox[3] * scale_x - ymax = bbox[4] * scale_y - new_anno.append([bbox[0], xmin, ymin, xmax, ymax]) - elif i == 1: # top-right - img = cv2.resize(img, (output_size[1] - divid_point_x, divid_point_y)) - output_img[:divid_point_y, divid_point_x : output_size[1], :] = img - for bbox in img_annos: - xmin = scale_x + bbox[1] * (1 - scale_x) - ymin = bbox[2] * scale_y - xmax = scale_x + bbox[3] * (1 - scale_x) - ymax = bbox[4] * scale_y - new_anno.append([bbox[0], xmin, ymin, xmax, ymax]) - elif i == 2: # bottom-left - img = cv2.resize(img, (divid_point_x, output_size[0] - divid_point_y)) - output_img[divid_point_y : output_size[0], :divid_point_x, :] = img - for bbox in img_annos: - xmin = bbox[1] * scale_x - ymin = scale_y + bbox[2] * (1 - scale_y) - xmax = bbox[3] * scale_x - ymax = scale_y + bbox[4] * (1 - scale_y) - new_anno.append([bbox[0], xmin, ymin, xmax, ymax]) - else: # bottom-right - img = cv2.resize( - img, (output_size[1] - divid_point_x, output_size[0] - divid_point_y) - ) - output_img[ - divid_point_y : output_size[0], divid_point_x : output_size[1], : - ] = img - for bbox in img_annos: - xmin = scale_x + bbox[1] * (1 - scale_x) - ymin = scale_y + bbox[2] * (1 - scale_y) - xmax = scale_x + bbox[3] * (1 - scale_x) - ymax = scale_y + bbox[4] * (1 - scale_y) - new_anno.append([bbox[0], xmin, ymin, xmax, ymax]) + match i: + case 0: # top-left + img = cv2.resize(img, (divid_point_x, divid_point_y)) + output_img[:divid_point_y, :divid_point_x, :] = img + for bbox in img_annos: + xmin = bbox[1] * scale_x + ymin = bbox[2] * scale_y + xmax = bbox[3] * scale_x + ymax = bbox[4] * scale_y + new_anno.append([bbox[0], xmin, ymin, xmax, ymax]) + case 1: # top-right + img = cv2.resize(img, (output_size[1] - divid_point_x, divid_point_y)) + output_img[:divid_point_y, divid_point_x : output_size[1], :] = img + for bbox in img_annos: + xmin = scale_x + bbox[1] * (1 - scale_x) + ymin = bbox[2] * scale_y + xmax = scale_x + bbox[3] * (1 - scale_x) + ymax = bbox[4] * scale_y + new_anno.append([bbox[0], xmin, ymin, xmax, ymax]) + case 2: # bottom-left + img = cv2.resize(img, (divid_point_x, output_size[0] - divid_point_y)) + output_img[divid_point_y : output_size[0], :divid_point_x, :] = img + for bbox in img_annos: + xmin = bbox[1] * scale_x + ymin = scale_y + bbox[2] * (1 - scale_y) + xmax = bbox[3] * scale_x + ymax = scale_y + bbox[4] * (1 - scale_y) + new_anno.append([bbox[0], xmin, ymin, xmax, ymax]) + case _: # bottom-right + img = cv2.resize( + img, + (output_size[1] - divid_point_x, output_size[0] - divid_point_y), + ) + output_img[ + divid_point_y : output_size[0], divid_point_x : output_size[1], : + ] = img + for bbox in img_annos: + xmin = scale_x + bbox[1] * (1 - scale_x) + ymin = scale_y + bbox[2] * (1 - scale_y) + xmax = scale_x + bbox[3] * (1 - scale_x) + ymax = scale_y + bbox[4] * (1 - scale_y) + new_anno.append([bbox[0], xmin, ymin, xmax, ymax]) # Remove bounding box small than scale of filter if filter_scale > 0: diff --git a/computer_vision/otsu_threshold.py b/computer_vision/otsu_threshold.py new file mode 100644 index 000000000000..983fe060bce7 --- /dev/null +++ b/computer_vision/otsu_threshold.py @@ -0,0 +1,77 @@ +import numpy as np +from PIL import Image + +""" +Otsu thresholding algorithm for image processing +https://en.wikipedia.org/wiki/Otsu%27s_method +""" + + +def otsu_threshold(image: Image.Image) -> Image.Image: + """ + Applies Otsu's thresholding method to a grayscale image. + + Parameters: + image (PIL.Image.Image): A grayscale PIL image object. + + Returns: + PIL.Image.Image: A binary image after applying Otsu's thresholding. + + Example: + >>> from PIL import Image + >>> import numpy as np + >>> image_array = np.array( + ... [[0, 0, 0, 0], [255, 255, 255, 255], [0, 0, 0, 0], [255, 255, 255, 255]], + ... dtype=np.uint8 + ... ) + >>> image = Image.fromarray(image_array) + >>> binary_image = otsu_threshold(image) + >>> np.array(binary_image) + array([[ 0, 0, 0, 0], + [255, 255, 255, 255], + [ 0, 0, 0, 0], + [255, 255, 255, 255]], dtype=uint8) + """ + # Convert the image to numpy array + pixel_array = np.array(image) + + # Compute histogram + hist, _ = np.histogram(pixel_array, bins=256, range=(0, 256)) + + # Compute between class variance + total_pixels = pixel_array.size + current_max, threshold = 0.0, 0 # Ensure current_max is a float + sum_total, sum_foreground = 0.0, 0.0 # Ensure these are floats + weight_background, weight_foreground = 0.0, 0.0 # Ensure these are floats + + for i in range(256): + sum_total += i * hist[i] + + for i in range(256): + weight_background += hist[i] + if weight_background == 0: + continue + weight_foreground = total_pixels - weight_background + if weight_foreground == 0: + break + sum_foreground += i * hist[i] + + mean_background = sum_foreground / weight_background + mean_foreground = (sum_total - sum_foreground) / weight_foreground + + between_class_variance = ( + weight_background + * weight_foreground + * (mean_background - mean_foreground) ** 2 + ) + + if between_class_variance > current_max: + current_max = between_class_variance + threshold = i + + # Apply threshold to the image + binary_image = pixel_array > threshold + binary_image = binary_image.astype(np.uint8) * 255 + + # Convert numpy array back to PIL image + return Image.fromarray(binary_image) diff --git a/computer_vision/vision_transformer.py b/computer_vision/vision_transformer.py new file mode 100644 index 000000000000..1c3e7d07b48e --- /dev/null +++ b/computer_vision/vision_transformer.py @@ -0,0 +1,442 @@ +""" +Vision Transformer (ViT) for Image Classification + +This module implements the Vision Transformer architecture as described in the paper +"An Image is Worth 16x16 Words: Transformers for Image Recognition at Scale" +by Dosovitskiy et al. (2020) + +Paper: https://arxiv.org/abs/2010.11929 + +The Vision Transformer splits an image into fixed-size patches, linearly embeds each +patch, adds position embeddings, and feeds the resulting sequence of vectors to a +standard Transformer encoder. For classification, a learnable classification token +is prepended to the sequence. + +Author: devvratpathak +""" + +import numpy as np + + +def create_patches( + image: np.ndarray, patch_size: int = 16 +) -> tuple[np.ndarray, tuple[int, int]]: + """ + Split an image into non-overlapping patches. + + Args: + image: Input image array of shape (height, width, channels) + patch_size: Size of each square patch (default: 16) + + Returns: + A tuple containing: + - patches: Array of shape (num_patches, patch_size, patch_size, channels) + - grid_size: Tuple (height_patches, width_patches) representing the grid + + Examples: + >>> img = np.random.rand(32, 32, 3) + >>> patches, grid = create_patches(img, patch_size=16) + >>> patches.shape + (4, 16, 16, 3) + >>> grid + (2, 2) + + >>> img = np.random.rand(224, 224, 3) + >>> patches, grid = create_patches(img, patch_size=16) + >>> patches.shape + (196, 16, 16, 3) + >>> grid + (14, 14) + """ + if len(image.shape) != 3: + msg = f"Expected 3D image, got shape {image.shape}" + raise ValueError(msg) + + height, width, channels = image.shape + + if height % patch_size != 0 or width % patch_size != 0: + msg = ( + f"Image dimensions ({height}x{width}) must be divisible by " + f"patch_size ({patch_size})" + ) + raise ValueError(msg) + + # Calculate number of patches in each dimension + num_patches_h = height // patch_size + num_patches_w = width // patch_size + + # Reshape image into patches + patches = image.reshape( + num_patches_h, patch_size, num_patches_w, patch_size, channels + ) + # Transpose to get patches in sequence + patches = patches.transpose(0, 2, 1, 3, 4) + # Reshape to (num_patches, patch_size, patch_size, channels) + patches = patches.reshape(-1, patch_size, patch_size, channels) + + return patches, (num_patches_h, num_patches_w) + + +def patch_embedding(patches: np.ndarray, embedding_dim: int = 768) -> np.ndarray: + """ + Linearly project flattened patches to embedding dimension. + + Args: + patches: Array of patches with shape + (num_patches, patch_size, patch_size, channels) + embedding_dim: Dimension of the embedding space (default: 768) + + Returns: + Embedded patches of shape (num_patches, embedding_dim) + + Examples: + >>> patches = np.random.rand(4, 16, 16, 3) + >>> embeddings = patch_embedding(patches, embedding_dim=768) + >>> embeddings.shape + (4, 768) + + >>> patches = np.random.rand(196, 16, 16, 3) + >>> embeddings = patch_embedding(patches, embedding_dim=512) + >>> embeddings.shape + (196, 512) + """ + num_patches = patches.shape[0] + # Flatten each patch + flattened = patches.reshape(num_patches, -1) + + # Linear projection (simplified - in practice this is a learned weight matrix) + # For demonstration, we use random projection + patch_dim = flattened.shape[1] + rng = np.random.default_rng() + projection_matrix = rng.standard_normal((patch_dim, embedding_dim)) * 0.02 + + embedded = flattened @ projection_matrix + + return embedded + + +def add_positional_encoding( + embeddings: np.ndarray, num_positions: int | None = None +) -> np.ndarray: + """ + Add learnable positional encodings to patch embeddings. + + Args: + embeddings: Embedded patches of shape (num_patches, embedding_dim) + num_positions: Number of positions (if None, uses num_patches + 1 for CLS token) + + Returns: + Embeddings with positional encoding of shape (num_positions, embedding_dim) + + Examples: + >>> embeddings = np.random.rand(4, 768) + >>> pos_embeddings = add_positional_encoding(embeddings) + >>> pos_embeddings.shape + (5, 768) + + >>> embeddings = np.random.rand(196, 512) + >>> pos_embeddings = add_positional_encoding(embeddings) + >>> pos_embeddings.shape + (197, 512) + """ + num_patches, embedding_dim = embeddings.shape + + if num_positions is None: + # Add 1 for the CLS token + num_positions = num_patches + 1 + + # Create learnable positional encodings (simplified - normally learned) + rng = np.random.default_rng() + positional_encodings = rng.standard_normal((num_positions, embedding_dim)) * 0.02 + + # Prepend CLS token + cls_token = rng.standard_normal((1, embedding_dim)) * 0.02 + + # Concatenate CLS token with patch embeddings + embeddings_with_cls = np.vstack([cls_token, embeddings]) + + # Add positional encodings + embeddings_with_pos = embeddings_with_cls + positional_encodings + + return embeddings_with_pos + + +def attention_mechanism( + query: np.ndarray, + key: np.ndarray, + value: np.ndarray, + mask: np.ndarray | None = None, +) -> tuple[np.ndarray, np.ndarray]: + """ + Compute scaled dot-product attention. + + Attention(Q, K, V) = softmax(QK^T / sqrt(d_k))V + + Args: + query: Query matrix of shape (seq_len, d_k) + key: Key matrix of shape (seq_len, d_k) + value: Value matrix of shape (seq_len, d_v) + mask: Optional attention mask + + Returns: + A tuple containing: + - output: Attention output of shape (seq_len, d_v) + - attention_weights: Attention weights of shape (seq_len, seq_len) + + Examples: + >>> q = np.random.rand(10, 64) + >>> k = np.random.rand(10, 64) + >>> v = np.random.rand(10, 64) + >>> output, weights = attention_mechanism(q, k, v) + >>> output.shape + (10, 64) + >>> weights.shape + (10, 10) + >>> np.allclose(weights.sum(axis=1), 1.0) + True + """ + d_k = query.shape[-1] + + # Compute attention scores: QK^T / sqrt(d_k) + scores = query @ key.T / np.sqrt(d_k) + + # Apply mask if provided + if mask is not None: + scores = np.where(mask, scores, -1e9) + + # Apply softmax to get attention weights + exp_scores = np.exp(scores - np.max(scores, axis=-1, keepdims=True)) + attention_weights = exp_scores / np.sum(exp_scores, axis=-1, keepdims=True) + + # Compute weighted sum of values + output = attention_weights @ value + + return output, attention_weights + + +def layer_norm(embeddings: np.ndarray, epsilon: float = 1e-6) -> np.ndarray: + """ + Apply Layer Normalization. + + Args: + embeddings: Input array of shape (seq_len, embedding_dim) + epsilon: Small constant for numerical stability (default: 1e-6) + + Returns: + Normalized array of same shape as input + + Examples: + >>> embeddings = np.random.rand(10, 768) + >>> normalized = layer_norm(embeddings) + >>> normalized.shape + (10, 768) + >>> np.allclose(normalized.mean(axis=1), 0.0, atol=1e-6) + True + >>> np.allclose(normalized.std(axis=1), 1.0, atol=1e-6) + True + """ + mean = embeddings.mean(axis=-1, keepdims=True) + std = embeddings.std(axis=-1, keepdims=True) + return (embeddings - mean) / (std + epsilon) + + +def feedforward_network(embeddings: np.ndarray, hidden_dim: int = 3072) -> np.ndarray: + """ + Apply position-wise feed-forward network. + + FFN(x) = max(0, xW1 + b1)W2 + b2 + + Args: + embeddings: Input array of shape (seq_len, embedding_dim) + hidden_dim: Hidden dimension size (default: 3072, typically 4x embedding_dim) + + Returns: + Output array of shape (seq_len, embedding_dim) + + Examples: + >>> embeddings = np.random.rand(10, 768) + >>> output = feedforward_network(embeddings, hidden_dim=3072) + >>> output.shape + (10, 768) + + >>> embeddings = np.random.rand(197, 512) + >>> output = feedforward_network(embeddings, hidden_dim=2048) + >>> output.shape + (197, 512) + """ + embedding_dim = embeddings.shape[1] + rng = np.random.default_rng() + + # First linear layer + w1 = rng.standard_normal((embedding_dim, hidden_dim)) * 0.02 + b1 = np.zeros(hidden_dim) + hidden = embeddings @ w1 + b1 + + # GELU activation (approximation) + gelu_factor = np.sqrt(2 / np.pi) * (hidden + 0.044715 * hidden**3) + hidden = 0.5 * hidden * (1 + np.tanh(gelu_factor)) + + # Second linear layer + w2 = rng.standard_normal((hidden_dim, embedding_dim)) * 0.02 + b2 = np.zeros(embedding_dim) + output = hidden @ w2 + b2 + + return output + + +def transformer_encoder_block( + embeddings: np.ndarray, + num_heads: int = 12, # noqa: ARG001 + hidden_dim: int = 3072, +) -> np.ndarray: + """ + Apply a single Transformer encoder block. + + The block consists of: + 1. Multi-head self-attention with residual connection and layer norm + 2. Feed-forward network with residual connection and layer norm + + Args: + embeddings: Input array of shape (seq_len, embedding_dim) + num_heads: Number of attention heads (default: 12, kept for API) + hidden_dim: Hidden dimension for FFN (default: 3072) + + Returns: + Output array of shape (seq_len, embedding_dim) + + Examples: + >>> embeddings = np.random.rand(197, 768) + >>> output = transformer_encoder_block( + ... embeddings, num_heads=12, hidden_dim=3072 + ... ) + >>> output.shape + (197, 768) + + >>> embeddings = np.random.rand(50, 512) + >>> output = transformer_encoder_block( + ... embeddings, num_heads=8, hidden_dim=2048 + ... ) + >>> output.shape + (50, 512) + """ + # Multi-head self-attention (simplified - using single head for demonstration) + # In practice, this would split into multiple heads + # num_heads parameter is kept for API compatibility + attention_output, _ = attention_mechanism(embeddings, embeddings, embeddings) + + # Add residual connection and apply layer norm + embeddings = layer_norm(embeddings + attention_output) + + # Feed-forward network + ffn_output = feedforward_network(embeddings, hidden_dim) + + # Add residual connection and apply layer norm + embeddings = layer_norm(embeddings + ffn_output) + + return embeddings + + +def vision_transformer( + image: np.ndarray, + patch_size: int = 16, + embedding_dim: int = 768, + num_layers: int = 12, + num_heads: int = 12, + hidden_dim: int = 3072, + num_classes: int = 1000, +) -> np.ndarray: + """ + Apply Vision Transformer for image classification. + + Architecture: + 1. Split image into patches + 2. Linear projection of flattened patches + 3. Add positional embeddings + 4. Pass through Transformer encoder layers + 5. Extract CLS token and apply classification head + + Args: + image: Input image array of shape (height, width, channels) + patch_size: Size of each patch (default: 16) + embedding_dim: Embedding dimension (default: 768) + num_layers: Number of Transformer layers (default: 12) + num_heads: Number of attention heads (default: 12) + hidden_dim: Hidden dimension in FFN (default: 3072) + num_classes: Number of output classes (default: 1000) + + Returns: + Class logits of shape (num_classes,) + + Examples: + >>> img = np.random.rand(224, 224, 3) + >>> logits = vision_transformer(img, patch_size=16, num_classes=10) + >>> logits.shape + (10,) + + >>> img = np.random.rand(32, 32, 3) + >>> logits = vision_transformer( + ... img, patch_size=16, embedding_dim=512, num_layers=6, num_classes=100 + ... ) + >>> logits.shape + (100,) + """ + # Step 1: Create patches + patches, _ = create_patches(image, patch_size) + + # Step 2: Embed patches + embeddings = patch_embedding(patches, embedding_dim) + + # Step 3: Add positional encodings (includes CLS token) + embeddings = add_positional_encoding(embeddings) + + # Step 4: Pass through Transformer encoder layers + for _ in range(num_layers): + embeddings = transformer_encoder_block(embeddings, num_heads, hidden_dim) + + # Step 5: Extract CLS token (first token) + cls_token = embeddings[0] + + # Step 6: Classification head (linear layer) + rng = np.random.default_rng() + classifier_weights = rng.standard_normal((embedding_dim, num_classes)) * 0.02 + classifier_bias = np.zeros(num_classes) + logits = cls_token @ classifier_weights + classifier_bias + + return logits + + +if __name__ == "__main__": + import doctest + + doctest.testmod() + + # Example usage + print("Vision Transformer Example") + print("=" * 50) + + # Create a sample image (224x224x3 for ImageNet-style input) + rng = np.random.default_rng() + sample_image = rng.random((224, 224, 3)) + print(f"Input image shape: {sample_image.shape}") + + # Apply Vision Transformer + logits = vision_transformer( + sample_image, + patch_size=16, + embedding_dim=768, + num_layers=12, + num_heads=12, + hidden_dim=3072, + num_classes=1000, + ) + + print(f"Output logits shape: {logits.shape}") + print(f"Predicted class: {np.argmax(logits)}") + + # Demonstrate patch creation + print("\n" + "=" * 50) + print("Patch Creation Example") + patches, grid = create_patches(sample_image, patch_size=16) + print(f"Number of patches: {patches.shape[0]}") + print(f"Patch size: {patches.shape[1:3]}") + print(f"Grid size: {grid}") diff --git a/conversions/base64_to_binary.py b/conversions/base64_to_binary.py new file mode 100644 index 000000000000..6973a303e2b2 --- /dev/null +++ b/conversions/base64_to_binary.py @@ -0,0 +1,112 @@ +""" +* Author: Siddharth Singh (https://github.com/coolsidd) +* Description: Convert a binary string to Base64. +References for better understanding: +https://en.wikipedia.org/wiki/Base64 +""" + +B64_TO_BITS = { + "A": "000000", + "B": "000001", + "C": "000010", + "D": "000011", + "E": "000100", + "F": "000101", + "G": "000110", + "H": "000111", + "I": "001000", + "J": "001001", + "K": "001010", + "L": "001011", + "M": "001100", + "N": "001101", + "O": "001110", + "P": "001111", + "Q": "010000", + "R": "010001", + "S": "010010", + "T": "010011", + "U": "010100", + "V": "010101", + "W": "010110", + "X": "010111", + "Y": "011000", + "Z": "011001", + "a": "011010", + "b": "011011", + "c": "011100", + "d": "011101", + "e": "011110", + "f": "011111", + "g": "100000", + "h": "100001", + "i": "100010", + "j": "100011", + "k": "100100", + "l": "100101", + "m": "100110", + "n": "100111", + "o": "101000", + "p": "101001", + "q": "101010", + "r": "101011", + "s": "101100", + "t": "101101", + "u": "101110", + "v": "101111", + "w": "110000", + "x": "110001", + "y": "110010", + "z": "110011", + "0": "110100", + "1": "110101", + "2": "110110", + "3": "110111", + "4": "111000", + "5": "111001", + "6": "111010", + "7": "111011", + "8": "111100", + "9": "111101", + "+": "111110", + "/": "111111", +} + + +def base64_to_bin(base64_str: str) -> str: + """Convert a base64 value to its binary equivalent. + + >>> base64_to_bin("ABC") + '000000000001000010' + >>> base64_to_bin(" -abc ") + '-011010011011011100' + >>> base64_to_bin(" a-bc ") + Traceback (most recent call last): + ... + ValueError: Invalid base64 string. Invalid char - at pos 1 + >>> base64_to_bin("") + Traceback (most recent call last): + ... + ValueError: Empty string was passed to the function + """ + b64_str = str(base64_str).strip() + if not b64_str: + raise ValueError("Empty string was passed to the function") + is_negative = b64_str[0] == "-" + if is_negative: + b64_str = b64_str[1:] + bin_str = "" + for i, x in enumerate(b64_str): + if x not in B64_TO_BITS: + exception_message = f"Invalid base64 string. Invalid char {x} at pos {i}" + raise ValueError(exception_message) + bin_str += B64_TO_BITS[x] + if is_negative: + bin_str = "-" + bin_str + return bin_str + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/conversions/binary_to_base64.py b/conversions/binary_to_base64.py new file mode 100644 index 000000000000..1ea9230cda76 --- /dev/null +++ b/conversions/binary_to_base64.py @@ -0,0 +1,120 @@ +""" +* Author: Siddharth Singh (https://github.com/coolsidd) +* Description: Convert a binary string to Base64. + +References for better understanding: +https://en.wikipedia.org/wiki/Base64 +""" + +BITS_TO_B64 = { + "000000": "A", + "000001": "B", + "000010": "C", + "000011": "D", + "000100": "E", + "000101": "F", + "000110": "G", + "000111": "H", + "001000": "I", + "001001": "J", + "001010": "K", + "001011": "L", + "001100": "M", + "001101": "N", + "001110": "O", + "001111": "P", + "010000": "Q", + "010001": "R", + "010010": "S", + "010011": "T", + "010100": "U", + "010101": "V", + "010110": "W", + "010111": "X", + "011000": "Y", + "011001": "Z", + "011010": "a", + "011011": "b", + "011100": "c", + "011101": "d", + "011110": "e", + "011111": "f", + "100000": "g", + "100001": "h", + "100010": "i", + "100011": "j", + "100100": "k", + "100101": "l", + "100110": "m", + "100111": "n", + "101000": "o", + "101001": "p", + "101010": "q", + "101011": "r", + "101100": "s", + "101101": "t", + "101110": "u", + "101111": "v", + "110000": "w", + "110001": "x", + "110010": "y", + "110011": "z", + "110100": "0", + "110101": "1", + "110110": "2", + "110111": "3", + "111000": "4", + "111001": "5", + "111010": "6", + "111011": "7", + "111100": "8", + "111101": "9", + "111110": "+", + "111111": "/", +} + + +def bin_to_base64(bin_str: str) -> str: + """Convert a binary value to its base64 equivalent + + + >>> bin_to_base64("000001") + 'AB' + >>> bin_to_base64("0") + 'A' + >>> bin_to_base64("1") + 'B' + >>> bin_to_base64("-1") + '-B' + >>> bin_to_base64(" -000001 ") + '-AB' + >>> bin_to_base64("0-0") + Traceback (most recent call last): + ... + ValueError: Non-binary value was passed to the function + >>> bin_to_base64("") + Traceback (most recent call last): + ... + ValueError: Empty string was passed to the function + """ + bin_str = str(bin_str).strip() + if not bin_str: + raise ValueError("Empty string was passed to the function") + is_negative = bin_str[0] == "-" + if is_negative: + bin_str = bin_str[1:] + if not all(char in "01" for char in bin_str): + raise ValueError("Non-binary value was passed to the function") + bin_str = "0" * (6 * (divmod(len(bin_str), 6)[0] + 1) - len(bin_str)) + bin_str + base64_str = "" + while len(bin_str) > 0: + base64_str += BITS_TO_B64[bin_str[:6]] + bin_str = bin_str[6:] + + return "-" + base64_str if is_negative else base64_str + + +if __name__ == "__main__": + from doctest import testmod + + testmod() diff --git a/conversions/binary_to_excess3.py b/conversions/binary_to_excess3.py new file mode 100644 index 000000000000..c410450df9dd --- /dev/null +++ b/conversions/binary_to_excess3.py @@ -0,0 +1,34 @@ +def binary_to_excess3(binary_str: str) -> str: + """ + Convert a binary number (as a string) to its Excess-3 code. + https://en.wikipedia.org/wiki/Excess-3 + + Args: + binary_str (str): Binary number as a string (e.g., "1010"). + + Returns: + str: Excess-3 code as a binary string. + + Example: + >>> binary_to_excess3("1010") + '1101' + """ + # Convert binary to decimal + decimal_value = int(binary_str, 2) + + # Add 3 (Excess-3 encoding) + excess3_value = decimal_value + 3 + + # Convert back to 4-bit binary + excess3_binary = format(excess3_value, "04b") + + return excess3_binary + + +if __name__ == "__main__": + from dostest import testmod + + testmod() + binary_input = input("Enter a 4-bit binary number: ") + excess3_output = binary_to_excess3(binary_input) + print(f"Excess-3 code of {binary_input} is: {excess3_output}") diff --git a/conversions/binary_to_gray.py b/conversions/binary_to_gray.py new file mode 100644 index 000000000000..f68e3a8832dd --- /dev/null +++ b/conversions/binary_to_gray.py @@ -0,0 +1,50 @@ +""" +Binary to Gray code conversion algorithm. + +Reference: +https://en.wikipedia.org/wiki/Gray_code +""" + + +def binary_to_gray(binary: str) -> str: + """ + Convert a binary number (as string) to its equivalent Gray code. + + The Gray code is generated by XOR-ing each bit with the bit just before it. + + Args: + binary (str): A string representing a binary number (e.g., "10101010"). + + Returns: + str: The corresponding Gray code string. + + Example: + >>> binary_to_gray("10101010") + '11111111' + + >>> binary_to_gray("1101") + '1011' + """ + # Convert binary string to integer + binary_int = int(binary, 2) + + # XOR the binary number with itself shifted right by 1 bit + gray_int = binary_int ^ (binary_int >> 1) + + # Convert the integer result back to a binary string (remove '0b' prefix) + gray_code = bin(gray_int)[2:] + + # Pad with leading zeros to maintain same bit length as input + return gray_code.zfill(len(binary)) + + +if __name__ == "__main__": + # Take input from user + binary_input = input("Enter a binary number: ").strip() + + # Validate the input (only 0s and 1s allowed) + if not all(bit in "01" for bit in binary_input): + print("❌ Invalid input! Please enter only 0s and 1s.") + else: + result = binary_to_gray(binary_input) + print(f"✅ The Gray code for binary {binary_input} is: {result}") diff --git a/conversions/binary_to_gray_code.py b/conversions/binary_to_gray_code.py new file mode 100644 index 000000000000..494cad66f503 --- /dev/null +++ b/conversions/binary_to_gray_code.py @@ -0,0 +1,224 @@ +""" +Convert between Binary and Gray Code representations. + +Gray Code (also known as reflected binary code) is a binary numeral system where +two successive values differ in only one bit. This property makes it useful in +error correction, digital communications, and position encoders. + +Wikipedia: https://en.wikipedia.org/wiki/Gray_code +""" + + +def binary_to_gray(binary_number: int) -> int: + """ + Convert a binary number to its Gray Code equivalent. + + The algorithm works by XORing the binary number with itself right-shifted by 1. + Formula: gray = binary XOR (binary >> 1) + + Args: + binary_number: A positive integer representing a binary number + + Returns: + The Gray Code equivalent as an integer + + Examples: + >>> binary_to_gray(0) + 0 + >>> binary_to_gray(1) + 1 + >>> binary_to_gray(2) + 3 + >>> binary_to_gray(3) + 2 + >>> binary_to_gray(4) + 6 + >>> binary_to_gray(7) + 4 + >>> binary_to_gray(10) + 15 + >>> binary_to_gray(15) + 8 + >>> binary_to_gray(255) + 128 + >>> binary_to_gray(-1) + Traceback (most recent call last): + ... + ValueError: Input must be a non-negative integer + >>> binary_to_gray(3.5) + Traceback (most recent call last): + ... + TypeError: Input must be an integer + """ + if not isinstance(binary_number, int): + raise TypeError("Input must be an integer") + if binary_number < 0: + raise ValueError("Input must be a non-negative integer") + + return binary_number ^ (binary_number >> 1) + + +def gray_to_binary(gray_number: int) -> int: + """ + Convert a Gray Code number to its binary equivalent. + + The algorithm works by repeatedly XORing the gray code with itself right-shifted, + until the right-shifted value becomes 0. + + Args: + gray_number: A positive integer representing a Gray Code number + + Returns: + The binary equivalent as an integer + + Examples: + >>> gray_to_binary(0) + 0 + >>> gray_to_binary(1) + 1 + >>> gray_to_binary(3) + 2 + >>> gray_to_binary(2) + 3 + >>> gray_to_binary(6) + 4 + >>> gray_to_binary(4) + 7 + >>> gray_to_binary(15) + 10 + >>> gray_to_binary(8) + 15 + >>> gray_to_binary(128) + 255 + >>> gray_to_binary(-1) + Traceback (most recent call last): + ... + ValueError: Input must be a non-negative integer + >>> gray_to_binary(5.5) + Traceback (most recent call last): + ... + TypeError: Input must be an integer + """ + if not isinstance(gray_number, int): + raise TypeError("Input must be an integer") + if gray_number < 0: + raise ValueError("Input must be a non-negative integer") + + binary_number = gray_number + gray_number >>= 1 + + while gray_number: + binary_number ^= gray_number + gray_number >>= 1 + + return binary_number + + +def decimal_to_gray(decimal_number: int) -> str: + """ + Convert a decimal number to its Gray Code representation as a binary string. + + Args: + decimal_number: A positive integer in decimal + + Returns: + Gray Code representation as a binary string + + Examples: + >>> decimal_to_gray(0) + '0' + >>> decimal_to_gray(1) + '1' + >>> decimal_to_gray(2) + '11' + >>> decimal_to_gray(3) + '10' + >>> decimal_to_gray(4) + '110' + >>> decimal_to_gray(10) + '1111' + >>> decimal_to_gray(15) + '1000' + >>> decimal_to_gray(-1) + Traceback (most recent call last): + ... + ValueError: Input must be a non-negative integer + """ + if not isinstance(decimal_number, int): + raise TypeError("Input must be an integer") + if decimal_number < 0: + raise ValueError("Input must be a non-negative integer") + + gray_code = binary_to_gray(decimal_number) + return bin(gray_code)[2:] # Remove '0b' prefix + + +def gray_to_decimal(gray_string: str) -> int: + """ + Convert a Gray Code binary string to its decimal equivalent. + + Args: + gray_string: A string of 0s and 1s representing Gray Code + + Returns: + The decimal equivalent as an integer + + Examples: + >>> gray_to_decimal('0') + 0 + >>> gray_to_decimal('1') + 1 + >>> gray_to_decimal('11') + 2 + >>> gray_to_decimal('10') + 3 + >>> gray_to_decimal('110') + 4 + >>> gray_to_decimal('1111') + 10 + >>> gray_to_decimal('1000') + 15 + >>> gray_to_decimal('invalid') + Traceback (most recent call last): + ... + ValueError: Invalid binary string + >>> gray_to_decimal('') + Traceback (most recent call last): + ... + ValueError: Input string cannot be empty + """ + if not gray_string: + raise ValueError("Input string cannot be empty") + + # Validate binary string + if not all(bit in "01" for bit in gray_string): + raise ValueError("Invalid binary string") + + gray_number = int(gray_string, 2) + return gray_to_binary(gray_number) + + +if __name__ == "__main__": + import doctest + + doctest.testmod() + + # Interactive demonstration + print("=== Binary to Gray Code Converter ===\n") + + # Demonstrate conversions for 0-15 + print("Decimal | Binary | Gray Code") + print("--------|----------|----------") + for i in range(16): + binary = bin(i)[2:].zfill(4) + gray = decimal_to_gray(i).zfill(4) + print(f"{i:7} | {binary:8} | {gray:9}") + + print("\n=== Verification: Gray to Binary ===\n") + print("Gray Code | Binary | Decimal") + print("----------|----------|--------") + for i in range(16): + gray = decimal_to_gray(i).zfill(4) + decimal = gray_to_decimal(gray) + binary = bin(decimal)[2:].zfill(4) + print(f"{gray:9} | {binary:8} | {decimal:7}") diff --git a/conversions/convert_number_to_words.py b/conversions/convert_number_to_words.py index dbab44c72e1f..6aa43738b9fe 100644 --- a/conversions/convert_number_to_words.py +++ b/conversions/convert_number_to_words.py @@ -1,5 +1,5 @@ from enum import Enum -from typing import ClassVar, Literal +from typing import Literal class NumberingSystem(Enum): @@ -54,7 +54,7 @@ def max_value(cls, system: str) -> int: class NumberWords(Enum): - ONES: ClassVar[dict[int, str]] = { + ONES = { # noqa: RUF012 0: "", 1: "one", 2: "two", @@ -67,7 +67,7 @@ class NumberWords(Enum): 9: "nine", } - TEENS: ClassVar[dict[int, str]] = { + TEENS = { # noqa: RUF012 0: "ten", 1: "eleven", 2: "twelve", @@ -80,7 +80,7 @@ class NumberWords(Enum): 9: "nineteen", } - TENS: ClassVar[dict[int, str]] = { + TENS = { # noqa: RUF012 2: "twenty", 3: "thirty", 4: "forty", diff --git a/conversions/decimal_to_any.py b/conversions/decimal_to_any.py index c9c2e9a5fb71..b257761eff40 100644 --- a/conversions/decimal_to_any.py +++ b/conversions/decimal_to_any.py @@ -81,11 +81,12 @@ def decimal_to_any(num: int, base: int) -> str: new_value += actual_value div = num // base num = div - if div == 0: - return str(new_value[::-1]) - elif div == 1: - new_value += str(div) - return str(new_value[::-1]) + match div: + case 0: + return str(new_value[::-1]) + case 1: + new_value += str(div) + return str(new_value[::-1]) return new_value[::-1] diff --git a/conversions/endianness.py b/conversions/endianness.py new file mode 100644 index 000000000000..291112fa42a2 --- /dev/null +++ b/conversions/endianness.py @@ -0,0 +1,329 @@ +""" +Endianness Conversion Algorithm + +This module implements endianness (byte order) conversion utilities for converting +between big-endian and little-endian representations of multi-byte integers. + +Endianness refers to the order of bytes in a multi-byte data type: +- Big-endian: Most significant byte first (e.g., 0x12345678 → [0x12, 0x34, 0x56, 0x78]) +- Little-endian: Least significant byte first + (e.g., 0x12345678 → [0x78, 0x56, 0x34, 0x12]) + +Common uses: +- Network protocols (TCP/IP uses big-endian for multi-byte fields) +- File format parsing (PNG, JPEG headers specify endianness) +- Cryptographic algorithms (MD5 uses little-endian, SHA-256 uses big-endian) +- Binary data serialization (Protocol Buffers, MessagePack) +- Hardware interfacing (ARM is bi-endian, x86 is strictly little-endian) +- Cross-platform data exchange + +Real-world examples: +- IP addresses are transmitted in big-endian (network byte order) +- Modern ARM and x86 processors typically operate in little-endian mode +- Java class files use big-endian format +- Bitcoin uses little-endian for block hashes +- USB and PCI protocols use little-endian + +References: +- https://en.wikipedia.org/wiki/Endianness +- RFC 1700 (Network Byte Order) +- https://tools.ietf.org/html/rfc1700 +""" + + +def swap_endianness_16(value: int) -> int: + """ + Swap the byte order of a 16-bit integer. + + Args: + value: 16-bit integer (0 to 65,535) + + Returns: + Integer with swapped byte order + + Raises: + ValueError: If value is negative or exceeds 16-bit range + + >>> swap_endianness_16(0x1234) + 13330 + + >>> hex(swap_endianness_16(0x1234)) + '0x3412' + + >>> swap_endianness_16(0xABCD) + 52651 + + >>> hex(swap_endianness_16(0xABCD)) + '0xcdab' + + >>> swap_endianness_16(0) + 0 + + >>> swap_endianness_16(0xFFFF) + 65535 + """ + if value < 0 or value > 0xFFFF: + msg = f"value must be between 0 and {0xFFFF}" + raise ValueError(msg) + + return ((value & 0xFF) << 8) | ((value & 0xFF00) >> 8) + + +def swap_endianness_32(value: int) -> int: + """ + Swap the byte order of a 32-bit integer. + + Args: + value: 32-bit integer (0 to 4,294,967,295) + + Returns: + Integer with swapped byte order + + Raises: + ValueError: If value is negative or exceeds 32-bit range + + >>> swap_endianness_32(0x12345678) + 2018915346 + + >>> hex(swap_endianness_32(0x12345678)) + '0x78563412' + + >>> swap_endianness_32(0xDEADBEEF) + 4022250974 + + >>> hex(swap_endianness_32(0xDEADBEEF)) + '0xefbeadde' + + >>> swap_endianness_32(0) + 0 + + >>> swap_endianness_32(0xFFFFFFFF) + 4294967295 + + >>> swap_endianness_32(0x01020304) + 67305985 + """ + if value < 0 or value > 0xFFFFFFFF: + msg = f"value must be between 0 and {0xFFFFFFFF}" + raise ValueError(msg) + + return ( + ((value & 0x000000FF) << 24) + | ((value & 0x0000FF00) << 8) + | ((value & 0x00FF0000) >> 8) + | ((value & 0xFF000000) >> 24) + ) + + +def swap_endianness_64(value: int) -> int: + """ + Swap the byte order of a 64-bit integer. + + Args: + value: 64-bit integer (0 to 18,446,744,073,709,551,615) + + Returns: + Integer with swapped byte order + + Raises: + ValueError: If value is negative or exceeds 64-bit range + + >>> swap_endianness_64(0x0123456789ABCDEF) + 17279655951921914625 + + >>> hex(swap_endianness_64(0x0123456789ABCDEF)) + '0xefcdab8967452301' + + >>> swap_endianness_64(0xFEDCBA9876543210) + 1167088121787636990 + + >>> hex(swap_endianness_64(0xFEDCBA9876543210)) + '0x1032547698badcfe' + + >>> swap_endianness_64(0) + 0 + + >>> swap_endianness_64(0xFFFFFFFFFFFFFFFF) + 18446744073709551615 + """ + if value < 0 or value > 0xFFFFFFFFFFFFFFFF: + msg = f"value must be between 0 and {0xFFFFFFFFFFFFFFFF}" + raise ValueError(msg) + + return ( + ((value & 0x00000000000000FF) << 56) + | ((value & 0x000000000000FF00) << 40) + | ((value & 0x0000000000FF0000) << 24) + | ((value & 0x00000000FF000000) << 8) + | ((value & 0x000000FF00000000) >> 8) + | ((value & 0x0000FF0000000000) >> 24) + | ((value & 0x00FF000000000000) >> 40) + | ((value & 0xFF00000000000000) >> 56) + ) + + +def bytes_to_int_little(data: bytes) -> int: + """ + Convert bytes to integer using little-endian byte order. + + Args: + data: Byte sequence to convert (1-8 bytes) + + Returns: + Integer representation in little-endian order + + Raises: + TypeError: If data is not bytes + ValueError: If data is empty or exceeds 8 bytes + + >>> bytes_to_int_little(b'\\x78\\x56\\x34\\x12') + 305419896 + + >>> hex(bytes_to_int_little(b'\\x78\\x56\\x34\\x12')) + '0x12345678' + + >>> bytes_to_int_little(b'\\x01\\x02') + 513 + + >>> bytes_to_int_little(b'\\xff') + 255 + + >>> bytes_to_int_little(b'\\x00\\x00\\x00\\x01') + 16777216 + """ + if not data or len(data) > 8: + msg = "data must be between 1 and 8 bytes" + raise ValueError(msg) + + return int.from_bytes(data, byteorder="little") + + +def bytes_to_int_big(data: bytes) -> int: + """ + Convert bytes to integer using big-endian byte order. + + Args: + data: Byte sequence to convert (1-8 bytes) + + Returns: + Integer representation in big-endian order + + Raises: + TypeError: If data is not bytes + ValueError: If data is empty or exceeds 8 bytes + + >>> bytes_to_int_big(b'\\x12\\x34\\x56\\x78') + 305419896 + + >>> hex(bytes_to_int_big(b'\\x12\\x34\\x56\\x78')) + '0x12345678' + + >>> bytes_to_int_big(b'\\x01\\x02') + 258 + + >>> bytes_to_int_big(b'\\xff') + 255 + + >>> bytes_to_int_big(b'\\x00\\x00\\x00\\x01') + 1 + """ + if not data or len(data) > 8: + msg = "data must be between 1 and 8 bytes" + raise ValueError(msg) + + return int.from_bytes(data, byteorder="big") + + +def int_to_bytes_little(value: int, num_bytes: int) -> bytes: + """ + Convert integer to bytes using little-endian byte order. + + Args: + value: Integer to convert (non-negative) + num_bytes: Number of bytes in output (1-8) + + Returns: + Bytes representation in little-endian order + + Raises: + ValueError: If value is negative, num_bytes invalid, or value too large + + >>> int_to_bytes_little(0x12345678, 4) + b'xV4\\x12' + + >>> int_to_bytes_little(513, 2) + b'\\x01\\x02' + + >>> int_to_bytes_little(255, 1) + b'\\xff' + + >>> int_to_bytes_little(16777216, 4) + b'\\x00\\x00\\x00\\x01' + """ + if value < 0: + msg = "value must be non-negative" + raise ValueError(msg) + + if num_bytes < 1 or num_bytes > 8: + msg = "num_bytes must be between 1 and 8" + raise ValueError(msg) + + if value >= (1 << (num_bytes * 8)): + msg = f"value {value} too large for {num_bytes} bytes" + raise ValueError(msg) + + return value.to_bytes(num_bytes, byteorder="little") + + +def int_to_bytes_big(value: int, num_bytes: int) -> bytes: + """ + Convert integer to bytes using big-endian byte order. + + Args: + value: Integer to convert (non-negative) + num_bytes: Number of bytes in output (1-8) + + Returns: + Bytes representation in big-endian order + + Raises: + ValueError: If value is negative, num_bytes invalid, or value too large + + >>> int_to_bytes_big(0x12345678, 4) + b'\\x124Vx' + + >>> int_to_bytes_big(258, 2) + b'\\x01\\x02' + + >>> int_to_bytes_big(255, 1) + b'\\xff' + + >>> int_to_bytes_big(1, 4) + b'\\x00\\x00\\x00\\x01' + """ + if value < 0: + msg = "value must be non-negative" + raise ValueError(msg) + + if num_bytes < 1 or num_bytes > 8: + msg = "num_bytes must be between 1 and 8" + raise ValueError(msg) + + if value >= (1 << (num_bytes * 8)): + msg = f"value {value} too large for {num_bytes} bytes" + raise ValueError(msg) + + return value.to_bytes(num_bytes, byteorder="big") + + +if __name__ == "__main__": + import doctest + + _ = doctest.testmod() + + print("Endianness Conversion Examples:") + print(f"16-bit: 0x1234 → {hex(swap_endianness_16(0x1234))}") + print(f"32-bit: 0x12345678 → {hex(swap_endianness_32(0x12345678))}") + print(f"64-bit: 0x0123456789ABCDEF → {hex(swap_endianness_64(0x0123456789ABCDEF))}") + print(f"Bytes to int (little): {bytes_to_int_little(b'\x78\x56\x34\x12'):#x}") + print(f"Bytes to int (big): {bytes_to_int_big(b'\x12\x34\x56\x78'):#x}") diff --git a/conversions/excel_title_to_column.py b/conversions/excel_title_to_column.py index d77031ec26f2..235b6a64a647 100644 --- a/conversions/excel_title_to_column.py +++ b/conversions/excel_title_to_column.py @@ -12,8 +12,24 @@ def excel_title_to_column(column_title: str) -> int: 28 >>> excel_title_to_column("Z") 26 + >>> excel_title_to_column("a") + 1 + >>> excel_title_to_column("ab") + 28 + >>> excel_title_to_column("") + Traceback (most recent call last): + ... + ValueError: Column title must contain only alphabetic characters. + >>> excel_title_to_column("A1") + Traceback (most recent call last): + ... + ValueError: Column title must contain only alphabetic characters. """ - assert column_title.isupper() + if not column_title or not column_title.isalpha(): + msg = "Column title must contain only alphabetic characters." + raise ValueError(msg) + + column_title = column_title.upper() answer = 0 index = len(column_title) - 1 power = 0 diff --git a/conversions/hex_to_rgb.py b/conversions/hex_to_rgb.py new file mode 100644 index 000000000000..6d97acb4fe4e --- /dev/null +++ b/conversions/hex_to_rgb.py @@ -0,0 +1,79 @@ +""" +* Author: Cicero Tiago Carneiro Valentim (https://github.com/cicerotcv) +* Description: Convert hexadecimal (#FF2000) color to RGB (rgb(255, 32, 0)). + +References: +https://www.w3schools.com/colors/colors_rgb.asp +https://www.w3schools.com/colors/colors_hexadecimal.asp +""" + + +def hex_to_rgb(hex_color: str) -> str: + """ + Converts a hexadecimal color code to RGB values. + + Args: + hex_color (str): A hexadecimal color code, e.g., "#RGB" or "#RRGGBB". + + Returns: + str: A string representation of a rgb value "rgb(r, g, b)" containing + three integers. + + Raises: + ValueError: If the input hex_color is not a valid hexadecimal color code. + + Examples: + >>> hex_to_rgb("#FF0000") + 'rgb(255, 0, 0)' + + >>> hex_to_rgb("#00FF00") + 'rgb(0, 255, 0)' + + >>> hex_to_rgb("#123") + 'rgb(17, 34, 51)' + + >>> hex_to_rgb("#000000") + 'rgb(0, 0, 0)' + + >>> hex_to_rgb("#FFFFFF") + 'rgb(255, 255, 255)' + + >>> hex_to_rgb("#0088FF") + 'rgb(0, 136, 255)' + + >>> hex_to_rgb("#0032ccAA") + Traceback (most recent call last): + ... + ValueError: Invalid hex color code + + >>> hex_to_rgb("#0032") + Traceback (most recent call last): + ... + ValueError: Invalid hex color code + + Note: + - The function supports both 6-digit and 3-digit hex color codes. + """ + + hex_color = hex_color.lstrip("#") + + # Check if the input is a valid hex color code + if not (len(hex_color) == 6 or len(hex_color) == 3): + raise ValueError("Invalid hex color code") + + # Expand 3-digit hex codes to 6 digits (e.g., "#123" to "#112233") + if len(hex_color) == 3: + hex_color = "".join([char * 2 for char in hex_color]) + + # Parse the hex values to integers + red = int(hex_color[0:2], 16) + green = int(hex_color[2:4], 16) + blue = int(hex_color[4:6], 16) + + return f"rgb({red}, {green}, {blue})" + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/conversions/int_to_negative_binary_base.py b/conversions/int_to_negative_binary_base.py new file mode 100644 index 000000000000..3f8a0042fff3 --- /dev/null +++ b/conversions/int_to_negative_binary_base.py @@ -0,0 +1,30 @@ +def decimal_to_negative_binary(number: int) -> int: + """ + a conversion algorithm from decimal + to negative binary base + + https://en.wikipedia.org/wiki/Negative_base#:~:text=Binary-,Negabinary,-Ternary + + >>> decimal_to_negative_binary(10) + 11110 + >>> decimal_to_negative_binary(-10) + 1010 + >>> decimal_to_negative_binary(-30) + 100110 + >>> decimal_to_negative_binary(30) + 1100010 + """ + + if number == 0: + return 0 + result_str = "" + while number != 0: + number, remainder = divmod(number, -2) + if remainder < 0: + number, remainder = number + 1, remainder + 2 + result_str = str(remainder) + result_str + return int(result_str) + + +if __name__ == "__main__": + __import__("doctest").testmod() diff --git a/conversions/molecular_chemistry.py b/conversions/molecular_chemistry.py index 51ffe534dd0d..69e3ae5b728f 100644 --- a/conversions/molecular_chemistry.py +++ b/conversions/molecular_chemistry.py @@ -4,6 +4,8 @@ * moles_to_pressure * moles_to_volume * pressure_and_volume_to_temperature +* mass_to_moles +* moles_to_molecules """ @@ -85,6 +87,44 @@ def pressure_and_volume_to_temperature( return round(float((pressure * volume) / (0.0821 * moles))) +def mass_to_moles(mass: float, molar_mass: float) -> float: + """ + Convert mass of a substance to moles. + Mass is taken in grams. + Molar mass is taken in grams per mole (g/mol). + + Wikipedia reference: https://en.wikipedia.org/wiki/Mole_(unit) + + >>> mass_to_moles(36.03, 18.015) + 2.0 + >>> mass_to_moles(11.0, 44.01) + 0.25 + """ + if molar_mass <= 0: + raise ValueError("Molar mass must be greater than zero.") + if mass < 0: + raise ValueError("Mass cannot be negative.") + + return round(float(mass / molar_mass), 2) + + +def moles_to_molecules(moles: float) -> float: + """ + Convert moles of a substance to total molecules using Avogadro's constant. + + Wikipedia reference: https://en.wikipedia.org/wiki/Avogadro_constant + + >>> moles_to_molecules(2) + 1.2044e+24 + >>> moles_to_molecules(0.5) + 3.011e+23 + """ + if moles < 0: + raise ValueError("Moles cannot be negative.") + + return float(f"{moles * 6.022e23:.4e}") + + if __name__ == "__main__": import doctest diff --git a/conversions/negative_binary_base_to_int.py b/conversions/negative_binary_base_to_int.py new file mode 100644 index 000000000000..082f63e9a358 --- /dev/null +++ b/conversions/negative_binary_base_to_int.py @@ -0,0 +1,24 @@ +def negative_binary_to_int(negative_binary: int) -> int: + """ + a conversion algorithm from negative binary + base to decimal + + https://en.wikipedia.org/wiki/Negative_base#:~:text=Binary-,Negabinary,-Ternary + + >>> negative_binary_to_int(101110) + -38 + >>> negative_binary_to_int(10111110) + -150 + >>> negative_binary_to_int(100) + 4 + >>> negative_binary_to_int(110) + 2 + """ + negative_binary_str = str(negative_binary) + r = negative_binary_str[::-1] + res = [int(r[c]) * (-2) ** c for c in range(len(r))] + return sum(res) + + +if __name__ == "__main__": + __import__("doctest").testmod() diff --git a/conversions/prefix_conversions_string.py b/conversions/prefix_conversions_string.py index 9344c9672a1f..c5fef49874ca 100644 --- a/conversions/prefix_conversions_string.py +++ b/conversions/prefix_conversions_string.py @@ -53,7 +53,7 @@ class SIUnit(Enum): yocto = -24 @classmethod - def get_positive(cls: type[T]) -> dict: + def get_positive(cls) -> dict: """ Returns a dictionary with only the elements of this enum that has a positive value @@ -68,7 +68,7 @@ def get_positive(cls: type[T]) -> dict: return {unit.name: unit.value for unit in cls if unit.value > 0} @classmethod - def get_negative(cls: type[T]) -> dict: + def get_negative(cls) -> dict: """ Returns a dictionary with only the elements of this enum that has a negative value diff --git a/conversions/rectangular_to_polar.py b/conversions/rectangular_to_polar.py new file mode 100644 index 000000000000..bed97d7410ec --- /dev/null +++ b/conversions/rectangular_to_polar.py @@ -0,0 +1,32 @@ +import math + + +def rectangular_to_polar(real: float, img: float) -> tuple[float, float]: + """ + https://en.wikipedia.org/wiki/Polar_coordinate_system + + >>> rectangular_to_polar(5,-5) + (7.07, -45.0) + >>> rectangular_to_polar(-1,1) + (1.41, 135.0) + >>> rectangular_to_polar(-1,-1) + (1.41, -135.0) + >>> rectangular_to_polar(1e-10,1e-10) + (0.0, 45.0) + >>> rectangular_to_polar(-1e-10,1e-10) + (0.0, 135.0) + >>> rectangular_to_polar(9.75,5.93) + (11.41, 31.31) + >>> rectangular_to_polar(10000,99999) + (100497.76, 84.29) + """ + + mod = round(math.sqrt((real**2) + (img**2)), 2) + ang = round(math.degrees(math.atan2(img, real)), 2) + return (mod, ang) + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/conversions/roman_numerals.py b/conversions/roman_numerals.py index 75af2ac72882..7764ee0d8de5 100644 --- a/conversions/roman_numerals.py +++ b/conversions/roman_numerals.py @@ -40,12 +40,35 @@ def roman_to_int(roman: str) -> int: def int_to_roman(number: int) -> str: """ - Given a integer, convert it to an roman numeral. + Given an integer, convert it to a Roman numeral. + Input must be an integer in the range 1 to 3999. https://en.wikipedia.org/wiki/Roman_numerals >>> tests = {"III": 3, "CLIV": 154, "MIX": 1009, "MMD": 2500, "MMMCMXCIX": 3999} >>> all(int_to_roman(value) == key for key, value in tests.items()) True + >>> int_to_roman(0) + Traceback (most recent call last): + ... + ValueError: int_to_roman only accepts integers in the range 1 to 3999, got 0 + >>> int_to_roman(-1) + Traceback (most recent call last): + ... + ValueError: int_to_roman only accepts integers in the range 1 to 3999, got -1 + >>> int_to_roman(4000) + Traceback (most recent call last): + ... + ValueError: int_to_roman only accepts integers in the range 1 to 3999, got 4000 + >>> int_to_roman(True) + Traceback (most recent call last): + ... + TypeError: int_to_roman only accepts integers, got bool """ + if isinstance(number, bool) or not isinstance(number, int): + msg = f"int_to_roman only accepts integers, got {type(number).__name__}" + raise TypeError(msg) + if not 1 <= number <= 3999: + msg = f"int_to_roman only accepts integers in the range 1 to 3999, got {number}" + raise ValueError(msg) result = [] for arabic, roman in ROMAN: (factor, number) = divmod(number, arabic) diff --git a/compression/README.md b/data_compression/README.md similarity index 100% rename from compression/README.md rename to data_compression/README.md diff --git a/compression/__init__.py b/data_compression/__init__.py similarity index 100% rename from compression/__init__.py rename to data_compression/__init__.py diff --git a/compression/burrows_wheeler.py b/data_compression/burrows_wheeler.py similarity index 100% rename from compression/burrows_wheeler.py rename to data_compression/burrows_wheeler.py diff --git a/data_compression/coordinate_compression.py b/data_compression/coordinate_compression.py new file mode 100644 index 000000000000..bdb5f204536b --- /dev/null +++ b/data_compression/coordinate_compression.py @@ -0,0 +1,145 @@ +""" +Assumption: + - The values to compress are assumed to be comparable, + values can be sorted and compared with '<' and '>' operators. +""" + + +class CoordinateCompressor: + """ + A class for coordinate compression. + + This class allows you to compress and decompress a list of values. + + Mapping: + In addition to compression and decompression, this class maintains a mapping + between original values and their compressed counterparts using two data + structures: a dictionary `coordinate_map` and a list `reverse_map`: + - `coordinate_map`: A dictionary that maps original values to their compressed + coordinates. Keys are original values, and values are compressed coordinates. + - `reverse_map`: A list used for reverse mapping, where each index corresponds + to a compressed coordinate, and the value at that index is the original value. + + Example of mapping: + Original: 10, Compressed: 0 + Original: 52, Compressed: 1 + Original: 83, Compressed: 2 + Original: 100, Compressed: 3 + + This mapping allows for efficient compression and decompression of values within + the list. + """ + + def __init__(self, arr: list[int | float | str]) -> None: + """ + Initialize the CoordinateCompressor with a list. + + Args: + arr: The list of values to be compressed. + + >>> arr = [100, 10, 52, 83] + >>> cc = CoordinateCompressor(arr) + >>> cc.compress(100) + 3 + >>> cc.compress(52) + 1 + >>> cc.decompress(1) + 52 + """ + + # A dictionary to store compressed coordinates + self.coordinate_map: dict[int | float | str, int] = {} + + # A list to store reverse mapping + self.reverse_map: list[int | float | str] = [-1] * len(arr) + + self.arr = sorted(arr) # The input list + self.n = len(arr) # The length of the input list + self.compress_coordinates() + + def compress_coordinates(self) -> None: + """ + Compress the coordinates in the input list. + + >>> arr = [100, 10, 52, 83] + >>> cc = CoordinateCompressor(arr) + >>> cc.coordinate_map[83] + 2 + >>> cc.coordinate_map[80] # Value not in the original list + Traceback (most recent call last): + ... + KeyError: 80 + >>> cc.reverse_map[2] + 83 + """ + key = 0 + for val in self.arr: + if val not in self.coordinate_map: + self.coordinate_map[val] = key + self.reverse_map[key] = val + key += 1 + + def compress(self, original: float | str) -> int: + """ + Compress a single value. + + Args: + original: The value to compress. + + Returns: + The compressed integer. + + Raises: + KeyError: If ``original`` was not part of the input list. + + >>> arr = [100, 10, 52, 83] + >>> cc = CoordinateCompressor(arr) + >>> cc.compress(100) + 3 + >>> cc.compress(7) # Value not in the original list + Traceback (most recent call last): + ... + KeyError: 7 + """ + return self.coordinate_map[original] + + def decompress(self, num: int) -> int | float | str: + """ + Decompress a single integer. + + Args: + num: The compressed integer to decompress. + + Returns: + The original value. + + Raises: + IndexError: If ``num`` is not a valid compressed coordinate. + + >>> arr = [100, 10, 52, 83] + >>> cc = CoordinateCompressor(arr) + >>> cc.decompress(0) + 10 + >>> cc.decompress(5) # Compressed coordinate out of range + Traceback (most recent call last): + ... + IndexError: compressed coordinate 5 is out of range + """ + if not 0 <= num < len(self.reverse_map): + msg = f"compressed coordinate {num} is out of range" + raise IndexError(msg) + return self.reverse_map[num] + + +if __name__ == "__main__": + from doctest import testmod + + testmod() + + arr: list[int | float | str] = [100, 10, 52, 83] + cc = CoordinateCompressor(arr) + + for original in arr: + compressed = cc.compress(original) + decompressed = cc.decompress(compressed) + print(f"Original: {decompressed}, Compressed: {compressed}") diff --git a/compression/huffman.py b/data_compression/huffman.py similarity index 91% rename from compression/huffman.py rename to data_compression/huffman.py index 44eda6c03180..425876f5e5e6 100644 --- a/compression/huffman.py +++ b/data_compression/huffman.py @@ -4,7 +4,7 @@ class Letter: - def __init__(self, letter: str, freq: int): + def __init__(self, letter: str, freq: int) -> None: self.letter: str = letter self.freq: int = freq self.bitstring: dict[str, str] = {} @@ -14,7 +14,9 @@ def __repr__(self) -> str: class TreeNode: - def __init__(self, freq: int, left: Letter | TreeNode, right: Letter | TreeNode): + def __init__( + self, freq: int, left: Letter | TreeNode, right: Letter | TreeNode + ) -> None: self.freq: int = freq self.left: Letter | TreeNode = left self.right: Letter | TreeNode = right @@ -74,9 +76,7 @@ def huffman(file_path: str) -> None: """ letters_list = parse_file(file_path) root = build_tree(letters_list) - letters = { - k: v for letter in traverse_tree(root, "") for k, v in letter.bitstring.items() - } + letters = {**letter.bitstring for letter in traverse_tree(root, "")} print(f"Huffman Coding of {file_path}: ") with open(file_path) as f: while True: diff --git a/compression/image_data/PSNR-example-base.png b/data_compression/image_data/PSNR-example-base.png similarity index 100% rename from compression/image_data/PSNR-example-base.png rename to data_compression/image_data/PSNR-example-base.png diff --git a/compression/image_data/PSNR-example-comp-10.jpg b/data_compression/image_data/PSNR-example-comp-10.jpg similarity index 100% rename from compression/image_data/PSNR-example-comp-10.jpg rename to data_compression/image_data/PSNR-example-comp-10.jpg diff --git a/compression/image_data/compressed_image.png b/data_compression/image_data/compressed_image.png similarity index 100% rename from compression/image_data/compressed_image.png rename to data_compression/image_data/compressed_image.png diff --git a/compression/image_data/example_image.jpg b/data_compression/image_data/example_image.jpg similarity index 100% rename from compression/image_data/example_image.jpg rename to data_compression/image_data/example_image.jpg diff --git a/compression/image_data/example_wikipedia_image.jpg b/data_compression/image_data/example_wikipedia_image.jpg similarity index 100% rename from compression/image_data/example_wikipedia_image.jpg rename to data_compression/image_data/example_wikipedia_image.jpg diff --git a/compression/image_data/original_image.png b/data_compression/image_data/original_image.png similarity index 100% rename from compression/image_data/original_image.png rename to data_compression/image_data/original_image.png diff --git a/compression/lempel_ziv.py b/data_compression/lempel_ziv.py similarity index 97% rename from compression/lempel_ziv.py rename to data_compression/lempel_ziv.py index 2751a0ebcdb6..648b029471bd 100644 --- a/compression/lempel_ziv.py +++ b/data_compression/lempel_ziv.py @@ -35,8 +35,8 @@ def add_key_to_lexicon( lexicon[curr_string + "0"] = last_match_id if math.log2(index).is_integer(): - for curr_key in lexicon: - lexicon[curr_key] = "0" + lexicon[curr_key] + for curr_key, value in lexicon.items(): + lexicon[curr_key] = f"0{value}" lexicon[curr_string + "1"] = bin(index)[2:] diff --git a/compression/lempel_ziv_decompress.py b/data_compression/lempel_ziv_decompress.py similarity index 100% rename from compression/lempel_ziv_decompress.py rename to data_compression/lempel_ziv_decompress.py diff --git a/compression/lz77.py b/data_compression/lz77.py similarity index 100% rename from compression/lz77.py rename to data_compression/lz77.py diff --git a/data_compression/move_to_front.py b/data_compression/move_to_front.py new file mode 100644 index 000000000000..07bdc32f7b34 --- /dev/null +++ b/data_compression/move_to_front.py @@ -0,0 +1,99 @@ +""" +Move-to-front transform. + +The move-to-front transform encodes each symbol as its current index in an +ordered alphabet, then moves that symbol to the front of the alphabet. +It is commonly used after the Burrows-Wheeler transform in lossless +compression pipelines. + +Reference: https://en.wikipedia.org/wiki/Move-to-front_transform +""" + + +def _validated_alphabet(alphabet: str) -> list[str]: + """ + Return a mutable alphabet list after validating uniqueness. + + >>> _validated_alphabet("abc") + ['a', 'b', 'c'] + >>> _validated_alphabet("aba") + Traceback (most recent call last): + ... + ValueError: alphabet must contain unique characters + """ + if not isinstance(alphabet, str): + raise TypeError("alphabet must be a string") + if len(set(alphabet)) != len(alphabet): + raise ValueError("alphabet must contain unique characters") + return list(alphabet) + + +def move_to_front_encode(text: str, alphabet: str) -> list[int]: + """ + Encode text using the move-to-front transform. + + >>> move_to_front_encode("banana", "abcdefghijklmnopqrstuvwxyz") + [1, 1, 13, 1, 1, 1] + >>> move_to_front_encode("banana", "abn") + [1, 1, 2, 1, 1, 1] + >>> move_to_front_encode("", "abc") + [] + >>> move_to_front_encode("bad", "abc") + Traceback (most recent call last): + ... + ValueError: character 'd' is not in the alphabet + """ + if not isinstance(text, str): + raise TypeError("text must be a string") + + symbols = _validated_alphabet(alphabet) + encoded_text: list[int] = [] + + for char in text: + try: + char_index = symbols.index(char) + except ValueError: + message = f"character {char!r} is not in the alphabet" + raise ValueError(message) from None + encoded_text.append(char_index) + symbols.insert(0, symbols.pop(char_index)) + + return encoded_text + + +def move_to_front_decode(encoded_text: list[int], alphabet: str) -> str: + """ + Decode a move-to-front encoded list of indexes. + + >>> move_to_front_decode([1, 1, 13, 1, 1, 1], "abcdefghijklmnopqrstuvwxyz") + 'banana' + >>> move_to_front_decode([1, 1, 2, 1, 1, 1], "abn") + 'banana' + >>> move_to_front_decode([], "abc") + '' + >>> move_to_front_decode([3], "abc") + Traceback (most recent call last): + ... + ValueError: index 3 is not valid for alphabet size 3 + >>> move_to_front_decode([-1], "abc") + Traceback (most recent call last): + ... + ValueError: index -1 is not valid for alphabet size 3 + """ + symbols = _validated_alphabet(alphabet) + decoded_text = [] + + for index in encoded_text: + if not 0 <= index < len(symbols): + message = f"index {index} is not valid for alphabet size {len(symbols)}" + raise ValueError(message) + decoded_text.append(symbols[index]) + symbols.insert(0, symbols.pop(index)) + + return "".join(decoded_text) + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/compression/peak_signal_to_noise_ratio.py b/data_compression/peak_signal_to_noise_ratio.py similarity index 100% rename from compression/peak_signal_to_noise_ratio.py rename to data_compression/peak_signal_to_noise_ratio.py diff --git a/compression/run_length_encoding.py b/data_compression/run_length_encoding.py similarity index 100% rename from compression/run_length_encoding.py rename to data_compression/run_length_encoding.py diff --git a/data_structures/arrays/dynamic_array.py b/data_structures/arrays/dynamic_array.py new file mode 100644 index 000000000000..9724270cb277 --- /dev/null +++ b/data_structures/arrays/dynamic_array.py @@ -0,0 +1,127 @@ +class DynamicArray: + def __init__(self) -> None: + self.size = 0 # Number of elements in the array + self.capacity = 1 # Initial capacity of the array + self.array = [None] * self.capacity # Create an array with initial capacity + + def append(self, item: int) -> None: + """ + The function adds an item to the end of the dynamic array. + + Runtime : O(1) amortized + Space: O(1) amortized + + >>> arr = DynamicArray() + >>> arr.append(1) + >>> arr.append(2) + >>> arr.append(3) + >>> arr.array[:arr.size] # Display only the filled part of the array + [1, 2, 3] + >>> arr.append(4) + >>> arr.array[:arr.size] + [1, 2, 3, 4] + >>> arr.append(5) + >>> arr.array[:arr.size] + [1, 2, 3, 4, 5] + """ + if self.size == self.capacity: + self._resize(2 * self.capacity) # Double the capacity + + self.array[self.size] = item + self.size += 1 + + def _resize(self, new_capacity: int) -> None: + """ + Resizes the array to the new capacity. + + Runtime : O(n) + Space: O(n) + + >>> arr = DynamicArray() + >>> arr.append(1) + >>> arr.append(2) + >>> arr._resize(10) + >>> arr.capacity + 10 + >>> arr.array[:arr.size] + [1, 2] + """ + new_array = [None] * new_capacity + for i in range(self.size): + new_array[i] = self.array[i] + self.array = new_array + self.capacity = new_capacity + + def get(self, index: int) -> int: + """ + The function returns the item at the specified index. + + Runtime : O(1) + Space: O(1) + + >>> arr = DynamicArray() + >>> arr.append(1) + >>> arr.append(2) + >>> arr.get(0) + 1 + >>> arr.get(1) + 2 + >>> arr.get(2) + Traceback (most recent call last): + ... + IndexError: index out of range + >>> arr.get(-1) + Traceback (most recent call last): + ... + IndexError: index out of range + """ + if index < 0 or index >= self.size: + raise IndexError("index out of range") + return self.array[index] + + def __setitem__(self, index: int, value: int) -> None: + if index < 0 or index >= self.size: + raise IndexError("index out of range") + self.array[index] = value + + def __len__(self) -> int: + """ + Returns the number of elements in the dynamic array. + + Runtime : O(1) + Space: O(1) + + >>> arr = DynamicArray() + >>> arr.append(1) + >>> len(arr) + 1 + >>> arr.append(2) + >>> len(arr) + 2 + >>> arr.append(3) + >>> len(arr) + 3 + """ + return self.size + + def __str__(self) -> str: + """ + Returns a string representation of the dynamic array. + + >>> arr = DynamicArray() + >>> arr.append(1) + >>> arr.append(2) + >>> arr.append(3) + >>> str(arr) + '[1, 2, 3]' + >>> arr.append(4) + >>> str(arr) + '[1, 2, 3, 4]' + """ + return "[" + ", ".join(str(self.array[i]) for i in range(self.size)) + "]" + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/data_structures/arrays/equilibrium_index_in_array.py b/data_structures/arrays/equilibrium_index_in_array.py index 0717a45d9f4b..dcb39959f8a7 100644 --- a/data_structures/arrays/equilibrium_index_in_array.py +++ b/data_structures/arrays/equilibrium_index_in_array.py @@ -1,54 +1,62 @@ """ Find the Equilibrium Index of an Array. -Reference: https://www.geeksforgeeks.org/equilibrium-index-of-an-array/ -Python doctest can be run with the following command: -python -m doctest -v equilibrium_index_in_array.py - -Given a sequence arr[] of size n, this function returns -an equilibrium index (if any) or -1 if no equilibrium index exists. - -The equilibrium index of an array is an index such that the sum of -elements at lower indexes is equal to the sum of elements at higher indexes. +Reference: +https://www.geeksforgeeks.org/equilibrium-index-of-an-array +Python doctest can be run with: +python -m doctest -v equilibrium_index_in_array.py -Example Input: -arr = [-7, 1, 5, 2, -4, 3, 0] -Output: 3 +Given an array arr of size n, return an equilibrium index +if one exists; otherwise return -1. +An equilibrium index is an index where the sum of all +elements to the left equals the sum of all elements +to the right. """ def equilibrium_index(arr: list[int]) -> int: """ - Find the equilibrium index of an array. - + Find the first equilibrium index of an array. Args: - arr (list[int]): The input array of integers. - + arr: The input array of integers. Returns: - int: The equilibrium index or -1 if no equilibrium index exists. - + The first equilibrium index, or -1 if none exists. Examples: + >>> equilibrium_index([]) + -1 + >>> equilibrium_index([5]) + 0 >>> equilibrium_index([-7, 1, 5, 2, -4, 3, 0]) 3 + >>> equilibrium_index([2, 4, 6, 8, 10, 3]) + -1 >>> equilibrium_index([1, 2, 3, 4, 5]) -1 >>> equilibrium_index([1, 1, 1, 1, 1]) 2 - >>> equilibrium_index([2, 4, 6, 8, 10, 3]) - -1 + >>> equilibrium_index([0, 0, 0]) + 0 + >>> equilibrium_index([-1, -1, -1]) + 1 + >>> equilibrium_index([1, -1, 0]) + 2 + + Time Complexity: + O(n), where n is the length of the array. + + Space Complexity: + O(1), using only constant extra space. """ total_sum = sum(arr) left_sum = 0 - for i, value in enumerate(arr): total_sum -= value if left_sum == total_sum: return i left_sum += value - return -1 diff --git a/data_structures/arrays/find_triplets_with_0_sum.py b/data_structures/arrays/find_triplets_with_0_sum.py index 52e521906873..b436d51fcbf0 100644 --- a/data_structures/arrays/find_triplets_with_0_sum.py +++ b/data_structures/arrays/find_triplets_with_0_sum.py @@ -81,6 +81,58 @@ def find_triplets_with_0_sum_hashing(arr: list[int]) -> list[list[int]]: return output_arr +def find_triplets_with_0_sum_two_pointers(nums: list[int]) -> list[list[int]]: + """ + Finds all unique triplets in the array which gives the sum of zero + using the two-pointer technique. + + Args: + nums: list of integers + Returns: + list of lists of integers where sum(each_list) == 0 + + Examples: + >>> find_triplets_with_0_sum_two_pointers([-1, 0, 1, 2, -1, -4]) + [[-1, -1, 2], [-1, 0, 1]] + >>> find_triplets_with_0_sum_two_pointers([]) + [] + >>> find_triplets_with_0_sum_two_pointers([0, 0, 0, 0]) + [[0, 0, 0]] + + Time Complexity: O(N^2) + Auxiliary Space: O(1) (excluding output) + """ + nums.sort() + result = [] + n = len(nums) + + for i in range(n - 2): + if i > 0 and nums[i] == nums[i - 1]: + continue + + left, right = i + 1, n - 1 + + while left < right: + total = nums[i] + nums[left] + nums[right] + + if total == 0: + result.append([nums[i], nums[left], nums[right]]) + left += 1 + right -= 1 + + while left < right and nums[left] == nums[left - 1]: + left += 1 + while left < right and nums[right] == nums[right + 1]: + right -= 1 + + elif total < 0: + left += 1 + else: + right -= 1 + + return result + + if __name__ == "__main__": from doctest import testmod diff --git a/data_structures/arrays/gas_station.py b/data_structures/arrays/gas_station.py new file mode 100644 index 000000000000..28eb88968fc6 --- /dev/null +++ b/data_structures/arrays/gas_station.py @@ -0,0 +1,50 @@ +from typing import NamedTuple + + +class GasStation(NamedTuple): + gas: int # Amount of gas available at this gas station + cost: int # Cost of gas required to drive to the next station + + +def can_complete_circuit(gas_stations: list[GasStation]) -> int: + """ + Finds the starting station index to complete the circuit, + or returns -1 if not possible. + Args: + gas_stations (List[GasStation]): List of gas stations with gas and cost. + Returns: + The index of the starting station, or -1 if no solution exists. + Examples: + >>> GS = GasStation + >>> test_stations = ( + ... [GS(1, 3), GS(2, 4), GS(3, 5), GS(4, 1), GS(5, 2)], + ... [GS(2, 3), GS(3, 4), GS(4, 3)], + ... [GS(5, 4), GS(1, 4), GS(2, 1), GS(3, 5), GS(4, 1)] + ... ) + >>> can_complete_circuit(test_stations[0]) + 3 + >>> can_complete_circuit(test_stations[1]) + -1 + >>> can_complete_circuit(test_stations[2]) + 4 + """ + total_gas = sum(station.gas - station.cost for station in gas_stations) + current_gas: int = 0 + start_station = 0 + for i, gas_station in enumerate(gas_stations): + needed_gas = gas_station.gas - gas_station.cost + total_gas += needed_gas + current_gas += needed_gas + if current_gas < 0: + start_station = i + 1 + current_gas = 0 + if total_gas < 0: + return -1 + return start_station + + +# Example usage with doctests +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/data_structures/arrays/merge_intervals.py b/data_structures/arrays/merge_intervals.py new file mode 100644 index 000000000000..c4c41ae1f016 --- /dev/null +++ b/data_structures/arrays/merge_intervals.py @@ -0,0 +1,64 @@ +def merge_intervals(intervals: list[list[int]]) -> list[list[int]]: + """ + Merge all overlapping intervals. + + Each interval is represented as a list of two integers [start, end]. + The function merges overlapping intervals and returns a list of + non-overlapping intervals sorted by start time. + + Parameters: + intervals (list[list[int]]): A list of intervals. + + Returns: + list[list[int]]: A list of merged non-overlapping intervals. + + Edge Cases Handled: + - Empty list: returns [] + - Single interval: returns the interval itself + - Intervals already sorted or unsorted + - Fully overlapping intervals + - Invalid intervals (e.g., [[]] or intervals not having exactly + 2 integers) raise ValueError + + Examples: + >>> merge_intervals([[1, 3], [2, 6], [8, 10], [15, 18]]) + [[1, 6], [8, 10], [15, 18]] + >>> merge_intervals([[1, 4], [4, 5]]) + [[1, 5]] + >>> merge_intervals([[6, 8], [1, 3], [2, 4]]) + [[1, 4], [6, 8]] + >>> merge_intervals([]) + [] + >>> merge_intervals([[1, 4]]) + [[1, 4]] + + Time Complexity: + O(n log n) - sorting the intervals, where n is the number of intervals. + + Space Complexity: + O(n) - storing the merged intervals. + """ + + if not intervals: + return [] + + for interval in intervals: + msg = f"Each interval must have exactly 2 integers, got {interval}" + if len(interval) != 2: + raise ValueError(msg) + + # Sort intervals based on the start time + # Sort a copy so the caller's list (and its inner lists) are never mutated + sorted_intervals = sorted(intervals, key=lambda interval: interval[0]) + + merged: list[list[int]] = [sorted_intervals[0][:]] + + for current in sorted_intervals[1:]: + last = merged[-1] + + # If current interval overlaps with the last merged interval + if current[0] <= last[1]: + last[1] = max(last[1], current[1]) + else: + merged.append(current[:]) + return merged diff --git a/data_structures/arrays/merge_sorted.py b/data_structures/arrays/merge_sorted.py new file mode 100644 index 000000000000..cef98fe3b435 --- /dev/null +++ b/data_structures/arrays/merge_sorted.py @@ -0,0 +1,76 @@ +def merge_sorted_arrays(nums1: list[int], nums2: list[int]) -> list[int]: + """ + Merge two sorted arrays into one sorted array. + + Args: + nums1: The first sorted array. + nums2: The second sorted array. + + Returns: + A single merged and sorted array. + + Examples: + >>> merge_sorted_arrays([1, 3, 5], [2, 4, 6]) + [1, 2, 3, 4, 5, 6] + + >>> merge_sorted_arrays([1, 2], []) + [1, 2] + + >>> merge_sorted_arrays([], [3, 4]) + [3, 4] + + >>> merge_sorted_arrays([], []) + [] + + >>> merge_sorted_arrays([0, 0], [0, 0]) + [0, 0, 0, 0] + + >>> merge_sorted_arrays([-5, -3, -1], [-2, -2]) + [-5, -3, -2, -2, -1] + + >>> merge_sorted_arrays(range(5), range(5)) + [0, 0, 1, 1, 2, 2, 3, 3, 4, 4] + + >>> merge_sorted_arrays([1, -1], []) + Traceback (most recent call last): + ... + ValueError: nums = [1, -1] is not sorted + + >>> merge_sorted_arrays([], [1, -1]) + Traceback (most recent call last): + ... + ValueError: nums = [1, -1] is not sorted + """ + for nums in (nums1, nums2): + if list(nums) != sorted(nums): + msg = f"{nums = } is not sorted" + raise ValueError(msg) + # If one array is empty, simply return the other. + if not nums1: + return nums2 + if not nums2: + return nums1 + + # Two-pointer approach to merge both sorted arrays. + i, j = 0, 0 + merged = [] + + while i < len(nums1) and j < len(nums2): + if nums1[i] <= nums2[j]: + merged.append(nums1[i]) + i += 1 + else: + merged.append(nums2[j]) + j += 1 + + # Append remaining elements if any. + merged.extend(nums1[i:]) + merged.extend(nums2[j:]) + + return merged + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/data_structures/arrays/monotonic_array.py b/data_structures/arrays/monotonic_array.py index c50a21530814..342d443a9cfc 100644 --- a/data_structures/arrays/monotonic_array.py +++ b/data_structures/arrays/monotonic_array.py @@ -9,6 +9,16 @@ def is_monotonic(nums: list[int]) -> bool: True >>> is_monotonic([1, 3, 2]) False + >>> is_monotonic([1,2,3,4,5,6,5]) + False + >>> is_monotonic([-3,-2,-1]) + True + >>> is_monotonic([-5,-6,-7]) + True + >>> is_monotonic([0,0,0]) + True + >>> is_monotonic([-100,0,100]) + True """ return all(nums[i] <= nums[i + 1] for i in range(len(nums) - 1)) or all( nums[i] >= nums[i + 1] for i in range(len(nums) - 1) @@ -21,3 +31,7 @@ def is_monotonic(nums: list[int]) -> bool: print(is_monotonic([1, 2, 2, 3])) # Output: True print(is_monotonic([6, 5, 4, 4])) # Output: True print(is_monotonic([1, 3, 2])) # Output: False + + import doctest + + doctest.testmod() diff --git a/data_structures/arrays/pairwise_iteration.py b/data_structures/arrays/pairwise_iteration.py new file mode 100644 index 000000000000..7342b90e9575 --- /dev/null +++ b/data_structures/arrays/pairwise_iteration.py @@ -0,0 +1,145 @@ +""" +Author : Matheus F. Vesco +Date : October 3, 2023 + +Implementation of pairwise iteration algorithms, which can be useful in +many domains. +Currently, there are two different implementations. +""" + +from collections.abc import Iterable, Iterator +from itertools import tee + + +def pairwise_iteration_tee(iterable: Iterable) -> Iterator[tuple]: + """ + Generate pairs of elements from an iterable just like: + https://docs.python.org/3/library/itertools.html#itertools.pairwise + + This function uses the `tee` function from the `itertools` module to + create two independent iterators (`a` and `b`) from the input + iterable. The `next` function is used to offset the `b` iterator by + one index, and then the two iterators are zipped together to create + pairs of elements. This implementation should work with any iterable + in Python. + + Args: + iterable (Iterable): The input iterable. + + Yields: + Iterator[Tuple]: An iterator that yields pairs of objects. + + Examples: + >>> list(pairwise_iteration_tee([1, 2, 3])) + [(1, 2), (2, 3)] + + >>> list(pairwise_iteration_tee((4, 3, 5))) + [(4, 3), (3, 5)] + + >>> list(pairwise_iteration_tee({'x':3, 'y':1, 'z':2, 'foo':4})) + [('x', 'y'), ('y', 'z'), ('z', 'foo')] + + >>> list(pairwise_iteration_tee('2345')) + [('2', '3'), ('3', '4'), ('4', '5')] + + >>> list(pairwise_iteration_tee(['ATG','GCT','TGC','TAA'])) + [('ATG', 'GCT'), ('GCT', 'TGC'), ('TGC', 'TAA')] + + >>> list(pairwise_iteration_tee(['a'])) + [] + + >>> from itertools import pairwise + >>> all(list(pairwise_iteration_tee(test)) == list(pairwise(test)) + ... for test in ( + ... [1, 2, 3], + ... (4, 3, 5), + ... {'x':3, 'y':1, 'z':2, 'foo':4}, + ... '2345', + ... ['ATG','GCT','TGC','TAA'], + ... [], + ... )) + True + """ + # Uses itertools.tee to create two independent iterators (a and b) + # from the iterable. This means we can use next() on each one + # without affecting the other, no matter the iterable type + a, b = tee(iterable) + + # Offsets the second iterator (b) by one step to create a staggered + # alignment. + # this means that (a[i],b[i]) represents the same as (a[i],a[i+1]) + next(b, None) + + # Returns a zip generator that pairs items from the two iterators in + # the format (a[i], a[i+1]). + return zip(a, b) + + +def pairwise_iteration_comprehension( + iterable: Iterable, step: int = 1 +) -> Iterator[tuple]: + """ + Generate pairs of elements from an iterable with a given step size. + + This function uses list comprehensions to get the items that are step + distance from each other and later the `iter()` conversion to create + two independent list iterators (`a` and `b`) from the input iterable. + The `next` function is used to offset the `b` iterator by one index, + and then the two iterators are zipped together to create pairs of + elements. + + Args: + iterable (Iterable): The input iterable. + step (int, optional): The step size for iterating through the + input iterable. Defaults to 1. + + Yields: + Iterator[Tuple]: An iterator that yields pairs of objects. + + Examples: + >>> list(pairwise_iteration_comprehension([0, 1, 2, 3, 4, 5, 6], step=2)) + [(0, 2), (2, 4), (4, 6)] + + >>> list(pairwise_iteration_comprehension([0, 1, 2, 3, 4, 5, 6], step=3)) + [(0, 3), (3, 6)] + + >>> list(pairwise_iteration_comprehension((0, 1, 2, 3, 4), step=2)) + [(0, 2), (2, 4)] + + >>> python_set = pairwise_iteration_comprehension( + ... {4, 3, 2, 1, 0}, step=2) + >>> list(python_set) # sets are unordered + [(0, 2), (2, 4)] + + >>> dictionary = pairwise_iteration_comprehension( + ... {'x1':4, 'y1':5, 'x2':1, 'y2':'a', 'spam':7}, step=2) + >>> list(dictionary) + [('x1', 'x2'), ('x2', 'spam')] + + >>> list(pairwise_iteration_comprehension({0, 1, 2, 3, 4, 5, 6}, step=3)) + [(0, 3), (3, 6)] + + >>> list(pairwise_iteration_comprehension(['ATG','GCT','TGC','TAA'])) + [('ATG', 'GCT'), ('GCT', 'TGC'), ('TGC', 'TAA')] + + >>> list(pairwise_iteration_comprehension(['a'], step=1)) + [] + """ + # creates a list, using list comprehensions, that only stores items + # that are n steps apart from each other. + items = [item for i, item in enumerate(iterable) if i % step == 0] + + # creates two independent list iterators (a and b) from the list + # we created earlier, using the iter() function. This means we can + # use next() on each one without affecting the other, no matter the + # iterable type + a, b = (iter(items), iter(items)) + + # Offsets the second iterator (b) by one step to create a staggered + # alignment. + # this means that (a[i],b[i]) represents the same as (a[i],a[i+1]) + next(b, None) + + # Returns a zip generator that pairs items from the two iterators in + # the format (a[i], a[i+1]). + return zip(a, b) diff --git a/data_structures/arrays/prefix_sum.py b/data_structures/arrays/prefix_sum.py index 2243a5308937..717b5f9d7e7e 100644 --- a/data_structures/arrays/prefix_sum.py +++ b/data_structures/arrays/prefix_sum.py @@ -30,11 +30,29 @@ def get_sum(self, start: int, end: int) -> int: 5 >>> PrefixSum([1,2,3]).get_sum(2, 2) 3 + >>> PrefixSum([]).get_sum(0, 0) + Traceback (most recent call last): + ... + ValueError: The array is empty. + >>> PrefixSum([1,2,3]).get_sum(-1, 2) + Traceback (most recent call last): + ... + ValueError: Invalid range specified. >>> PrefixSum([1,2,3]).get_sum(2, 3) Traceback (most recent call last): ... - IndexError: list index out of range + ValueError: Invalid range specified. + >>> PrefixSum([1,2,3]).get_sum(2, 1) + Traceback (most recent call last): + ... + ValueError: Invalid range specified. """ + if not self.prefix_sum: + raise ValueError("The array is empty.") + + if start < 0 or end >= len(self.prefix_sum) or start > end: + raise ValueError("Invalid range specified.") + if start == 0: return self.prefix_sum[end] diff --git a/data_structures/arrays/product_sum.py b/data_structures/arrays/product_sum.py index 4fb906f369ab..1d7d6ee94dbc 100644 --- a/data_structures/arrays/product_sum.py +++ b/data_structures/arrays/product_sum.py @@ -15,10 +15,12 @@ Example Input: [5, 2, [-7, 1], 3, [6, [-13, 8], 4]] -Output: 12 +Output: -12 """ +from timeit import timeit + def product_sum(arr: list[int | list], depth: int) -> int: """ @@ -92,7 +94,129 @@ def product_sum_array(array: list[int | list]) -> int: return product_sum(array, 1) +def product_sum_iterative(arr: list[int | list]) -> int: + """ + It Calculates the product sum of an array using iterative approach. + It's similar to BFS algorithm (Breadth first search algorithm). + It's won't run into stack overflow as compared to recursion approach + + Args: + array(List[Union[int, List]]): The array of integers/lists + + Returns: + int: The product sum of the array. + + Logic : + 1. Initialize a queue which stores the list, current + depth and it's multiplication factor + eg. queue -> [(arr, depth, multiplication_factor)] + + 2. Loop until queue is empty + 1. Take front item from Queue and pop it + 2. Iterate on front element + If current element is nested list + - then add that into queue with updated depth + and multiplication factor + Else if current element is not nested + - then update product sum variable by multiplying + current element with multiplicaton factor + + Algorithm flow example -> + Input list - [5, 2, [-7, 1], 3, [6, [-13, 8], 4]] + + Initialize queue - [([5, 2, [-7, 1], 3, [6, [-13, 8], 4]], 1, 1)] + + Step 0 + Queue - [([5, 2, [-7, 1], 3, [6, [-13, 8], 4]], 1, 1)] + Queue front item - + List - [5, 2, [-7, 1], 3, [6, [-13, 8], 4]] + depth - 1 + multiplication factor - 1 + + product sum = 0 (previous) + 5 * 1 + 2 * 1 + 3 * 1 = 10 + ------------------------------------------------------- + Step 1 + Queue - [([-7, 1], 2, 2), ([6, [-13, 8], 4], 2, 2)] + Queue front item - + List - [-7, 1] + depth - 2 + multiplication factor - 2 + + product sum = 10 (previous) + (-7) * 2 + 1 * 2 = -2 + ------------------------------------------------------- + Step 2 + Queue - [([6, [-13, 8], 4], 2, 2)] + Queue front item - + List - [6, [-13, 8], 4] + depth - 2 + multiplication factor - 2 + + product sum = -2 (previous) + 6 * 2 + 4 * 2 = 18 + ------------------------------------------------------- + Step 3 + Queue - [([-13, 8], 3, 6)] + Queue front item - + List - [-13, 8] + depth - 3 + multiplication factor - 6 + + product sum = 18 (previous) + (-13) * 6 + 8 * 6 = -12 + ------------------------------------------------------- + + 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 + """ + + # Initialize queue with depth and multiplication factor + queue = [(arr, 1, 1)] + + product_sum = 0 + + while queue: + queue_front_list, depth, multiplication_factor = queue.pop(0) + + for element in queue_front_list: + if isinstance(element, list): + queue.append((element, depth + 1, multiplication_factor * (depth + 1))) + else: + product_sum += element * multiplication_factor + + return product_sum + + +def benchmark() -> None: + """ + Benchmark code comparing different version. + """ + + setup = "from __main__ import product_sum_array, product_sum_iterative" + + print( + timeit("product_sum_array([5, 2, [-7, 1], 3, [6, [-13, 8], 4]])", setup=setup) + ) + # 1.1448657000437379 + + print( + timeit( + "product_sum_iterative([5, 2, [-7, 1], 3, [6, [-13, 8], 4]])", setup=setup + ) + ) + # 1.6824490998405963 + + if __name__ == "__main__": import doctest doctest.testmod() + benchmark() diff --git a/data_structures/arrays/reverse_array.py b/data_structures/arrays/reverse_array.py new file mode 100644 index 000000000000..8834d5007461 --- /dev/null +++ b/data_structures/arrays/reverse_array.py @@ -0,0 +1,72 @@ +""" +In-place array reversal that also returns the reversed list to the caller. +This algorithm reverses the elements of a list without using extra space. +""" + +from typing import Any + + +def reverse_array(arr: list[Any]) -> list[Any]: + """ + Reverses a list in-place. + + This function takes a list and reverses its elements using a two-pointer + approach. The left pointer starts at the beginning of the list, and the + right pointer starts at the end. The elements at these two pointers are + swapped, and the pointers move towards the center until they meet or cross. + + Args: + arr: The list to be reversed. + + Returns: + The same list, now reversed. This allows for method chaining. + + Doctests: + >>> reverse_array([1, 2, 3, 4, 5]) + [5, 4, 3, 2, 1] + >>> reverse_array(['a', 'b', 'c', 'd']) + ['d', 'c', 'b', 'a'] + >>> reverse_array([10.5, 20.2, 30.8]) + [30.8, 20.2, 10.5] + >>> reverse_array(["apple", "banana", "cherry"]) + ['cherry', 'banana', 'apple'] + >>> reverse_array([1]) + [1] + >>> reverse_array([]) + [] + >>> reverse_array(list(range(5))) + [4, 3, 2, 1, 0] + >>> reverse_array(tuple(range(5))) + Traceback (most recent call last): + ... + TypeError: 'tuple' object does not support item assignment + >>> reverse_array(range(5)) + Traceback (most recent call last): + ... + TypeError: 'range' object does not support item assignment + """ + left = 0 + right = len(arr) - 1 + + while left < right: + # Swap the elements at the left and right pointers + arr[left], arr[right] = arr[right], arr[left] + # Move the pointers towards the center + left += 1 + right -= 1 + return arr + + +if __name__ == "__main__": + # The doctest module runs the tests embedded in the function's docstring. + # To run the tests, execute this script from the command line: + # python -m doctest -v reverse_array.py + import doctest + + doctest.testmod() + + # Example usage: + print("\n--- Example Usage ---") + sample_array = [10, 20, 30, 40, 50, 60] + print(f"{sample_array = }") + print(f"{reverse_array(sample_array) = }") diff --git a/data_structures/arrays/rotate_array.py b/data_structures/arrays/rotate_array.py new file mode 100644 index 000000000000..d5ce4b4078b3 --- /dev/null +++ b/data_structures/arrays/rotate_array.py @@ -0,0 +1,80 @@ +def rotate_array(arr: list[int], steps: int) -> list[int]: + """ + Rotates a list to the right by steps positions. + + Parameters: + arr (List[int]): The list of integers to rotate. + steps (int): Number of positions to rotate. Can be negative for left rotation. + + Returns: + List[int]: Rotated list. + + Examples: + >>> rotate_array([1, 2, 3, 4, 5], 2) + [4, 5, 1, 2, 3] + >>> rotate_array([1, 2, 3, 4, 5], -2) + [3, 4, 5, 1, 2] + >>> rotate_array([1, 2, 3, 4, 5], 7) + [4, 5, 1, 2, 3] + >>> rotate_array([], 3) + [] + """ + + n = len(arr) + if n == 0: + return arr + + steps = steps % n + + if steps < 0: + steps += n + + def reverse(start: int, end: int) -> None: + """ + Reverses a portion of the list in place from index start to end. + + Parameters: + start (int): Starting index of the portion to reverse. + end (int): Ending index of the portion to reverse. + + Returns: + None + + Examples: + >>> example = [1, 2, 3, 4, 5] + >>> def reverse_test(arr, start, end): + ... while start < end: + ... arr[start], arr[end] = arr[end], arr[start] + ... start += 1 + ... end -= 1 + >>> reverse_test(example, 0, 2) + >>> example + [3, 2, 1, 4, 5] + >>> reverse_test(example, 2, 4) + >>> example + [3, 2, 5, 4, 1] + """ + + while start < end: + arr[start], arr[end] = arr[end], arr[start] + start += 1 + end -= 1 + + reverse(0, n - 1) + reverse(0, steps - 1) + reverse(steps, n - 1) + + return arr + + +if __name__ == "__main__": + examples = [ + ([1, 2, 3, 4, 5], 2), + ([1, 2, 3, 4, 5], -2), + ([1, 2, 3, 4, 5], 7), + ([], 3), + ] + + for arr, steps in examples: + rotated = rotate_array(arr.copy(), steps) + print(f"Rotate {arr} by {steps}: {rotated}") diff --git a/data_structures/arrays/set_matrix_zeroes.py b/data_structures/arrays/set_matrix_zeroes.py new file mode 100644 index 000000000000..905d03b2daf5 --- /dev/null +++ b/data_structures/arrays/set_matrix_zeroes.py @@ -0,0 +1,67 @@ +""" +Set Matrix Zeroes Algorithm +--------------------------- +If an element in an m x n matrix is 0, set its entire row and column to 0. + +Explanation: +We use the first row and first column as markers to track which rows and +columns should be zeroed, avoiding extra space usage (O(1) space complexity). + +References: +https://leetcode.com/problems/set-matrix-zeroes/ + +Doctest: +>>> matrix = [ +... [1, 1, 1], +... [1, 0, 1], +... [1, 1, 1] +... ] +>>> set_matrix_zeroes(matrix) +>>> matrix +[[1, 0, 1], [0, 0, 0], [1, 0, 1]] +>>> matrix = [[0, 1, 2, 0], [3, 4, 5, 2], [1, 3, 1, 5]] +>>> set_matrix_zeroes(matrix) +>>> matrix +[[0, 0, 0, 0], [0, 4, 5, 0], [0, 3, 1, 0]] +""" + + +def set_matrix_zeroes(matrix: list[list[int]]) -> None: + """ + Modify the matrix in-place such that if an element is 0, + its entire row and column are set to 0. + + :param matrix: 2D list of integers + :return: None (modifies matrix in-place) + + Time Complexity: O(m * n) + Space Complexity: O(1) + """ + rows = len(matrix) + cols = len(matrix[0]) + col0 = 1 + + # Step 1: Mark rows and columns that need to be zeroed + for i in range(rows): + if matrix[i][0] == 0: + col0 = 0 + for j in range(1, cols): + if matrix[i][j] == 0: + matrix[i][0] = 0 + matrix[0][j] = 0 + + # Step 2: Update the inner matrix cells + for i in range(1, rows): + for j in range(1, cols): + if matrix[i][0] == 0 or matrix[0][j] == 0: + matrix[i][j] = 0 + + # Step 3: Handle the first row + if matrix[0][0] == 0: + for j in range(cols): + matrix[0][j] = 0 + + # Step 4: Handle the first column + if col0 == 0: + for i in range(rows): + matrix[i][0] = 0 diff --git a/data_structures/arrays/sudoku_solver.py b/data_structures/arrays/sudoku_solver.py index a8157a520c97..6cc05d18adb1 100644 --- a/data_structures/arrays/sudoku_solver.py +++ b/data_structures/arrays/sudoku_solver.py @@ -9,7 +9,22 @@ def cross(items_a, items_b): - "Cross product of elements in A and elements in B." + """ + Cross product of elements in A and elements in B. + + >>> cross('AB', '12') + ['A1', 'A2', 'B1', 'B2'] + >>> cross('ABC', '123') + ['A1', 'A2', 'A3', 'B1', 'B2', 'B3', 'C1', 'C2', 'C3'] + >>> cross('ABC', '1234') + ['A1', 'A2', 'A3', 'A4', 'B1', 'B2', 'B3', 'B4', 'C1', 'C2', 'C3', 'C4'] + >>> cross('', '12') + [] + >>> cross('A', '') + [] + >>> cross('', '') + [] + """ return [a + b for a in items_a for b in items_b] @@ -23,11 +38,11 @@ def cross(items_a, items_b): + [cross(rs, cs) for rs in ("ABC", "DEF", "GHI") for cs in ("123", "456", "789")] ) units = {s: [u for u in unitlist if s in u] for s in squares} -peers = {s: set(sum(units[s], [])) - {s} for s in squares} # noqa: RUF017 +peers = {s: {*u for u in units[s]} - {s} for s in squares} -def test(): - "A set of unit tests." +def test() -> None: + """A set of unit tests.""" assert len(squares) == 81 assert len(unitlist) == 27 assert all(len(units[s]) == 3 for s in squares) @@ -47,10 +62,12 @@ def test(): def parse_grid(grid): - """Convert grid to a dict of possible values, {square: digits}, or - return False if a contradiction is detected.""" + """ + Convert grid to a dict of possible values, {square: digits}, or + return False if a contradiction is detected. + """ ## To start, every square can be any digit; then assign values from the grid. - values = {s: digits for s in squares} + values = dict.fromkeys(squares, digits) for s, d in grid_values(grid).items(): if d in digits and not assign(values, s, d): return False ## (Fail if we can't assign d to square s.) @@ -58,15 +75,19 @@ def parse_grid(grid): def grid_values(grid): - "Convert grid into a dict of {square: char} with '0' or '.' for empties." + """ + Convert grid into a dict of {square: char} with '0' or '.' for empties. + """ chars = [c for c in grid if c in digits or c in "0."] assert len(chars) == 81 return dict(zip(squares, chars)) def assign(values, s, d): - """Eliminate all the other values (except d) from values[s] and propagate. - Return values, except return False if a contradiction is detected.""" + """ + Eliminate all the other values (except d) from values[s] and propagate. + Return values, except return False if a contradiction is detected. + """ other_values = values[s].replace(d, "") if all(eliminate(values, s, d2) for d2 in other_values): return values @@ -75,8 +96,10 @@ def assign(values, s, d): def eliminate(values, s, d): - """Eliminate d from values[s]; propagate when values or places <= 2. - Return values, except return False if a contradiction is detected.""" + """ + Eliminate d from values[s]; propagate when values or places <= 2. + Return values, except return False if a contradiction is detected. + """ if d not in values[s]: return values ## Already eliminated values[s] = values[s].replace(d, "") @@ -98,8 +121,10 @@ def eliminate(values, s, d): return values -def display(values): - "Display these values as a 2-D grid." +def display(values) -> None: + """ + Display these values as a 2-D grid. + """ width = 1 + max(len(values[s]) for s in squares) line = "+".join(["-" * (width * 3)] * 3) for r in rows: @@ -114,11 +139,14 @@ def display(values): def solve(grid): + """ + Solve the grid. + """ return search(parse_grid(grid)) def some(seq): - "Return some element of seq that is true." + """Return some element of seq that is true.""" for e in seq: if e: return e @@ -126,20 +154,24 @@ def some(seq): def search(values): - "Using depth-first search and propagation, try all possible values." + """ + Using depth-first search and propagation, try all possible values. + """ if values is False: return False ## Failed earlier if all(len(values[s]) == 1 for s in squares): return values ## Solved! ## Chose the unfilled square s with the fewest possibilities - n, s = min((len(values[s]), s) for s in squares if len(values[s]) > 1) + _n, s = min((len(values[s]), s) for s in squares if len(values[s]) > 1) return some(search(assign(values.copy(), s, d)) for d in values[s]) -def solve_all(grids, name="", showif=0.0): - """Attempt to solve a sequence of grids. Report results. +def solve_all(grids, name="", showif=0.0) -> None: + """ + Attempt to solve a sequence of grids. Report results. When showif is a number of seconds, display puzzles that take longer. - When showif is None, don't display any puzzles.""" + When showif is None, don't display any puzzles. + """ def time_solve(grid): start = time.monotonic() @@ -156,13 +188,15 @@ def time_solve(grid): times, results = zip(*[time_solve(grid) for grid in grids]) if (n := len(grids)) > 1: print( - "Solved %d of %d %s puzzles (avg %.2f secs (%d Hz), max %.2f secs)." + "Solved %d of %d %s puzzles (avg %.2f secs (%d Hz), max %.2f secs)." # noqa: UP031 % (sum(results), n, name, sum(times) / n, n / sum(times), max(times)) ) def solved(values): - "A puzzle is solved if each unit is a permutation of the digits 1 to 9." + """ + A puzzle is solved if each unit is a permutation of the digits 1 to 9. + """ def unitsolved(unit): return {values[s] for s in unit} == set(digits) @@ -172,14 +206,17 @@ def unitsolved(unit): def from_file(filename, sep="\n"): "Parse a file into a list of strings, separated by sep." - return open(filename).read().strip().split(sep) # noqa: SIM115 + with open(filename) as file: + return file.read().strip().split(sep) def random_puzzle(assignments=17): - """Make a random puzzle with N or more assignments. Restart on contradictions. + """ + Make a random puzzle with N or more assignments. Restart on contradictions. Note the resulting puzzle is not guaranteed to be solvable, but empirically - about 99.8% of them are solvable. Some have multiple solutions.""" - values = {s: digits for s in squares} + about 99.8% of them are solvable. Some have multiple solutions. + """ + values = dict.fromkeys(squares, digits) for s in shuffled(squares): if not assign(values, s, random.choice(values[s])): break @@ -190,7 +227,9 @@ def random_puzzle(assignments=17): def shuffled(seq): - "Return a randomly shuffled copy of the input sequence." + """ + Return a randomly shuffled copy of the input sequence. + """ seq = list(seq) random.shuffle(seq) return seq diff --git a/data_structures/binary_tree/README.md b/data_structures/binary_tree/README.md index ebe727b6589d..07116fa5b038 100644 --- a/data_structures/binary_tree/README.md +++ b/data_structures/binary_tree/README.md @@ -36,7 +36,8 @@ Algorithm Pre-order Conclusion: This problem involves the classic recursive data structure (i.e. a binary tree), and the algorithm above demonstrates how a simplified solution can be reached by using a stack. -If you look at the bigger picture, you'll find that the process of traversal is as followed. `Visit the left subtrees respectively from top to bottom, and visit the right subtrees respectively from bottom to top`. If we are to implement it from this perspective, things will be somewhat different. For the `top to bottom` part we can simply use recursion, and for the `bottom to top` part we can turn to stack. +If you look at the bigger picture, you'll find that the process of traversal is as followed. `Visit the left subtrees respectively from top to bottom, and visit the right subtrees respectively from bottom to top`. +If we are to implement it from this perspective, things will be somewhat different. For the `top to bottom` part we can simply use recursion, and for the `bottom to top` part we can turn to stack. ## In-order Traversal @@ -50,7 +51,7 @@ Algorithm In-order 2. If there is a left child node, push it into the stack. Repeat this process until a leaf node reached. - > At this point the root node and all the left nodes are in the stack. + > At this point the root node and all the left nodes are in the stack. 3. Start popping nodes from the stack. If a node has a right child node, push the child node into the stack. Repeat step 2. @@ -68,7 +69,8 @@ Record whether the current node has been visited. If 1) it's a leaf node or 2) b As for `1) it's a leaf node`, you can easily tell whether a node is a leaf if both its left and right are `null`. -As for `2) both its left and right subtrees have been traversed`, we only need a variable to record whether a node has been visited or not. In the worst case, we need to record the status for every single node and the space complexity is `O(n)`. But if you come to think about it, as we are using a stack and start printing the result from the leaf nodes, it makes sense that we only record the status for the current node popping from the stack, reducing the space complexity to `O(1)`. +As for `2) both its left and right subtrees have been traversed`, we only need a variable to record whether a node has been visited or not. In the worst case, we need to record the status for every single node and the space complexity is `O(n)`. +But if you come to think about it, as we are using a stack and start printing the result from the leaf nodes, it makes sense that we only record the status for the current node popping from the stack, reducing the space complexity to `O(1)`. ## Level Order Traversal diff --git a/data_structures/binary_tree/avl_tree.py b/data_structures/binary_tree/avl_tree.py index 9fca7237404c..bb15afd331a8 100644 --- a/data_structures/binary_tree/avl_tree.py +++ b/data_structures/binary_tree/avl_tree.py @@ -221,18 +221,23 @@ def del_node(root: MyNode, data: Any) -> MyNode | None: else: root.set_right(del_node(right_child, data)) - if get_height(right_child) - get_height(left_child) == 2: - assert right_child is not None - if get_height(right_child.get_right()) > get_height(right_child.get_left()): - root = left_rotation(root) - else: - root = rl_rotation(root) - elif get_height(right_child) - get_height(left_child) == -2: - assert left_child is not None - if get_height(left_child.get_left()) > get_height(left_child.get_right()): - root = right_rotation(root) - else: - root = lr_rotation(root) + # Re-fetch left_child and right_child references + left_child = root.get_left() + right_child = root.get_right() + + match get_height(right_child) - get_height(left_child): + case 2: + assert right_child is not None + if get_height(right_child.get_right()) > get_height(right_child.get_left()): + root = left_rotation(root) + else: + root = rl_rotation(root) + case -2: + assert left_child is not None + if get_height(left_child.get_left()) > get_height(left_child.get_right()): + root = right_rotation(root) + else: + root = lr_rotation(root) height = my_max(get_height(root.get_right()), get_height(root.get_left())) + 1 root.set_height(height) return root diff --git a/data_structures/binary_tree/binary_search_tree.py b/data_structures/binary_tree/binary_search_tree.py index 3f214d0113a4..16b7b6b1ede2 100644 --- a/data_structures/binary_tree/binary_search_tree.py +++ b/data_structures/binary_tree/binary_search_tree.py @@ -183,8 +183,7 @@ def __insert(self, value) -> None: if parent_node.left is None: parent_node.left = new_node # We insert the new node in a leaf break - else: - parent_node = parent_node.left + parent_node = parent_node.left elif parent_node.right is None: parent_node.right = new_node break @@ -224,12 +223,11 @@ def search(self, value) -> Node | None: if self.empty(): raise IndexError("Warning: Tree is empty! please use another.") - else: - node = self.root - # use lazy evaluation here to avoid NoneType Attribute error - while node is not None and node.value is not value: - node = node.left if value < node.value else node.right - return node + node = self.root + # use lazy evaluation here to avoid NoneType Attribute error + while node is not None and node.value is not value: + node = node.left if value < node.value else node.right + return node def get_max(self, node: Node | None = None) -> Node | None: """ diff --git a/data_structures/binary_tree/binary_search_tree_recursive.py b/data_structures/binary_tree/binary_search_tree_recursive.py index d94ac5253360..0bafcc8f4ea0 100644 --- a/data_structures/binary_tree/binary_search_tree_recursive.py +++ b/data_structures/binary_tree/binary_search_tree_recursive.py @@ -105,7 +105,7 @@ def _search(self, node: Node | None, label: int) -> Node: if node is None: msg = f"Node with label {label} does not exist" raise ValueError(msg) - elif label < node.label: + if label < node.label: node = self._search(node.left, label) elif label > node.label: node = self._search(node.right, label) diff --git a/data_structures/binary_tree/binary_tree_maximum_path_sum.py b/data_structures/binary_tree/binary_tree_maximum_path_sum.py new file mode 100644 index 000000000000..cc8c7a3c2e55 --- /dev/null +++ b/data_structures/binary_tree/binary_tree_maximum_path_sum.py @@ -0,0 +1,116 @@ +from __future__ import annotations + +from dataclasses import dataclass + + +# Leetcode Reference : https://leetcode.com/problems/binary-tree-maximum-path-sum/ +@dataclass +class TreeNode: + val: int + left: TreeNode | None = None + right: TreeNode | None = None + + +class GetMaxPathSum: + r""" + + GetMaxPathSum takes root node of a tree as initial argument. + Upon calling max_path_sum(), it returns maximum path + sum from the tree. + + # Test + + The below tree looks like this + 10 + / \ + 5 -3 + / \ \ + 3 2 11 + / \ \ + 3 -2 1 + + Result will be calculated like : 3 -> 3 -> 5 -> 10 -> -3 -> 11 + As it is the maximum path possible. + + + >>> root = TreeNode(10) + >>> root.left = TreeNode(5) + >>> root.right = TreeNode(-3) + >>> root.left.left = TreeNode(3) + >>> root.left.right = TreeNode(2) + >>> root.right.right = TreeNode(11) + >>> root.left.left.left = TreeNode(3) + >>> root.left.left.right = TreeNode(-2) + >>> root.left.right.right = TreeNode(1) + + >>> GetMaxPathSum(root).max_path_sum() + 29 + """ + + def __init__(self, root: TreeNode) -> None: + self.sum = -9999999999 + self.root = root + + def traverse(self, root: TreeNode | None) -> int: + """ + Returns maximum path sum by recursively taking max_path_sum from left + and max_path_sum from right if current Node has a left or right Node. + + :param root -> tree root: + :return int: + """ + + if root is None: + return 0 + + right_sum = max(self.traverse(root.right), 0) + left_sum = max(self.traverse(root.left), 0) + + val = root.val + right_sum + left_sum + self.sum = max(val, self.sum) + + return root.val + max(right_sum, left_sum) + + def max_path_sum(self) -> int: + """ + Driver method to get max_path_sum by calling traverse method. + :return max_path_sum: + """ + self.traverse(self.root) + return self.sum + + +def construct_tree() -> TreeNode: + r""" + The below tree + -10 + / \ + 9 20 + / \ + 15 7 + + >>> root = TreeNode(-10) + >>> root.left = TreeNode(9) + >>> root.right = TreeNode(20) + >>> root.right.left = TreeNode(15) + >>> root.right.right = TreeNode(7) + + >>> GetMaxPathSum(construct_tree()).max_path_sum() + 42 + """ + + root = TreeNode(-10) + root.left = TreeNode(9) + root.right = TreeNode(20) + root.right.left = TreeNode(15) + root.right.right = TreeNode(7) + return root + + +if __name__ == "__main__": + import doctest + + doctest.testmod() + + tree = GetMaxPathSum(construct_tree()) + print(f"{tree.max_path_sum() = }") diff --git a/data_structures/binary_tree/binary_tree_mirror.py b/data_structures/binary_tree/binary_tree_mirror.py index b8548f4ec515..47cb7fc3917a 100644 --- a/data_structures/binary_tree/binary_tree_mirror.py +++ b/data_structures/binary_tree/binary_tree_mirror.py @@ -4,7 +4,7 @@ """ -def binary_tree_mirror_dict(binary_tree_mirror_dictionary: dict, root: int): +def binary_tree_mirror_dict(binary_tree_mirror_dictionary: dict, root: int) -> None: if not root or root not in binary_tree_mirror_dictionary: return left_child, right_child = binary_tree_mirror_dictionary[root][:2] diff --git a/data_structures/binary_tree/binary_tree_path_sum.py b/data_structures/binary_tree/binary_tree_path_sum.py index a3fe9ca7a7e2..8477690c777a 100644 --- a/data_structures/binary_tree/binary_tree_path_sum.py +++ b/data_structures/binary_tree/binary_tree_path_sum.py @@ -50,6 +50,26 @@ class BinaryTreePathSum: >>> tree.right.right = Node(10) >>> BinaryTreePathSum().path_sum(tree, 8) 2 + >>> BinaryTreePathSum().path_sum(None, 0) + 0 + >>> BinaryTreePathSum().path_sum(tree, 0) + 0 + + The second tree looks like this + 0 + / \ + 5 5 + + >>> tree2 = Node(0) + >>> tree2.left = Node(5) + >>> tree2.right = Node(5) + + >>> BinaryTreePathSum().path_sum(tree2, 5) + 4 + >>> BinaryTreePathSum().path_sum(tree2, -1) + 0 + >>> BinaryTreePathSum().path_sum(tree2, 0) + 1 """ target: int diff --git a/data_structures/binary_tree/binary_tree_traversals.py b/data_structures/binary_tree/binary_tree_traversals.py index 49c208335b2c..5ba149d0cbc6 100644 --- a/data_structures/binary_tree/binary_tree_traversals.py +++ b/data_structures/binary_tree/binary_tree_traversals.py @@ -30,7 +30,7 @@ def make_tree() -> Node | None: return tree -def preorder(root: Node | None) -> Generator[int, None, None]: +def preorder(root: Node | None) -> Generator[int]: """ Pre-order traversal visits root node, left subtree, right subtree. >>> list(preorder(make_tree())) @@ -43,7 +43,7 @@ def preorder(root: Node | None) -> Generator[int, None, None]: yield from preorder(root.right) -def postorder(root: Node | None) -> Generator[int, None, None]: +def postorder(root: Node | None) -> Generator[int]: """ Post-order traversal visits left subtree, right subtree, root node. >>> list(postorder(make_tree())) @@ -56,7 +56,7 @@ def postorder(root: Node | None) -> Generator[int, None, None]: yield root.data -def inorder(root: Node | None) -> Generator[int, None, None]: +def inorder(root: Node | None) -> Generator[int]: """ In-order traversal visits left subtree, root node, right subtree. >>> list(inorder(make_tree())) @@ -69,7 +69,7 @@ def inorder(root: Node | None) -> Generator[int, None, None]: yield from inorder(root.right) -def reverse_inorder(root: Node | None) -> Generator[int, None, None]: +def reverse_inorder(root: Node | None) -> Generator[int]: """ Reverse in-order traversal visits right subtree, root node, left subtree. >>> list(reverse_inorder(make_tree())) @@ -93,7 +93,7 @@ def height(root: Node | None) -> int: return (max(height(root.left), height(root.right)) + 1) if root else 0 -def level_order(root: Node | None) -> Generator[int, None, None]: +def level_order(root: Node | None) -> Generator[int]: """ Returns a list of nodes value from a whole binary tree in Level Order Traverse. Level Order traverse: Visit nodes of the tree level-by-level. @@ -116,9 +116,7 @@ def level_order(root: Node | None) -> Generator[int, None, None]: process_queue.append(node.right) -def get_nodes_from_left_to_right( - root: Node | None, level: int -) -> Generator[int, None, None]: +def get_nodes_from_left_to_right(root: Node | None, level: int) -> Generator[int]: """ Returns a list of nodes value from a particular level: Left to right direction of the binary tree. @@ -128,7 +126,7 @@ def get_nodes_from_left_to_right( [2, 3] """ - def populate_output(root: Node | None, level: int) -> Generator[int, None, None]: + def populate_output(root: Node | None, level: int) -> Generator[int]: if not root: return if level == 1: @@ -140,9 +138,7 @@ def populate_output(root: Node | None, level: int) -> Generator[int, None, None] yield from populate_output(root, level) -def get_nodes_from_right_to_left( - root: Node | None, level: int -) -> Generator[int, None, None]: +def get_nodes_from_right_to_left(root: Node | None, level: int) -> Generator[int]: """ Returns a list of nodes value from a particular level: Right to left direction of the binary tree. @@ -152,7 +148,7 @@ def get_nodes_from_right_to_left( [3, 2] """ - def populate_output(root: Node | None, level: int) -> Generator[int, None, None]: + def populate_output(root: Node | None, level: int) -> Generator[int]: if not root: return if level == 1: @@ -164,7 +160,7 @@ def populate_output(root: Node | None, level: int) -> Generator[int, None, None] yield from populate_output(root, level) -def zigzag(root: Node | None) -> Generator[int, None, None]: +def zigzag(root: Node | None) -> Generator[int]: """ ZigZag traverse: Returns a list of nodes value from left to right and right to left, alternatively. diff --git a/data_structures/binary_tree/inorder_tree_traversal_2022.py b/data_structures/binary_tree/inorder_tree_traversal_2022.py index 1357527d2953..a4846a5c29a5 100644 --- a/data_structures/binary_tree/inorder_tree_traversal_2022.py +++ b/data_structures/binary_tree/inorder_tree_traversal_2022.py @@ -43,7 +43,7 @@ def insert(node: BinaryTreeNode | None, new_value: int) -> BinaryTreeNode | None return node -def inorder(node: None | BinaryTreeNode) -> list[int]: # if node is None,return +def inorder(node: BinaryTreeNode | None) -> list[int]: # if node is None,return """ >>> inorder(make_tree()) [6, 10, 14, 15, 20, 25, 60] diff --git a/data_structures/binary_tree/lowest_common_ancestor.py b/data_structures/binary_tree/lowest_common_ancestor.py index 651037703b95..ea0e31256903 100644 --- a/data_structures/binary_tree/lowest_common_ancestor.py +++ b/data_structures/binary_tree/lowest_common_ancestor.py @@ -15,6 +15,8 @@ def swap(a: int, b: int) -> tuple[int, int]: (4, 3) >>> swap(67, 12) (12, 67) + >>> swap(3,-4) + (-4, 3) """ a ^= b b ^= a @@ -25,6 +27,23 @@ def swap(a: int, b: int) -> tuple[int, int]: def create_sparse(max_node: int, parent: list[list[int]]) -> list[list[int]]: """ creating sparse table which saves each nodes 2^i-th parent + >>> max_node = 6 + >>> parent = [[0, 0, 1, 1, 2, 2, 3]] + [[0] * 7 for _ in range(19)] + >>> parent = create_sparse(max_node=max_node, parent=parent) + >>> parent[0] + [0, 0, 1, 1, 2, 2, 3] + >>> parent[1] + [0, 0, 0, 0, 1, 1, 1] + >>> parent[2] + [0, 0, 0, 0, 0, 0, 0] + + >>> max_node = 1 + >>> parent = [[0, 0]] + [[0] * 2 for _ in range(19)] + >>> parent = create_sparse(max_node=max_node, parent=parent) + >>> parent[0] + [0, 0] + >>> parent[1] + [0, 0] """ j = 1 while (1 << j) < max_node: @@ -38,6 +57,21 @@ def create_sparse(max_node: int, parent: list[list[int]]) -> list[list[int]]: def lowest_common_ancestor( u: int, v: int, level: list[int], parent: list[list[int]] ) -> int: + """ + Return the lowest common ancestor between u and v + + >>> level = [-1, 0, 1, 1, 2, 2, 2] + >>> parent = [[0, 0, 1, 1, 2, 2, 3],[0, 0, 0, 0, 1, 1, 1]] + \ + [[0] * 7 for _ in range(17)] + >>> lowest_common_ancestor(u=4, v=5, level=level, parent=parent) + 2 + >>> lowest_common_ancestor(u=4, v=6, level=level, parent=parent) + 1 + >>> lowest_common_ancestor(u=2, v=3, level=level, parent=parent) + 1 + >>> lowest_common_ancestor(u=6, v=6, level=level, parent=parent) + 6 + """ # u must be deeper in the tree than v if level[u] < level[v]: u, v = swap(u, v) @@ -68,6 +102,26 @@ def breadth_first_search( sets every nodes direct parent parent of root node is set to 0 calculates depth of each node from root node + >>> level = [-1] * 7 + >>> parent = [[0] * 7 for _ in range(20)] + >>> graph = {1: [2, 3], 2: [4, 5], 3: [6], 4: [], 5: [], 6: []} + >>> level, parent = breadth_first_search( + ... level=level, parent=parent, max_node=6, graph=graph, root=1) + >>> level + [-1, 0, 1, 1, 2, 2, 2] + >>> parent[0] + [0, 0, 1, 1, 2, 2, 3] + + + >>> level = [-1] * 2 + >>> parent = [[0] * 2 for _ in range(20)] + >>> graph = {1: []} + >>> level, parent = breadth_first_search( + ... level=level, parent=parent, max_node=1, graph=graph, root=1) + >>> level + [-1, 0] + >>> parent[0] + [0, 0] """ level[root] = 0 q: Queue[int] = Queue(maxsize=max_node) diff --git a/data_structures/binary_tree/maximum_fenwick_tree.py b/data_structures/binary_tree/maximum_fenwick_tree.py index 84967a70cc73..fd6351e288dd 100644 --- a/data_structures/binary_tree/maximum_fenwick_tree.py +++ b/data_structures/binary_tree/maximum_fenwick_tree.py @@ -34,6 +34,26 @@ class MaxFenwickTree: >>> ft.update(0, 1000) >>> ft.query(0, 1) 1000 + + Updating a smaller sibling preserves the maximum, including after decreases. + >>> ft = MaxFenwickTree(8) + >>> ft.update(4, 20) + >>> ft.update(5, 1) + >>> ft.query(0, 6) + 20 + >>> ft.update(4, 0) + >>> ft.query(0, 6) + 1 + >>> ft.update(5, 0) + >>> ft.query(0, 6) + 0 + + Updating a child must also preserve the ancestor's own array value. + >>> ft = MaxFenwickTree(8) + >>> ft.update(5, 100) + >>> ft.update(4, 0) + >>> ft.query(0, 6) + 100 """ def __init__(self, size: int) -> None: @@ -75,13 +95,32 @@ def update(self, index: int, value: int) -> None: Returns: None """ + old_value = self.arr[index] + if value == old_value: + return self.arr[index] = value while index < self.size: - current_left_border = self.get_prev(index) + 1 - if current_left_border == index: + old_maximum = self.tree[index] + if value > old_maximum: self.tree[index] = value + elif old_value == old_maximum: + current_left_border = self.get_prev(index) + 1 + maximum = self.arr[index] + if current_left_border != index: + maximum = max(0, maximum) + child = index - 1 + # These disjoint child buckets cover the rest of this bucket. + while child >= current_left_border: + maximum = max(maximum, self.tree[child]) + if maximum == old_maximum: + break + child = self.get_prev(child) + self.tree[index] = maximum + if maximum == old_maximum: + break else: - self.tree[index] = max(value, current_left_border, index) + # An unchanged bucket maximum leaves all its ancestors unchanged. + break index = self.get_next(index) def query(self, left: int, right: int) -> int: @@ -110,5 +149,41 @@ def query(self, left: int, right: int) -> int: if __name__ == "__main__": import doctest + import sys + from timeit import repeat doctest.testmod() + + # Run with --benchmark on each revision to compare the same 2,000-item workload. + if "--benchmark" in sys.argv: + size = 2000 + values = [(index * 97) % size for index in range(size)] + updates = [(index, (index * 37) % size) for index in range(size)] + updates += [(index, values[index]) for index in reversed(range(size))] + queries = [(left, size) for left in range(size)] + + # Build correct query buckets outside the timer, even on the buggy revision. + query_setup = """ +tree = MaxFenwickTree(size) +tree.arr = values[:] +tree.tree = [ + max(values[tree.get_prev(index) + 1 : index + 1]) + for index in range(size) +] +""" + for operation, statement, setup in ( + ( + "4000 updates", + "for index, value in updates: tree.update(index, value)", + "tree = MaxFenwickTree(size)", + ), + ( + "2000 queries", + "for left, right in queries: tree.query(left, right)", + query_setup, + ), + ): + timings = repeat( + statement, setup=setup, repeat=5, number=1, globals=globals() + ) + print(f"{size} items, {operation}: {min(timings):.6f} seconds (best of 5)") diff --git a/data_structures/binary_tree/maximum_sum_bst.py b/data_structures/binary_tree/maximum_sum_bst.py new file mode 100644 index 000000000000..7dadc7b95920 --- /dev/null +++ b/data_structures/binary_tree/maximum_sum_bst.py @@ -0,0 +1,78 @@ +from __future__ import annotations + +import sys +from dataclasses import dataclass + +INT_MIN = -sys.maxsize + 1 +INT_MAX = sys.maxsize - 1 + + +@dataclass +class TreeNode: + val: int = 0 + left: TreeNode | None = None + right: TreeNode | None = None + + +def max_sum_bst(root: TreeNode | None) -> int: + """ + The solution traverses a binary tree to find the maximum sum of + keys in any subtree that is a Binary Search Tree (BST). It uses + recursion to validate BST properties and calculates sums, returning + the highest sum found among all valid BST subtrees. + + >>> t1 = TreeNode(4) + >>> t1.left = TreeNode(3) + >>> t1.left.left = TreeNode(1) + >>> t1.left.right = TreeNode(2) + >>> print(max_sum_bst(t1)) + 2 + >>> t2 = TreeNode(-4) + >>> t2.left = TreeNode(-2) + >>> t2.right = TreeNode(-5) + >>> print(max_sum_bst(t2)) + 0 + >>> t3 = TreeNode(1) + >>> t3.left = TreeNode(4) + >>> t3.left.left = TreeNode(2) + >>> t3.left.right = TreeNode(4) + >>> t3.right = TreeNode(3) + >>> t3.right.left = TreeNode(2) + >>> t3.right.right = TreeNode(5) + >>> t3.right.right.left = TreeNode(4) + >>> t3.right.right.right = TreeNode(6) + >>> print(max_sum_bst(t3)) + 20 + """ + ans: int = 0 + + def solver(node: TreeNode | None) -> tuple[bool, int, int, int]: + """ + Returns the maximum sum by making recursive calls + >>> t1 = TreeNode(1) + >>> print(solver(t1)) + 1 + """ + nonlocal ans + + if not node: + return True, INT_MAX, INT_MIN, 0 # Valid BST, min, max, sum + + is_left_valid, min_left, max_left, sum_left = solver(node.left) + is_right_valid, min_right, max_right, sum_right = solver(node.right) + + if is_left_valid and is_right_valid and max_left < node.val < min_right: + total_sum = sum_left + sum_right + node.val + ans = max(ans, total_sum) + return True, min(min_left, node.val), max(max_right, node.val), total_sum + + return False, -1, -1, -1 # Not a valid BST + + solver(root) + return ans + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/data_structures/binary_tree/mirror_binary_tree.py b/data_structures/binary_tree/mirror_binary_tree.py index 62e2f08dd4e0..f6611d66d676 100644 --- a/data_structures/binary_tree/mirror_binary_tree.py +++ b/data_structures/binary_tree/mirror_binary_tree.py @@ -56,6 +56,8 @@ def mirror(self) -> Node: def make_tree_seven() -> Node: r""" Return a binary tree with 7 nodes that looks like this: + :: + 1 / \ 2 3 @@ -81,13 +83,15 @@ def make_tree_seven() -> Node: def make_tree_nine() -> Node: r""" Return a binary tree with 9 nodes that looks like this: - 1 - / \ - 2 3 - / \ \ - 4 5 6 - / \ \ - 7 8 9 + :: + + 1 + / \ + 2 3 + / \ \ + 4 5 6 + / \ \ + 7 8 9 >>> tree_nine = make_tree_nine() >>> len(tree_nine) @@ -117,23 +121,25 @@ def main() -> None: >>> tuple(tree.mirror()) (6, 3, 1, 9, 5, 2, 8, 4, 7) - nine_tree: - 1 - / \ - 2 3 - / \ \ - 4 5 6 - / \ \ - 7 8 9 - - The mirrored tree looks like this: + nine_tree:: + + 1 + / \ + 2 3 + / \ \ + 4 5 6 + / \ \ + 7 8 9 + + The mirrored tree looks like this:: + 1 - / \ - 3 2 - / / \ - 6 5 4 - / / \ - 9 8 7 + / \ + 3 2 + / / \ + 6 5 4 + / / \ + 9 8 7 """ trees = {"zero": Node(0), "seven": make_tree_seven(), "nine": make_tree_nine()} for name, tree in trees.items(): diff --git a/data_structures/binary_tree/non_recursive_segment_tree.py b/data_structures/binary_tree/non_recursive_segment_tree.py index ca0d5c111c4f..d2f36547ca69 100644 --- a/data_structures/binary_tree/non_recursive_segment_tree.py +++ b/data_structures/binary_tree/non_recursive_segment_tree.py @@ -39,12 +39,12 @@ from __future__ import annotations from collections.abc import Callable -from typing import Any, Generic, TypeVar +from typing import TypeVar, cast T = TypeVar("T") -class SegmentTree(Generic[T]): +class SegmentTree[T]: def __init__(self, arr: list[T], fnc: Callable[[T, T], T]) -> None: """ Segment Tree constructor, it works just with commutative combiner. @@ -57,10 +57,9 @@ def __init__(self, arr: list[T], fnc: Callable[[T, T], T]) -> None: ... lambda a, b: (a[0] + b[0], a[1] + b[1])).query(0, 2) (6, 9) """ - any_type: Any | T = None self.N: int = len(arr) - self.st: list[T] = [any_type for _ in range(self.N)] + arr + self.st: list[T] = [cast(T, None) for _ in range(self.N)] + arr self.fn = fnc self.build() diff --git a/data_structures/binary_tree/persistent_segment_tree.py b/data_structures/binary_tree/persistent_segment_tree.py new file mode 100644 index 000000000000..8d52f4599484 --- /dev/null +++ b/data_structures/binary_tree/persistent_segment_tree.py @@ -0,0 +1,138 @@ +from __future__ import annotations + +from dataclasses import dataclass + + +@dataclass +class Node: + value: int + left: Node | None = None + right: Node | None = None + + +class PersistentSegmentTree: + def __init__(self, arr: list[int]) -> None: + self.n: int = len(arr) + self.roots: list[Node] = [] + self.roots.append(self._build(arr, 0, self.n - 1)) + + def _build(self, arr: list[int], start: int, end: int) -> Node: + """ + Builds a segment tree from the provided array. + + >>> pst = PersistentSegmentTree([1, 2, 3, 4]) + >>> root = pst._build([1, 2, 3, 4], 0, 3) + >>> root.value # Sum of the whole array + 10 + >>> root.left.value # Sum of the left half + 3 + >>> root.right.value # Sum of the right half + 7 + """ + if start == end: + return Node(arr[start]) + mid = (start + end) // 2 + left = self._build(arr, start, mid) + right = self._build(arr, mid + 1, end) + return Node(value=left.value + right.value, left=left, right=right) + + def update(self, version: int, index: int, value: int) -> int: + """ + Updates the value at the given index and returns the new version. + + >>> pst = PersistentSegmentTree([1, 2, 3, 4]) + >>> version_1 = pst.update(0, 1, 5) # Update index 1 to 5 + >>> pst.query(version_1, 0, 3) # Query sum of all elements in new version + 13 + >>> pst.query(0, 0, 3) # Original version remains unchanged + 10 + >>> version_2 = pst.update(version_1, 3, 6) # Update index 3 to 6 in version_1 + >>> pst.query(version_2, 0, 3) # Query sum of all elements in newest version + 15 + """ + new_root = self._update(self.roots[version], 0, self.n - 1, index, value) + self.roots.append(new_root) + return len(self.roots) - 1 + + def _update(self, node: Node, start: int, end: int, index: int, value: int) -> Node: + """ + Update the node for the specified index and value and return the new node. + + >>> pst = PersistentSegmentTree([1, 2, 3, 4]) + >>> old_root = pst.roots[0] + >>> new_root = pst._update(old_root, 0, 3, 1, 5) # Update index 1 to 5 + >>> new_root.value # New sum after update + 13 + >>> old_root.value # Old root remains unchanged + 10 + >>> new_root.left.value # Updated left child + 6 + >>> new_root.right.value # Right child remains the same + 7 + """ + if start == end: + return Node(value) + + mid = (start + end) // 2 + new_node = Node(0) + + if index <= mid: + new_node.left = self._update(node.left, start, mid, index, value) + new_node.right = node.right # Ensure right node is the same as the original + else: + new_node.left = node.left # Ensure left node is the same as the original + new_node.right = self._update(node.right, mid + 1, end, index, value) + + new_node.value = new_node.left.value + ( + new_node.right.value if new_node.right else 0 + ) + + return new_node + + def query(self, version: int, left: int, right: int) -> int: + """ + Queries the sum in the given range for the specified version. + + >>> pst = PersistentSegmentTree([1, 2, 3, 4]) + >>> pst.query(0, 0, 3) # Sum of all elements in original version + 10 + >>> pst.query(0, 1, 2) # Sum of elements at index 1 and 2 in original version + 5 + >>> version_1 = pst.update(0, 1, 5) # Update index 1 to 5 + >>> pst.query(version_1, 0, 3) # Sum of all elements in new version + 13 + >>> pst.query(version_1, 1, 2) # Sum of elements at index 1 and 2 + 8 + """ + return self._query(self.roots[version], 0, self.n - 1, left, right) + + def _query(self, node: Node, start: int, end: int, left: int, right: int) -> int: + """ + Queries the sum of values in the range [left, right] for the given node. + + >>> pst = PersistentSegmentTree([1, 2, 3, 4]) + >>> root = pst.roots[0] + >>> pst._query(root, 0, 3, 1, 2) # Sum of elements at index 1 and 2 + 5 + >>> pst._query(root, 0, 3, 0, 3) # Sum of all elements + 10 + >>> pst._query(root, 0, 3, 2, 3) # Sum of elements at index 2 and 3 + 7 + """ + if node is None or left > end or right < start: + return 0 + if left <= start and right >= end: + return node.value + mid = (start + end) // 2 + return self._query(node.left, start, mid, left, right) + self._query( + node.right, mid + 1, end, left, right + ) + + +# Running the doctests +if __name__ == "__main__": + import doctest + + print("Running doctests...") + result = doctest.testmod() + print(f"Ran {result.attempted} tests, {result.failed} failed.") diff --git a/data_structures/binary_tree/segment_tree.py b/data_structures/binary_tree/segment_tree.py index 084fcf84955d..b802a52157c1 100644 --- a/data_structures/binary_tree/segment_tree.py +++ b/data_structures/binary_tree/segment_tree.py @@ -2,7 +2,7 @@ class SegmentTree: - def __init__(self, a): + def __init__(self, a) -> None: self.A = a self.N = len(self.A) self.st = [0] * ( @@ -11,7 +11,7 @@ def __init__(self, a): if self.N: self.build(1, 0, self.N - 1) - def left(self, idx): + def left(self, idx) -> int: """ Returns the left child index for a given index in a binary tree. @@ -23,7 +23,7 @@ def left(self, idx): """ return idx * 2 - def right(self, idx): + def right(self, idx) -> int: """ Returns the right child index for a given index in a binary tree. @@ -35,7 +35,7 @@ def right(self, idx): """ return idx * 2 + 1 - def build(self, idx, left, right): + def build(self, idx, left, right) -> None: if left == right: self.st[idx] = self.A[left] else: @@ -44,7 +44,7 @@ def build(self, idx, left, right): self.build(self.right(idx), mid + 1, right) self.st[idx] = max(self.st[self.left(idx)], self.st[self.right(idx)]) - def update(self, a, b, val): + def update(self, a, b, val) -> bool: """ Update the values in the segment tree in the range [a,b] with the given value. @@ -56,7 +56,7 @@ def update(self, a, b, val): """ return self.update_recursive(1, 0, self.N - 1, a - 1, b - 1, val) - def update_recursive(self, idx, left, right, a, b, val): + def update_recursive(self, idx, left, right, a, b, val) -> bool: """ update(1, 1, N, a, b, v) for update val v to [a,b] """ @@ -71,7 +71,7 @@ def update_recursive(self, idx, left, right, a, b, val): self.st[idx] = max(self.st[self.left(idx)], self.st[self.right(idx)]) return True - def query(self, a, b): + def query(self, a, b) -> float: """ Query the maximum value in the range [a,b]. @@ -83,7 +83,7 @@ def query(self, a, b): """ return self.query_recursive(1, 0, self.N - 1, a - 1, b - 1) - def query_recursive(self, idx, left, right, a, b): + def query_recursive(self, idx, left, right, a, b) -> float: """ query(1, 1, N, a, b) for query max of [a,b] """ @@ -96,7 +96,7 @@ def query_recursive(self, idx, left, right, a, b): q2 = self.query_recursive(self.right(idx), mid + 1, right, a, b) return max(q1, q2) - def show_data(self): + def show_data(self) -> None: show_list = [] for i in range(1, self.N + 1): show_list += [self.query(i, i)] diff --git a/data_structures/binary_tree/segment_tree_other.py b/data_structures/binary_tree/segment_tree_other.py index 95f21ddd4777..36f295382439 100644 --- a/data_structures/binary_tree/segment_tree_other.py +++ b/data_structures/binary_tree/segment_tree_other.py @@ -9,7 +9,7 @@ class SegmentTreeNode: - def __init__(self, start, end, val, left=None, right=None): + def __init__(self, start, end, val, left=None, right=None) -> None: self.start = start self.end = end self.val = val @@ -17,7 +17,7 @@ def __init__(self, start, end, val, left=None, right=None): self.left = left self.right = right - def __repr__(self): + def __repr__(self) -> str: return f"SegmentTreeNode(start={self.start}, end={self.end}, val={self.val})" @@ -127,13 +127,13 @@ class SegmentTree: >>> """ - def __init__(self, collection: Sequence, function): + def __init__(self, collection: Sequence, function) -> None: self.collection = collection self.fn = function if self.collection: self.root = self._build_tree(0, len(collection) - 1) - def update(self, i, val): + def update(self, i, val) -> None: """ Update an element in log(N) time :param i: position to be update @@ -173,7 +173,7 @@ def _build_tree(self, start, end): right = self._build_tree(mid + 1, end) return SegmentTreeNode(start, end, self.fn(left.val, right.val), left, right) - def _update_tree(self, node, i, val): + def _update_tree(self, node, i, val) -> None: if node.start == i and node.end == i: node.val = val return diff --git a/data_structures/binary_tree/serialize_deserialize_binary_tree.py b/data_structures/binary_tree/serialize_deserialize_binary_tree.py index 7d3e0c61f96d..bdbc3b46f584 100644 --- a/data_structures/binary_tree/serialize_deserialize_binary_tree.py +++ b/data_structures/binary_tree/serialize_deserialize_binary_tree.py @@ -19,7 +19,7 @@ class TreeNode: left: TreeNode | None = None right: TreeNode | None = None - def __post_init__(self): + def __post_init__(self) -> None: if not isinstance(self.value, int): raise TypeError("Value must be an integer.") diff --git a/data_structures/binary_tree/splay_tree.py b/data_structures/binary_tree/splay_tree.py new file mode 100644 index 000000000000..c200bad761a5 --- /dev/null +++ b/data_structures/binary_tree/splay_tree.py @@ -0,0 +1,237 @@ +""" +Splay Tree - a self-adjusting binary search tree. + +A splay tree is a binary search tree with the additional property that +recently accessed elements are quick to access again. Every access (search, +insert or delete) moves the target node to the root through a sequence of +rotations called "splaying". This gives an amortized time complexity of +O(log n) per operation and makes the tree very efficient when the access +pattern has locality of reference (a small subset of keys is touched often). + +Reference: https://en.wikipedia.org/wiki/Splay_tree +""" + +from __future__ import annotations + +from collections.abc import Iterator +from dataclasses import dataclass, field + + +@dataclass +class Node: + """ + A single node of a splay tree. + + The ``left`` and ``right`` children are excluded from ``repr`` so that a + node prints compactly instead of recursively dumping the whole subtree. + + >>> Node(10) + Node(key=10) + """ + + key: int + left: Node | None = field(default=None, repr=False) + right: Node | None = field(default=None, repr=False) + + +class SplayTree: + """ + A self-adjusting binary search tree. + + >>> tree = SplayTree() + >>> tree.insert(10) + >>> tree.insert(20) + >>> tree.insert(30) + >>> tree.root.key # last inserted key is splayed to the root + 30 + >>> tree.search(10) + True + >>> tree.root.key # the searched key is now the root + 10 + >>> tree.search(99) + False + >>> list(tree) + [10, 20, 30] + """ + + def __init__(self) -> None: + self.root: Node | None = None + + def _rotate_right(self, node: Node) -> Node: + """ + Perform a right rotation around ``node`` and return the new subtree root. + + node left + / \\ / \\ + left c --> a node + / \\ / \\ + a b b c + """ + left = node.left + assert left is not None + node.left = left.right + left.right = node + return left + + def _rotate_left(self, node: Node) -> Node: + """ + Perform a left rotation around ``node`` and return the new subtree root. + + node right + / \\ / \\ + a right --> node c + / \\ / \\ + b c a b + """ + right = node.right + assert right is not None + node.right = right.left + right.left = node + return right + + def _splay(self, root: Node | None, key: int) -> Node | None: + """ + Splay the node with ``key`` (or the last node on the search path if + ``key`` is absent) to the root of the subtree and return the new root. + This uses the classic bottom-up recursive formulation. + """ + if root is None or root.key == key: + return root + + if key < root.key: + if root.left is None: + return root + if key < root.left.key: + # Zig-Zig (left left) + root.left.left = self._splay(root.left.left, key) + root = self._rotate_right(root) + elif key > root.left.key: + # Zig-Zag (left right) + root.left.right = self._splay(root.left.right, key) + if root.left.right is not None: + root.left = self._rotate_left(root.left) + return root if root.left is None else self._rotate_right(root) + else: + if root.right is None: + return root + if key > root.right.key: + # Zig-Zig (right right) + root.right.right = self._splay(root.right.right, key) + root = self._rotate_left(root) + elif key < root.right.key: + # Zig-Zag (right left) + root.right.left = self._splay(root.right.left, key) + if root.right.left is not None: + root.right = self._rotate_right(root.right) + return root if root.right is None else self._rotate_left(root) + + def insert(self, key: int) -> None: + """ + Insert ``key`` into the tree and splay it to the root. + + >>> tree = SplayTree() + >>> for key in (5, 3, 8, 3): # duplicate keys are ignored + ... tree.insert(key) + >>> list(tree) + [3, 5, 8] + >>> tree.root.key # the duplicate access splays 3 back to the root + 3 + """ + if self.root is None: + self.root = Node(key) + return + + self.root = self._splay(self.root, key) + assert self.root is not None + if self.root.key == key: + return # key already present, it is now at the root + + node = Node(key) + if key < self.root.key: + node.right = self.root + node.left = self.root.left + self.root.left = None + else: + node.left = self.root + node.right = self.root.right + self.root.right = None + self.root = node + + def search(self, key: int) -> bool: + """ + Return whether ``key`` is present and splay the last accessed node. + + >>> tree = SplayTree() + >>> tree.search(1) + False + >>> for key in (40, 20, 60): + ... tree.insert(key) + >>> tree.search(20) + True + >>> tree.root.key + 20 + """ + self.root = self._splay(self.root, key) + return self.root is not None and self.root.key == key + + def delete(self, key: int) -> None: + """ + Remove ``key`` from the tree if it is present. + + >>> tree = SplayTree() + >>> for key in (10, 20, 30, 40): + ... tree.insert(key) + >>> tree.delete(20) + >>> list(tree) + [10, 30, 40] + >>> tree.delete(99) # deleting an absent key is a no-op + >>> list(tree) + [10, 30, 40] + >>> for key in (10, 30, 40): + ... tree.delete(key) + >>> list(tree) + [] + """ + if self.root is None: + return + + self.root = self._splay(self.root, key) + assert self.root is not None + if self.root.key != key: + return # key not found + + left, right = self.root.left, self.root.right + if left is None: + self.root = right + else: + # Splay the maximum of the left subtree to its root; it has no + # right child, so the right subtree can be attached there. + left = self._splay(left, key) + assert left is not None + left.right = right + self.root = left + + def __iter__(self) -> Iterator[int]: + """ + Yield the keys of the tree in ascending (in-order) order. + + >>> tree = SplayTree() + >>> for key in (7, 2, 9, 4, 1): + ... tree.insert(key) + >>> list(tree) + [1, 2, 4, 7, 9] + """ + + def in_order(node: Node | None) -> Iterator[int]: + if node is not None: + yield from in_order(node.left) + yield node.key + yield from in_order(node.right) + + yield from in_order(self.root) + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/data_structures/binary_tree/symmetric_tree.py b/data_structures/binary_tree/symmetric_tree.py index 98a766cab988..2bfeac98b2c9 100644 --- a/data_structures/binary_tree/symmetric_tree.py +++ b/data_structures/binary_tree/symmetric_tree.py @@ -13,7 +13,21 @@ @dataclass class Node: """ - A Node has data variable and pointers to Nodes to its left and right. + A Node represents an element of a binary tree, which contains: + + Attributes: + data: The value stored in the node (int). + left: Pointer to the left child node (Node or None). + right: Pointer to the right child node (Node or None). + + Example: + >>> node = Node(1, Node(2), Node(3)) + >>> node.data + 1 + >>> node.left.data + 2 + >>> node.right.data + 3 """ data: int @@ -24,12 +38,25 @@ class Node: def make_symmetric_tree() -> Node: r""" Create a symmetric tree for testing. + The tree looks like this: 1 / \ 2 2 / \ / \ 3 4 4 3 + + Returns: + Node: Root node of a symmetric tree. + + Example: + >>> tree = make_symmetric_tree() + >>> tree.data + 1 + >>> tree.left.data == tree.right.data + True + >>> tree.left.left.data == tree.right.right.data + True """ root = Node(1) root.left = Node(2) @@ -43,13 +70,26 @@ def make_symmetric_tree() -> Node: def make_asymmetric_tree() -> Node: r""" - Create a asymmetric tree for testing. + Create an asymmetric tree for testing. + The tree looks like this: 1 / \ 2 2 / \ / \ 3 4 3 4 + + Returns: + Node: Root node of an asymmetric tree. + + Example: + >>> tree = make_asymmetric_tree() + >>> tree.data + 1 + >>> tree.left.data == tree.right.data + True + >>> tree.left.left.data == tree.right.right.data + False """ root = Node(1) root.left = Node(2) @@ -63,7 +103,15 @@ def make_asymmetric_tree() -> Node: def is_symmetric_tree(tree: Node) -> bool: """ - Test cases for is_symmetric_tree function + Check if a binary tree is symmetric (i.e., a mirror of itself). + + Parameters: + tree: The root node of the binary tree. + + Returns: + bool: True if the tree is symmetric, False otherwise. + + Example: >>> is_symmetric_tree(make_symmetric_tree()) True >>> is_symmetric_tree(make_asymmetric_tree()) @@ -76,8 +124,17 @@ def is_symmetric_tree(tree: Node) -> bool: def is_mirror(left: Node | None, right: Node | None) -> bool: """ + Check if two subtrees are mirror images of each other. + + Parameters: + left: The root node of the left subtree. + right: The root node of the right subtree. + + Returns: + bool: True if the two subtrees are mirrors of each other, False otherwise. + + Example: >>> tree1 = make_symmetric_tree() - >>> tree1.right.right = Node(3) >>> is_mirror(tree1.left, tree1.right) True >>> tree2 = make_asymmetric_tree() @@ -91,7 +148,7 @@ def is_mirror(left: Node | None, right: Node | None) -> bool: # One side is empty while the other is not, which is not symmetric. return False if left.data == right.data: - # The values match, so check the subtree + # The values match, so check the subtrees recursively. return is_mirror(left.left, right.right) and is_mirror(left.right, right.left) return False diff --git a/data_structures/binary_tree/treap.py b/data_structures/binary_tree/treap.py index 3114c6fa1c26..7f105328ccea 100644 --- a/data_structures/binary_tree/treap.py +++ b/data_structures/binary_tree/treap.py @@ -9,7 +9,7 @@ class Node: Treap is a binary tree by value and heap by priority """ - def __init__(self, value: int | None = None): + def __init__(self, value: int | None = None) -> None: self.value = value self.prior = random() self.left: Node | None = None @@ -41,7 +41,7 @@ def split(root: Node | None, value: int) -> tuple[Node | None, Node | None]: """ if root is None or root.value is None: # None tree is split into 2 Nones return None, None - elif value < root.value: + elif value <= root.value: """ Right tree's root will be current node. Now we split(with the same value) current node's left son @@ -65,7 +65,7 @@ def merge(left: Node | None, right: Node | None) -> Node | None: """ if (not left) or (not right): # If one node is None, return the other return left or right - elif left.prior < right.prior: + elif left.prior > right.prior: """ Left will be root because it has more priority Now we need to merge left's right son and right tree @@ -101,8 +101,8 @@ def erase(root: Node | None, value: int) -> Node | None: Split all nodes with values greater into right. Merge left, right """ - left, right = split(root, value - 1) - _, right = split(right, value) + left, right = split(root, value) + _, right = split(right, value + 1) return merge(left, right) @@ -143,14 +143,15 @@ def interact_treap(root: Node | None, args: str) -> Node | None: Unknown command """ for arg in args.split(): - if arg[0] == "+": - root = insert(root, int(arg[1:])) + match arg[0]: + case "+": + root = insert(root, int(arg[1:])) - elif arg[0] == "-": - root = erase(root, int(arg[1:])) + case "-": + root = erase(root, int(arg[1:])) - else: - print("Unknown command") + case _: + print("Unknown command") return root diff --git a/data_structures/disjoint_set/disjoint_set.py b/data_structures/disjoint_set/disjoint_set.py index edc4736b6132..0a0f0181b27e 100644 --- a/data_structures/disjoint_set/disjoint_set.py +++ b/data_structures/disjoint_set/disjoint_set.py @@ -3,17 +3,28 @@ Reference: https://en.wikipedia.org/wiki/Disjoint-set_data_structure """ +from dataclasses import dataclass + +@dataclass class Node: - def __init__(self, data: int) -> None: - self.data = data - self.rank: int - self.parent: Node + data: int + rank: int = 0 + parent: Node | None = None def make_set(x: Node) -> None: """ Make x as a set. + + >>> node = Node(1) + >>> make_set(node) + >>> node.parent == node + True + >>> node.rank + 0 + >>> node.data + 1 """ # rank is the distance from x to its' parent # root's rank is 0 @@ -26,6 +37,22 @@ def union_set(x: Node, y: Node) -> None: Union of two sets. set with bigger rank should be parent, so that the disjoint set tree will be more flat. + + >>> node1 = Node(1) + >>> node2 = Node(2) + >>> make_set(node1) + >>> make_set(node2) + >>> union_set(node1, node2) + >>> find_set(node1) == find_set(node2) + True + >>> # Test union of already connected nodes + >>> node3 = Node(3) + >>> make_set(node3) + >>> union_set(node1, node3) + >>> find_set(node1) == find_set(node3) + True + >>> find_set(node2) == find_set(node3) + True """ x, y = find_set(x), find_set(y) if x == y: @@ -42,6 +69,24 @@ def union_set(x: Node, y: Node) -> None: def find_set(x: Node) -> Node: """ Return the parent of x + + >>> node = Node(1) + >>> make_set(node) + >>> find_set(node) == node + True + >>> node1 = Node(1) + >>> node2 = Node(2) + >>> make_set(node1) + >>> make_set(node2) + >>> union_set(node1, node2) + >>> find_set(node1) == find_set(node2) + True + >>> # Test path compression + >>> node3 = Node(3) + >>> make_set(node3) + >>> union_set(node1, node3) + >>> find_set(node1) == find_set(node3) + True """ if x != x.parent: x.parent = find_set(x.parent) @@ -51,6 +96,18 @@ def find_set(x: Node) -> Node: def find_python_set(node: Node) -> set: """ Return a Python Standard Library set that contains i. + + >>> node = Node(1) + >>> find_python_set(node) + {0, 1, 2} + >>> node = Node(4) + >>> find_python_set(node) + {3, 4, 5} + >>> node = Node(6) + >>> find_python_set(node) + Traceback (most recent call last): + ... + ValueError: 6 is not in ({0, 1, 2}, {3, 4, 5}) """ sets = ({0, 1, 2}, {3, 4, 5}) for s in sets: @@ -62,6 +119,9 @@ def find_python_set(node: Node) -> set: def test_disjoint_set() -> None: """ + Test the disjoint set operations with a comprehensive example. + Creates two disjoint sets: {0, 1, 2} and {3, 4, 5} + >>> test_disjoint_set() """ vertex = [Node(i) for i in range(6)] diff --git a/data_structures/hashing/double_hash.py b/data_structures/hashing/double_hash.py index 324282cbfd8d..d4b46679ffbb 100644 --- a/data_structures/hashing/double_hash.py +++ b/data_structures/hashing/double_hash.py @@ -21,7 +21,7 @@ class DoubleHash(HashTable): Hash Table example with open addressing and Double Hash """ - def __init__(self, *args, **kwargs): + def __init__(self, *args, **kwargs) -> None: super().__init__(*args, **kwargs) def __hash_function_2(self, value, data): @@ -74,8 +74,7 @@ def _collision_resolution(self, key, data=None): ) if new_key is None: break - else: - i += 1 + i += 1 return new_key diff --git a/data_structures/hashing/hash_map.py b/data_structures/hashing/hash_map.py index 9213d6930f67..0d99e578b73e 100644 --- a/data_structures/hashing/hash_map.py +++ b/data_structures/hashing/hash_map.py @@ -10,14 +10,14 @@ from collections.abc import Iterator, MutableMapping from dataclasses import dataclass -from typing import Generic, TypeVar +from typing import TypeVar KEY = TypeVar("KEY") VAL = TypeVar("VAL") -@dataclass(frozen=True, slots=True) -class _Item(Generic[KEY, VAL]): +@dataclass(slots=True) +class _Item[KEY, VAL]: key: KEY val: VAL @@ -72,16 +72,17 @@ def _try_set(self, ind: int, key: KEY, val: VAL) -> bool: If bucket is empty or key is the same, does insert and return True. - If bucket has another key or deleted placeholder, - that means that we need to check next bucket. + If bucket has another key that means that we need to check next bucket. """ stored = self._buckets[ind] if not stored: + # A falsy item means that bucket was never used (None) + # or was deleted (_deleted). self._buckets[ind] = _Item(key, val) self._len += 1 return True elif stored.key == key: - self._buckets[ind] = _Item(key, val) + stored.val = val return True else: return False @@ -228,6 +229,27 @@ def __delitem__(self, key: KEY) -> None: Traceback (most recent call last): ... KeyError: 4 + + # Test resize down when sparse + ## Setup: resize up + >>> hm = HashMap(initial_block_size=100, capacity_factor=0.75) + >>> len(hm._buckets) + 100 + >>> for i in range(75): + ... hm[i] = i + >>> len(hm._buckets) + 100 + >>> hm[75] = 75 + >>> len(hm._buckets) + 200 + + ## Resize down + >>> del hm[75] + >>> len(hm._buckets) + 200 + >>> del hm[74] + >>> len(hm._buckets) + 100 """ for ind in self._iterate_buckets(key): item = self._buckets[ind] diff --git a/data_structures/hashing/hash_table.py b/data_structures/hashing/hash_table.py index 40fcad9a3dab..cfc1db4feea4 100644 --- a/data_structures/hashing/hash_table.py +++ b/data_structures/hashing/hash_table.py @@ -22,7 +22,7 @@ def __init__( self.__aux_list: list = [] self._keys: dict = {} - def keys(self): + def keys(self) -> dict: """ The keys function returns a dictionary containing the key value pairs. key being the index number in hash table and value being the data value. @@ -48,12 +48,12 @@ def keys(self): """ return self._keys - def balanced_factor(self): + def balanced_factor(self) -> float: return sum(1 for slot in self.values if slot is not None) / ( self.size_table * self.charge_factor ) - def hash_function(self, key): + def hash_function(self, key) -> int: """ Generates hash for the given key value @@ -80,12 +80,12 @@ def hash_function(self, key): """ return key % self.size_table - def _step_by_step(self, step_ord): + def _step_by_step(self, step_ord) -> None: print(f"step {step_ord}") print(list(range(len(self.values)))) print(self.values) - def bulk_insert(self, values): + def bulk_insert(self, values) -> None: """ bulk_insert is used for entering more than one element at a time in the HashTable. @@ -130,7 +130,7 @@ def bulk_insert(self, values): self._step_by_step(i) i += 1 - def _set_value(self, key, data): + def _set_value(self, key, data) -> None: """ _set_value functions allows to update value at a particular hash @@ -236,7 +236,7 @@ def _collision_resolution(self, key, data=None): return new_key - def rehashing(self): + def rehashing(self) -> None: survivor_values = [value for value in self.values if value is not None] self.size_table = next_prime(self.size_table, factor=2) self._keys.clear() @@ -244,7 +244,7 @@ def rehashing(self): for value in survivor_values: self.insert_data(value) - def insert_data(self, data): + def insert_data(self, data) -> None: """ insert_data is used for inserting a single element at a time in the HashTable. diff --git a/data_structures/hashing/hash_table_with_linked_list.py b/data_structures/hashing/hash_table_with_linked_list.py index f404c5251246..4903db73a782 100644 --- a/data_structures/hashing/hash_table_with_linked_list.py +++ b/data_structures/hashing/hash_table_with_linked_list.py @@ -4,15 +4,15 @@ class HashTableWithLinkedList(HashTable): - def __init__(self, *args, **kwargs): + def __init__(self, *args, **kwargs) -> None: super().__init__(*args, **kwargs) - def _set_value(self, key, data): - self.values[key] = deque([]) if self.values[key] is None else self.values[key] + def _set_value(self, key, data) -> None: + self.values[key] = deque() if self.values[key] is None else self.values[key] self.values[key].appendleft(data) self._keys[key] = self.values[key] - def balanced_factor(self): + def balanced_factor(self) -> float: return ( sum(self.charge_factor - len(slot) for slot in self.values) / self.size_table diff --git a/data_structures/hashing/number_theory/prime_numbers.py b/data_structures/hashing/number_theory/prime_numbers.py index 2549a1477b2b..82071b5e9f09 100644 --- a/data_structures/hashing/number_theory/prime_numbers.py +++ b/data_structures/hashing/number_theory/prime_numbers.py @@ -32,9 +32,9 @@ def is_prime(number: int) -> bool: """ # precondition - assert isinstance(number, int) and ( - number >= 0 - ), "'number' must been an int and positive" + assert isinstance(number, int) and (number >= 0), ( + "'number' must been an int and positive" + ) if 1 < number < 4: # 2 and 3 are primes diff --git a/data_structures/hashing/quadratic_probing.py b/data_structures/hashing/quadratic_probing.py index 56d4926eee9b..8d8b4457232a 100644 --- a/data_structures/hashing/quadratic_probing.py +++ b/data_structures/hashing/quadratic_probing.py @@ -8,7 +8,7 @@ class QuadraticProbing(HashTable): Basic Hash Table example with open addressing using Quadratic Probing """ - def __init__(self, *args, **kwargs): + def __init__(self, *args, **kwargs) -> None: super().__init__(*args, **kwargs) def _collision_resolution(self, key, data=None): # noqa: ARG002 diff --git a/data_structures/hashing/tests/test_hash_map.py b/data_structures/hashing/tests/test_hash_map.py index 4292c0178b7b..0ec55595965e 100644 --- a/data_structures/hashing/tests/test_hash_map.py +++ b/data_structures/hashing/tests/test_hash_map.py @@ -74,7 +74,7 @@ def _run_operation(obj, fun, *args): pytest.param(_add_with_resize_down, id="add with resize down"), ], ) -def test_hash_map_is_the_same_as_dict(operations): +def test_hash_map_is_the_same_as_dict(operations) -> None: my = HashMap(initial_block_size=4) py = {} for _, (fun, *args) in enumerate(operations): @@ -87,7 +87,7 @@ def test_hash_map_is_the_same_as_dict(operations): assert set(my.items()) == set(py.items()) -def test_no_new_methods_was_added_to_api(): +def test_no_new_methods_was_added_to_api() -> None: def is_public(name: str) -> bool: return not name.startswith("_") diff --git a/data_structures/heap/binomial_heap.py b/data_structures/heap/binomial_heap.py index 099bd2871023..489355ee7271 100644 --- a/data_structures/heap/binomial_heap.py +++ b/data_structures/heap/binomial_heap.py @@ -12,7 +12,7 @@ class Node: - link to left, right and parent nodes """ - def __init__(self, val): + def __init__(self, val) -> None: self.val = val # Number of nodes in left subtree self.left_tree_size = 0 @@ -73,7 +73,7 @@ class BinomialHeap: 30 Deleting - delete() test - >>> [first_heap.delete_min() for _ in range(20)] + >>> [int(first_heap.delete_min()) for _ in range(20)] [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19] Create a new Heap @@ -118,12 +118,12 @@ class BinomialHeap: values in merged heap; (merge is inplace) >>> results = [] >>> while not first_heap.is_empty(): - ... results.append(first_heap.delete_min()) + ... results.append(int(first_heap.delete_min())) >>> results [17, 20, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 31, 34] """ - def __init__(self, bottom_root=None, min_node=None, heap_size=0): + def __init__(self, bottom_root=None, min_node=None, heap_size=0) -> None: self.size = heap_size self.bottom_root = bottom_root self.min_node = min_node @@ -203,7 +203,7 @@ def merge_heaps(self, other): # Return the merged heap return self - def insert(self, val): + def insert(self, val) -> None: """ insert a value in the heap """ @@ -222,6 +222,7 @@ def insert(self, val): if val < self.min_node.val: self.min_node = new_node # Put new_node as a bottom_root in heap + assert self.bottom_root is not None self.bottom_root.left = new_node new_node.parent = self.bottom_root self.bottom_root = new_node @@ -250,7 +251,7 @@ def peek(self): """ return self.min_node.val - def is_empty(self): + def is_empty(self) -> bool: return self.size == 0 def delete_min(self): @@ -283,6 +284,7 @@ def delete_min(self): # Update bottom root self.bottom_root = self.bottom_root.parent + assert self.bottom_root is not None self.bottom_root.left = None # Update min_node @@ -354,7 +356,7 @@ def delete_min(self): # Merge heaps self.merge_heaps(new_heap) - return min_value + return int(min_value) def pre_order(self): """ @@ -371,7 +373,7 @@ def pre_order(self): self.__traversal(top_root, heap_pre_order) return heap_pre_order - def __traversal(self, curr_node, preorder, level=0): + def __traversal(self, curr_node, preorder, level=0) -> None: """ Pre-order traversal of nodes """ @@ -382,7 +384,7 @@ def __traversal(self, curr_node, preorder, level=0): else: preorder.append(("#", level)) - def __str__(self): + def __str__(self) -> str: """ Overwriting str for a pre-order print of nodes in heap; Performance is poor, so use only for small examples diff --git a/data_structures/heap/heap.py b/data_structures/heap/heap.py index 7b15e69f13ca..bf2c14c40dc9 100644 --- a/data_structures/heap/heap.py +++ b/data_structures/heap/heap.py @@ -2,27 +2,16 @@ from abc import abstractmethod from collections.abc import Iterable -from typing import Generic, Protocol, TypeVar +from typing import Protocol class Comparable(Protocol): @abstractmethod - def __lt__(self: T, other: T) -> bool: + def __gt__(self, other: object, /) -> bool: pass - @abstractmethod - def __gt__(self: T, other: T) -> bool: - pass - - @abstractmethod - def __eq__(self: T, other: object) -> bool: - pass - - -T = TypeVar("T", bound=Comparable) - -class Heap(Generic[T]): +class Heap[T: Comparable]: """A Max Heap Implementation >>> unsorted = [103, 9, 1, 7, 11, 15, 25, 201, 209, 107, 5] @@ -54,7 +43,7 @@ def __repr__(self) -> str: def parent_index(self, child_idx: int) -> int | None: """ - returns the parent index based on the given child index + Returns the parent index based on the given child index >>> h = Heap() >>> h.build_max_heap([103, 9, 1, 7, 11, 15, 25, 201, 209, 107, 5]) @@ -90,8 +79,8 @@ def parent_index(self, child_idx: int) -> int | None: def left_child_idx(self, parent_idx: int) -> int | None: """ - return the left child index if the left child exists. - if not, return None. + Return the left child index if the left child exists. + If not, return None. """ left_child_index = 2 * parent_idx + 1 if left_child_index < self.heap_size: @@ -100,8 +89,8 @@ def left_child_idx(self, parent_idx: int) -> int | None: def right_child_idx(self, parent_idx: int) -> int | None: """ - return the right child index if the right child exists. - if not, return None. + Return the right child index if the right child exists. + If not, return None. """ right_child_index = 2 * parent_idx + 2 if right_child_index < self.heap_size: @@ -110,10 +99,10 @@ def right_child_idx(self, parent_idx: int) -> int | None: def max_heapify(self, index: int) -> None: """ - correct a single violation of the heap property in a subtree's root. + Correct a single violation of the heap property in a subtree's root. It is the function that is responsible for restoring the property - of Max heap i.e the maximum element is always at top. + of a max heap, i.e the maximum element is always at the top. """ if index < self.heap_size: violation: int = index @@ -133,7 +122,7 @@ def max_heapify(self, index: int) -> None: def build_max_heap(self, collection: Iterable[T]) -> None: """ - build max heap from an unsorted array + Build a max heap from an unsorted array >>> h = Heap() >>> h.build_max_heap([20,40,50,20,10]) @@ -164,7 +153,7 @@ def build_max_heap(self, collection: Iterable[T]) -> None: def extract_max(self) -> T: """ - get and remove max from heap + Get and remove max from heap >>> h = Heap() >>> h.build_max_heap([20,40,50,20,10]) @@ -195,7 +184,7 @@ def extract_max(self) -> T: def insert(self, value: T) -> None: """ - insert a new value into the max heap + Insert a new value into the max heap >>> h = Heap() >>> h.insert(10) @@ -241,7 +230,6 @@ def heap_sort(self) -> None: if __name__ == "__main__": import doctest - # run doc test doctest.testmod() # demo diff --git a/data_structures/heap/max_heap.py b/data_structures/heap/max_heap.py index 589f2595a8da..ae322616c9fd 100644 --- a/data_structures/heap/max_heap.py +++ b/data_structures/heap/max_heap.py @@ -16,7 +16,7 @@ class BinaryHeap: 2 """ - def __init__(self): + def __init__(self) -> None: self.__heap = [0] self.__size = 0 @@ -60,10 +60,10 @@ def pop(self) -> int: return max_value @property - def get_list(self): + def get_list(self) -> list: return self.__heap[1:] - def __len__(self): + def __len__(self) -> int: """Length of the array""" return self.__size diff --git a/data_structures/heap/min_heap.py b/data_structures/heap/min_heap.py index ce7ed570a58d..10ecb37ade71 100644 --- a/data_structures/heap/min_heap.py +++ b/data_structures/heap/min_heap.py @@ -3,14 +3,14 @@ class Node: - def __init__(self, name, val): + def __init__(self, name, val) -> None: self.name = name self.val = val - def __str__(self): + def __str__(self) -> str: return f"{self.__class__.__name__}({self.name}, {self.val})" - def __lt__(self, other): + def __lt__(self, other) -> bool: return self.val < other.val @@ -31,7 +31,7 @@ class MinHeap: -17 """ - def __init__(self, array): + def __init__(self, array) -> None: self.idx_of_element = {} self.heap_dict = {} self.heap = self.build_heap(array) @@ -39,19 +39,19 @@ def __init__(self, array): def __getitem__(self, key): return self.get_value(key) - def get_parent_idx(self, idx): + def get_parent_idx(self, idx) -> int: return (idx - 1) // 2 - def get_left_child_idx(self, idx): + def get_left_child_idx(self, idx) -> int: return idx * 2 + 1 - def get_right_child_idx(self, idx): + def get_right_child_idx(self, idx) -> int: return idx * 2 + 2 def get_value(self, key): return self.heap_dict[key] - def build_heap(self, array): + def build_heap(self, array) -> list: last_idx = len(array) - 1 start_from = self.get_parent_idx(last_idx) @@ -64,7 +64,7 @@ def build_heap(self, array): return array # this is min-heapify method - def sift_down(self, idx, array): + def sift_down(self, idx, array) -> None: while True: left = self.get_left_child_idx(idx) right = self.get_right_child_idx(idx) @@ -88,7 +88,7 @@ def sift_down(self, idx, array): else: break - def sift_up(self, idx): + def sift_up(self, idx) -> None: p = self.get_parent_idx(idx) while p >= 0 and self.heap[p] > self.heap[idx]: self.heap[p], self.heap[idx] = self.heap[idx], self.heap[p] @@ -114,19 +114,19 @@ def remove(self): self.sift_down(0, self.heap) return x - def insert(self, node): + def insert(self, node) -> None: self.heap.append(node) self.idx_of_element[node] = len(self.heap) - 1 self.heap_dict[node.name] = node.val self.sift_up(len(self.heap) - 1) - def is_empty(self): + def is_empty(self) -> bool: return len(self.heap) == 0 - def decrease_key(self, node, new_value): - assert ( - self.heap[self.idx_of_element[node]].val > new_value - ), "newValue must be less that current value" + def decrease_key(self, node, new_value) -> None: + assert self.heap[self.idx_of_element[node]].val > new_value, ( + "newValue must be less that current value" + ) node.val = new_value self.heap_dict[node.name] = new_value self.sift_up(self.idx_of_element[node]) diff --git a/data_structures/heap/randomized_heap.py b/data_structures/heap/randomized_heap.py index 12888c1f4089..9668d3ac2a45 100644 --- a/data_structures/heap/randomized_heap.py +++ b/data_structures/heap/randomized_heap.py @@ -4,12 +4,12 @@ import random from collections.abc import Iterable -from typing import Any, Generic, TypeVar +from typing import Any, TypeVar T = TypeVar("T", bound=bool) -class RandomizedHeapNode(Generic[T]): +class RandomizedHeapNode[T: bool]: """ One node of the randomized heap. Contains the value and references to two children. @@ -73,7 +73,7 @@ def merge( return root1 -class RandomizedHeap(Generic[T]): +class RandomizedHeap[T: bool]: """ A data structure that allows inserting a new value and to pop the smallest values. Both operations take O(logN) time where N is the size of the diff --git a/data_structures/heap/skew_heap.py b/data_structures/heap/skew_heap.py index 0839db711cb1..4e82569444fa 100644 --- a/data_structures/heap/skew_heap.py +++ b/data_structures/heap/skew_heap.py @@ -3,12 +3,12 @@ from __future__ import annotations from collections.abc import Iterable, Iterator -from typing import Any, Generic, TypeVar +from typing import Any, TypeVar T = TypeVar("T", bound=bool) -class SkewNode(Generic[T]): +class SkewNode[T: bool]: """ One node of the skew heap. Contains the value and references to two children. @@ -87,7 +87,7 @@ def merge( return result -class SkewHeap(Generic[T]): +class SkewHeap[T: bool]: """ A data structure that allows inserting a new value and to pop the smallest values. Both operations take O(logN) time where N is the size of the diff --git a/data_structures/kd_tree/tests/test_kdtree.py b/data_structures/kd_tree/tests/test_kdtree.py index dce5e4f34ff4..4722aeb477c6 100644 --- a/data_structures/kd_tree/tests/test_kdtree.py +++ b/data_structures/kd_tree/tests/test_kdtree.py @@ -23,7 +23,9 @@ (10, 10.0, 3, -2, KDNode), # Depth = -2, 3D points ], ) -def test_build_kdtree(num_points, cube_size, num_dimensions, depth, expected_result): +def test_build_kdtree( + num_points, cube_size, num_dimensions, depth, expected_result +) -> None: """ Test that KD-Tree is built correctly. @@ -48,17 +50,17 @@ def test_build_kdtree(num_points, cube_size, num_dimensions, depth, expected_res assert kdtree is not None, "Expected a KDNode, got None" # Check if root has correct dimensions - assert ( - len(kdtree.point) == num_dimensions - ), f"Expected point dimension {num_dimensions}, got {len(kdtree.point)}" + assert len(kdtree.point) == num_dimensions, ( + f"Expected point dimension {num_dimensions}, got {len(kdtree.point)}" + ) # Check that the tree is balanced to some extent (simplistic check) - assert isinstance( - kdtree, KDNode - ), f"Expected KDNode instance, got {type(kdtree)}" + assert isinstance(kdtree, KDNode), ( + f"Expected KDNode instance, got {type(kdtree)}" + ) -def test_nearest_neighbour_search(): +def test_nearest_neighbour_search() -> None: """ Test the nearest neighbor search function. """ @@ -85,7 +87,7 @@ def test_nearest_neighbour_search(): assert nodes_visited >= 0 -def test_edge_cases(): +def test_edge_cases() -> None: """ Test edge cases such as an empty KD-Tree. """ diff --git a/data_structures/linked_list/deque_doubly.py b/data_structures/linked_list/deque_doubly.py index 2b9d70c223c4..34378e86de2e 100644 --- a/data_structures/linked_list/deque_doubly.py +++ b/data_structures/linked_list/deque_doubly.py @@ -12,26 +12,26 @@ class _DoublyLinkedBase: """A Private class (to be inherited)""" class _Node: - __slots__ = "_prev", "_data", "_next" + __slots__ = "_data", "_next", "_prev" - def __init__(self, link_p, element, link_n): + def __init__(self, link_p, element, link_n) -> None: self._prev = link_p self._data = element self._next = link_n - def has_next_and_prev(self): + def has_next_and_prev(self) -> str: return ( f" Prev -> {self._prev is not None}, Next -> {self._next is not None}" ) - def __init__(self): + def __init__(self) -> None: self._header = self._Node(None, None, None) self._trailer = self._Node(None, None, None) self._header._next = self._trailer self._trailer._prev = self._header self._size = 0 - def __len__(self): + def __len__(self) -> int: return self._size def is_empty(self): diff --git a/data_structures/linked_list/doubly_linked_list.py b/data_structures/linked_list/doubly_linked_list.py index bd3445f9f6c5..0b4ac65ac2b9 100644 --- a/data_structures/linked_list/doubly_linked_list.py +++ b/data_structures/linked_list/doubly_linked_list.py @@ -2,21 +2,25 @@ https://en.wikipedia.org/wiki/Doubly_linked_list """ +from __future__ import annotations + +from typing import Any + class Node: - def __init__(self, data): + def __init__(self, data: Any) -> None: self.data = data - self.previous = None - self.next = None + self.previous: Node | None = None + self.next: Node | None = None - def __str__(self): + def __str__(self) -> str: return f"{self.data}" class DoublyLinkedList: - def __init__(self): - self.head = None - self.tail = None + def __init__(self) -> None: + self.head: Node | None = None + self.tail: Node | None = None def __iter__(self): """ @@ -32,7 +36,7 @@ def __iter__(self): yield node.data node = node.next - def __str__(self): + def __str__(self) -> str: """ >>> linked_list = DoublyLinkedList() >>> linked_list.insert_at_tail('a') @@ -43,7 +47,7 @@ def __str__(self): """ return "->".join([str(item) for item in self]) - def __len__(self): + def __len__(self) -> int: """ >>> linked_list = DoublyLinkedList() >>> for i in range(0, 5): @@ -53,13 +57,13 @@ def __len__(self): """ return sum(1 for _ in self) - def insert_at_head(self, data): + def insert_at_head(self, data) -> None: self.insert_at_nth(0, data) - def insert_at_tail(self, data): + def insert_at_tail(self, data) -> None: self.insert_at_nth(len(self), data) - def insert_at_nth(self, index: int, data): + def insert_at_nth(self, index: int, data) -> None: """ >>> linked_list = DoublyLinkedList() >>> linked_list.insert_at_nth(-1, 666) @@ -93,13 +97,18 @@ def insert_at_nth(self, index: int, data): new_node.next = self.head self.head = new_node elif index == length: + assert self.tail is not None self.tail.next = new_node + assert self.tail is not None new_node.previous = self.tail self.tail = new_node else: temp = self.head + assert temp is not None for _ in range(index): temp = temp.next + assert temp is not None + assert temp.previous is not None temp.previous.next = new_node new_node.previous = temp.previous new_node.next = temp @@ -141,23 +150,32 @@ def delete_at_nth(self, index: int): if length == 1: self.head = self.tail = None elif index == 0: + assert self.head is not None self.head = self.head.next + assert self.head is not None self.head.previous = None elif index == length - 1: + assert self.tail is not None delete_node = self.tail self.tail = self.tail.previous + assert self.tail is not None self.tail.next = None else: temp = self.head + assert temp is not None for _ in range(index): temp = temp.next + assert temp is not None delete_node = temp + assert temp.next is not None + assert temp.previous is not None temp.next.previous = temp.previous temp.previous.next = temp.next return delete_node.data def delete(self, data) -> str: current = self.head + assert current is not None while current.data != data: # Find the position to delete if current.next: @@ -172,11 +190,13 @@ def delete(self, data) -> str: self.delete_tail() else: # Before: 1 <--> 2(current) <--> 3 + assert current.previous is not None + assert current.next is not None current.previous.next = current.next # 1 --> 3 current.next.previous = current.previous # 1 <--> 3 return data - def is_empty(self): + def is_empty(self) -> bool: """ >>> linked_list = DoublyLinkedList() >>> linked_list.is_empty() diff --git a/data_structures/linked_list/doubly_linked_list_two.py b/data_structures/linked_list/doubly_linked_list_two.py index e993cc5a20af..9d963537c25d 100644 --- a/data_structures/linked_list/doubly_linked_list_two.py +++ b/data_structures/linked_list/doubly_linked_list_two.py @@ -9,28 +9,24 @@ Delete operation is more efficient """ +from dataclasses import dataclass +from typing import Self, TypeVar -class Node: - def __init__(self, data: int, previous=None, next_node=None): - self.data = data - self.previous = previous - self.next = next_node +DataType = TypeVar("DataType") - def __str__(self) -> str: - return f"{self.data}" - - def get_data(self) -> int: - return self.data - def get_next(self): - return self.next +@dataclass +class Node[DataType]: + data: DataType + previous: Self | None = None + next: Self | None = None - def get_previous(self): - return self.previous + def __str__(self) -> str: + return f"{self.data}" class LinkedListIterator: - def __init__(self, head): + def __init__(self, head) -> None: self.current = head def __iter__(self): @@ -39,31 +35,30 @@ def __iter__(self): def __next__(self): if not self.current: raise StopIteration - else: - value = self.current.get_data() - self.current = self.current.get_next() - return value + value = self.current.data + self.current = self.current.next + return value +@dataclass class LinkedList: - def __init__(self): - self.head = None # First node in list - self.tail = None # Last node in list + head: Node | None = None # First node in list + tail: Node | None = None # Last node in list - def __str__(self): + def __str__(self) -> str: current = self.head nodes = [] while current is not None: - nodes.append(current.get_data()) - current = current.get_next() + nodes.append(current.data) + current = current.next return " ".join(str(node) for node in nodes) - def __contains__(self, value: int): + def __contains__(self, value: DataType) -> bool: current = self.head while current: - if current.get_data() == value: + if current.data == value: return True - current = current.get_next() + current = current.next return False def __iter__(self): @@ -71,12 +66,12 @@ def __iter__(self): def get_head_data(self): if self.head: - return self.head.get_data() + return self.head.data return None def get_tail_data(self): if self.tail: - return self.tail.get_data() + return self.tail.data return None def set_head(self, node: Node) -> None: @@ -87,12 +82,13 @@ def set_head(self, node: Node) -> None: self.insert_before_node(self.head, node) def set_tail(self, node: Node) -> None: - if self.head is None: - self.set_head(node) + if self.tail is None: + self.head = node + self.tail = node else: self.insert_after_node(self.tail, node) - def insert(self, value: int) -> None: + def insert(self, value: DataType) -> None: node = Node(value) if self.head is None: self.set_head(node) @@ -103,7 +99,7 @@ def insert_before_node(self, node: Node, node_to_insert: Node) -> None: node_to_insert.next = node node_to_insert.previous = node.previous - if node.get_previous() is None: + if node.previous is None: self.head = node_to_insert else: node.previous.next = node_to_insert @@ -114,14 +110,14 @@ def insert_after_node(self, node: Node, node_to_insert: Node) -> None: node_to_insert.previous = node node_to_insert.next = node.next - if node.get_next() is None: + if node.next is None: self.tail = node_to_insert else: node.next.previous = node_to_insert node.next = node_to_insert - def insert_at_position(self, position: int, value: int) -> None: + def insert_at_position(self, position: int, value: DataType) -> None: current_position = 1 new_node = Node(value) node = self.head @@ -131,38 +127,38 @@ def insert_at_position(self, position: int, value: int) -> None: return current_position += 1 node = node.next - self.insert_after_node(self.tail, new_node) + self.set_tail(new_node) - def get_node(self, item: int) -> Node: + def get_node(self, item: DataType) -> Node: node = self.head while node: - if node.get_data() == item: + if node.data == item: return node - node = node.get_next() + node = node.next raise Exception("Node not found") - def delete_value(self, value): + def delete_value(self, value) -> None: if (node := self.get_node(value)) is not None: if node == self.head: - self.head = self.head.get_next() + self.head = self.head.next if node == self.tail: - self.tail = self.tail.get_previous() + self.tail = self.tail.previous self.remove_node_pointers(node) @staticmethod def remove_node_pointers(node: Node) -> None: - if node.get_next(): + if node.next: node.next.previous = node.previous - if node.get_previous(): + if node.previous: node.previous.next = node.next node.next = None node.previous = None - def is_empty(self): + def is_empty(self) -> bool: return self.head is None @@ -241,6 +237,22 @@ def create_linked_list() -> None: 7 8 9 + >>> linked_list = LinkedList() + >>> linked_list.insert_at_position(position=1, value=10) + >>> str(linked_list) + '10' + >>> linked_list.insert_at_position(position=2, value=20) + >>> str(linked_list) + '10 20' + >>> linked_list.insert_at_position(position=1, value=30) + >>> str(linked_list) + '30 10 20' + >>> linked_list.insert_at_position(position=3, value=40) + >>> str(linked_list) + '30 10 40 20' + >>> linked_list.insert_at_position(position=5, value=50) + >>> str(linked_list) + '30 10 40 20 50' """ diff --git a/data_structures/linked_list/from_sequence.py b/data_structures/linked_list/from_sequence.py index 94b44f15037f..c41b25b211e9 100644 --- a/data_structures/linked_list/from_sequence.py +++ b/data_structures/linked_list/from_sequence.py @@ -1,13 +1,15 @@ -# Recursive Prorgam to create a Linked List from a sequence and -# print a string representation of it. +""" +Recursive Program to create a Linked List from a sequence and +print a string representation of it. +""" class Node: - def __init__(self, data=None): + def __init__(self, data=None) -> None: self.data = data self.next = None - def __repr__(self): + def __repr__(self) -> str: """Returns a visual representation of the node and all its following nodes.""" string_rep = "" temp = self @@ -18,13 +20,32 @@ def __repr__(self): return string_rep -def make_linked_list(elements_list): - """Creates a Linked List from the elements of the given sequence - (list/tuple) and returns the head of the Linked List.""" +def make_linked_list(elements_list: list | tuple) -> Node: + """ + Creates a Linked List from the elements of the given sequence + (list/tuple) and returns the head of the Linked List. + + >>> make_linked_list([]) + Traceback (most recent call last): + ... + ValueError: The Elements List is empty + >>> make_linked_list(()) + Traceback (most recent call last): + ... + ValueError: The Elements List is empty + >>> make_linked_list([1]) + <1> ---> + >>> make_linked_list((1,)) + <1> ---> + >>> make_linked_list([1, 3, 5, 32, 44, 12, 43]) + <1> ---> <3> ---> <5> ---> <32> ---> <44> ---> <12> ---> <43> ---> + >>> make_linked_list((1, 3, 5, 32, 44, 12, 43)) + <1> ---> <3> ---> <5> ---> <32> ---> <44> ---> <12> ---> <43> ---> + """ # if elements_list is empty if not elements_list: - raise Exception("The Elements List is empty") + raise ValueError("The Elements List is empty") # Set first element as Head head = Node(elements_list[0]) @@ -34,11 +55,3 @@ def make_linked_list(elements_list): current.next = Node(data) current = current.next return head - - -list_data = [1, 3, 5, 32, 44, 12, 43] -print(f"List: {list_data}") -print("Creating Linked List from List.") -linked_list = make_linked_list(list_data) -print("Linked List:") -print(linked_list) diff --git a/data_structures/linked_list/has_loop.py b/data_structures/linked_list/has_loop.py index bc06ffe150e8..a25204e3c4ce 100644 --- a/data_structures/linked_list/has_loop.py +++ b/data_structures/linked_list/has_loop.py @@ -1,5 +1,6 @@ from __future__ import annotations +from collections.abc import Iterator from typing import Any @@ -12,13 +13,13 @@ def __init__(self, data: Any) -> None: self.data: Any = data self.next_node: Node | None = None - def __iter__(self): + def __iter__(self) -> Iterator[Any]: node = self - visited = [] + visited = set() while node: if node in visited: raise ContainsLoopError - visited.append(node) + visited.add(node) yield node.data node = node.next_node diff --git a/data_structures/linked_list/kth_element_from_end.py b/data_structures/linked_list/kth_element_from_end.py new file mode 100644 index 000000000000..b994d17c4608 --- /dev/null +++ b/data_structures/linked_list/kth_element_from_end.py @@ -0,0 +1,140 @@ +from __future__ import annotations + +from dataclasses import dataclass +from typing import Any + + +@dataclass +class Node: + item: Any + next: Node | Any = None + + +class LinkedList: + def __init__(self) -> None: + self.head: Node | None = None + self.size = 0 + + def __str__(self) -> str: + """ + >>> linked_list = LinkedList() + >>> linked_list.add(23) + >>> linked_list.add(14) + >>> linked_list.add(9) + >>> print(linked_list) + 9 --> 14 --> 23 + """ + iterate = self.head + item_str = "" + item_list: list[str] = [] + while iterate: + item_list.append(str(iterate.item)) + iterate = iterate.next + + item_str = " --> ".join(item_list) + + return item_str + + def __len__(self) -> int: + """ + >>> linked_list = LinkedList() + >>> len(linked_list) + 0 + >>> linked_list.add("a") + >>> len(linked_list) + 1 + >>> linked_list.add("b") + >>> len(linked_list) + 2 + """ + return self.size + + def add(self, item: Any, position: int = 0) -> None: + """ + Add an item to the LinkedList at the specified position. + Default position is 0 (the head). + + Args: + item (Any): The item to add to the LinkedList. + position (int, optional): The position at which to add the item. + Defaults to 0. + + Raises: + ValueError: If the position is negative or out of bounds. + + >>> linked_list = LinkedList() + >>> linked_list.add(1) + >>> linked_list.add(2) + >>> linked_list.add(3) + >>> linked_list.add(4, 2) + >>> print(linked_list) + 3 --> 2 --> 4 --> 1 + + # Test adding to a negative position + >>> linked_list.add(5, -3) + Traceback (most recent call last): + ... + ValueError: Position must be non-negative + + # Test adding to an out-of-bounds position + >>> linked_list.add(5,7) + Traceback (most recent call last): + ... + ValueError: Out of bounds + >>> linked_list.add(5, 4) + >>> print(linked_list) + 3 --> 2 --> 4 --> 1 --> 5 + """ + if position < 0: + raise ValueError("Position must be non-negative") + + if position == 0 or self.head is None: + new_node = Node(item, self.head) + self.head = new_node + else: + current = self.head + for _ in range(position - 1): + current = current.next + if current is None: + raise ValueError("Out of bounds") + new_node = Node(item, current.next) + current.next = new_node + self.size += 1 + + def kth_element_from_end(self, position: int) -> Any: + """ + Find the kth node element from the end of the Linked List. + This is not a zero-based index search. + If position=1, it will return the last element in the list. + + >>> linked_list = LinkedList() + >>> linked_list.add(1) + >>> linked_list.add(2) + >>> linked_list.add(3) + >>> linked_list.add(4, 2) + >>> linked_list.add(5, 4) + >>> print(linked_list) + 3 --> 2 --> 4 --> 1 --> 5 + >>> linked_list.kth_element_from_end(2) + 1 + >>> linked_list.kth_element_from_end(5) + 3 + >>> linked_list.kth_element_from_end(3) + 4 + >>> linked_list.kth_element_from_end(10) + >>> linked_list.kth_element_from_end(0) + >>> linked_list.kth_element_from_end(-5) + """ + if (self.head is None) or (position <= 0) or (position > self.size): + return None + + slow_pointer = fast_pointer = self.head + + for _ in range(position): + fast_pointer = fast_pointer.next + + while fast_pointer is not None and slow_pointer is not None: + slow_pointer = slow_pointer.next + fast_pointer = fast_pointer.next + + return slow_pointer.item diff --git a/data_structures/linked_list/merge_sort_linked_list.py b/data_structures/linked_list/merge_sort_linked_list.py new file mode 100644 index 000000000000..e43c14b68ed2 --- /dev/null +++ b/data_structures/linked_list/merge_sort_linked_list.py @@ -0,0 +1,162 @@ +from collections.abc import Iterable +from dataclasses import dataclass + + +@dataclass(order=True) +class Node: + """ + A class representing a node in a linked list. + + Attributes: + data: The data stored in the node. + next: A reference to the next node in the linked list. + """ + + data: int + next: Node | None = None + + +def iter_linked_list(head: Node | None) -> Iterable[Node]: + """ + Iterate over the nodes of a linked list. + + Parameters: + head: The head node of the linked list. + + Yields: + Each node in the linked list, one by one. + + Example: + >>> head = Node(3, Node(1, Node(2))) + >>> head # dataclasses provide a nice .__repr__(). + Node(data=3, next=Node(data=1, next=Node(data=2, next=None))) + >>> tuple(iter_linked_list(head)) + (3, 1, 2) + """ + current = head + while current: + yield current.data + current = current.next + + +def get_middle(head: Node | None) -> Node | None: + """ + Find the node before the middle of the linked list + using the slow and fast pointer technique. + + Parameters: + head: The head node of the linked list. + + Returns: + The node before the middle of the linked list, + or None if the list has fewer than 2 nodes. + + Example: + >>> head = Node(1) + >>> head.next = Node(2) + >>> head.next.next = Node(3) + >>> middle = get_middle(head) + >>> middle.data + 2 + """ + if head is None or head.next is None: + return None + + slow: Node | None = head + fast: Node | None = head.next + + while fast is not None and fast.next is not None: + if slow is None: + return None + slow = slow.next + fast = fast.next.next + + return slow + + +def merge(left: Node | None, right: Node | None) -> Node | None: + """ + Merge two sorted linked lists into one sorted linked list. + + Parameters: + left: The head of the first sorted linked list. + right: The head of the second sorted linked list. + + Returns: + The head of the merged sorted linked list. + + Example: + >>> left = Node(1) + >>> left.next = Node(3) + >>> tuple(iter_linked_list(left)) + (1, 3) + >>> right = Node(2) + >>> right.next = Node(4) + >>> tuple(iter_linked_list(right)) + (2, 4) + >>> merged = merge(left, right) + >>> tuple(iter_linked_list(merged)) + (1, 2, 3, 4) + """ + + if left is None: + return right + if right is None: + return left + + if left <= right: + result = left + result.next = merge(left.next, right) + else: + result = right + result.next = merge(left, right.next) + + return result + + +def merge_sort_linked_list(head: Node | None) -> Node | None: + """ + Sort a linked list using the Merge Sort algorithm. + + Parameters: + head: The head node of the linked list to be sorted. + + Returns: + The head node of the sorted linked list. + + Example: + >>> head = Node(4) + >>> head.next = Node(2) + >>> head.next.next = Node(1) + >>> head.next.next.next = Node(3) + >>> tuple(iter_linked_list(head)) + (4, 2, 1, 3) + >>> sorted_head = merge_sort_linked_list(head) + >>> tuple(iter_linked_list(sorted_head)) + (1, 2, 3, 4) + """ + + # Base Case: 0 or 1 node + if head is None or head.next is None: + return head + + # Split the linked list into two halves + middle = get_middle(head) + if middle is None or middle.next is None: + return head + + next_to_middle = middle.next + middle.next = None # Split the list into two parts + + # Recursively sort both halves + left = merge_sort_linked_list(head) + right = merge_sort_linked_list(next_to_middle) + + # Merge sorted halves + return merge(left, right) + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/data_structures/linked_list/middle_element_of_linked_list.py b/data_structures/linked_list/middle_element_of_linked_list.py index 86dad6b41d73..330193fef21e 100644 --- a/data_structures/linked_list/middle_element_of_linked_list.py +++ b/data_structures/linked_list/middle_element_of_linked_list.py @@ -8,7 +8,7 @@ def __init__(self, data: int) -> None: class LinkedList: - def __init__(self): + def __init__(self) -> None: self.head = None def push(self, new_data: int) -> int: diff --git a/data_structures/linked_list/partition_linked_list.py b/data_structures/linked_list/partition_linked_list.py new file mode 100644 index 000000000000..52bc5ed35989 --- /dev/null +++ b/data_structures/linked_list/partition_linked_list.py @@ -0,0 +1,175 @@ +from __future__ import annotations + +from dataclasses import dataclass +from typing import Any + + +@dataclass +class Node: + item: Any + next: Node | Any = None + + +class LinkedList: + def __init__(self) -> None: + self.head: Node | None = None + self.size = 0 + + def __str__(self) -> str: + """ + >>> linked_list = LinkedList() + >>> linked_list.add(23) + >>> linked_list.add(14) + >>> linked_list.add(9) + >>> print(linked_list) + 9 --> 14 --> 23 + """ + iterate = self.head + item_str = "" + item_list: list[str] = [] + while iterate: + item_list.append(str(iterate.item)) + iterate = iterate.next + + item_str = " --> ".join(item_list) + + return item_str + + def __len__(self) -> int: + """ + >>> linked_list = LinkedList() + >>> len(linked_list) + 0 + >>> linked_list.add("a") + >>> len(linked_list) + 1 + >>> linked_list.add("b") + >>> len(linked_list) + 2 + """ + return self.size + + def add(self, item: Any, position: int = 0) -> None: + """ + Add an item to the LinkedList at the specified position. + Default position is 0 (the head). + + Args: + item (Any): The item to add to the LinkedList. + position (int, optional): The position at which to add the item. + Defaults to 0. + + Raises: + ValueError: If the position is negative or out of bounds. + + >>> linked_list = LinkedList() + >>> linked_list.add(1) + >>> linked_list.add(2) + >>> linked_list.add(3) + >>> linked_list.add(4, 2) + >>> print(linked_list) + 3 --> 2 --> 4 --> 1 + + # Test adding to a negative position + >>> linked_list.add(5, -3) + Traceback (most recent call last): + ... + ValueError: Position must be non-negative + + # Test adding to an out-of-bounds position + >>> linked_list.add(5,7) + Traceback (most recent call last): + ... + ValueError: Out of bounds + >>> linked_list.add(5, 4) + >>> print(linked_list) + 3 --> 2 --> 4 --> 1 --> 5 + """ + if position < 0: + raise ValueError("Position must be non-negative") + + if position == 0 or self.head is None: + new_node = Node(item, self.head) + self.head = new_node + else: + current = self.head + for _ in range(position - 1): + current = current.next + if current is None: + raise ValueError("Out of bounds") + new_node = Node(item, current.next) + current.next = new_node + self.size += 1 + + def partition_liked_list(self, value: int) -> None: + """ + Partition the linked list based on node elements in order. + All nodes with elements less than value should occur on the left, + while those greater than or equal to value should occur on the right. + + >>> linked_list = LinkedList() + >>> linked_list.add(1) + >>> linked_list.add(2) + >>> linked_list.add(3) + >>> linked_list.add(4, 2) + >>> linked_list.add(5, 4) + >>> print(linked_list) + 3 --> 2 --> 4 --> 1 --> 5 + >>> linked_list.partition_liked_list(3) + >>> print(linked_list) + 2 --> 1 --> 3 --> 4 --> 5 + >>> linked_list = LinkedList() + >>> linked_list.add(1) + >>> linked_list.add(2) + >>> linked_list.add(3) + >>> print(linked_list) + 3 --> 2 --> 1 + >>> linked_list.partition_liked_list(3) + >>> print(linked_list) + 2 --> 1 --> 3 + >>> linked_list = LinkedList() + >>> linked_list.add(5) + >>> linked_list.add(5) + >>> linked_list.add(5) + >>> print(linked_list) + 5 --> 5 --> 5 + >>> linked_list.partition_liked_list(5) + >>> print(linked_list) + 5 --> 5 --> 5 + >>> linked_list = LinkedList() + >>> linked_list.add(1, 0) + >>> linked_list.add(2, 1) + >>> linked_list.add(3, 2) + >>> linked_list.add(4, 3) + >>> linked_list.add(5, 4) + >>> print(linked_list) + 1 --> 2 --> 3 --> 4 --> 5 + >>> linked_list.partition_liked_list(6) + >>> print(linked_list) + 1 --> 2 --> 3 --> 4 --> 5 + >>> linked_list = LinkedList() + >>> linked_list.add(1) + >>> print(linked_list) + 1 + >>> linked_list.partition_liked_list(1) + >>> print(linked_list) + 1 + """ + if self.head is None: + return + + less_nodes, greater_nodes = Node(0), Node(0) + current, current_less, current_greater = self.head, less_nodes, greater_nodes + + while current is not None: + if current.item < value: + current_less.next = current + current_less = current_less.next + else: + current_greater.next = current + current_greater = current_greater.next + current = current.next + + current_less.next = greater_nodes.next + current_greater.next = None + self.head = less_nodes.next diff --git a/data_structures/linked_list/print_reverse.py b/data_structures/linked_list/print_reverse.py index a023745dee69..98c8b4e11505 100644 --- a/data_structures/linked_list/print_reverse.py +++ b/data_structures/linked_list/print_reverse.py @@ -98,7 +98,14 @@ def make_linked_list(elements_list: Iterable[int]) -> LinkedList: abc >>> make_linked_list([7, 25]) 7 -> 25 + >>> make_linked_list(x for x in [7, 25]) + 7 -> 25 + >>> make_linked_list(x for x in range(0)) + Traceback (most recent call last): + ... + Exception: The Elements List is empty """ + elements_list = list(elements_list) if not elements_list: raise Exception("The Elements List is empty") diff --git a/data_structures/linked_list/remove_nth_node_from_end_of_list.py b/data_structures/linked_list/remove_nth_node_from_end_of_list.py new file mode 100644 index 000000000000..4bb048c7ca1c --- /dev/null +++ b/data_structures/linked_list/remove_nth_node_from_end_of_list.py @@ -0,0 +1,142 @@ +"""Learn more about this algorithm: https://www.geeksforgeeks.org/delete-nth-node-from-the-end-of-the-given-linked-list/""" + +from __future__ import annotations + +from dataclasses import dataclass + + +@dataclass +class Node: + def __init__(self, data: int) -> None: + self.data = data + self.next: Node | None = None + + +class LinkedListExceptionError(Exception): + pass + + +class LinkedList: + def __init__(self) -> None: + self.head: Node | None = None + + # pulled from middle_element_of_linked_list + def append(self, new_data: int) -> int: + """ + >>> link = LinkedList() + >>> link.append(5) + 5 + >>> link.append(6) + 6 + """ + new_node = Node(new_data) + new_node.next = self.head + self.head = new_node + if not self.head: + raise LinkedListExceptionError( + "Unexpected error: Head of linked list is None after append operation." + ) + return self.head.data + + def view(self) -> str: + """ + >>> link = LinkedList() + >>> link.append(5) + 5 + >>> link.append(6) + 6 + >>> link.view() + '6->5' + """ + ret = "" + temp = self.head + while temp is not None: + ret += str(temp.data) + ret += "->" + temp = temp.next + return ret[:-2] + + def remove_nth_from_end(self, position_from_end: int) -> Node | None: + """ + >>> link = LinkedList() + >>> link.remove_nth_from_end(3) + Traceback (most recent call last): + ... + IndexError: No element found. + >>> link.append(5) + 5 + >>> link.append(6) + 6 + >>> link.append(8) + 8 + >>> link.append(8) + 8 + >>> link.append(10) + 10 + >>> link.append(12) + 12 + >>> link.append(17) + 17 + >>> link.remove_nth_from_end(100) + Traceback (most recent call last): + ... + IndexError: Index out of bounds error. + >>> link.append(-25) + -25 + >>> link.append(-20) + -20 + >>> link.remove_nth_from_end(3) + Node() + >>> + """ + # want to have two pointers, one at the start and the other k nodes forward + # We could complete this in one pass if we stored a self.size variable + if not self.head: + raise IndexError("No element found.") + + size = 0 + current: Node | None = self.head + while current: + size += 1 + current = current.next + + if position_from_end > size or position_from_end <= 0: + raise IndexError("Index out of bounds error.") + return None + + first: Node | None = self.head + for _i in range(position_from_end): + if first: + first = first.next + + # This condition checks if position_from_end is equal to the size of the list. + # If it is, then we simply delete the head node of the list. + if not first: + self.head = self.head.next if self.head else None + return self.head + + second: Node | None = self.head + prev: Node | None = None + + while first: + first = first.next + prev = second + if second: + second = second.next + + if prev and second: + prev.next = second.next + + return self.head + + +if __name__ == "__main__": + link = LinkedList() + for _ in range(int(input().strip())): + data = int(input().strip()) + link.append(data) + print("Before list: ") + print(link.view()) + print(link.remove_nth_from_end(int(input().strip()))) + print("After list: ") + print(link.view()) diff --git a/data_structures/linked_list/singly_linked_list.py b/data_structures/linked_list/singly_linked_list.py index 2c6713a47ad9..e7d1bcd1c2c8 100644 --- a/data_structures/linked_list/singly_linked_list.py +++ b/data_structures/linked_list/singly_linked_list.py @@ -38,14 +38,14 @@ def __repr__(self) -> str: class LinkedList: - def __init__(self): + def __init__(self) -> None: """ Create and initialize LinkedList class instance. >>> linked_list = LinkedList() >>> linked_list.head is None True """ - self.head = None + self.head: Node | None = None def __iter__(self) -> Iterator[Any]: """ @@ -153,8 +153,10 @@ def __setitem__(self, index: int, data: Any) -> None: if not 0 <= index < len(self): raise ValueError("list index out of range.") current = self.head + assert current is not None for _ in range(index): current = current.next_node + assert current is not None current.data = data def insert_tail(self, data: Any) -> None: @@ -215,8 +217,10 @@ def insert_nth(self, index: int, data: Any) -> None: self.head = new_node else: temp = self.head + assert temp is not None for _ in range(index - 1): temp = temp.next_node + assert temp is not None new_node.next_node = temp.next_node temp.next_node = new_node @@ -316,10 +320,13 @@ def delete_nth(self, index: int = 0) -> Any: self.head = self.head.next_node else: temp = self.head + assert temp is not None for _ in range(index - 1): temp = temp.next_node + assert temp is not None delete_node = temp.next_node - temp.next_node = temp.next_node.next_node + assert delete_node is not None + temp.next_node = delete_node.next_node return delete_node.data def is_empty(self) -> bool: @@ -491,7 +498,7 @@ def test_singly_linked_list_2() -> None: ) -def main(): +def main() -> None: from doctest import testmod testmod() diff --git a/data_structures/linked_list/skip_list.py b/data_structures/linked_list/skip_list.py index 13e9a94a8698..214f32b55eda 100644 --- a/data_structures/linked_list/skip_list.py +++ b/data_structures/linked_list/skip_list.py @@ -7,14 +7,14 @@ from itertools import pairwise from random import random -from typing import Generic, TypeVar +from typing import TypeVar KT = TypeVar("KT") VT = TypeVar("VT") -class Node(Generic[KT, VT]): - def __init__(self, key: KT | str = "root", value: VT | None = None): +class Node[KT, VT]: + def __init__(self, key: KT | str = "root", value: VT | None = None) -> None: self.key = key self.value = value self.forward: list[Node[KT, VT]] = [] @@ -49,8 +49,8 @@ def level(self) -> int: return len(self.forward) -class SkipList(Generic[KT, VT]): - def __init__(self, p: float = 0.5, max_level: int = 16): +class SkipList[KT, VT]: + def __init__(self, p: float = 0.5, max_level: int = 16) -> None: self.head: Node[KT, VT] = Node[KT, VT]() self.level = 0 self.p = p @@ -160,7 +160,7 @@ def _locate_node(self, key) -> tuple[Node[KT, VT] | None, list[Node[KT, VT]]]: else: return None, update_vector - def delete(self, key: KT): + def delete(self, key: KT) -> None: """ :param key: Key to remove from list. @@ -186,7 +186,7 @@ def delete(self, key: KT): else: update_node.forward = update_node.forward[:i] - def insert(self, key: KT, value: VT): + def insert(self, key: KT, value: VT) -> None: """ :param key: Key to insert. :param value: Value associated with given key. @@ -246,7 +246,7 @@ def find(self, key: VT) -> VT | None: return None -def test_insert(): +def test_insert() -> None: skip_list = SkipList() skip_list.insert("Key1", 3) skip_list.insert("Key2", 12) @@ -266,7 +266,7 @@ def test_insert(): assert all_values["Key4"] == -19 -def test_insert_overrides_existing_value(): +def test_insert_overrides_existing_value() -> None: skip_list = SkipList() skip_list.insert("Key1", 10) skip_list.insert("Key1", 12) @@ -294,12 +294,12 @@ def test_insert_overrides_existing_value(): assert all_values["Key10"] == 10 -def test_searching_empty_list_returns_none(): +def test_searching_empty_list_returns_none() -> None: skip_list = SkipList() assert skip_list.find("Some key") is None -def test_search(): +def test_search() -> None: skip_list = SkipList() skip_list.insert("Key2", 20) @@ -315,14 +315,14 @@ def test_search(): assert skip_list.find("V") == 13 -def test_deleting_item_from_empty_list_do_nothing(): +def test_deleting_item_from_empty_list_do_nothing() -> None: skip_list = SkipList() skip_list.delete("Some key") assert len(skip_list.head.forward) == 0 -def test_deleted_items_are_not_founded_by_find_method(): +def test_deleted_items_are_not_founded_by_find_method() -> None: skip_list = SkipList() skip_list.insert("Key1", 12) @@ -337,7 +337,7 @@ def test_deleted_items_are_not_founded_by_find_method(): assert skip_list.find("Key2") is None -def test_delete_removes_only_given_key(): +def test_delete_removes_only_given_key() -> None: skip_list = SkipList() skip_list.insert("Key1", 12) @@ -370,7 +370,7 @@ def test_delete_removes_only_given_key(): assert skip_list.find("Key2") is None -def test_delete_doesnt_leave_dead_nodes(): +def test_delete_doesnt_leave_dead_nodes() -> None: skip_list = SkipList() skip_list.insert("Key1", 12) @@ -388,7 +388,7 @@ def traverse_keys(node): assert len(set(traverse_keys(skip_list.head))) == 4 -def test_iter_always_yields_sorted_values(): +def test_iter_always_yields_sorted_values() -> None: def is_sorted(lst): return all(next_item >= item for item, next_item in pairwise(lst)) @@ -405,7 +405,7 @@ def is_sorted(lst): assert is_sorted(list(skip_list)) -def pytests(): +def pytests() -> None: for _ in range(100): # Repeat test 100 times due to the probabilistic nature of skip list # random values == random bugs @@ -423,7 +423,7 @@ def pytests(): test_iter_always_yields_sorted_values() -def main(): +def main() -> None: """ >>> pytests() """ diff --git a/data_structures/linked_list/sorted_linked_list.py b/data_structures/linked_list/sorted_linked_list.py new file mode 100644 index 000000000000..82807ff0b135 --- /dev/null +++ b/data_structures/linked_list/sorted_linked_list.py @@ -0,0 +1,330 @@ +from __future__ import annotations + +from collections.abc import Iterator +from dataclasses import dataclass + + +@dataclass(order=True) +class Node: + """ + A class representing a node in a linked list. + + Attributes: + data: The data stored in the node. + next: A reference to the next node in the linked list. + + >>> Node(1, Node(2, Node(3))) + Node(data=1, next=Node(data=2, next=Node(data=3, next=None))) + """ + + data: int + next: Node | None = None + + +class SortedLinkedList: + """This class represents a sorted linked list.""" + + def __init__(self) -> None: + """ + Create and initialize LinkedList class instance. + >>> linked_list = SortedLinkedList() + >>> linked_list.head is None + True + """ + self.head: Node | None = None + self.tail: Node | None = None + + def __iter__(self) -> Iterator[int]: + """Iterate over the data of the nodes in the linked list. + + >>> linked_list = SortedLinkedList() + >>> linked_list.insert(3) + >>> linked_list.insert(1) + >>> linked_list.insert(2) + >>> tuple(linked_list) + (1, 2, 3) + """ + current = self.head + while current: + yield current.data + current = current.next + + def __len__(self) -> int: + """Return the number of nodes in the linked list. + + >>> linked_list = SortedLinkedList() + >>> len(linked_list) + 0 + >>> linked_list.insert(3) + >>> len(linked_list) + 1 + >>> linked_list.insert(1) + >>> linked_list.insert(2) + >>> len(linked_list) + 3 + """ + return len(tuple(self)) + + def __contains__(self, data: int) -> bool: + """Check if a node with the given data exists in the linked list. + + >>> linked_list = SortedLinkedList() + >>> linked_list.insert(3) + >>> 3 in linked_list + True + >>> 1 in linked_list + False + """ + return data in tuple(self) + + def insert(self, data: int) -> None: + """Inserts a node in its sorted position + This function can be rewritten for any data type, but + the comparator here must be changed + + Args: + data (int): the data of the linked list + + Doctests + >>> linked_list = SortedLinkedList() + >>> linked_list.insert(32) + >>> linked_list.insert(57) + >>> linked_list.insert(45) + >>> tuple(linked_list) + (32, 45, 57) + """ + new_node = Node(data) + if self.head is None: + self.head = new_node + self.tail = new_node + elif new_node < self.head: + new_node.next = self.head + self.head = new_node + else: + temp_node: Node | None = self.head + if temp_node: + while temp_node.next and temp_node.next.data < data: + temp_node = temp_node.next + new_node.next = temp_node.next + temp_node.next = new_node + if new_node.next is None: + self.tail = new_node + + def delete(self, data: int) -> bool: + """This Function deletes first appearance of node with + data from it's sorted position + + This function can be re written for any data type but + the comparator her must have to be changed + + Args: + data (int): the data of the node that is needed to be deleted + + Returns: + bool: status whether the node got deleted or not + + Doctests + + >>> linkedList=SortedLinkedList() + >>> linkedList.insert(32) + >>> linkedList.insert(57) + >>> linkedList.insert(45) + >>> tuple(linkedList) + (32, 45, 57) + >>> linkedList.delete(45) + True + >>> tuple(linkedList) + (32, 57) + """ + if self.head is None: + return False + + if self.head.data == data: + self.head = self.head.next + if self.head is None: + self.tail = None + return True + + temp_node: Node | None = self.head + if temp_node: + while temp_node.next: + if temp_node.next.data == data: + temp_node.next = temp_node.next.next + if temp_node.next is None: + self.tail = temp_node + return True + temp_node = temp_node.next + + return False + + def search(self, data: int) -> bool: + """This function searches the data given input from user + and return whether the data exists or not + + Args: + data (int): Data to be searched + + Returns: + bool: flag indicating whether data exists or not + + Doctests + >>> linkedList=SortedLinkedList() + >>> linkedList.insert(32) + >>> linkedList.insert(57) + >>> linkedList.insert(45) + >>> tuple(linkedList) + (32, 45, 57) + >>> linkedList.search(45) + True + >>> linkedList.search(90) + False + """ + return data in self + + def is_empty(self) -> bool: + """This function will check whether the list is empty or not + + Returns: + bool: flag indicating whether list is empty or not + + Doctests + + >>> linkedList=SortedLinkedList() + >>> linkedList.is_empty() + True + >>> linkedList.insert(32) + >>> linkedList.insert(57) + >>> linkedList.insert(45) + >>> linkedList.is_empty() + False + """ + return not self + + def min_value(self) -> int | None: + """This function will return minimum value + + Returns: + int | None: min value or None if list is empty + + Doctests + + >>> linkedList=SortedLinkedList() + >>> linkedList.min_value() is None + True + >>> linkedList.insert(32) + >>> linkedList.insert(57) + >>> linkedList.insert(45) + >>> linkedList.min_value() + 32 + """ + return min(self) if self.head else None + + def max_value(self) -> int | None: + """This function will return maximum value + + + Returns: + int | None: max value or None if list is empty + + Doctests + + >>> linkedList=SortedLinkedList() + >>> linkedList.max_value() is None + True + >>> linkedList.insert(32) + >>> linkedList.insert(57) + >>> linkedList.insert(45) + >>> linkedList.max_value() + 57 + """ + return max(self) if self.head else None + + def remove_duplicates(self) -> None: + """ + This Function will remove the duplicates from the list + + Doctests + + >>> linkedList=SortedLinkedList() + >>> linkedList.insert(32) + >>> linkedList.insert(57) + >>> linkedList.insert(45) + >>> linkedList.insert(45) + >>> tuple(linkedList) + (32, 45, 45, 57) + >>> linkedList.remove_duplicates() + >>> tuple(linkedList) + (32, 45, 57) + """ + + temp: Node | None = self.head + while temp and temp.next: + if temp.data == temp.next.data: + temp.next = temp.next.next + else: + temp = temp.next + + def merge(self, other_list: SortedLinkedList) -> None: + """This Function will merge the input list with current list + + Args: + other_list (SortedLinkedList): The list to be merged + + Doctests + + >>> linkedList=SortedLinkedList() + >>> linkedList.insert(32) + >>> linkedList.insert(57) + >>> linkedList.insert(45) + >>> tuple(linkedList) + (32, 45, 57) + >>> linkedList2=SortedLinkedList() + >>> linkedList2.insert(23) + >>> linkedList2.insert(47) + >>> linkedList2.insert(95) + >>> tuple(linkedList2) + (23, 47, 95) + >>> linkedList.merge(linkedList2) + >>> tuple(linkedList) + (23, 32, 45, 47, 57, 95) + """ + if other_list.head is None: + return + elif self.head is None: + self.head = other_list.head + self.tail = other_list.tail + return + else: + temp: Node | None = other_list.head + + while temp: + self.insert(temp.data) + temp = temp.next + + +if __name__ == "__main__": + linked_list = SortedLinkedList() + while True: + print("Enter") + print("1. Insert") + print("2. Display") + print("3. Delete") + print("4. Exit") + choice = input("Enter your choice: ") + + match choice: + case "1": + node_data = int(input("Enter a number: ")) + linked_list.insert(node_data) + case "2": + linked_list.display() + case "3": + node_data = int(input("Enter the data to delete: ")) + if linked_list.delete(node_data): + print(f"Node with data {node_data} deleted successfully") + else: + print(f"Node with data {node_data} not found in the list") + case "4": + break + case _: + print("Wrong input") diff --git a/data_structures/linked_list/xor_linked_list.py b/data_structures/linked_list/xor_linked_list.py new file mode 100644 index 000000000000..3de6e12c910e --- /dev/null +++ b/data_structures/linked_list/xor_linked_list.py @@ -0,0 +1,85 @@ +""" +XOR Linked List implementation +A memory-efficient doubly linked list that uses the XOR of node addresses. +Each node stores one pointer that is the XOR of the previous and next node addresses. +https://en.wikipedia.org/wiki/XOR_linked_list +Example: +>>> xor_list = XORLinkedList() +>>> xor_list.insert(10) +>>> xor_list.insert(20) +>>> xor_list.insert(30) +>>> xor_list.to_list() +[10, 20, 30] +""" + +from dataclasses import dataclass + + +@dataclass +class Node: + value: int + both: int = 0 # XOR of prev and next node IDs + + +class XORLinkedList: + def __init__(self) -> None: + """Initializes an empty XOR Linked List.""" + # Use 'Node | None' instead of 'Optional[Node]' (per ruff UP045) + self.head: Node | None = None + self.tail: Node | None = None + # id -> node map to simulate pointer references + self._nodes: dict[int, Node] = {} + + def _xor(self, node_a: Node | None, node_b: Node | None) -> int: + """ + Helper function to get the XOR of two node IDs (simulated addresses). + Names 'node_a' and 'node_b' are used for descriptive parameters. + """ + id_a = id(node_a) if node_a else 0 + id_b = id(node_b) if node_b else 0 + return id_a ^ id_b + + def insert(self, value: int) -> None: + """Inserts a value at the end of the list.""" + node = Node(value) + self._nodes[id(node)] = node + node_id = id(node) + + if self.head is None: + # If the list is empty, head and tail are the new node + self.head = self.tail = node + else: + # If the list is not empty, append to the tail + # The new node's pointer is just the ID of the old tail + node.both = id(self.tail) + if self.tail: # Type checker guard + # The old tail's pointer must be updated to XOR + # its previous node ID with the new node's ID. + # self.tail.both was (prev_id ^ 0) + # self.tail.both becomes (prev_id ^ new_node_id) + self.tail.both ^= node_id + self.tail = node + + def to_list(self) -> list[int]: + """Converts the XOR list to a standard Python list (forward traversal).""" + result = [] + prev_id = 0 + current = self.head + while current: + result.append(current.value) + # Find next node's ID: + # current.both = prev_id ^ next_id + # so, next_id = prev_id ^ current.both + current_id = id(current) + next_id = prev_id ^ current.both + + # Move forward + prev_id = current_id + current = self._nodes.get(next_id) + return result + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/compression/image_data/__init__.py b/data_structures/queues/__init__.py similarity index 100% rename from compression/image_data/__init__.py rename to data_structures/queues/__init__.py diff --git a/data_structures/queue/circular_queue.py b/data_structures/queues/circular_queue.py similarity index 77% rename from data_structures/queue/circular_queue.py rename to data_structures/queues/circular_queue.py index f2fb4c01e467..e7920a31d0c9 100644 --- a/data_structures/queue/circular_queue.py +++ b/data_structures/queues/circular_queue.py @@ -4,7 +4,7 @@ class CircularQueue: """Circular FIFO queue with a fixed capacity""" - def __init__(self, n: int): + def __init__(self, n: int) -> None: self.n = n self.array = [None] * self.n self.front = 0 # index of the first element @@ -17,7 +17,9 @@ def __len__(self) -> int: >>> len(cq) 0 >>> cq.enqueue("A") # doctest: +ELLIPSIS - + >>> cq.array + ['A', None, None, None, None] >>> len(cq) 1 """ @@ -45,19 +47,28 @@ def first(self): """ return False if self.is_empty() else self.array[self.front] - def enqueue(self, data): + def enqueue(self, data) -> "CircularQueue": """ This function inserts an element at the end of the queue using self.rear value as an index. + >>> cq = CircularQueue(5) >>> cq.enqueue("A") # doctest: +ELLIPSIS - >>> (cq.size, cq.first()) (1, 'A') >>> cq.enqueue("B") # doctest: +ELLIPSIS - + >>> cq.array + ['A', 'B', None, None, None] >>> (cq.size, cq.first()) (2, 'A') + >>> cq.enqueue("C").enqueue("D").enqueue("E") # doctest: +ELLIPSIS + + >>> cq.enqueue("F") + Traceback (most recent call last): + ... + Exception: QUEUE IS FULL """ if self.size >= self.n: raise Exception("QUEUE IS FULL") @@ -71,6 +82,7 @@ def dequeue(self): """ This function removes an element from the queue using on self.front value as an index and returns it + >>> cq = CircularQueue(5) >>> cq.dequeue() Traceback (most recent call last): diff --git a/data_structures/queue/circular_queue_linked_list.py b/data_structures/queues/circular_queue_linked_list.py similarity index 100% rename from data_structures/queue/circular_queue_linked_list.py rename to data_structures/queues/circular_queue_linked_list.py diff --git a/data_structures/queue/double_ended_queue.py b/data_structures/queues/double_ended_queue.py similarity index 99% rename from data_structures/queue/double_ended_queue.py rename to data_structures/queues/double_ended_queue.py index 607d0bda3df4..c28d46c65168 100644 --- a/data_structures/queue/double_ended_queue.py +++ b/data_structures/queues/double_ended_queue.py @@ -33,7 +33,7 @@ class Deque: the number of nodes """ - __slots__ = ("_front", "_back", "_len") + __slots__ = ("_back", "_front", "_len") @dataclass class _Node: diff --git a/data_structures/queue/linked_queue.py b/data_structures/queues/linked_queue.py similarity index 100% rename from data_structures/queue/linked_queue.py rename to data_structures/queues/linked_queue.py diff --git a/data_structures/queues/monotonic_queue.py b/data_structures/queues/monotonic_queue.py new file mode 100644 index 000000000000..b19672fd7e66 --- /dev/null +++ b/data_structures/queues/monotonic_queue.py @@ -0,0 +1,39 @@ +from __future__ import annotations + +from collections import deque + +arr = [1, 3, -1, -3, 5, 3, 6, 7] +window_size = 3 +expect = [3, 3, 5, 5, 6, 7] + + +def max_sliding_window(arr: list[float], window_size: int) -> list[float]: + """ + Given an array of integers nums, there is a sliding window of size k which is moving + from the very left of the array to the very right. + Each time the sliding window of length window_size moves right by one position. + Return the max sliding window. + >>> max_sliding_window(arr, window_size) == expect + True + """ + max_val = [] + mono_queue: deque = deque() + for i in range(len(arr)): + # pop the element if the index is outside the window size k + if mono_queue and i - mono_queue[0] >= window_size: + mono_queue.popleft() + # keep the queue monotonically decreasing + # so that the max value is always on the top + while mono_queue and arr[i] >= arr[mono_queue[-1]]: + mono_queue.pop() + mono_queue.append(i) + # the maximum value is the first element in queue + if i >= window_size - 1: + max_val.append(arr[mono_queue[0]]) + return max_val + + +if __name__ == "__main__": + from doctest import testmod + + testmod() diff --git a/data_structures/queue/priority_queue_using_list.py b/data_structures/queues/priority_queue_using_list.py similarity index 92% rename from data_structures/queue/priority_queue_using_list.py rename to data_structures/queues/priority_queue_using_list.py index f61b5e8e664d..a5bf93b8e2c6 100644 --- a/data_structures/queue/priority_queue_using_list.py +++ b/data_structures/queues/priority_queue_using_list.py @@ -59,14 +59,14 @@ class FixedPriorityQueue: >>> fpq.dequeue() Traceback (most recent call last): ... - data_structures.queue.priority_queue_using_list.UnderFlowError: All queues are empty + data_structures.queues.priority_queue_using_list.UnderFlowError: All queues are empty >>> print(fpq) Priority 0: [] Priority 1: [] Priority 2: [] - """ + """ # noqa: E501 - def __init__(self): + def __init__(self) -> None: self.queues = [ [], [], @@ -141,12 +141,12 @@ class ElementPriorityQueue: >>> epq.dequeue() Traceback (most recent call last): ... - data_structures.queue.priority_queue_using_list.UnderFlowError: The queue is empty + data_structures.queues.priority_queue_using_list.UnderFlowError: The queue is empty >>> print(epq) [] """ - def __init__(self): + def __init__(self) -> None: self.queue = [] def enqueue(self, data: int) -> None: @@ -165,10 +165,9 @@ def dequeue(self) -> int: """ if not self.queue: raise UnderFlowError("The queue is empty") - else: - data = min(self.queue) - self.queue.remove(data) - return data + data = min(self.queue) + self.queue.remove(data) + return data def __str__(self) -> str: """ @@ -177,7 +176,7 @@ def __str__(self) -> str: return str(self.queue) -def fixed_priority_queue(): +def fixed_priority_queue() -> None: fpq = FixedPriorityQueue() fpq.enqueue(0, 10) fpq.enqueue(1, 70) @@ -202,7 +201,7 @@ def fixed_priority_queue(): print(fpq.dequeue()) -def element_priority_queue(): +def element_priority_queue() -> None: epq = ElementPriorityQueue() epq.enqueue(10) epq.enqueue(70) diff --git a/data_structures/queue/queue_by_list.py b/data_structures/queues/queue_by_list.py similarity index 90% rename from data_structures/queue/queue_by_list.py rename to data_structures/queues/queue_by_list.py index 4b05be9fd08e..182cc4147c47 100644 --- a/data_structures/queue/queue_by_list.py +++ b/data_structures/queues/queue_by_list.py @@ -1,13 +1,10 @@ """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: +class QueueByList[T]: + def __init__(self, iterable: Iterable[T] | None = None) -> None: """ >>> QueueByList() Queue(()) @@ -16,7 +13,7 @@ def __init__(self, iterable: Iterable[_T] | None = None) -> None: >>> QueueByList((i**2 for i in range(1, 4))) Queue((1, 4, 9)) """ - self.entries: list[_T] = list(iterable or []) + self.entries: list[T] = list(iterable or []) def __len__(self) -> int: """ @@ -58,7 +55,7 @@ def __repr__(self) -> str: return f"Queue({tuple(self.entries)})" - def put(self, item: _T) -> None: + def put(self, item: T) -> None: """Put `item` to the Queue >>> queue = QueueByList() @@ -72,7 +69,7 @@ def put(self, item: _T) -> None: self.entries.append(item) - def get(self) -> _T: + def get(self) -> T: """ Get `item` from the Queue @@ -118,7 +115,7 @@ def rotate(self, rotation: int) -> None: for _ in range(rotation): put(get(0)) - def get_front(self) -> _T: + def get_front(self) -> T: """Get the front item from the Queue >>> queue = QueueByList((10, 20, 30)) diff --git a/data_structures/queue/queue_by_two_stacks.py b/data_structures/queues/queue_by_two_stacks.py similarity index 88% rename from data_structures/queue/queue_by_two_stacks.py rename to data_structures/queues/queue_by_two_stacks.py index cd62f155a63b..f9e302ffcedd 100644 --- a/data_structures/queue/queue_by_two_stacks.py +++ b/data_structures/queues/queue_by_two_stacks.py @@ -1,13 +1,10 @@ """Queue implementation using two stacks""" from collections.abc import Iterable -from typing import Generic, TypeVar -_T = TypeVar("_T") - -class QueueByTwoStacks(Generic[_T]): - def __init__(self, iterable: Iterable[_T] | None = None) -> None: +class QueueByTwoStacks[T]: + def __init__(self, iterable: Iterable[T] | None = None) -> None: """ >>> QueueByTwoStacks() Queue(()) @@ -16,8 +13,8 @@ def __init__(self, iterable: Iterable[_T] | None = None) -> None: >>> QueueByTwoStacks((i**2 for i in range(1, 4))) Queue((1, 4, 9)) """ - self._stack1: list[_T] = list(iterable or []) - self._stack2: list[_T] = [] + self._stack1: list[T] = list(iterable or []) + self._stack2: list[T] = [] def __len__(self) -> int: """ @@ -59,7 +56,7 @@ def __repr__(self) -> str: """ return f"Queue({tuple(self._stack2[::-1] + self._stack1)})" - def put(self, item: _T) -> None: + def put(self, item: T) -> None: """ Put `item` into the Queue @@ -74,7 +71,7 @@ def put(self, item: _T) -> None: self._stack1.append(item) - def get(self) -> _T: + def get(self) -> T: """ Get `item` from the Queue diff --git a/data_structures/queue/queue_on_pseudo_stack.py b/data_structures/queues/queue_on_pseudo_stack.py similarity index 92% rename from data_structures/queue/queue_on_pseudo_stack.py rename to data_structures/queues/queue_on_pseudo_stack.py index 2da67ecc263c..95b84a309783 100644 --- a/data_structures/queue/queue_on_pseudo_stack.py +++ b/data_structures/queues/queue_on_pseudo_stack.py @@ -4,11 +4,11 @@ class Queue: - def __init__(self): + def __init__(self) -> None: self.stack = [] self.length = 0 - def __str__(self): + def __str__(self) -> str: printed = "<" + str(self.stack)[1:-1] + ">" return printed diff --git a/data_structures/stacks/balanced_parentheses.py b/data_structures/stacks/balanced_parentheses.py index 928815bb2111..a05627bd12dd 100644 --- a/data_structures/stacks/balanced_parentheses.py +++ b/data_structures/stacks/balanced_parentheses.py @@ -11,6 +11,12 @@ def balanced_parentheses(parentheses: str) -> bool: False >>> balanced_parentheses("1+2*3-4") True + >>> balanced_parentheses("{}") + True + >>> balanced_parentheses("))((") + False + >>> balanced_parentheses("((") + False >>> balanced_parentheses("") True """ diff --git a/data_structures/stacks/infix_to_prefix_conversion.py b/data_structures/stacks/infix_to_prefix_conversion.py index 878473b93c19..8eb86ba60530 100644 --- a/data_structures/stacks/infix_to_prefix_conversion.py +++ b/data_structures/stacks/infix_to_prefix_conversion.py @@ -173,10 +173,11 @@ def infix_2_prefix(infix: str) -> str: reversed_infix = list(infix[::-1]) # reverse the infix equation for i in range(len(reversed_infix)): - if reversed_infix[i] == "(": - reversed_infix[i] = ")" # change "(" to ")" - elif reversed_infix[i] == ")": - reversed_infix[i] = "(" # change ")" to "(" + match reversed_infix[i]: + case "(": + reversed_infix[i] = ")" # change "(" to ")" + case ")": + reversed_infix[i] = "(" # change ")" to "(" # call infix_2_postfix on Infix, return reverse of Postfix return (infix_2_postfix("".join(reversed_infix)))[::-1] diff --git a/data_structures/stacks/kth_next_greater_element.py b/data_structures/stacks/kth_next_greater_element.py new file mode 100644 index 000000000000..d10ff1e80863 --- /dev/null +++ b/data_structures/stacks/kth_next_greater_element.py @@ -0,0 +1,95 @@ +""" +Implement the function to find kth Next Greatest Element (NGE) for all elements. +""" + +test_k = 10 +test_array = list(range(10000)) +expected_answers = [value + test_k for value in range(10000 - test_k)] + [None] * test_k + + +def find_kth_next_greater_element( + array: list[int | float], kth_ord: int +) -> list[int | float | None]: + """ + Efficient general method to seek the kth NGE for all elements. + Approach is entirely based on k stacks, which are actually very easy to understand. + These k stacks symbolize how many NGEs an element has already found. + + For example, for 1 <= j <= k, if an element is currently at the jth stack, + it means that this element has found its (j - 1)th NGE, now looking for jth NGE. + + By processing stacks from higher to lower ordinals, we can always ensure that + each stack stays monotonically non-increasing in terms of element value. + + Time complexity: O(kn) where n is the length of input array. + However, if k >= n, all elements won't find their respective kth NGE. + As a result, worst case time complexity is O(n^2) when k < n but k ≈ n. + + Space complexity: O(n), since at any point, an element is only in one of k stacks. + + Args: + array (list[int | float]): A list for which the kth NGE is computed. + A mix of integers and floats in list is allowed. + + kth_ord (int): Ordinal of the NGE to find. kth_ord must be a positive integer. + + Returns: + A list containing each element's kth NGE. If an element can't find its kth NGE, + None, instead of -1, is put as its entry, because input array might have -1. + + Example: + >>> find_kth_next_greater_element([1, 2, 3, 4, 5], 3) == [4, 5, None, None, None] + True + >>> find_kth_next_greater_element([2.5, 1.9, 4.3, 6.0], 1) == [4.3, 4.3, 6.0, None] + True + >>> find_kth_next_greater_element([1, 2, 3], 0) + Traceback (most recent call last): + ... + ValueError: kth_ord must be a positive integer. + >>> find_kth_next_greater_element(list(range(1000)), 1000) == [None] * 1000 + True + >>> find_kth_next_greater_element(test_array, test_k) == expected_answers + True + """ + if not isinstance(kth_ord, int) or kth_ord < 1: + raise ValueError("kth_ord must be a positive integer.") + + kth_next_greater_elements: list[int | float | None] = [None] * len(array) + if kth_ord >= len(array): # Trivial cases: nobody can have kth NGE. + return kth_next_greater_elements + + # For 1 <= j <= k, the jth stack is at the jth idx of stacks list. + # stacks[0]: a transporter that transfers entries between stacks. + # Each stack's entry is a tuple of (element, idx). + stacks: list[list[tuple[int | float, int]]] = [[] for _ in range(kth_ord + 1)] + + for idx, element in enumerate(array): + # From kth stack to answer found. + while stacks[kth_ord] and stacks[kth_ord][-1][0] < element: + _, prev_idx = stacks[kth_ord].pop() + kth_next_greater_elements[prev_idx] = element + + for stack_ord in range(kth_ord - 1, 0, -1): # From (k - 1)th to 1st stack. + while stacks[stack_ord] and stacks[stack_ord][-1][0] < element: + stacks[0].append(stacks[stack_ord].pop()) + + while stacks[0]: # Move to the next ordered stack. + stacks[stack_ord + 1].append(stacks[0].pop()) + + unvisited_elements_count = len(array) - 1 - idx + if unvisited_elements_count >= kth_ord: # Element has a chance to find kth NGE. + stacks[1].append((element, idx)) # Always join 1st stack to begin search. + + return kth_next_greater_elements + + +if __name__ == "__main__": + from doctest import testmod + from timeit import timeit + + testmod() + setup = "from __main__ import test_array, test_k, find_kth_next_greater_element" + print( + "find_kth_next_greater_element():", + timeit("find_kth_next_greater_element(test_array, test_k)", setup=setup), + ) diff --git a/data_structures/stacks/largest_rectangle_histogram.py b/data_structures/stacks/largest_rectangle_histogram.py new file mode 100644 index 000000000000..7575bd9f628d --- /dev/null +++ b/data_structures/stacks/largest_rectangle_histogram.py @@ -0,0 +1,39 @@ +def largest_rectangle_area(heights: list[int]) -> int: + """ + Inputs an array of integers representing the heights of bars, + and returns the area of the largest rectangle that can be formed + + >>> largest_rectangle_area([2, 1, 5, 6, 2, 3]) + 10 + + >>> largest_rectangle_area([2, 4]) + 4 + + >>> largest_rectangle_area([6, 2, 5, 4, 5, 1, 6]) + 12 + + >>> largest_rectangle_area([1]) + 1 + """ + stack: list[int] = [] + max_area = 0 + heights = [*heights, 0] # make a new list by appending the sentinel 0 + n = len(heights) + + for i in range(n): + # make sure the stack remains in increasing order + while stack and heights[i] < heights[stack[-1]]: + h = heights[stack.pop()] # height of the bar + # if stack is empty, it means entire width can be taken from index 0 to i-1 + w = i if not stack else i - stack[-1] - 1 # calculate width + max_area = max(max_area, h * w) + + stack.append(i) + + return max_area + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/data_structures/stacks/lexicographical_numbers.py b/data_structures/stacks/lexicographical_numbers.py new file mode 100644 index 000000000000..6a174e7d9e95 --- /dev/null +++ b/data_structures/stacks/lexicographical_numbers.py @@ -0,0 +1,38 @@ +from collections.abc import Iterator + + +def lexical_order(max_number: int) -> Iterator[int]: + """ + Generate numbers in lexical order from 1 to max_number. + + >>> " ".join(map(str, lexical_order(13))) + '1 10 11 12 13 2 3 4 5 6 7 8 9' + >>> list(lexical_order(1)) + [1] + >>> " ".join(map(str, lexical_order(20))) + '1 10 11 12 13 14 15 16 17 18 19 2 20 3 4 5 6 7 8 9' + >>> " ".join(map(str, lexical_order(25))) + '1 10 11 12 13 14 15 16 17 18 19 2 20 21 22 23 24 25 3 4 5 6 7 8 9' + >>> list(lexical_order(12)) + [1, 10, 11, 12, 2, 3, 4, 5, 6, 7, 8, 9] + """ + + stack = [1] + + while stack: + num = stack.pop() + if num > max_number: + continue + + yield num + if (num % 10) != 9: + stack.append(num + 1) + + stack.append(num * 10) + + +if __name__ == "__main__": + from doctest import testmod + + testmod() + print(f"Numbers from 1 to 25 in lexical order: {list(lexical_order(26))}") diff --git a/data_structures/stacks/next_greater_element.py b/data_structures/stacks/next_greater_element.py index 7d76d1f47dfa..216850b4b894 100644 --- a/data_structures/stacks/next_greater_element.py +++ b/data_structures/stacks/next_greater_element.py @@ -6,9 +6,20 @@ def next_greatest_element_slow(arr: list[float]) -> list[float]: """ - Get the Next Greatest Element (NGE) for all elements in a list. - Maximum element present after the current one which is also greater than the - current one. + Get the Next Greatest Element (NGE) for each element in the array + by checking all subsequent elements to find the next greater one. + + This is a brute-force implementation, and it has a time complexity + of O(n^2), where n is the size of the array. + + Args: + arr: List of numbers for which the NGE is calculated. + + Returns: + List containing the next greatest elements. If no + greater element is found, -1 is placed in the result. + + Example: >>> next_greatest_element_slow(arr) == expect True """ @@ -28,9 +39,21 @@ def next_greatest_element_slow(arr: list[float]) -> list[float]: def next_greatest_element_fast(arr: list[float]) -> list[float]: """ - Like next_greatest_element_slow() but changes the loops to use - enumerate() instead of range(len()) for the outer loop and - for in a slice of arr for the inner loop. + Find the Next Greatest Element (NGE) for each element in the array + using a more readable approach. This implementation utilizes + enumerate() for the outer loop and slicing for the inner loop. + + While this improves readability over next_greatest_element_slow(), + it still has a time complexity of O(n^2). + + Args: + arr: List of numbers for which the NGE is calculated. + + Returns: + List containing the next greatest elements. If no + greater element is found, -1 is placed in the result. + + Example: >>> next_greatest_element_fast(arr) == expect True """ @@ -47,14 +70,23 @@ def next_greatest_element_fast(arr: list[float]) -> list[float]: def next_greatest_element(arr: list[float]) -> list[float]: """ - Get the Next Greatest Element (NGE) for all elements in a list. - Maximum element present after the current one which is also greater than the - current one. - - A naive way to solve this is to take two loops and check for the next bigger - number but that will make the time complexity as O(n^2). The better way to solve - this would be to use a stack to keep track of maximum number giving a linear time - solution. + Efficient solution to find the Next Greatest Element (NGE) for all elements + using a stack. The time complexity is reduced to O(n), making it suitable + for larger arrays. + + The stack keeps track of elements for which the next greater element hasn't + been found yet. By iterating through the array in reverse (from the last + element to the first), the stack is used to efficiently determine the next + greatest element for each element. + + Args: + arr: List of numbers for which the NGE is calculated. + + Returns: + List containing the next greatest elements. If no + greater element is found, -1 is placed in the result. + + Example: >>> next_greatest_element(arr) == expect True """ diff --git a/data_structures/stacks/postfix_to_infix_conversion.py b/data_structures/stacks/postfix_to_infix_conversion.py new file mode 100644 index 000000000000..dd8464914cfe --- /dev/null +++ b/data_structures/stacks/postfix_to_infix_conversion.py @@ -0,0 +1,63 @@ +""" +https://math.oxford.emory.edu/site/cs171/postfixExpressions/ +https://en.wikipedia.org/wiki/Shunting_yard_algorithm +""" + + +def postfix_to_infix(postfix_expression: str) -> str: + """ + Returns the infix expression for the given postfix expression as an argument + >>> postfix_to_infix("") + Traceback (most recent call last): + ... + ValueError: Invalid postfix expression. + >>> postfix_to_infix("123+*4+") + '((1*(2+3))+4)' + >>> postfix_to_infix("abc*+de*f+g*+") + '((a+(b*c))+(((d*e)+f)*g))' + >>> postfix_to_infix("xy^5z*/2+") + '(((x^y)/(5*z))+2)' + >>> postfix_to_infix("232^^") + '(2^(3^2))' + >>> postfix_to_infix("32+") + '(3+2)' + """ + + # Check for invalid input. + if postfix_expression is None or postfix_expression == "": + raise ValueError("Invalid postfix expression.") + + # Create a stack to store the operands and operators. + stack = [] + + # Iterate over the postfix expression. + for item in postfix_expression: + # If the item is an operand, push it onto the stack. + if item not in ["+", "-", "*", "/", "^"]: + stack.append(item) + else: + # If the item is an operator, pop the top two operands from the stack + # and concatenate the operator between them. + operand_2 = stack.pop() + operand_1 = stack.pop() + infix_expression = "(" + operand_1 + item + operand_2 + ")" + + # Push the resulting infix expression onto the stack. + stack.append(infix_expression) + + # The top element of the stack is the final infix expression. + return stack.pop() + + +if __name__ == "__main__": + from doctest import testmod + + testmod() + # Enter the posfix expression with no whitespaces. + postfix_expression = "512+4*+3-" + + try: + infix_expression = postfix_to_infix(postfix_expression) + print("Infix expression: " + infix_expression) + except ValueError as e: + print(e) diff --git a/data_structures/stacks/prefix_evaluation.py b/data_structures/stacks/prefix_evaluation.py index f48eca23d7b5..2c5c60d1a850 100644 --- a/data_structures/stacks/prefix_evaluation.py +++ b/data_structures/stacks/prefix_evaluation.py @@ -1,8 +1,9 @@ """ -Python3 program to evaluate a prefix expression. +Program to evaluate a prefix expression. +https://en.wikipedia.org/wiki/Polish_notation """ -calc = { +operators = { "+": lambda x, y: x + y, "-": lambda x, y: x - y, "*": lambda x, y: x * y, @@ -10,7 +11,7 @@ } -def is_operand(c): +def is_operand(c) -> bool: """ Return True if the given char c is an operand, e.g. it is a number @@ -22,7 +23,7 @@ def is_operand(c): return c.isdigit() -def evaluate(expression): +def evaluate(expression) -> float: """ Evaluate a given expression in prefix notation. Asserts that the given expression is valid. @@ -31,6 +32,10 @@ def evaluate(expression): 21 >>> evaluate("/ * 10 2 + 4 1 ") 4.0 + >>> evaluate("2") + 2 + >>> evaluate("+ * 2 3 / 8 4") + 8.0 """ stack = [] @@ -45,11 +50,39 @@ def evaluate(expression): # push the result onto the stack again o1 = stack.pop() o2 = stack.pop() - stack.append(calc[c](o1, o2)) + stack.append(operators[c](o1, o2)) return stack.pop() +def evaluate_recursive(expression: list[str]) -> float: + """ + Alternative recursive implementation + + >>> evaluate_recursive(['2']) + 2 + >>> expression = ['+', '*', '2', '3', '/', '8', '4'] + >>> evaluate_recursive(expression) + 8.0 + >>> expression + [] + >>> evaluate_recursive(['+', '9', '*', '2', '6']) + 21 + >>> evaluate_recursive(['/', '*', '10', '2', '+', '4', '1']) + 4.0 + """ + + op = expression.pop(0) + if is_operand(op): + return int(op) + + operation = operators[op] + + a = evaluate_recursive(expression) + b = evaluate_recursive(expression) + return operation(a, b) + + # Driver code if __name__ == "__main__": test_expression = "+ 9 * 2 6" diff --git a/data_structures/stacks/stack.py b/data_structures/stacks/stack.py index 93698f5aa116..8de2f61085c9 100644 --- a/data_structures/stacks/stack.py +++ b/data_structures/stacks/stack.py @@ -1,6 +1,6 @@ from __future__ import annotations -from typing import Generic, TypeVar +from typing import TypeVar T = TypeVar("T") @@ -13,7 +13,7 @@ class StackUnderflowError(BaseException): pass -class Stack(Generic[T]): +class Stack[T]: """A stack is an abstract data type that serves as a collection of elements with two principal operations: push() and pop(). push() adds an element to the top of the stack, and pop() removes an element from the top @@ -22,7 +22,7 @@ class Stack(Generic[T]): https://en.wikipedia.org/wiki/Stack_(abstract_data_type) """ - def __init__(self, limit: int = 10): + def __init__(self, limit: int = 10) -> None: self.stack: list[T] = [] self.limit = limit diff --git a/data_structures/stacks/stack_tracking_min_max.py b/data_structures/stacks/stack_tracking_min_max.py new file mode 100644 index 000000000000..6c638110de19 --- /dev/null +++ b/data_structures/stacks/stack_tracking_min_max.py @@ -0,0 +1,175 @@ +from __future__ import annotations + +import math + +""" +Python3 stack implementation that retrieves min/max +elements of the stack in constant time +""" + + +class StackData: + """ + Object stored on the stack + """ + + def __init__( + self, current_value: float, min_value: float, max_value: float + ) -> None: + self.current_value = current_value + self.min_value = min_value + self.max_value = max_value + + +class MinMaxStack: + """ + Main stack implementation + """ + + def __init__(self, max_stack_size: int = 10) -> None: + self.max_size = max_stack_size + self.stack: list[StackData] = [] + + def push_value(self, value: float) -> bool: + """ + Push new value on top of stack + + >>> test_stack = MinMaxStack(3) + >>> test_stack.push_value(1) + True + >>> test_stack.push_value(2) + True + >>> test_stack.push_value(3) + True + >>> test_stack.push_value(4) + Traceback (most recent call last): + ... + Exception: Max stack size reached. + + """ + + if len(self.stack) == self.max_size: + raise Exception("Max stack size reached.") + + if len(self.stack) == 0: + self.stack.append(StackData(value, value, value)) + else: + """Store min/max values with current value""" + + new_min = min(self.stack[-1].min_value, value) + new_max = max(self.stack[-1].max_value, value) + self.stack.append(StackData(value, new_min, new_max)) + + return True + + def pop_value(self) -> float: + """ + Remove the top value from the stack. + + >>> test_stack = MinMaxStack() + >>> test_stack.push_value(1) + True + >>> test_stack.push_value(2) + True + >>> test_stack.pop_value() + 2 + >>> test_stack.pop_value() + 1 + >>> test_stack.pop_value() + Stack is empty + -inf + """ + + if self.stack_is_valid(): + return self.stack.pop().current_value + + return -math.inf + + def get_current_max(self) -> float: + """ + Get the highest value on the stack in constant time + + >>> test_stack = MinMaxStack(3) + >>> test_stack.push_value(-450.45) + True + >>> test_stack.push_value(450.45) + True + >>> test_stack.push_value(0) + True + >>> test_stack.get_current_max() + 450.45 + >>> test_stack.pop_value() + 0 + >>> test_stack.get_current_max() + 450.45 + >>> test_stack.pop_value() + 450.45 + >>> test_stack.get_current_max() + -450.45 + >>> test_stack.pop_value() + -450.45 + >>> test_stack.get_current_max() + Stack is empty + -inf + """ + if self.stack_is_valid(): + return self.stack[-1].max_value + + return -math.inf + + def get_current_min(self) -> float: + """ + Get the lowest value on the stack in constant time + + >>> test_stack = MinMaxStack(3) + >>> test_stack.push_value(123) + True + >>> test_stack.push_value(-123) + True + >>> test_stack.push_value(0) + True + >>> test_stack.get_current_min() + -123 + >>> test_stack.pop_value() + 0 + >>> test_stack.get_current_min() + -123 + >>> test_stack.pop_value() + -123 + >>> test_stack.get_current_min() + 123 + >>> test_stack.pop_value() + 123 + >>> test_stack.get_current_min() + Stack is empty + -inf + """ + if self.stack_is_valid(): + return self.stack[-1].min_value + + return -math.inf + + def stack_is_valid(self) -> bool: + """ + Validate stack is not empty + + >>> test_stack = MinMaxStack(3) + >>> test_stack.stack_is_valid() + Stack is empty + False + >>> test_stack.push_value(0) + True + >>> test_stack.stack_is_valid() + True + """ + if len(self.stack) == 0: + print("Stack is empty") + return False + + return True + + +if __name__ == "__main__": + from doctest import testmod + + testmod() diff --git a/data_structures/stacks/stack_using_two_queues.py b/data_structures/stacks/stack_using_two_queues.py index 4b73246a045c..c6687785de37 100644 --- a/data_structures/stacks/stack_using_two_queues.py +++ b/data_structures/stacks/stack_using_two_queues.py @@ -62,24 +62,25 @@ def peek(self) -> int | None: choice = input("Enter choice (1/2/3/4): ") - if choice == "1": - element = int(input("Enter an integer to push: ").strip()) - stack.push(element) - print(f"{element} pushed onto the stack.") - elif choice == "2": - popped_element = stack.pop() - if popped_element is not None: - print(f"Popped element: {popped_element}") - else: - print("Stack is empty.") - elif choice == "3": - peeked_element = stack.peek() - if peeked_element is not None: - print(f"Top element: {peeked_element}") - else: - print("Stack is empty.") - elif choice == "4": - del stack - stack = None - else: - print("Invalid choice. Please try again.") + match choice: + case "1": + element = int(input("Enter an integer to push: ").strip()) + stack.push(element) + print(f"{element} pushed onto the stack.") + case "2": + popped_element = stack.pop() + if popped_element is not None: + print(f"Popped element: {popped_element}") + else: + print("Stack is empty.") + case "3": + peeked_element = stack.peek() + if peeked_element is not None: + print(f"Top element: {peeked_element}") + else: + print("Stack is empty.") + case "4": + del stack + stack = None + case _: + print("Invalid choice. Please try again.") diff --git a/data_structures/stacks/stack_with_doubly_linked_list.py b/data_structures/stacks/stack_with_doubly_linked_list.py index 50c5236e073c..347ae8ec801c 100644 --- a/data_structures/stacks/stack_with_doubly_linked_list.py +++ b/data_structures/stacks/stack_with_doubly_linked_list.py @@ -3,19 +3,19 @@ from __future__ import annotations -from typing import Generic, TypeVar +from typing import TypeVar T = TypeVar("T") -class Node(Generic[T]): - def __init__(self, data: T): +class Node[T]: + def __init__(self, data: T) -> None: self.data = data # Assign data self.next: Node[T] | None = None # Initialize next as null self.prev: Node[T] | None = None # Initialize prev as null -class Stack(Generic[T]): +class Stack[T]: """ >>> stack = Stack() >>> stack.is_empty() diff --git a/data_structures/stacks/stack_with_singly_linked_list.py b/data_structures/stacks/stack_with_singly_linked_list.py index 8e77c2b967ef..6257c33a4ee8 100644 --- a/data_structures/stacks/stack_with_singly_linked_list.py +++ b/data_structures/stacks/stack_with_singly_linked_list.py @@ -3,13 +3,13 @@ from __future__ import annotations from collections.abc import Iterator -from typing import Generic, TypeVar +from typing import TypeVar T = TypeVar("T") -class Node(Generic[T]): - def __init__(self, data: T): +class Node[T]: + def __init__(self, data: T) -> None: self.data = data self.next: Node[T] | None = None @@ -17,7 +17,7 @@ def __str__(self) -> str: return f"{self.data}" -class LinkedStack(Generic[T]): +class LinkedStack[T]: """ Linked List Stack implementing push (to top), pop (from top) and is_empty diff --git a/data_structures/stacks/stock_span_problem.py b/data_structures/stacks/stock_span_problem.py index 5efe58d25798..7a364f0debb6 100644 --- a/data_structures/stacks/stock_span_problem.py +++ b/data_structures/stacks/stock_span_problem.py @@ -8,8 +8,29 @@ """ -def calculation_span(price, s): +def calculate_span(price: list[int]) -> list[int]: + """ + Calculate the span values for a given list of stock prices. + Args: + price: List of stock prices. + Returns: + List of span values. + + >>> calculate_span([10, 4, 5, 90, 120, 80]) + [1, 1, 2, 4, 5, 1] + >>> calculate_span([100, 50, 60, 70, 80, 90]) + [1, 1, 2, 3, 4, 5] + >>> calculate_span([5, 4, 3, 2, 1]) + [1, 1, 1, 1, 1] + >>> calculate_span([1, 2, 3, 4, 5]) + [1, 2, 3, 4, 5] + >>> calculate_span([10, 20, 30, 40, 50]) + [1, 2, 3, 4, 5] + >>> calculate_span([100, 80, 60, 70, 60, 75, 85]) + [1, 1, 1, 2, 1, 4, 6] + """ n = len(price) + s = [0] * n # Create a stack and push index of fist element to it st = [] st.append(0) @@ -21,31 +42,32 @@ def calculation_span(price, s): for i in range(1, n): # Pop elements from stack while stack is not # empty and top of stack is smaller than price[i] - while len(st) > 0 and price[st[0]] <= price[i]: + while len(st) > 0 and price[st[-1]] <= price[i]: st.pop() # If stack becomes empty, then price[i] is greater # than all elements on left of it, i.e. price[0], # price[1], ..price[i-1]. Else the price[i] is # greater than elements after top of stack - s[i] = i + 1 if len(st) <= 0 else (i - st[0]) + s[i] = i + 1 if len(st) <= 0 else (i - st[-1]) # Push this element to stack st.append(i) + return s + # A utility function to print elements of array -def print_array(arr, n): +def print_array(arr, n) -> None: for i in range(n): print(arr[i], end=" ") # Driver program to test above function price = [10, 4, 5, 90, 120, 80] -S = [0 for i in range(len(price) + 1)] -# Fill the span values in array S[] -calculation_span(price, S) +# Calculate the span values +S = calculate_span(price) # Print the calculated span values print_array(S, len(price)) diff --git a/data_structures/suffix_tree/tests/test_suffix_tree.py b/data_structures/suffix_tree/tests/test_suffix_tree.py index 45c6790ac48a..c9dbe199d19d 100644 --- a/data_structures/suffix_tree/tests/test_suffix_tree.py +++ b/data_structures/suffix_tree/tests/test_suffix_tree.py @@ -22,18 +22,18 @@ def test_search_existing_patterns(self) -> None: patterns = ["ana", "ban", "na"] for pattern in patterns: with self.subTest(pattern=pattern): - assert self.suffix_tree.search( - pattern - ), f"Pattern '{pattern}' should be found." + assert self.suffix_tree.search(pattern), ( + f"Pattern '{pattern}' should be found." + ) def test_search_non_existing_patterns(self) -> None: """Test searching for patterns that do not exist in the suffix tree.""" patterns = ["xyz", "apple", "cat"] for pattern in patterns: with self.subTest(pattern=pattern): - assert not self.suffix_tree.search( - pattern - ), f"Pattern '{pattern}' should not be found." + assert not self.suffix_tree.search(pattern), ( + f"Pattern '{pattern}' should not be found." + ) def test_search_empty_pattern(self) -> None: """Test searching for an empty pattern.""" @@ -41,18 +41,18 @@ def test_search_empty_pattern(self) -> None: def test_search_full_text(self) -> None: """Test searching for the full text.""" - assert self.suffix_tree.search( - self.text - ), "The full text should be found in the suffix tree." + assert self.suffix_tree.search(self.text), ( + "The full text should be found in the suffix tree." + ) def test_search_substrings(self) -> None: """Test searching for substrings of the full text.""" substrings = ["ban", "ana", "a", "na"] for substring in substrings: with self.subTest(substring=substring): - assert self.suffix_tree.search( - substring - ), f"Substring '{substring}' should be found." + assert self.suffix_tree.search(substring), ( + f"Substring '{substring}' should be found." + ) if __name__ == "__main__": diff --git a/data_structures/trie/radix_tree.py b/data_structures/trie/radix_tree.py index caf566a6ce30..11e0dc23faa9 100644 --- a/data_structures/trie/radix_tree.py +++ b/data_structures/trie/radix_tree.py @@ -1,9 +1,11 @@ """ A Radix Tree is a data structure that represents a space-optimized -trie (prefix tree) in whicheach node that is the only child is merged +trie (prefix tree) in which each node that is the only child is merged with its parent [https://en.wikipedia.org/wiki/Radix_tree] """ +import unittest + class RadixNode: def __init__(self, prefix: str = "", is_leaf: bool = False) -> None: @@ -62,6 +64,11 @@ def insert(self, word: str) -> None: -- A (leaf) --- A (leaf) """ + ## Handle the Case where the word is empty by using an if branch + if word == "": + self.is_leaf = True + return + # Case 1: If the word is the prefix of the node # Solution: We set the current node as leaf if self.prefix == word and not self.is_leaf: @@ -80,11 +87,11 @@ def insert(self, word: str) -> None: ) # Case 3: The node prefix is equal to the matching - # Solution: We insert remaining word on the next node + # Solution: We insert the remaining word on the next node if remaining_prefix == "": self.nodes[matching_string[0]].insert(remaining_word) - # Case 4: The word is greater equal to the matching + # Case 4: The word is greater than or equal to the matching # Solution: Create a node in between both nodes, change # prefixes and add the new node for the remaining word else: @@ -100,7 +107,7 @@ def insert(self, word: str) -> None: self.nodes[matching_string[0]].insert(remaining_word) def find(self, word: str) -> bool: - """Returns if the word is on the tree + """Returns whether the word is on the tree Args: word (str): word to check @@ -115,7 +122,7 @@ def find(self, word: str) -> bool: if not incoming_node: return False else: - matching_string, remaining_prefix, remaining_word = incoming_node.match( + _matching_string, remaining_prefix, remaining_word = incoming_node.match( word ) # If there is remaining prefix, the word can't be on the tree @@ -144,7 +151,7 @@ def delete(self, word: str) -> bool: if not incoming_node: return False else: - matching_string, remaining_prefix, remaining_word = incoming_node.match( + _matching_string, remaining_prefix, remaining_word = incoming_node.match( word ) # If there is remaining prefix, the word can't be on the tree @@ -191,7 +198,7 @@ def print_tree(self, height: int = 0) -> None: value.print_tree(height + 1) -def test_trie() -> bool: +def test_trie() -> None: words = "banana bananas bandana band apple all beast".split() root = RadixNode() root.insert_many(words) @@ -205,25 +212,41 @@ def test_trie() -> bool: assert not root.find("banana") assert root.find("bananas") - return True - -def pytests() -> None: - assert test_trie() +class TestRadixNode(unittest.TestCase): + def test_trie(self) -> None: + words = "banana bananas bandana band apple all beast".split() + root = RadixNode() + root.insert_many(words) + assert all(root.find(word) for word in words) + assert not root.find("bandanas") + assert not root.find("apps") + root.delete("all") + assert not root.find("all") + root.delete("banana") + assert not root.find("banana") + assert root.find("bananas") -def main() -> None: - """ - >>> pytests() - """ - root = RadixNode() - words = "banana bananas bandanas bandana band apple all beast".split() - root.insert_many(words) + def test_trie_2(self) -> None: + """ + Now add a new test case that inserts + foobbb, fooaaa, foo in the given order and checks + for different assertions + """ + words = "foobbb fooaaa foo".split() + root = RadixNode() + root.insert_many(words) - print("Words:", words) - print("Tree:") - root.print_tree() + assert all(root.find(word) for word in words) + root.delete("foo") + assert not root.find("foo") + assert root.find("foobbb") + assert root.find("fooaaa") if __name__ == "__main__": - main() + import doctest + + doctest.testmod() + unittest.main() diff --git a/digital_image_processing/change_brightness.py b/digital_image_processing/change_brightness.py index 97493f1a399e..b6ebcc9371c6 100644 --- a/digital_image_processing/change_brightness.py +++ b/digital_image_processing/change_brightness.py @@ -1,9 +1,36 @@ from PIL import Image -def change_brightness(img: Image, level: float) -> Image: +def change_brightness(img: Image.Image, level: float) -> Image.Image: """ Change the brightness of a PIL Image to a given level. + + Args: + img: PIL Image to adjust + level: Brightness level adjustment (-255.0 to 255.0) + Negative values darken, positive values brighten + + Returns: + New PIL Image with adjusted brightness + + Raises: + ValueError: If level is not in range [-255.0, 255.0] + + >>> from PIL import Image + >>> import numpy as np + >>> img = Image.new('RGB', (2, 2), color=(100, 100, 100)) + >>> bright = change_brightness(img, 50) + >>> px = bright.load() + >>> px[0, 0] + (150, 150, 150) + >>> dark = change_brightness(img, -50) + >>> px_dark = dark.load() + >>> px_dark[0, 0] + (50, 50, 50) + >>> change_brightness(img, 300) + Traceback (most recent call last): + ... + ValueError: level must be between -255.0 (black) and 255.0 (white) """ def brightness(c: int) -> float: diff --git a/digital_image_processing/change_contrast.py b/digital_image_processing/change_contrast.py index 7e49694708f8..80ed53de6308 100644 --- a/digital_image_processing/change_contrast.py +++ b/digital_image_processing/change_contrast.py @@ -11,7 +11,7 @@ from PIL import Image -def change_contrast(img: Image, level: int) -> Image: +def change_contrast(img: Image.Image, level: int) -> Image.Image: """ Function to change contrast """ diff --git a/digital_image_processing/dithering/burkes.py b/digital_image_processing/dithering/burkes.py index 4b59356d8f08..d9aa11849cc1 100644 --- a/digital_image_processing/dithering/burkes.py +++ b/digital_image_processing/dithering/burkes.py @@ -16,7 +16,7 @@ class Burkes: * This implementation get RGB image and converts it to greyscale in runtime. """ - def __init__(self, input_img, threshold: int): + def __init__(self, input_img, threshold: int) -> None: self.min_threshold = 0 # max greyscale value for #FFFFFF self.max_threshold = int(self.get_greyscale(255, 255, 255)) diff --git a/digital_image_processing/edge_detection/canny.py b/digital_image_processing/edge_detection/canny.py index 944161c31cfc..450e061f712d 100644 --- a/digital_image_processing/edge_detection/canny.py +++ b/digital_image_processing/edge_detection/canny.py @@ -72,7 +72,7 @@ def suppress_non_maximum(image_shape, gradient_direction, sobel_grad): def detect_high_low_threshold( image_shape, destination, threshold_low, threshold_high, weak, strong -): +) -> None: """ High-Low threshold detection. If an edge pixel's gradient value is higher than the high threshold value, it is marked as a strong edge pixel. If an @@ -91,7 +91,7 @@ def detect_high_low_threshold( destination[row, col] = weak -def track_edge(image_shape, destination, weak, strong): +def track_edge(image_shape, destination, weak, strong) -> None: """ Edge tracking. Usually a weak edge pixel caused from true edges will be connected to a strong edge pixel while noise responses are unconnected. As long as there is diff --git a/digital_image_processing/filters/local_binary_pattern.py b/digital_image_processing/filters/local_binary_pattern.py index 861369ba6a32..ac54ecce755c 100644 --- a/digital_image_processing/filters/local_binary_pattern.py +++ b/digital_image_processing/filters/local_binary_pattern.py @@ -19,7 +19,7 @@ def get_neighbors_pixel( try: return int(image[x_coordinate][y_coordinate] >= center) - except (IndexError, TypeError): + except IndexError, TypeError: return 0 diff --git a/digital_image_processing/histogram_equalization/histogram_stretch.py b/digital_image_processing/histogram_equalization/histogram_stretch.py index 1270c964dee6..f5bab685b746 100644 --- a/digital_image_processing/histogram_equalization/histogram_stretch.py +++ b/digital_image_processing/histogram_equalization/histogram_stretch.py @@ -13,7 +13,7 @@ class ConstantStretch: - def __init__(self): + def __init__(self) -> None: self.img = "" self.original_image = "" self.last_list = [] @@ -24,7 +24,7 @@ def __init__(self): self.number_of_rows = 0 self.number_of_cols = 0 - def stretch(self, input_image): + def stretch(self, input_image) -> None: self.img = cv2.imread(input_image, 0) self.original_image = copy.deepcopy(self.img) x, _, _ = plt.hist(self.img.ravel(), 256, [0, 256], label="x") @@ -46,10 +46,10 @@ def stretch(self, input_image): self.img[j][i] = self.last_list[num] cv2.imwrite("output_data/output.jpg", self.img) - def plot_histogram(self): + def plot_histogram(self) -> None: plt.hist(self.img.ravel(), 256, [0, 256]) - def show_image(self): + def show_image(self) -> None: cv2.imshow("Output-Image", self.img) cv2.imshow("Input-Image", self.original_image) cv2.waitKey(5000) diff --git a/digital_image_processing/index_calculation.py b/digital_image_processing/index_calculation.py index 988f8e72b9a8..b09573f4a521 100644 --- a/digital_image_processing/index_calculation.py +++ b/digital_image_processing/index_calculation.py @@ -104,10 +104,14 @@ class IndexCalculation: #RGBIndex = ["GLI", "CI", "Hue", "I", "NGRDI", "RI", "S", "IF"] """ - def __init__(self, red=None, green=None, blue=None, red_edge=None, nir=None): + def __init__( + self, red=None, green=None, blue=None, red_edge=None, nir=None + ) -> None: self.set_matricies(red=red, green=green, blue=blue, red_edge=red_edge, nir=nir) - def set_matricies(self, red=None, green=None, blue=None, red_edge=None, nir=None): + def set_matricies( + self, red=None, green=None, blue=None, red_edge=None, nir=None + ) -> bool: if red is not None: self.red = red if green is not None: diff --git a/digital_image_processing/resize/resize.py b/digital_image_processing/resize/resize.py index 7bde118da69b..d977a1ab7418 100644 --- a/digital_image_processing/resize/resize.py +++ b/digital_image_processing/resize/resize.py @@ -10,7 +10,7 @@ class NearestNeighbour: Source: https://en.wikipedia.org/wiki/Nearest-neighbor_interpolation """ - def __init__(self, img, dst_width: int, dst_height: int): + def __init__(self, img, dst_width: int, dst_height: int) -> None: if dst_width < 0 or dst_height < 0: raise ValueError("Destination width/height should be > 0") @@ -27,7 +27,7 @@ def __init__(self, img, dst_width: int, dst_height: int): np.ones((self.dst_h, self.dst_w, 3), np.uint8) * 255 ) - def process(self): + def process(self) -> None: for i in range(self.dst_h): for j in range(self.dst_w): self.output[i][j] = self.img[self.get_y(i)][self.get_x(j)] diff --git a/digital_image_processing/test_digital_image_processing.py b/digital_image_processing/test_digital_image_processing.py index d1200f4d65ca..4bc0fb94b900 100644 --- a/digital_image_processing/test_digital_image_processing.py +++ b/digital_image_processing/test_digital_image_processing.py @@ -24,14 +24,14 @@ # Test: convert_to_negative() -def test_convert_to_negative(): +def test_convert_to_negative() -> None: negative_img = cn.convert_to_negative(img) # assert negative_img array for at least one True assert negative_img.any() # Test: change_contrast() -def test_change_contrast(): +def test_change_contrast() -> None: with Image.open("digital_image_processing/image_data/lena_small.jpg") as img: # Work around assertion for response assert str(cc.change_contrast(img, 110)).startswith( @@ -40,14 +40,14 @@ def test_change_contrast(): # canny.gen_gaussian_kernel() -def test_gen_gaussian_kernel(): +def test_gen_gaussian_kernel() -> None: resp = canny.gen_gaussian_kernel(9, sigma=1.4) # Assert ambiguous array assert resp.all() # canny.py -def test_canny(): +def test_canny() -> None: canny_img = imread("digital_image_processing/image_data/lena_small.jpg", 0) # assert ambiguous array for all == True assert canny_img.all() @@ -57,33 +57,35 @@ def test_canny(): # filters/gaussian_filter.py -def test_gen_gaussian_kernel_filter(): +def test_gen_gaussian_kernel_filter() -> None: assert gg.gaussian_filter(gray, 5, sigma=0.9).all() -def test_convolve_filter(): +def test_convolve_filter() -> None: # laplace diagonals laplace = array([[0.25, 0.5, 0.25], [0.5, -3, 0.5], [0.25, 0.5, 0.25]]) res = conv.img_convolve(gray, laplace).astype(uint8) assert res.any() -def test_median_filter(): +def test_median_filter() -> None: assert med.median_filter(gray, 3).any() -def test_sobel_filter(): +def test_sobel_filter() -> None: grad, theta = sob.sobel_filter(gray) assert grad.any() assert theta.any() -def test_sepia(): +def test_sepia() -> None: sepia = sp.make_sepia(img, 20) assert sepia.all() -def test_burkes(file_path: str = "digital_image_processing/image_data/lena_small.jpg"): +def test_burkes( + file_path: str = "digital_image_processing/image_data/lena_small.jpg", +) -> None: burkes = bs.Burkes(imread(file_path, 1), 120) burkes.process() assert burkes.output_img.any() @@ -91,13 +93,13 @@ def test_burkes(file_path: str = "digital_image_processing/image_data/lena_small def test_nearest_neighbour( file_path: str = "digital_image_processing/image_data/lena_small.jpg", -): +) -> None: nn = rs.NearestNeighbour(imread(file_path, 1), 400, 200) nn.process() assert nn.output.any() -def test_local_binary_pattern(): +def test_local_binary_pattern() -> None: # pull request 10161 before: # "digital_image_processing/image_data/lena.jpg" # after: "digital_image_processing/image_data/lena_small.jpg" diff --git a/divide_and_conquer/convex_hull.py b/divide_and_conquer/convex_hull.py index 93f6daf1f88c..24eec4af23d8 100644 --- a/divide_and_conquer/convex_hull.py +++ b/divide_and_conquer/convex_hull.py @@ -45,43 +45,43 @@ class Point: ValueError: could not convert string to float: 'pi' """ - def __init__(self, x, y): + def __init__(self, x, y) -> None: self.x, self.y = float(x), float(y) - def __eq__(self, other): + def __eq__(self, other) -> bool: return self.x == other.x and self.y == other.y - def __ne__(self, other): + def __ne__(self, other) -> bool: return not self == other - def __gt__(self, other): + def __gt__(self, other) -> bool: if self.x > other.x: return True elif self.x == other.x: return self.y > other.y return False - def __lt__(self, other): + def __lt__(self, other) -> bool: return not self > other - def __ge__(self, other): + def __ge__(self, other) -> bool: if self.x > other.x: return True elif self.x == other.x: return self.y >= other.y return False - def __le__(self, other): + def __le__(self, other) -> bool: if self.x < other.x: return True elif self.x == other.x: return self.y <= other.y return False - def __repr__(self): + def __repr__(self) -> str: return f"({self.x}, {self.y})" - def __hash__(self): + def __hash__(self) -> int: return hash(self.x) @@ -124,7 +124,7 @@ def _construct_points( else: try: points.append(Point(p[0], p[1])) - except (IndexError, TypeError): + except IndexError, TypeError: print( f"Ignoring deformed point {p}. All points" " must have at least 2 coordinates." @@ -451,11 +451,10 @@ def convex_hull_melkman(points: list[Point]) -> list[Point]: if det > 0: convex_hull.insert(0, points[i]) break - elif det < 0: + if det < 0: convex_hull.append(points[i]) break - else: - convex_hull[1] = points[i] + convex_hull[1] = points[i] i += 1 for j in range(i, n): @@ -477,7 +476,7 @@ def convex_hull_melkman(points: list[Point]) -> list[Point]: return sorted(convex_hull[1:] if len(convex_hull) > 3 else convex_hull) -def main(): +def main() -> None: points = [ (0, 3), (2, 2), diff --git a/divide_and_conquer/heaps_algorithm.py b/divide_and_conquer/heaps_algorithm.py index af30ad664101..3235d59e5d90 100644 --- a/divide_and_conquer/heaps_algorithm.py +++ b/divide_and_conquer/heaps_algorithm.py @@ -32,7 +32,7 @@ def heaps(arr: list) -> list: res = [] - def generate(k: int, arr: list): + def generate(k: int, arr: list) -> None: if k == 1: res.append(tuple(arr[:])) return diff --git a/divide_and_conquer/heaps_algorithm_iterative.py b/divide_and_conquer/heaps_algorithm_iterative.py index 4dab41f539c0..6701489b304c 100644 --- a/divide_and_conquer/heaps_algorithm_iterative.py +++ b/divide_and_conquer/heaps_algorithm_iterative.py @@ -32,7 +32,7 @@ def heaps(arr: list) -> list: res = [] - def generate(n: int, arr: list): + def generate(n: int, arr: list) -> None: c = [0] * n res.append(tuple(arr)) diff --git a/divide_and_conquer/inversions.py b/divide_and_conquer/inversions.py index 35f78fe5cf1e..6fe1fd9c7cb7 100644 --- a/divide_and_conquer/inversions.py +++ b/divide_and_conquer/inversions.py @@ -9,7 +9,7 @@ """ -def count_inversions_bf(arr): +def count_inversions_bf(arr: list[int]) -> int: """ Counts the number of inversions using a naive brute-force algorithm Parameters @@ -40,7 +40,7 @@ def count_inversions_bf(arr): return num_inversions -def count_inversions_recursive(arr): +def count_inversions_recursive(arr: list[int]) -> tuple[list[int], int]: """ Counts the number of inversions using a divide-and-conquer algorithm Parameters @@ -74,7 +74,7 @@ def count_inversions_recursive(arr): return c, num_inversions -def _count_cross_inversions(p, q): +def _count_cross_inversions(p: list[int], q: list[int]) -> tuple[list[int], int]: """ Counts the inversions across two sorted arrays. And combine the two arrays into one sorted array @@ -118,7 +118,7 @@ def _count_cross_inversions(p, q): return r, num_inversion -def main(): +def main() -> None: arr_1 = [10, 2, 1, 5, 5, 2, 11] # this arr has 8 inversions: diff --git a/divide_and_conquer/minimum_element_of_array.py b/divide_and_conquer/minimum_element_of_array.py new file mode 100644 index 000000000000..b0f5ac03d031 --- /dev/null +++ b/divide_and_conquer/minimum_element_of_array.py @@ -0,0 +1,129 @@ +""" +Return the minimum element of an array using the +divide-and-conquer algorithm for selection sort. +Like quicksort, it partitions the input array recursively. +But unlike quicksort, +which recursively processes both sides of the partition, +this algorithm works on only one side of the partition. +The expected running time of this selection sort algorithm is 0(n), +assuming that the elements are distinct. +It returns the ith smallest element of the array A[p: r], where 1 ≤ i ≤ r-p+1. +(From Introduction to Algorithms, Fourth Edition, Cormen, 2022: Chapter 9.2) +""" + +from __future__ import annotations + +import random + + +def partition(array: list, starting_index: int, ending_index: int) -> int: + """ + Partition the array. + Args: + array: list of elements + starting_index: starting index of the array + ending_index: ending index of the array + + Returns: + index of the pivot + + >>> arr = [-2, 3, -10, 11, 99, 100000, 100, -200] + >>> partition(arr, 0, len(arr) - 1) + 0 + """ + pivot = array[ending_index] + i = starting_index - 1 + for j in range(starting_index, ending_index): + if array[j] <= pivot: + i += 1 + array[i], array[j] = array[j], array[i] + array[i + 1], array[ending_index] = array[ending_index], array[i + 1] + return i + 1 + + +def randomized_partition(array: list, starting_index: int, ending_index: int) -> int: + """ + Randomized partition of the array. + Args: + array: list of elements + starting_index: starting index of the array + ending_index: ending index of the array + + Returns: + call to partition function + + >>> arr = [-2, 3, -10, 11, 99, 100000, 100, -200] + >>> arr1 = randomized_partition(arr, 0, len(arr) - 1) + >>> arr == arr1 + False + """ + + rand_idx = random.randint(starting_index, ending_index) + array[rand_idx], array[ending_index] = array[ending_index], array[rand_idx] + return partition(array, starting_index, ending_index) + + +def selection_sort( + array: list, starting_index: int, ending_index: int, smallest_element: int +) -> list | None: + """ + Returns a list of sorted array elements using selection sort. + Using selection to find a minimum is O(n) overkill vs. a linear scan — the + value here is the DAC/partition demonstration. + + Args: + array: list of elements + starting_index: starting index of the array + ending_index: ending index of the array + smallest_element: the ith smallest element of + the array A[p: r], where 1 ≤ i ≤ r-p+1 + + Returns: + sorted array + + >>> from random import shuffle + >>> arr = [-2, 3, -10, 11, 99, 100000, 100, -200] + >>> shuffle(arr) + >>> selection_sort(arr, 0, len(arr) - 1, 1) + -200 + + >>> shuffle(arr) + >>> selection_sort(arr, 0, len(arr) - 1, 1) + -200 + + >>> arr = [-200] + >>> selection_sort(arr, 0, len(arr) - 1, 1) + -200 + + >>> arr = [-2] + >>> selection_sort(arr, 0, len(arr) - 1, 1) + -2 + + >>> arr = [] + >>> selection_sort(arr, 0, len(arr) - 1, 1) + [] + """ + + if not array: + return array + + if starting_index == ending_index: + # 1 <= i <= r - p + 1 when p == r means that i == 1 + return array[starting_index] + + q = randomized_partition(array, starting_index, ending_index) + + k = q - starting_index + 1 + + if smallest_element == k: + return array[q] # the pivot value is the answer + if smallest_element < k: + return selection_sort(array, starting_index, q - 1, smallest_element) + else: + return selection_sort(array, q + 1, ending_index, smallest_element - k) + + +if __name__ == "__main__": + import doctest + + doctest.testmod() diff --git a/divide_and_conquer/power.py b/divide_and_conquer/power.py index faf6a3476d40..492ee6dd12f0 100644 --- a/divide_and_conquer/power.py +++ b/divide_and_conquer/power.py @@ -1,4 +1,4 @@ -def actual_power(a: int, b: int): +def actual_power(a: int, b: int) -> int: """ Function using divide and conquer to calculate a^b. It only works for integer a,b. @@ -19,10 +19,12 @@ def actual_power(a: int, b: int): """ if b == 0: return 1 + half = actual_power(a, b // 2) + if (b % 2) == 0: - return actual_power(a, int(b / 2)) * actual_power(a, int(b / 2)) + return half * half else: - return a * actual_power(a, int(b / 2)) * actual_power(a, int(b / 2)) + return a * half * half def power(a: int, b: int) -> float: @@ -43,9 +45,9 @@ def power(a: int, b: int) -> float: -0.125 """ if b < 0: - return 1 / actual_power(a, b) + return 1 / actual_power(a, -b) return actual_power(a, b) if __name__ == "__main__": - print(power(-2, -3)) + print(power(-2, -3)) # output -0.125 diff --git a/divide_and_conquer/strassen_matrix_multiplication.py b/divide_and_conquer/strassen_matrix_multiplication.py index f529a255d2ef..8b0ab3b7ded1 100644 --- a/divide_and_conquer/strassen_matrix_multiplication.py +++ b/divide_and_conquer/strassen_matrix_multiplication.py @@ -1,3 +1,7 @@ +""" +https://en.wikipedia.org/wiki/Strassen_algorithm +""" + from __future__ import annotations import math @@ -32,7 +36,7 @@ def matrix_subtraction(matrix_a: list, matrix_b: list): def split_matrix(a: list) -> tuple[list, list, list, list]: """ - Given an even length matrix, returns the top_left, top_right, bot_left, bot_right + Given an even-length matrix, returns the top_left, top_right, bot_left, bot_right quadrant. >>> split_matrix([[4,3,2,4],[2,3,1,1],[6,5,4,3],[8,4,1,6]]) @@ -49,18 +53,20 @@ def split_matrix(a: list) -> tuple[list, list, list, list]: if len(a) % 2 != 0 or len(a[0]) % 2 != 0: raise Exception("Odd matrices are not supported!") - matrix_length = len(a) - mid = matrix_length // 2 + def extract_submatrix(rows, cols): + return [[a[i][j] for j in cols] for i in rows] - top_right = [[a[i][j] for j in range(mid, matrix_length)] for i in range(mid)] - bot_right = [ - [a[i][j] for j in range(mid, matrix_length)] for i in range(mid, matrix_length) - ] + mid = len(a) // 2 - top_left = [[a[i][j] for j in range(mid)] for i in range(mid)] - bot_left = [[a[i][j] for j in range(mid)] for i in range(mid, matrix_length)] + rows_top, rows_bot = range(mid), range(mid, len(a)) + cols_left, cols_right = range(mid), range(mid, len(a)) - return top_left, top_right, bot_left, bot_right + return ( + extract_submatrix(rows_top, cols_left), # Top-left + extract_submatrix(rows_top, cols_right), # Top-right + extract_submatrix(rows_bot, cols_left), # Bottom-left + extract_submatrix(rows_bot, cols_right), # Bottom-right + ) def matrix_dimensions(matrix: list) -> tuple[int, int]: @@ -74,7 +80,36 @@ def print_matrix(matrix: list) -> None: def actual_strassen(matrix_a: list, matrix_b: list) -> list: """ Recursive function to calculate the product of two matrices, using the Strassen - Algorithm. It only supports square matrices of any size that is a power of 2. + Algorithm. + + Time complexity: + The recurrence is T(n) = 7 T(n/2) + \u0398(n^2), which solves to + T(n) = \u0398(n^{log_2 7}) \u2248 \u0398(n^{2.8074}). This is asymptotically + faster than the naive \u0398(n^3) algorithm for sufficiently large n. + + Space complexity: + Uses additional memory for temporary submatrices and padding; overall + space complexity is O(n^2). + + Notes: + This function expects square matrices whose size is a power of two. + Matrices of other sizes are handled by `strassen` which pads to the + next power of two. + + It only supports square matrices of any size that is a power of 2. + + Strassen's algorithm reduces the number of recursive multiplications needed to + multiply two n x n matrices from the 8 required by the naive divide-and-conquer + approach down to 7, at the cost of a few extra matrix additions/subtractions + (which are cheaper, O(n^2), operations). Each matrix is split into four + (n/2) x (n/2) quadrants; 7 products of quadrant combinations are computed + recursively, and those products are combined with additions/subtractions to + form the four quadrants of the result. + + Time complexity: O(n^log2(7)) ~= O(n^2.807), an improvement over the O(n^3) of + the standard/naive matrix multiplication algorithm. + Space complexity: O(n^2) for storing the intermediate quadrant matrices, plus + O(log n) recursion stack depth. """ if matrix_dimensions(matrix_a) == (2, 2): return default_matrix_multiplication(matrix_a, matrix_b) @@ -106,6 +141,24 @@ def actual_strassen(matrix_a: list, matrix_b: list) -> list: def strassen(matrix1: list, matrix2: list) -> list: """ + Multiply two matrices using Strassen's divide-and-conquer algorithm. + + Time complexity: + \u0398(n^{log_2 7}) \u2248 \u0398(n^{2.8074}) + (recurrence T(n) = 7 T(n/2) + \u0398(n^2)). + + Space complexity: + O(n^2) due to padding and temporary matrices used during recursion. + + Multiply two matrices using Strassen's algorithm, which runs in + O(n^log2(7)) ~= O(n^2.807) time, compared to O(n^3) for naive matrix + multiplication. This implementation pads both input matrices with zeros + until they are square matrices whose dimension is a power of 2 (required + by the divide-and-conquer recursion in actual_strassen), performs the + multiplication, then trims the padding back off the result. + + Examples: + >>> strassen([[2,1,3],[3,4,6],[1,4,2],[7,6,7]], [[4,2,3,4],[2,1,1,1],[8,6,4,2]]) [[34, 23, 19, 15], [68, 46, 37, 28], [28, 18, 15, 12], [96, 62, 55, 48]] >>> strassen([[3,7,5,6,9],[1,5,3,7,8],[1,4,4,5,7]], [[2,4],[5,2],[1,7],[5,5],[7,8]]) diff --git a/data_structures/queue/__init__.py b/divide_and_conquer/tests/__init__.py similarity index 100% rename from data_structures/queue/__init__.py rename to divide_and_conquer/tests/__init__.py diff --git a/divide_and_conquer/tests/test_strassen_matrix_multiplication.py b/divide_and_conquer/tests/test_strassen_matrix_multiplication.py new file mode 100644 index 000000000000..d3ed399adfbd --- /dev/null +++ b/divide_and_conquer/tests/test_strassen_matrix_multiplication.py @@ -0,0 +1,47 @@ +import pytest + +from divide_and_conquer.strassen_matrix_multiplication import split_matrix + + +def test_4x4_matrix(): + matrix = [[4, 3, 2, 4], [2, 3, 1, 1], [6, 5, 4, 3], [8, 4, 1, 6]] + expected = ([[4, 3], [2, 3]], [[2, 4], [1, 1]], [[6, 5], [8, 4]], [[4, 3], [1, 6]]) + assert split_matrix(matrix) == expected + + +def test_8x8_matrix(): + matrix = [ + [4, 3, 2, 4, 4, 3, 2, 4], + [2, 3, 1, 1, 2, 3, 1, 1], + [6, 5, 4, 3, 6, 5, 4, 3], + [8, 4, 1, 6, 8, 4, 1, 6], + [4, 3, 2, 4, 4, 3, 2, 4], + [2, 3, 1, 1, 2, 3, 1, 1], + [6, 5, 4, 3, 6, 5, 4, 3], + [8, 4, 1, 6, 8, 4, 1, 6], + ] + expected = ( + [[4, 3, 2, 4], [2, 3, 1, 1], [6, 5, 4, 3], [8, 4, 1, 6]], + [[4, 3, 2, 4], [2, 3, 1, 1], [6, 5, 4, 3], [8, 4, 1, 6]], + [[4, 3, 2, 4], [2, 3, 1, 1], [6, 5, 4, 3], [8, 4, 1, 6]], + [[4, 3, 2, 4], [2, 3, 1, 1], [6, 5, 4, 3], [8, 4, 1, 6]], + ) + assert split_matrix(matrix) == expected + + +def test_invalid_odd_matrix(): + matrix = [[1, 2, 3], [4, 5, 6], [7, 8, 9]] + with pytest.raises(Exception, match="Odd matrices are not supported!"): + split_matrix(matrix) + + +def test_invalid_non_square_matrix(): + matrix = [ + [1, 2, 3, 4], + [5, 6, 7, 8], + [9, 10, 11, 12], + [13, 14, 15, 16], + [17, 18, 19, 20], + ] + with pytest.raises(Exception, match="Odd matrices are not supported!"): + split_matrix(matrix) diff --git a/machine_learning/lstm/__init__.py b/docs/__init__.py similarity index 100% rename from machine_learning/lstm/__init__.py rename to docs/__init__.py diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000000..5e3653860b8a --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,102 @@ +# Configuration file for the Sphinx documentation builder. +# https://www.sphinx-doc.org/en/master/usage/configuration.html +# +# Project metadata (name/version/authors) is single-sourced from pyproject.toml +# so it never drifts from the packaging metadata. +import tomllib +from pathlib import Path + +_pyproject = tomllib.loads( + (Path(__file__).parent.parent / "pyproject.toml").read_text(encoding="utf-8") +) +_project = _pyproject["project"] + +project = _project["name"] +author = ", ".join(a["name"] for a in _project.get("authors", [])) +release = version = _project["version"] +copyright = "2014, TheAlgorithms" # noqa: A001 # Sphinx requires this exact name + +extensions = [ + "autoapi.extension", + "myst_parser", +] + +autoapi_dirs = [ + "audio_filters", + "backtracking", + "bit_manipulation", + "blockchain", + "boolean_algebra", + "cellular_automata", + "ciphers", + "computer_vision", + "conversions", + "data_compression", + "data_structures", + "digital_image_processing", + "divide_and_conquer", + "dynamic_programming", + "electronics", + "file_transfer", + "financial", + "fractals", + "fuzzy_logic", + "genetic_algorithm", + "geodesy", + "geometry", + "graphics", + "graphs", + "greedy_methods", + "hashes", + "knapsack", + "linear_algebra", + "linear_programming", + "machine_learning", + "maths", + "matrix", + "networking_flow", + "neural_network", + "other", + "physics", + "project_euler", + "quantum", + "scheduling", + "searches", + "sorts", + "strings", + "web_programming", +] +autoapi_member_order = "groupwise" + +exclude_patterns = [ + ".*/*", + "docs/", +] + +html_theme = "alabaster" +html_static_path = ["_static"] +templates_path = ["_templates"] + +source_suffix = { + ".rst": "restructuredtext", + ".md": "markdown", +} + +myst_enable_extensions = [ + "amsmath", + "attrs_inline", + "colon_fence", + "deflist", + "dollarmath", + "fieldlist", + "html_admonition", + "html_image", + "replacements", + "smartquotes", + "strikethrough", + "substitution", + "tasklist", +] +myst_fence_as_directive = [ + "include", +] diff --git a/docs/hacktober_2026_prep.md b/docs/hacktober_2026_prep.md new file mode 100644 index 000000000000..f89bdcc9daf3 --- /dev/null +++ b/docs/hacktober_2026_prep.md @@ -0,0 +1,2076 @@ +# Hacktoberfest 2026 preparation — open PR cleanup tracker + +This file tracks the cleanup of open pull requests ahead of [Hacktoberfest 2026](https://hacktoberfest.com) so the queue is ready for the October influx of contributions. + +Each of the `scripts/close_pull_requests_with_*.sh` jobs is run one at a time by a maintainer. After each run, the affected lines below are checked off (`[ ]` -> `[x]`), their labels replaced with "closed by