Compact Python pseudocode for explaining algorithms. Clarity over correctness.

For ML researchers in markdown, comments, and chat. Not for formal papers (use typst lovelace/algo packages) or teaching non-programmers (use traditional pseudocode with IF...THEN...ENDIF).

Pseudocode is "a mix of programming language conventions with compact mathematical notation, intended for human reading rather than machine control." No broad standard exists. This is mathematical style pseudocode (a.k.a. pidgin Python).

• For humans, not machines -- not runnable, not compiled, omits implementation details
• Programming language + math notation -- Python control flow (for, def, @) mixed with unicode math (θ ← θ - α * ∇ℒ)
• Match the paper -- variable names and notation should look like the equations they implement
• Skip boilerplate, keep structure -- no imports/.to(device), keep the algorithm shape

• Python syntax (def, for, slicing, @) but not runnable
• Greek unicode for math variables: ε θ λ μ σ δ Σ ∇
• ← for conceptual assignment, = for definitions
• Shapes in trailing comments: # x ∈ ℝ^{b×d}
• # ── section dividers for algorithm steps
• Short aliases: svd, sol, norm, inv, eig
• Skip: imports, boilerplate, .to(device), error handling
• ... for obvious/boring parts
• Few comments; only when intent is non-obvious
• Short names: single-letter dims b s h d, suffixes for spaces _proj _hat
• x̂ ŷ W̃ (combining diacritics) are valid Python identifiers — use them

The whole point is leveraging Python's readability -- for, if, while, def already read like pseudocode. No need to invent a parallel comment language.

Traditional pseudocode (VCAA, CLRS, textbooks) uses IF...THEN...ELSE...ENDIF, WHILE...DO...ENDWHILE, SET x TO 5, PRINT. That's for audiences who don't know a programming language. We skip all that because Python's own syntax is already more readable than those keywords.

• Subscript digits ₁₂₃ — not valid identifiers, use x[i] or x_1
• √ — use sqrt() or **0.5
• ½ ⅓ — use 0.5, 1/3
• Fancy arrows → ⟶ in code — use ← for assignment, # comments for the rest

# ── Forward ─────────────────
def predict(x, θ):
    z = encode(x)              # z ∈ ℝ^{b×d}
    ŷ = softmax(z @ θ.W + θ.b)
    return ŷ

# ── Loss ────────────────────
ℒ = -mean(log(ŷ[y]))          # cross-entropy
g = ∇(ℒ, θ)
θ ← θ - α * g

for batch in batches:
    W̃ ← A @ (B + δ * ΔB)

def svd_steer(W, δ):
    U, s, Vt = svd(W)         # W ∈ ℝ^{m×n}
    R = init_rotation(r)       # R ∈ SO(r)
    A, B = U @ R, R.T @ diag(s) @ Vt
    W̃ ← A @ (B + δ * ΔB)     # δ ∈ {-1,+1}
    return W̃

def kl(p, q):  return sum(p * log(p / q))
def H(p):      return -sum(p * log(p))

Since our pseudocode is just Python with details removed, you can write runnable Python using unicode notation, then strip it down to pseudocode automatically. Benefits:

• The pseudocode is always correct (it ran)
• You can lint, test, and type-check the full version
• Two views of the same code: full (executable) and pseudocode (readable)

• Use unicode variable names from the start: θ, W̃, ŷ, ℒ, ΔB
• Use jaxtyping for verifiable shape annotations: W: Float[Tensor, "m n"]
• Add # ── section dividers
• Use explicit imports (from torch.linalg import svd) so code already has short names
• Use comment markers to control the transform:
  • # hide -- drop this line or block (works on def, for, if, etc.)
  • # to `R = init_rotation(r)` -- replace line with custom pseudocode

import torch
from torch import Tensor, randn_like, diag
from torch.linalg import svd
from torch.nn.init import orthogonal_
from jaxtyping import Float, jaxtyped
from beartype import beartype

def init_rotation(r: int) -> Tensor:  # hide
    """Helper: random orthogonal matrix."""
    return orthogonal_(torch.empty(r, r))

# ── SVD Steering ────────────────────
@jaxtyped(typechecker=beartype)
def svd_steer(
    W: Float[Tensor, "m n"],
    δ: float,
    r: int = 4,
) -> Float[Tensor, "m n"]:
    """Steer weight matrix W by rotating its SVD basis."""
    U, s, Vt = svd(W, full_matrices=False)
    R = init_rotation(r)
    A = U @ R
    B = R.T @ diag(s) @ Vt
    ΔB = randn_like(B)
    W̃ = A @ (B + δ * ΔB)
    return W̃

python to_pseudocode.py example_full.py auto-strips imports, annotations, defaults, decorators, asserts, docstrings, __main__ blocks, and implementation kwargs. Collapses multi-line def to one line. Extracts jaxtyping dims into inline comments. User-controlled markers:

• # hide on a line: drop that line (if on def/for/if/while, drops entire block)
• # to `pseudocode`: replace the line with the backtick-quoted content

Output:

# ── SVD Steering ────────────────────
def svd_steer(W, δ, r):  # W: m×n, -> m×n
    U, s, Vt = svd(W)
    R = init_rotation(r)
    A = U @ R
    B = R.T @ diag(s) @ Vt
    ΔB = randn_like(B)
    W̃ = A @ (B + δ * ΔB)
    return W̃

The full Python file should pass normal linting. Unicode identifiers are valid Python 3:

# check syntax
python -c "import ast; ast.parse(open('example_full.py').read())"
# run ruff
ruff check example_full.py --ignore F401,F811
# run as test (verifies shapes at runtime)
python example_full.py