DEV Community: Malcolm Low

Say Goodbye to Finder. Meet Marta.

Malcolm Low — Sat, 16 May 2026 03:29:43 +0000

Originally published on malcolmlow.net

macOS Finder has served Mac users faithfully since 1984 — but its age is showing. For anyone who regularly moves files between folders, manages projects with complex directory structures, or simply wants a more keyboard-friendly workflow, Finder's single-pane design quickly becomes a bottleneck.

Marta is a modern, native macOS file manager that addresses every one of these frustrations. Best of all — it's free.

What is Marta?

Marta is a dual-pane, keyboard-driven file manager built exclusively for macOS. Developed by Yan Zhulanow, it borrows the powerful two-panel paradigm from classic file managers like Total Commander and Midnight Commander — but wraps it in a clean, native macOS interface.

It is highly customisable, supports themes, and has its own plugin and scripting ecosystem. But even out of the box, the difference is immediately noticeable.

How to Install Marta

Option A — Direct Download (Recommended)

Head to the official Marta website and download the latest release:
marta.sh

Option B — Install via Homebrew

brew install --cask marta

After installation, optionally grant Full Disk Access for unrestricted folder navigation:
System Settings → Privacy & Security → Full Disk Access → toggle Marta on

Why Marta Beats Finder

🪟 Dual-Pane Navigation — The Game Changer

The single biggest advantage: a side-by-side dual-pane view. Your screen is split into two independent file panels, each showing a different folder. You can see your source and destination simultaneously — copy or move files between them without ever losing your place or juggling multiple windows.

For power users — developers, academics, content creators — this alone is worth the switch.

📁 Create New Folders in Seconds

In Finder, creating a new folder means right-clicking through a context menu. In Marta, it's a single keyboard shortcut (⌘ + ⇧ + N) — a new folder appears inline, ready to be named. Your workflow never breaks stride.

⌨️ Fully Keyboard-Driven

Navigate, open, rename, copy, move, and delete files without ever touching the mouse. Marta's keyboard-first design means experienced users can fly through file operations far faster than any GUI-only workflow allows.

🗃️ Tabs & Bookmarks

Keep multiple folder locations open as tabs within each panel. Bookmark your most-used directories and jump to them instantly — particularly powerful for large project hierarchies.

🎨 Themeable & Configurable

Marta supports custom themes and a powerful configuration file (conf.marco). You can remap shortcuts, add plugins, and tailor the entire interface to your exact preferences.

The Verdict

Marta won't replace Finder for every macOS task — but as a daily driver for navigating, organising, and moving files, it is simply in a different league. The dual-pane view alone transforms how you work with files, and features like instant folder creation and keyboard navigation make it feel like a tool built for people who actually use their computer seriously.

If you've ever felt frustrated waiting on Finder's slow animations, losing track of copy destinations, or clicking through five menus just to create a folder — give Marta five minutes. You won't go back.

marta.sh →

The Cost of Garbage in Quantum Computing: Why You Must Clean Up Junk Bits

Malcolm Low — Sat, 16 May 2026 03:29:12 +0000

Originally published on malcolmlow.net

In quantum computing, anything that "knows" what a qubit is doing acts as a Witness. Leftover data (Junk Bits) on an ancilla qubit act as witnesses, destroying the interference your algorithm needs to work.

1 . The Observer Effect

Consider a simple circuit where a qubit passes through two Hadamard gates. Classically, two inversions cancel. Quantum mechanically, the same is true — only if no information leaks out between them.

Case A: Ideal — No Junk

q0: |0> --H-----------H-- => |0>  (100% probability)

The two Hadamard gates cancel perfectly. Measurement always yields |0>.

Case B: Broken — With Junk

q0: |0> --H----*-------H-- => |0> or |1>  (50/50 noise)
               |
q1: |0> -------X---------- => |junk>      (records q0's path)

The ancilla qubit q1 becomes entangled with q0. It now "knows" which path q0 took — and that knowledge destroys the interference.

2 . Mathematical Working

Ideal Case — interference works:

Start:    |0>
After H:  (1/sqrt2)(|0> + |1>)
After H:  (1/2)(|0> + |1> + |0> - |1>) = |0>   (cancel!)

The |1> terms cancel — constructive interference on |0>.

Junk Case — interference destroyed:

Start:          |0>|0>
After H on q0:  (1/sqrt2)(|0> + |1>)|0>
After CX:       (1/sqrt2)(|00> + |11>)    <- entangled!
After H on q0:  (1/2)(|00> + |10> + |01> - |11>)

The terms cannot cancel because q1 differs in each: |00> vs |10> are orthogonal states. Interference is destroyed.

3 . The Solution: Uncomputation

To restore interference, follow the Compute-Copy-Uncompute pattern:

q_in : |x> --[COMPUTE]--+--[UNCOMPUTE]-- |x>    (unchanged)
                        |
q_anc: |0> -------------+--[UNCOMPUTE]-- |0>     (cleaned)
                        |
q_out: |0> -------------+--------------- |f(x)>  (result)

Step by step:

Compute — apply your function gates, writing the result onto q_anc
Copy — CNOT the result from q_anc into q_out
Uncompute — run the compute gates in reverse, resetting q_anc to |0>

With q_anc back to |0>, the witness is gone and interference is fully restored.

4 . Qiskit Implementation

from qiskit import QuantumCircuit, transpile
from qiskit_aer import AerSimulator

qc = QuantumCircuit(3)
# q0 = input, q1 = ancilla, q2 = output

qc.h(0)
qc.cx(0, 1)   # COMPUTE:    entangle q0 -> q1 (creates junk)
qc.cx(1, 2)   # COPY:       copy result q1 -> q2
qc.cx(0, 1)   # UNCOMPUTE:  reverse compute, reset q1 -> |0>
qc.h(0)       # Interference fully restored

qc.measure_all()
counts = AerSimulator().run(transpile(qc, AerSimulator())).result().get_counts()
print(f"Resulting state: {counts}")

The same circuit as a wire diagram (@ = control, X = target):

q0: |0> --H--@---------@--H-- M
             |         |
q1: |0> -----X----@----X----- M   (ancilla: |0> -> junk -> |0>)
                  |
q2: |0> ----------X---------- M   (output: holds f(x))

The second cx(0,1) exactly reverses the first, leaving q1 in |0>. With the witness removed, the final h(0) performs clean interference and q0 deterministically outputs |0>.

5 . Why This Matters in Practice

Uncomputation is not just a theoretical nicety. In real quantum algorithms:

Context	Why it matters
Grover's oracle	Must leave ancilla qubits clean after marking the target, or subsequent diffusion steps decohere
Arithmetic circuits	Reversible adders/multipliers accumulate garbage at every intermediate step — all must be uncomputed before measurement
Fault-tolerant circuits	Strict qubit budgets; junk bits consume physical qubits that could otherwise be used for error correction

The Compute-Copy-Uncompute pattern is the standard solution across all three contexts.

Quantum Series 2025 · Built with Qiskit 1.x

Quantum Computing: Grover's Algorithm — Inversion About the Mean

Malcolm Low — Sat, 16 May 2026 03:18:38 +0000

Originally published on malcolmlow.net

Grover's algorithm is a quantum search procedure that locates a marked item in an unsorted list of N items in O(√N) oracle queries — a quadratic speedup over any classical approach. For N = 8 (3 qubits), this means roughly ⌊π/4 × √8⌋ = 2 optimal iterations before the probability of measuring the target state peaks.

This walkthrough tracks the exact amplitude of every basis state through each gate operation for the 3-qubit case, with target state |101⟩. All arithmetic is shown so each step can be verified by hand.

Structure of each iteration (Grover operator G):

Oracle Uf — Phase-flips the target state: |x⟩ → −|x⟩ if f(x) = 1, otherwise |x⟩ → |x⟩
Diffusion operator D = H⊗n(2|0⟩⟨0| − I)H⊗n — Reflects all amplitudes about their mean, amplifying the marked state at the expense of the others

Key insight: The oracle introduces destructive interference at the target, which the diffusion operator converts into constructive interference by inverting amplitudes about their mean. Each iteration rotates the state vector by angle 2θ closer to the target, where sin(θ) = 1/√N.

Phase 0: Initialization

Apply H⊗3 to |000⟩ to create a uniform superposition over all 8 basis states:

|ψinit⟩ = (1/√8)[ |000⟩ + |001⟩ + |010⟩ + |011⟩
                 + |100⟩ + |101⟩ + |110⟩ + |111⟩ ]

Every state has amplitude +1/√8 ≈ 0.3535 and probability 12.5%.

Hadamard Reference (Standard Signs)

Element (i, j) has sign (−1)^popcount(i AND j). This table is used in every Hadamard step below — each row shows how an input basis state distributes into all 8 output states.

          |000⟩ |001⟩ |010⟩ |011⟩ |100⟩ |101⟩ |110⟩ |111⟩
          ─────────────────────────────────────────────────
H|000⟩ →    +     +     +     +     +     +     +     +
H|001⟩ →    +     −     +     −     +     −     +     −
H|010⟩ →    +     +     −     −     +     +     −     −
H|011⟩ →    +     −     −     +     +     −     −     +
H|100⟩ →    +     +     +     +     −     −     −     −
H|101⟩ →    +     −     +     −     −     +     −     +
H|110⟩ →    +     +     −     −     −     −     +     +
H|111⟩ →    +     −     −     +     −     +     +     −

Round 1: Oracle → Diffusion

Step 3 — Oracle Uf

The oracle recognises |101⟩ as the marked state and flips its amplitude from +1/√8 to −1/√8. All other amplitudes remain unchanged. The superposition is preserved — no measurement is made.

Step 4.1 — First H (mapping to Hadamard basis)

Each input state contributes ±1/8 to each output column via the sign table. The oracle-marked |101⟩ row is fully sign-inverted.

                  |000⟩  |001⟩  |010⟩  |011⟩  |100⟩  |101⟩  |110⟩  |111⟩
                  ──────────────────────────────────────────────────────────
+H|000⟩  (+1/√8)  +1/8   +1/8   +1/8   +1/8   +1/8   +1/8   +1/8   +1/8
+H|001⟩  (+1/√8)  +1/8   -1/8   +1/8   -1/8   +1/8   -1/8   +1/8   -1/8
+H|010⟩  (+1/√8)  +1/8   +1/8   -1/8   -1/8   +1/8   +1/8   -1/8   -1/8
+H|011⟩  (+1/√8)  +1/8   -1/8   -1/8   +1/8   +1/8   -1/8   -1/8   +1/8
+H|100⟩  (+1/√8)  +1/8   +1/8   +1/8   +1/8   -1/8   -1/8   -1/8   -1/8
-H|101⟩  (-1/√8)  -1/8   +1/8   -1/8   +1/8   +1/8   -1/8   +1/8   -1/8  ← oracle row
+H|110⟩  (+1/√8)  +1/8   +1/8   -1/8   -1/8   -1/8   -1/8   +1/8   +1/8
+H|111⟩  (+1/√8)  +1/8   -1/8   -1/8   +1/8   -1/8   +1/8   +1/8   -1/8
          ───────────────────────────────────────────────────────────────────
Net 4.1           +6/8   +2/8   -2/8   +2/8   +2/8   -2/8   +2/8   -2/8

Step 4.2 — Phase Flip (2|0⟩⟨0|−I)

Keep |000⟩ unchanged, negate all other states. This is the heart of inversion-about-the-mean.

         |000⟩  |001⟩  |010⟩  |011⟩  |100⟩  |101⟩  |110⟩  |111⟩
Post-Z:  +6/8   -2/8   +2/8   -2/8   -2/8   +2/8   -2/8   +2/8

Step 4.3 — Second H (back to computational basis)

                  |000⟩  |001⟩  |010⟩  |011⟩  |100⟩  |101⟩  |110⟩  |111⟩
Net R1 (exact):  +4/8√8 +4/8√8 +4/8√8 +4/8√8 +4/8√8 +20/8√8 +4/8√8 +4/8√8
Net R1 (decimal):  0.177  0.177  0.177  0.177  0.177   0.884  0.177  0.177

After Round 1, |101⟩ has been amplified from 0.354 to 0.884.

Round 2: Oracle → Diffusion

Step 5 — Oracle Uf

The oracle flips |101⟩ from +20/8√8 to −20/8√8. The 7 non-target states remain at +4/8√8. This large asymmetry drives even stronger constructive interference in the diffusion step.

Step 6.1 — First H

                      |000⟩   |001⟩   |010⟩   |011⟩   |100⟩   |101⟩   |110⟩   |111⟩
                      ──────────────────────────────────────────────────────────────────
+H|000⟩  (+4/8√8)    +4/64   +4/64   +4/64   +4/64   +4/64   +4/64   +4/64   +4/64
+H|001⟩  (+4/8√8)    +4/64   -4/64   +4/64   -4/64   +4/64   -4/64   +4/64   -4/64
+H|010⟩  (+4/8√8)    +4/64   +4/64   -4/64   -4/64   +4/64   +4/64   -4/64   -4/64
+H|011⟩  (+4/8√8)    +4/64   -4/64   -4/64   +4/64   +4/64   -4/64   -4/64   +4/64
+H|100⟩  (+4/8√8)    +4/64   +4/64   +4/64   +4/64   -4/64   -4/64   -4/64   -4/64
-H|101⟩  (-20/8√8)  -20/64  +20/64  -20/64  +20/64  +20/64  -20/64  +20/64  -20/64  ← oracle row
+H|110⟩  (+4/8√8)    +4/64   +4/64   -4/64   -4/64   -4/64   -4/64   +4/64   +4/64
+H|111⟩  (+4/8√8)    +4/64   -4/64   -4/64   +4/64   -4/64   +4/64   +4/64   -4/64
          ──────────────────────────────────────────────────────────────────────────────
Net 6.1              +8/64  +24/64  -24/64  +24/64  +24/64  -24/64  +24/64  -24/64

Step 6.2 — Phase Flip

         |000⟩   |001⟩   |010⟩   |011⟩   |100⟩   |101⟩   |110⟩   |111⟩
Post-Z:  +8/64  -24/64  +24/64  -24/64  -24/64  +24/64  -24/64  +24/64

Step 6.3 — Second H

                   |000⟩    |001⟩    |010⟩    |011⟩    |100⟩    |101⟩    |110⟩    |111⟩
Net R2 (exact):  -16/64√8 -16/64√8 -16/64√8 -16/64√8 -16/64√8 +176/64√8 -16/64√8 -16/64√8
Net R2 (decimal):  -0.088   -0.088   -0.088   -0.088   -0.088    +0.972   -0.088   -0.088

Success Probability after Round 2: P(|101⟩) = |0.972|² ≈ 94.5%

Round 2 is the optimal stopping point for 3-qubit Grover search — ⌊π/4 × √8⌋ = 2 iterations.

Round 3: The Overcooking Effect

Step 7 — Oracle Uf

With P(|101⟩) at 94.5%, one more iteration is one too many. The oracle flips |101⟩ from +176/64√8 to −176/64√8. The state vector has been rotated 2θ past its peak — a third diffusion step pushes it further away from the target, not closer.

Steps 8.1–8.3 — Diffusion

                   |000⟩    |001⟩    |010⟩    |011⟩    |100⟩    |101⟩    |110⟩    |111⟩
Net R3 (exact):  -448/512√8 (×7 non-target states)    +832/512√8 (target)
Net R3 (decimal):  -0.309   -0.309   -0.309   -0.309   -0.309    +0.575   -0.309   -0.309

P(|101⟩) = |0.575|² ≈ 33.0%

Summary: Amplitude Evolution Across Rounds

Round   Target |101⟩   Non-target states   P(|101⟩)
──────────────────────────────────────────────────────
Init       +0.354          +0.354            12.5%
R1         +0.884          +0.177            78.1%
R2         +0.972          -0.088            94.5%  ← optimal stop
R3         +0.575          -0.309            33.0%  ← overcooked

The state vector has rotated past the optimal angle. P(|101⟩) drops from 94.5% to 33.0% — a significant fall, but |101⟩ still has more than double the probability of any other state. The algorithm has not lost the answer; it has merely overshot the maximum.

Importantly, the target amplitude is still positive (+0.575) — the vector has not crossed zero, it has simply overshot past the maximum. The result comes directly from the Born rule: P(|101⟩) = |amplitude|² = |+0.575|² ≈ 0.330.

Quantum Series 2026 · Built with Qiskit 1.x

Quantum Computing: The Walsh-Hadamard Matrix — Backbone of Grover's Diffusion Operator

Malcolm Low — Sat, 16 May 2026 03:13:06 +0000

Originally published on malcolmlow.net

In the Grover's Algorithm — Inversion About the Mean walkthrough, the diffusion operator applies H⊗³ twice per iteration. Every single step is governed by a sign table called the Hadamard Reference. That table is not a lookup shortcut — it is the 8×8 Walsh-Hadamard Transform matrix written out in full. This post derives it from scratch: one qubit, then two, then all three, arriving at the complete matrix and the rule behind every sign in it.

1 · The Circuit: Three Qubits, Three Hadamard Gates

We initialise all three qubits in the ground state |0⟩ and route each through its own independent Hadamard gate. There are no two-qubit (entangling) gates — the circuit is entirely parallel.

Qubit	Input	Gate	Output
q₀	\|0⟩	H	(1/√2)(\|0⟩ + \|1⟩)
q₁	\|0⟩	H	(1/√2)(\|0⟩ + \|1⟩)
q₂	\|0⟩	H	(1/√2)(\|0⟩ + \|1⟩)

All three outputs are identical because all three inputs are identical. The structure emerges when we take their tensor product.

2 · Single-Qubit Hadamard Action

Input	H\|input⟩	Short notation
\|0⟩	(1/√2)(\|0⟩ + \|1⟩)	\|+⟩
\|1⟩	(1/√2)(\|0⟩ − \|1⟩)	\|−⟩

In matrix form:

H = (1/√2) [ +1  +1 ]
            [ +1  -1 ]

Key property: H is its own inverse — H² = I. Every element has magnitude 1/√2, so tensoring three copies multiplies the magnitudes to 1/√8 while the signs follow a precise bitwise pattern.

3 · Two-Qubit Tensor Product: q₀ ⊗ q₁

|+⟩ ⊗ |+⟩
= (1/√2)(|0⟩ + |1⟩) ⊗ (1/√2)(|0⟩ + |1⟩)
= (1/2)( |00⟩ + |01⟩ + |10⟩ + |11⟩ )

All four two-qubit basis states appear with equal amplitude 1/2. Measurement probability per state: (1/2)² = 25%.

4 · Three-Qubit Tensor Product: q₀ ⊗ q₁ ⊗ q₂

|+⟩ ⊗ |+⟩ ⊗ |+⟩
= (1/√8)( |000⟩ + |001⟩ + |010⟩ + |011⟩
        + |100⟩ + |101⟩ + |110⟩ + |111⟩ )

This is |ψinit⟩ — the uniform superposition over all 8 basis states that opens Grover's algorithm. Each state carries amplitude +1/√8 ≈ 0.3535 and measurement probability 1/8 = 12.5%.

5 · The 8×8 Walsh-Hadamard Sign Matrix

When H⊗³ is applied to an arbitrary basis state |j⟩:

H⊗³ |j⟩ = (1/√8) Σᵢ (−1)^popcount(i AND j) |i⟩

The entry at row i, column j carries sign (−1)^popcount(i AND j) divided by √8.
+ = amplitude +1/√8 ≈ +0.3535 / − = amplitude −1/√8 ≈ −0.3535

          |000⟩ |001⟩ |010⟩ |011⟩ |100⟩ |101⟩ |110⟩ |111⟩
          ─────────────────────────────────────────────────
H|000⟩ →    +     +     +     +     +     +     +     +
H|001⟩ →    +     −     +     −     +     −     +     −
H|010⟩ →    +     +     −     −     +     +     −     −
H|011⟩ →    +     −     −     +     +     −     −     +
H|100⟩ →    +     +     +     +     −     −     −     −
H|101⟩ →    +     −     +     −     −     +     −     +
H|110⟩ →    +     +     −     −     −     −     +     +
H|111⟩ →    +     −     −     +     −     +     +     −

Each row shows how an input basis state |j⟩ distributes its amplitude across all 8 output states after H⊗³ is applied.

6 · Why the Sign is (−1)^popcount(i AND j)

Because H acts independently on each qubit, H⊗³ is the tensor product of three 2×2 matrices. The entry at row i, column j is the product of the three corresponding single-qubit entries:

H⊗³[i, j] = H[i₀, j₀] × H[i₁, j₁] × H[i₂, j₂]

Each single-qubit factor equals +1 unless both the k-th bit of i and the k-th bit of j are 1, in which case it equals −1. Multiplying all three:

sign(i, j) = (−1)^(i₀j₀ + i₁j₁ + i₂j₂) = (−1)^popcount(i AND j)

The rule in plain terms: bitwise AND the row index and the column index, count the 1-bits, check parity. Even count → positive. Odd count → negative.

Quick verification: row H|101⟩, column |011⟩

i (row)	j (col)	i AND j	popcount	Sign
101 (=5)	011 (=3)	001	1 (odd)	− ✓

Matches the matrix in Section 5: row H|101⟩, column |011⟩ is indeed −.

7 · Connection to Grover's Diffusion Operator

This matrix is the Hadamard Reference used throughout the Grover's Algorithm walkthrough. The diffusion operator D = H⊗³ (2|0⟩⟨0| − I) H⊗³ works in three sub-steps, each directly using this matrix:

Sub-step	Operation	Effect
First H⊗³	Maps computational basis → Hadamard basis	Each amplitude spreads across all 8 columns via the sign table
Phase flip	2\|0⟩⟨0\|−I	Keeps \|000⟩ unchanged, negates all other states
Second H⊗³	Maps back to computational basis	Routes constructive interference into the target state

Without the sign structure of the Walsh-Hadamard matrix, neither the uniform superposition nor the diffusion step would work. The matrix is the silent engine behind Grover's quadratic speedup.

Quantum Series 2026 · Built with Qiskit 1.x

Connecting an OpenClaw Bot to a Telegram Group Topic

Malcolm Low — Sat, 16 May 2026 03:00:40 +0000

Originally published on malcolmlow.net

Route OpenClaw agent notifications and responses through a private Telegram group using Topics for clean per-bot threading.

Prerequisites

Item	Details
OpenClaw with Telegram bot	OpenClaw must already be set up and working with a Telegram bot before proceeding. This guide only covers configuring it to post into a specific group topic.
Telegram account	Active account with admin rights on a Telegram group
Telegram group with Topics	A Telegram group with the Topics feature enabled
SingIDBot	@SingIDBot — a custom bot built by the author, used to retrieve the chat ID and topic thread ID. Responds in Singlish, so don't be surprised by the personality.

Step 1 · Create a Topic for the Bot

With Topics enabled on your group, create a dedicated topic for your OpenClaw bot to keep its messages isolated from other group activity.

Tap the pencil / new topic icon in your group and give it a clear name such as:

OpenClaw-Bot

Note the topic thread ID — you will retrieve this precisely in Step 2 using SingIDBot.

Tip: If the Topics toggle is not visible in your group settings, try adding 4–5 members to the group first. Telegram requires a minimum number of members before the Topics feature becomes available.

Step 2 · Get IDs from SingIDBot

SingIDBot (@SingIDBot) returns the exact numeric IDs that OpenClaw needs: the group's chat ID and the topic's thread ID. See the full SingIDBot setup guide for how it works under the hood.

Add @SingIDBot to your group and grant it member access.
Navigate into your OpenClaw-Bot topic (not the General topic) before sending the command.
Inside the topic, send: /getids
SingIDBot will reply with a block like this:

Chat ID  : -1001234567890
Thread ID: 42
User ID  : 987654321

Copy the Chat ID and Thread ID. You will pass them to OpenClaw in Step 4.

Step 3 · Ask OpenClaw to Build the Config Tool

Rather than editing the .env file manually, ask the OpenClaw agent to write a Python tool that does it for you. The tool only needs the chat ID and topic thread ID — the bot token is already present in the .env from initial setup.

Use this prompt in your OpenClaw chat interface:

Create a Python tool called update_telegram_config that accepts
chat_id and topic_id as arguments and writes the values of
TELEGRAM_CHAT_ID and TELEGRAM_TOPIC_ID into the OpenClaw .env file.

OpenClaw will scaffold the tool, register it, and confirm it is ready to call. Proceed to Step 4 once the agent confirms the tool is available.

Step 4 · Run the Tool and Reload OpenClaw

With the IDs from Step 2 in hand, instruct OpenClaw to run the tool using your actual values:

Run update_telegram_config with:
  chat_id = "-1001234567890"
  topic_id = "42"

Replace the placeholder values with the IDs from Step 2. After the tool executes, reload OpenClaw so the new environment variables are picked up:

# In your terminal (if running OpenClaw locally)
Ctrl+C       # stop the current process
openclaw     # restart

Step 5 · Test the Setup

Navigate into the OpenClaw-Bot topic in your Telegram group and post any message. Wait for your OpenClaw bot to reply.

If the group ID and topic ID have been configured correctly, your OpenClaw bot will respond directly inside the topic. If there is no response, double-check the IDs from Step 2 and rerun Step 4.

Note: By default, OpenClaw bots are configured to not respond to any message in a Telegram topic unless the correct group ID and topic ID are added into the config file. A missing or incorrect ID will result in complete silence from the bot.

SingIDBot Quick Reference

@SingIDBot is a custom Telegram bot built by the author. It does one job well: return the IDs you need for bot configuration. It also speaks Singlish, so expect replies like "Wah, your chat ID here lah" — just read past the flavour text and grab your numbers.

Command	What it returns	Notes
`/getids`	Chat ID, Thread ID (topic), and your User ID	Must be run inside the target topic to get the correct Thread ID

Also tested on Hermes Agent: The same setup process works with the NousResearch Hermes Agent framework. The update_telegram_config tool and environment variable structure are identical — simply run the same steps with Hermes Agent in place of OpenClaw.

Your agent is now wired to a dedicated Telegram topic. Every notification, response, or alert it sends will land in the OpenClaw-Bot thread, keeping it separate from general group activity. To add more agents or tools later, repeat Steps 1–4 with a new topic and a new set of environment variable names.

SingIDBot — Telegram ID Retrieval Bot for OpenClaw Topic Configuration

Malcolm Low — Sat, 16 May 2026 02:58:42 +0000

Originally published on malcolmlow.net

If you have been working through the OpenClaw Telegram integration guide, you already know that one of the trickiest steps is obtaining the correct Chat ID and Topic Thread ID before you can configure your bot endpoints. Getting those IDs wrong means your bot silently sends messages into the void — no errors, no feedback, just nothing arriving in the right place.

SingIDBot was built specifically to solve that problem. Drop it into any Telegram chat or group, fire the /getids command, and it instantly reports back the Chat ID and — crucially — the message_thread_id for whichever topic the command was sent from.

Beyond the ID retrieval utility, SingIDBot has a second personality: it responds to free-text messages in Singlish — Singapore's beloved colloquial English creole — cycling through randomised phrases like "Aiyoh, you finally came! Welcome lah!" and "Wah, interesting leh. Tell me more can?"

This guide walks through the complete source code, explains each architectural decision, and covers deployment on PythonAnywhere including the free-tier network restrictions you will inevitably hit.

Prerequisites

Requirement	Details
Python 3.10+	Required for python-telegram-bot v20+ async support
python-telegram-bot v20+	The async-native version. Install with `pip install python-telegram-bot`
Telegram Bot Token	Create via @botfather — send `/newbot` and copy the token
PythonAnywhere account	Free Beginner account is sufficient to run and test the bot

Section 1 — What SingIDBot Does

The message_thread_id Mechanism

Telegram supergroups can be divided into named Topics, each identified by a message_thread_id. When a message is sent inside a topic, Telegram attaches this integer to the message object. When sent outside any topic, the field is absent entirely — not zero, not null, but genuinely missing.

This is the exact value OpenClaw requires to route notifications to the correct topic thread. SingIDBot's /getids command reads message_thread_id from the incoming message and reports it in plain text for direct copy-paste into your configuration.

Because the field may be absent, the code uses getattr(update.effective_message, 'message_thread_id', None) rather than direct attribute access, which would raise an AttributeError in non-topic contexts.

The Singlish Responder

Any free-text message (not a command) triggers the singlish_chat handler. It classifies the message into greeting, thanks, or default using keyword matching, then picks a random phrase from the corresponding pool.

Section 2 — Code Walkthrough

2.1 Logging Setup

Two handlers run simultaneously: a FileHandler writing UTF-8 lines to singidbot.log, and a StreamHandler for the console.

LOG_FILE = "singidbot.log"
logging.basicConfig(
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
    level=logging.INFO,
    handlers=[
        logging.FileHandler(LOG_FILE, encoding="utf-8"),
        logging.StreamHandler(),
    ],
)
logger = logging.getLogger(__name__)

Tip: The encoding="utf-8" argument is essential if any Telegram usernames contain non-ASCII characters. Without it, a single emoji in a username can crash the logger with a UnicodeEncodeError.

2.2 Singlish Response Bank

SINGLISH_RESPONSES maps category keys to phrase lists. get_singlish_response() uses dict.get() with a "default" fallback so unknown categories never raise a KeyError.

SINGLISH_RESPONSES = {
    "greeting": [
        "Wah, you here ah! Come come, sit down lah!",
        "Eh hello! Long time no see, how are you?",
        "Aiyoh, you finally came! Welcome lah!",
        "Oi! Good to see you sia. What can I help you?",
    ],
    "thanks": [
        "Aiyah, no need to thank one lah!",
        "Wah, so polite! Welcome lah, anytime!",
        "No problem one! Next time also can help you.",
        "Eh, paiseh lah - that is what I am here for!",
    ],
    "default": [
        "Hah? Can repeat or not? I blur blur lah.",
        "Wah, interesting leh. Tell me more can?",
        "Aiyoh, I also dunno how to answer you sia.",
        "Got it lah! But I not so sure about that one.",
        "Eh, you very clever leh. I learn from you!",
    ],
}

def get_singlish_response(category):
    pool = SINGLISH_RESPONSES.get(category, SINGLISH_RESPONSES["default"])
    return random.choice(pool)

2.3 log_activity() Async Helper

async def log_activity(user, event_type, metadata):
    user_info = (
        f"@{user.username}" if user and user.username
        else f"id={user.id}" if user
        else "unknown"
    )
    timestamp = datetime.now(timezone.utc).isoformat()
    logger.info("[%s] event=%s user=%s metadata=%s",
                timestamp, event_type, user_info, metadata)

2.4 /start and /help Handlers

async def start(update, context):
    user = update.effective_user
    await log_activity(user, "START", {"chat_id": update.effective_chat.id})
    greeting = get_singlish_response("greeting")
    name = user.first_name if user and user.first_name else "friend"
    welcome_text = (
        f"{greeting}

Eh {name}, I am *SingIDBot* lah!

"
        "Commands:
- /start
- /help
- /getids"
    )
    await update.message.reply_text(welcome_text, parse_mode="Markdown")

2.5 /getids Handler

The key line is the getattr call. Telegram only populates message_thread_id when a message arrives inside a topic thread — in a regular chat the attribute simply does not exist.

async def get_ids(update, context):
    user = update.effective_user
    await log_activity(user, "ID_RETRIEVAL", {"chat_id": update.effective_chat.id})
    chat_id = update.effective_chat.id
    topic_id = getattr(update.effective_message, "message_thread_id", None)
    response = f"Chat/Group ID: `{chat_id}`
"
    if topic_id is not None:
        response += f"Topic ID: `{topic_id}`
(This ID confirms the specific topic thread)"
    else:
        response += "Topic ID: Not available
(Topics may not be enabled)"
    response += "

Tip: Record these IDs for configuring bot endpoints!"
    await update.message.reply_text(response, parse_mode="Markdown")
    await update.message.reply_text(f"{get_singlish_response('thanks')} Lah!")

2.6 singlish_chat Handler

Registered with filters.TEXT and ~filters.COMMAND. A guard clause checks if the sender is the bot itself to prevent infinite reply loops.

async def singlish_chat(update, context):
    user = update.effective_user
    await log_activity(user, "MESSAGE", {
        "text_preview": update.message.text[:50] if update.message else "N/A"
    })
    if (not update.message
            or update.message.text.startswith("/")
            or update.effective_user.id == context.bot.id):
        return
    user_text = update.message.text.lower().strip()
    if any(w in user_text for w in ["thanks", "thank", "appreciate"]):
        category = "thanks"
    elif any(w in user_text for w in ["hello", "hi", "hey", "oi", "wah", "alamak"]):
        category = "greeting"
    else:
        category = "default"
    await update.message.reply_text(get_singlish_response(category))

2.7 error_handler — Two-Tier Approach

async def error_handler(update, context):
    error = context.error
    if isinstance(error, Exception):
        error_name = type(error).__name__
        error_msg = str(error)
        if "ProxyError" in error_msg or "NetworkError" in error_name:
            logger.warning("Network error (transient): %s", error_msg)
        elif "Conflict" in error_name or "terminated by other getUpdates" in error_msg:
            logger.warning("Conflict error (duplicate instance?): %s", error_msg)
        else:
            logger.error("Unhandled exception: %s: %s",
                         error_name, error_msg, exc_info=context.error)

2.8 main() — Builder Chain and Handler Registration

def main():
    TOKEN = "YOUR_BOT_TOKEN_HERE"
    application = (
        Application.builder()
        .token(TOKEN)
        .connect_timeout(30)
        .read_timeout(30)
        .write_timeout(30)
        .build()
    )
    application.add_handler(CommandHandler("start", start))
    application.add_handler(CommandHandler("help", help_command))
    application.add_handler(CommandHandler("getids", get_ids))
    application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, singlish_chat))
    application.add_error_handler(error_handler)
    logger.info("--- SingIDBot Initializing ---")
    application.run_polling(allowed_updates=Update.ALL_TYPES)

Section 3 — Deployment on PythonAnywhere

Upload singidbot.py via the Files tab, open a Bash console, and run:

pip install python-telegram-bot --upgrade
python singidbot.py

Free-Tier Proxy Restriction

Free accounts route outbound traffic through a proxy that does not whitelist api.telegram.org. Outbound sendMessage calls can fail with httpx.ProxyError: 503 Service Unavailable. Inbound polling via getUpdates works fine — it is only the reply direction that is intermittently blocked.

In practice across four live sessions totalling over 5 hours, only 2 ProxyErrors occurred in 1800+ polling cycles.

Options if you need reliable reply delivery: Upgrade to a paid PythonAnywhere plan, or switch from polling to webhook mode via PythonAnywhere's WSGI layer.

Avoiding Duplicate Instance Conflicts

Telegram only allows one active getUpdates poller per token. Always kill the old process before restarting:

pkill -f singidbot.py
pgrep -a -f singidbot
python singidbot.py

Section 4 — Log Analysis

Session	Duration	Key Events	Errors
Session 1	~2 min	First run. `/getids` succeeded returning Chat ID 5024469893.	1 ProxyError (no error handler yet)
Session 2	~3 min	Error handler added. `/help` ProxyError suppressed to WARNING.	1 ProxyError (WARNING only)
Session 3	~14 min	Extended run. 47 consecutive clean polling cycles.	1 ProxyError (WARNING only)
Session 4	~5 hours	1800+ log lines. Clean polling throughout. No conflicts.	2 ProxyErrors total

SingIDBot is production-stable on the free tier. The intermittent ProxyError is a platform constraint, not a code defect.

Quick Reference

Command	What it returns	Notes
`/start`	Personalised Singlish greeting and command list	Works in any chat context
`/help`	List of all available commands	Works in any chat context
`/getids`	Chat ID and Topic Thread ID (if inside a topic)	Must be run inside the target topic to get a valid Thread ID

Word Embeddings Explained: The Math Behind AI, LLMs, and Chatbots

Malcolm Low — Sat, 16 May 2026 02:55:33 +0000

Originally published on malcolmlow.net

When a search engine retrieves a document about automobiles in response to a query about cars, it is not matching text character by character. Somewhere beneath the interface, the system understands that these two words are semantically related. The mechanism behind that understanding is the word embedding — and once you see the geometry, you cannot unsee it.

This article walks through the key mathematical operations that make embeddings work: distance, similarity, arithmetic, scaling, and the dot product. Each concept is illustrated with concrete numerical vectors so the math is visible, not just described. Real embeddings typically use hundreds of dimensions; the 3- and 4-dimensional examples here preserve all the structure while staying readable on a page.

1 · What is a Word Embedding?

A word embedding is a representation of a word as a vector — an ordered list of numbers — in a high-dimensional space. A typical embedding model might use 300 dimensions, so the word cat becomes a point with 300 coordinates. The key insight: the position of that point encodes meaning.

This is what researchers call a semantic space. Words with related meanings end up positioned close to each other. King and Queen live near each other. Paris and London live near each other. Bicycle and democracy live far apart.

Example: 4-dimensional vectors (simplified from real 300-dim embeddings)

vec("King")  = [ 0.9,  0.7,  0.4, +0.6 ]
vec("Queen") = [ 0.9,  0.7,  0.4, -0.6 ]
vec("Man")   = [ 0.5,  0.3,  0.1, +0.8 ]
vec("Woman") = [ 0.5,  0.3,  0.1, -0.8 ]

The first three dimensions encode royalty, authority, and age. The fourth dimension encodes gender: positive = masculine, negative = feminine.

2 · The Geometry of Meaning: Distance and Similarity

Once words are points in space, we need a way to measure how close they are. Two approaches dominate: Euclidean distance and cosine similarity.

Temperature vectors (3 dimensions)

vec("Hot")  = [ 1.0,  0.8,  0.6 ]
vec("Warm") = [ 0.8,  0.6,  0.4 ]
vec("Cold") = [-0.6,  0.4, -0.8 ]

2.1 Euclidean Distance

The straight-line gap between the tips of two vectors:

d(a, b) = √ Σᵢ (aᵢ − bᵢ)²

Worked example:

d(Hot, Warm) = √[(1.0-0.8)² + (0.8-0.6)² + (0.6-0.4)²]
             = √[0.04 + 0.04 + 0.04] = √0.12 ≈ 0.346  ← small: close together

d(Hot, Cold) = √[(1.0-(-0.6))² + (0.8-0.4)² + (0.6-(-0.8))²]
             = √[2.56 + 0.16 + 1.96] = √4.68 ≈ 2.163  ← large: far apart

2.2 Cosine Similarity — The Industry Standard

In practice, NLP systems almost universally prefer cosine similarity. It ignores vector length entirely and focuses only on the angle between them — two vectors pointing the same direction score 1.0 regardless of magnitude.

cos(θ) = (a · b) / (‖a‖ × ‖b‖)

Range: −1 (opposite) → 0 (orthogonal) → +1 (identical direction)

Worked example:

‖Hot‖  = √(1.0² + 0.8² + 0.6²) = √2.00 ≈ 1.414
‖Warm‖ = √(0.8² + 0.6² + 0.4²) = √1.16 ≈ 1.077
‖Cold‖ = √(0.6² + 0.4² + 0.8²) = √1.16 ≈ 1.077

dot(Hot, Warm) = (1.0)(0.8) + (0.8)(0.6) + (0.6)(0.4) = 1.52
cos(Hot, Warm) = 1.52 / (1.414 × 1.077) ≈ +0.998   ← nearly identical direction

dot(Hot, Cold) = (1.0)(-0.6) + (0.8)(0.4) + (0.6)(-0.8) = -0.76
cos(Hot, Cold) = -0.76 / (1.414 × 1.077) ≈ -0.499  ← opposite directions

Word Pair	Euclidean d	cos(θ)	Interpretation
Hot vs Warm	0.346	+0.998	Nearly identical direction — closely related
Hot vs Cold	2.163	−0.499	Opposite directions — antonyms

3 · Vector Arithmetic: Meaning You Can Add and Subtract

Because words are vectors, you can perform arithmetic on them — and the results are semantically meaningful. The most famous example:

vec("King") − vec("Man") + vec("Woman") ≈ vec("Queen")

Worked example:

King  = [ 0.9,  0.7,  0.4, +0.6 ]
Man   = [ 0.5,  0.3,  0.1, +0.8 ]
Woman = [ 0.5,  0.3,  0.1, -0.8 ]

King − Man = [ 0.4,  0.4,  0.3, -0.2 ]
+ Woman    = [ 0.9,  0.7,  0.4, -1.0 ]

d(result, Queen)  ≈ 0.400  ← nearest
d(result, Woman)  ≈ 0.671
d(result, King)   = 1.600
cos(result, Queen) ≈ 0.974  ← highest cosine similarity

What happened geometrically? Subtracting Man stripped out the gender dimension, leaving the royalty structure intact. Adding Woman injected the feminine gender value. The result sits 0.4 units from Queen — the nearest word in this vocabulary.

4 · Scalar Multiplication and Division: Changing Intensity

Multiplying or dividing a vector by a scalar changes its magnitude without changing its direction. This maps onto the idea of degree in language — Tiny, Large, and Gigantic all point in roughly the same semantic direction, at different intensities.

Size vectors (3 dimensions)

vec("Tiny")     = [ 0.10,  0.20,  0.10 ]
vec("Large")    = [ 0.50,  0.70,  0.40 ]
vec("Gigantic") = [ 1.10,  1.50,  0.90 ]

Worked example:

Large × 2   = [ 1.00, 1.40, 0.80 ]
vec("Gigantic") = [ 1.10, 1.50, 0.90 ]
d(Large × 2, Gigantic) ≈ 0.173  ← very close

Large × 0.2 = [ 0.10, 0.14, 0.08 ]
vec("Tiny")     = [ 0.10, 0.20, 0.10 ]
d(Large × 0.2, Tiny) ≈ 0.063   ← very close

Loud ÷ 2 lands near "Soft" — direction unchanged, intensity halved.

Key intuition: Scalar operations change how much of something a vector represents, without changing what kind of thing it represents.

5 · The Dot Product: Agreement and Magnitude Together

a · b = Σᵢ (aᵢ × bᵢ) = a₁b₁ + a₂b₂ + … + aₙbₙ

The dot product captures two things simultaneously: the direction of agreement and the combined magnitude. Cosine similarity captures only the first.

Worked example — Very Loud vs A Little Loud:

vec("A Little Loud") = [ 0.30, 0.40, 0.20 ]  |magnitude| = 0.539
vec("Very Loud")     = [ 0.90, 1.20, 0.60 ]  |magnitude| = 1.616

dot(AL, VL) = (0.3)(0.9) + (0.4)(1.2) + (0.2)(0.6) = 0.87
cos(AL, VL) = 0.87 / (0.539 × 1.616) ≈ 1.000  ← perfect alignment

AL · AL = 0.09 + 0.16 + 0.04 = 0.29
VL · VL = 0.81 + 1.44 + 0.36 = 2.61

Comparison	Magnitude	cos(θ)	v · v
A Little Loud	0.539	1.000	0.29
Very Loud	1.616	1.000	2.61

Both are perfectly collinear — cosine similarity is 1.0 in both cases. But the dot products are 0.29 vs 2.61, a 9× difference. This is why recommendation systems and attention mechanisms in transformer models often prefer raw dot products: when you want to know not just whether a document is relevant but also how prominently it discusses a topic, the dot product gives you both dimensions at once.

6 · Practical Applications

Search engines convert your query into a vector and retrieve documents whose vectors are nearest to it — using cosine similarity to rank by relevance regardless of exact word match. When you search for car insurance and get results about vehicle coverage, that's nearest-neighbour lookup in embedding space.

Recommendation systems represent your interests as a vector computed from your history, then find products whose vectors are closest. The dot product is particularly useful here: a highly-relevant item with a large magnitude will score higher than a mildly-relevant item even if they point in the same direction.

Large language models use the scaled dot product directly inside the attention mechanism. For every token, a query vector and a set of key vectors are compared via dot product to determine which parts of the context deserve attention — a direct descendant of the arithmetic in Section 5.

Quick Reference: Embedding Operations

Operation	Formula	Result
Euclidean Distance	√(Σ(aᵢ−bᵢ)²)	d(Hot,Warm)=0.346 / d(Hot,Cold)=2.163
Cosine Similarity	(a·b)/(‖a‖×‖b‖)	cos(Hot,Warm)=+0.998 / cos(Hot,Cold)=-0.499
Vector Arithmetic	a ± b	King−Man+Woman → nearest Queen (d=0.400)
Scalar Multiplication	λ · a	Large×2 → near Gigantic / Loud÷2 → near Soft
Dot Product	a·b = Σaᵢbᵢ	cos=1.00 for both; dot 0.29 (soft) vs 2.61 (loud)

Agentic Code Generation with OpenAI Codex CLI — A Knight's Tour Walkthrough

Malcolm Low — Sat, 16 May 2026 02:51:42 +0000

Originally published on malcolmlow.net

A step-by-step walkthrough of using OpenAI's agentic coding tool to scaffold, solve, test, and visualise the classic Knight's Tour chess problem — entirely through natural language prompts.

This post assumes you have Codex CLI installed and authenticated. We'll be working in three phases, each driven by a carefully crafted Codex prompt.

♞ What is the Knight's Tour Problem?

The Knight's Tour is a classic puzzle from combinatorics and graph theory: given an n×n chessboard and a knight placed on any starting square, can the knight visit every square on the board exactly once using only valid knight moves? A knight moves in an L-shape — two squares in one direction and one square perpendicular, giving it up to eight possible moves from any position.

The problem has been studied for over a thousand years. Arab mathematicians documented it as early as the 9th century, and Leonhard Euler conducted a systematic mathematical analysis in 1759. There are two variants: an open tour, where the starting and ending squares differ, and a closed (re-entrant) tour, where the knight can return to its starting square in one move. On the standard 8×8 board, there are over 26 trillion distinct open tours.

From an algorithmic standpoint, the Knight's Tour is a special case of the Hamiltonian path problem on a graph, where each square is a node and edges connect squares reachable by a knight move. Finding a Hamiltonian path is NP-complete in general, but the regular structure of the chessboard makes efficient heuristics possible.

The most well-known heuristic is Warnsdorff's rule (H.C. von Warnsdorff, 1823): at each step, move to the unvisited square that has the fewest onward moves. This greedy approach runs in linear time relative to the number of squares and finds a tour almost always on boards of size 5×5 and above.

🗺️ What We're Building

Phase	What Codex Builds	Output
Phase 1	Core solver using Warnsdorff's heuristic	CLI app, ASCII board output
Phase 2	Pytest test suite and colourised terminal output	ANSI colour board, passing tests
Phase 3	Flask web app with animated HTML canvas	Interactive browser visualisation

⚙️ Prerequisites

Before starting, make sure you have:

Codex CLI installed (brew install --cask codex or npm i -g @openai/codex)
Authenticated with a ChatGPT Plus/Pro account or an OpenAI API key
Python 3.10+ available in your shell
Git installed on your machine

📁 Project Setup

We'll use Git throughout this guide as a safety net. Configure your identity first if needed:

git config --global user.name  "Your Name"
git config --global user.email "you@example.com"

Create the project directory and initialise the repo:

mkdir knights-tour && cd knights-tour
git init
git commit --allow-empty -m "initial commit"
codex

Once the TUI loads, generate an AGENTS.md file first. It acts as a standing project-level system prompt — Codex reads it automatically at the start of every future session.

📝 Codex Prompt — Generate AGENTS.md

"Create an AGENTS.md file in the project root for a Python CLI and web application project. Include the following standing instructions: use Python 3.10+ with type hints throughout; place all tests in a /tests directory using pytest; never use global mutable state; prefer functions over classes unless OOP is genuinely the better fit; handle all CLI arguments with argparse; use Flask for any web routes; keep each module focused on a single responsibility."

Why prompt Codex to write AGENTS.md instead of writing it yourself? You describe your intent conversationally rather than worrying about format, and it sets the right mental model for the rest of the guide. You can update it at any time: "Add a rule that all functions must have docstrings" — Codex will edit the file in place.

Phase 1 — Core Solver

📝 Codex Prompt — Phase 1

"Create a Python CLI app that solves the Knight's Tour problem. Use Warnsdorff's heuristic: at each step, move to the unvisited square with the fewest onward moves. The board size and starting position (row, col) should be configurable via argparse with defaults of n=8, row=0, col=0. The solver should return None if no tour is found. Display the completed board as a grid of move numbers, right-aligned. Save the solver logic in knight_tour.py and the entry point in main.py. Include a requirements.txt and a .gitignore for Python."

Here's a simplified version of what the generated knight_tour.py looks like:

MOVES = [(2,1),(2,-1),(-2,1),(-2,-1),(1,2),(1,-2),(-1,2),(-1,-2)]

def get_neighbours(x, y, n, visited):
    return [(x+dx, y+dy) for dx,dy in MOVES
            if 0 <= x+dx < n and 0 <= y+dy < n
            and not visited[x+dx][y+dy]]

def solve(n, start_x, start_y):
    visited = [[False]*n for _ in range(n)]
    board   = [[-1]*n   for _ in range(n)]
    x, y = start_x, start_y
    visited[x][y] = True
    board[x][y]   = 0
    for move in range(1, n*n):
        neighbours = get_neighbours(x, y, n, visited)
        if not neighbours:
            return None
        x, y = min(neighbours,
                   key=lambda p: len(get_neighbours(p[0],p[1],n,visited)))
        visited[x][y] = True
        board[x][y]   = move
    return board

Run it to verify:

python3 main.py --size 8 --row 0 --col 0

💡 Approval Flow: In Codex's default Auto mode, press A to accept or R to reject each diff. If Codex proposes something you don't want, reject and follow up with a corrective prompt — it retains full context.

Phase 2 — Tests & Colourised Output

📝 Codex Prompt — Phase 2

"Now add two things. First, create a test suite in tests/test_knight_tour.py using pytest. Test that: (1) solve() returns a valid tour where every integer from 0 to n²−1 appears exactly once, (2) consecutive moves are a valid knight's move apart, (3) solve() returns None for n=2 which has no solution. Second, add a new function print_coloured_board() in knight_tour.py that uses ANSI escape codes to colour the board — alternate between a light and dark background for a chess-style pattern, with white text for the move numbers. Call it from main.py instead of format_board() when --colour flag is passed."

Key tests:

import pytest
from knight_tour import solve

def is_valid_knight_move(x1, y1, x2, y2):
    dx, dy = abs(x2-x1), abs(y2-y1)
    return (dx, dy) in {(1,2),(2,1)}

@pytest.mark.parametrize("n,r,c", [(5,0,0),(6,1,1),(8,0,0),(8,3,4)])
def test_valid_tour(n, r, c):
    board = solve(n, r, c)
    assert board is not None
    flat = sorted(v for row in board for v in row)
    assert flat == list(range(n*n))

def test_no_solution_n2():
    assert solve(2, 0, 0) is None

Install pytest and run:

pip3 install pytest
pytest tests/ -v
python3 main.py --size 8 --colour

Phase 3 — Flask Web App with Animated Visualisation

📝 Codex Prompt — Phase 3

"Add a Flask web app in app.py. It needs two routes: GET / serves a single-page HTML form where users can input board size (5–10) and starting row/col. POST /solve accepts these inputs, runs the solver, and returns the board as JSON. The HTML page should also contain a JavaScript canvas visualisation that animates the knight's path one move at a time — draw the board as a grid, colour visited squares progressively, and draw a ♞ symbol on the current square. Add flask to requirements.txt."

The key backend endpoint:

from flask import Flask, request, jsonify, render_template_string
from knight_tour import solve
app = Flask(__name__)

@app.route("/solve", methods=["POST"])
def solve_tour():
    data = request.get_json()
    n, row, col = int(data.get("size",8)), int(data.get("row",0)), int(data.get("col",0))
    if not (5 <= n <= 10):
        return jsonify({"error": "Board size must be between 5 and 10"}), 400
    board = solve(n, row, col)
    if board is None:
        return jsonify({"error": "No solution found"}), 422
    return jsonify({"board": board, "n": n})

pip3 install flask
python3 app.py
# Visit http://localhost:5000

🔄 Iterating Further — More Prompt Ideas

Goal	Follow-up Prompt
Speed comparison	"Add a backtracking solver as an alternative to Warnsdorff's. Add a --solver flag to switch between them, and time both with Python's timeit."
Export result	"Add a --export flag to main.py that saves the board as a CSV and a PNG using matplotlib, with the knight path drawn as a line."
User clicks board	"Update the web app so users click a cell on the canvas to set the starting position instead of using the form fields."
Code review	"Review the current codebase for edge cases, type annotation completeness, and any issues with input validation in app.py."

✅ Effective Prompting Tips for Codex

Tip	Why It Helps
Name your files explicitly	Codex won't guess at naming conventions — "save to knight_tour.py" prevents arbitrary filenames.
Specify what None/failure means	Without "return None if no tour is found," Codex might raise an exception instead.
Bundle related changes in one prompt	Codex handles multi-file tasks well when given in a single cohesive prompt.
Keep sessions alive for follow-ups	Staying in the same session means Codex retains full context — no re-explaining.
Use AGENTS.md for standing rules	Anything you'd say in every prompt belongs in AGENTS.md. It keeps prompts shorter and style consistent.

📁 Final Project Structure

knights-tour/
├── AGENTS.md
├── .gitignore
├── requirements.txt      ← flask
├── knight_tour.py        ← solver + display logic
├── main.py               ← CLI entry point
├── app.py                ← Flask web app
└── tests/
    └── test_knight_tour.py

The workflow rhythm: each Codex prompt builds on the last without re-explaining context, and AGENTS.md silently enforces project conventions. The three phases took roughly 15 minutes end-to-end, most of which was reviewing diffs and running tests rather than writing code.

The Knight's Tour is just the illustration. The same prompt-iterate-commit loop applies to any project — and the more you invest in a good AGENTS.md upfront, the more useful each Codex session becomes.

Eigenvectors and Eigenvalues: The Quantum Computing Secret Sauce

Malcolm Low — Sun, 26 Apr 2026 15:44:05 +0000

Eigenvectors and Eigenvalues: The Quantum Computing Secret Sauce

Ever wondered what makes quantum computers so powerful? At the heart of quantum mechanics—and thus quantum computing—lies a pair of mathematical twins: eigenvectors and eigenvalues. Don’t worry, no advanced linear algebra background needed. Let’s break it down with everyday analogies.

What Are Eigenvectors and Eigenvalues? (The Simple Version)

Imagine a spinning top. No matter how you tilt it, if you spin it around its symmetry axis, it just spins faster or slower—it doesn’t wobble. That axis is like an eigenvector: a special direction where a transformation (here, spinning) only stretches or shrinks the object, never changes its direction. The amount of stretching/shrinking is the eigenvalue.

In math terms: if you have a square matrix A (representing a transformation) and a vector v, then

A v = λ v

v is an eigenvector, λ (lambda) is its eigenvalue. The transformation A acting on v just scales it by λ.

Example: Finding Eigenvalues and Eigenvectors

Let’s compute the eigenvalues and eigenvectors for a simple matrix:

A = [2  1]
    [1  2]

Step 1: Set up the characteristic equation

We want to find scalars λ and non-zero vectors v such that A v = λ v.

Rearranging: (A - λI) v = 0.

For a non-zero solution v to exist, the matrix (A - λI) must be singular,

meaning its determinant equals zero: det(A - λI) = 0.

Solve det(A - λI) = 0:

det([[2-λ, 1], [1, 2-λ]]) = (2-λ)² - 1 = 0

Step 2: Solve for λ

Expand: λ² - 4λ + 3 = 0

Factor: (λ - 1)(λ - 3) = 0

Eigenvalues: λ₁ = 1, λ₂ = 3

Step 3: Find eigenvectors

For λ₁ = 1:

Solve (A - I)v = 0:

[[1, 1], [1, 1]] [v₁, v₂]ᵀ = 0 → v₁ + v₂ = 0

Choose v₁ = 1, then v₂ = -1

Eigenvector: v₁ = [1, -1]ᵀ
For λ₂ = 3:

Solve (A - 3I)v = 0:

[[-1, 1], [1, -1]] [v₁, v₂]ᵀ = 0 → -v₁ + v₂ = 0

Choose v₁ = 1, then v₂ = 1

Eigenvector: v₂ = [1, 1]ᵀ

Verification:

A v₁ = [[2,1],[1,2]] [1, -1]ᵀ = [1, -1]ᵀ = 1 · v₁  
A v₂ = [[2,1],[1,2]] [1, 1]ᵀ = [3, 3]ᵀ = 3 · v₂

Why Does This Matter for Quantum Computing?

1. Quantum States Are Vectors

A quantum system’s state (like an electron’s spin or a photon’s polarization) is represented by a vector in a complex vector space. For a single qubit, the state looks like:

|ψ⟩ = α|0⟩ + β|1⟩

where α and β are complex numbers, and |0⟩, |1⟩ are basis vectors.

2. Quantum Gates Are Matrices

Quantum operations (gates like X, H, CNOT) are unitary matrices. Applying a gate to a state means multiplying the state vector by that matrix.

3. Eigenvectors = Stable States

When a quantum gate acts on one of its eigenvectors, the state only picks up a phase factor (a complex number of magnitude 1). In other words, the state’s “direction” in Hilbert space stays the same—it’s just rotated in phase. These eigenvectors are the invariant directions under that gate.

4. Eigenvalues = Phase Shifts

The eigenvalue (a complex number e^iθ for unitary gates) tells you how much phase the eigenstate acquires. Phase is crucial in quantum interference—the phenomenon that lets quantum algorithms amplify correct answers and cancel wrong ones.

5. Diagonalization = Simulating Quantum Evolution

If you can find a basis of eigenvectors for a Hamiltonian (the energy operator governing time evolution), you can easily compute how the system evolves: each eigenstate just picks up a phase e^-iEt/ℏ where E is the eigenvalue (energy). This is the foundation of algorithms like Quantum Phase Estimation and Variational Quantum Eigensolver (VQE).

Everyday Analogies

Eigenvector = The “preferred spinning axis” of a quantum object under a certain operation.
Eigenvalue = How much the object’s phase twists when spinning around that axis.
Quantum Algorithm = Cleverly choosing operations so that the eigenvectors of the problem’s Hamiltonian align with the answer you want, then reading off the phases.

Further Exploration (Lay‑Friendly)

Watch: “Quantum Computing for the Determined” – visual analogies of spin and phase.
Read: “Quantum Computing Since Democritus” by Scott Aaronson – chapter on linear algebra, written with humor.

- Experiment: Use the IBM Quantum Experience to prepare an eigenstate of a Pauli gate and see the phase kickback.

Understanding Reversible Quantum Computation: Why Reversibility Matters in Quantum Computing

Malcolm Low — Fri, 24 Apr 2026 01:08:19 +0000

Understanding Reversible Quantum Computation: Why Reversibility Matters in Quantum Computing

Introduction

In the pursuit of more efficient and powerful computing paradigms, reversible quantum computation stands at the intersection of fundamental physics and practical engineering. While classical computing has benefited enormously from reversible logic concepts, quantum computing inherently requires reversibility due to the unitary nature of quantum evolution. This article explores why reversibility is not just beneficial but essential in quantum computing, and how it shapes the design of quantum algorithms and hardware.

The Thermodynamic Imperative: Landauer's Principle

To understand why reversibility matters, we start with Rolf Landauer's groundbreaking insight from 1961: information erasure has a thermodynamic cost. Specifically, erasing one bit of information necessarily dissipates at least kBT ln 2 joules of energy as heat, where k_B is Boltzmann's constant and T is the absolute temperature.

This principle reveals a profound connection between information theory and thermodynamics. In conventional (irreversible) computing, logic gates like AND, OR, and NAND lose information about their inputs when producing outputs. For example, knowing the output of an AND gate doesn't tell you uniquely what the inputs were - multiple input combinations can produce the same output.

Reversible computing avoids this information loss by ensuring that every computational step is invertible: given the output, you can uniquely determine the input. This eliminates the fundamental thermodynamic cost associated with information erasure.

Quantum Mechanics and Unitary Evolution

In quantum computing, reversibility takes on even greater significance due to the postulates of quantum mechanics. The time evolution of a closed quantum system is described by the Schrödinger equation, which implies that quantum state transformations must be unitary operations.

A unitary operation U satisfies U^†U = I, where U† is the conjugate transpose of U and I is the identity matrix. This property guarantees that:

The transformation is reversible (invertible)
Probability is preserved (the norm of the state vector remains 1)
No information is lost during the computation

Every quantum gate must therefore be represented by a unitary matrix. This is why quantum circuits are composed of reversible gates - it's not an optimization choice, but a fundamental requirement imposed by quantum mechanics itself.

Essential Reversible Quantum Gates

Several key gates form the foundation of reversible quantum computation:

The CNOT Gate (Controlled-NOT)

The CNOT gate flips the target qubit if and only if the control qubit is |1⟩:

|00⟩ → |00⟩
|01⟩ → |01⟩
|10⟩ → |11⟩
|11⟩ → |10⟩

Its unitary matrix is:

[[1, 0, 0, 0],
 [0, 1, 0, 0],
 [0, 0, 0, 1],
 [0, 0, 1, 0]]

The Toffoli Gate (CCNOT)

Often called the "quantum AND gate," the Toffoli gate flips the target qubit only when both control qubits are |1⟩. It's universal for classical reversible computation and, when combined with Hadamard gates, becomes universal for quantum computation.

The Fredkin Gate (CSWAP)

This controlled-swap gate exchanges the states of two target qubits conditioned on a control qubit being |1⟩. Like the Toffoli, it's universal for reversible classical computation.

Single-Qubit Rotations

Gates like the Hadamard (H), phase (S), and π/8 (T) gates, along with rotation gates (Rx, Ry, Rz), are all unitary and reversible. The Hadamard gate, for instance, is its own inverse: H² = I.

Why Reversibility Enables Quantum Advantage

The requirement of reversibility in quantum computing isn't merely a constraint - it's what enables quantum advantage:

Interference: Reversible unitary operations preserve quantum coherence, allowing probability amplitudes to interfere constructively and destructively. This interference is the mechanism behind quantum speedups in algorithms like Grover's search and Shor's factoring.
Entanglement Generation: Reversible gates like CNOT can create entangled states from separable ones. Entanglement, a uniquely quantum correlation, is essential for most quantum speedups.
Error Correction: Quantum error correction codes rely on the ability to reversibly encode and decode logical qubits into entangled states of multiple physical qubits.
Algorithmic Structure: Many quantum algorithms (e.g., quantum Fourier transform, amplitude amplification) are built from sequences of reversible operations that manipulate interference patterns to increase the probability of correct answers.

Reversibility vs. Irreversibility in Quantum Measurement

It's important to distinguish between quantum gate operations (which must be reversible) and quantum measurement (which is inherently irreversible). Measurement collapses the quantum state according to the Born rule, losing information about the pre-measurement superposition.

This asymmetry is fundamental: while quantum evolution is unitary and reversible, measurement introduces irreversibility and thermodynamical cost. Quantum algorithms carefully separate these phases - performing many reversible operations to shape the probability distribution, then performing a (typically) single irreversible measurement to extract the result.

Practical Implications for Quantum Hardware

The reversibility constraint affects quantum hardware design in several ways:

Gate Design

Physical implementations of quantum gates must realize unitary operations. This requires precise control over quantum systems (trapped ions, superconducting circuits, photonic systems, etc.) to implement the desired unitary without introducing dissipation or decoherence.

Error Sources

Irreversible processes in quantum hardware (decoherence, relaxation, dephasing) represent deviations from ideal unitary evolution. Quantum error correction aims to protect against these irreversibilities.

Energy Considerations

While Landauer's principle sets a lower bound on energy dissipation for irreversible classical operations, quantum gates ideally operate below this threshold since they're reversible. However, practical implementations still face energy costs from control electronics, cooling, and other overhead.

Applications and Current Research

Reversible quantum computation finds applications across the quantum computing stack:

Algorithm Design

Shor's algorithm: Relies on the quantum Fourier transform (a sequence of reversible gates) for period finding
Grover's algorithm: Uses reversible oracle and diffusion operators for amplitude amplification
Quantum simulation: Employs reversible Trotter-Suzuki decompositions to simulate Hamiltonian evolution

Quantum Error Correction

Codes like the surface code use stabilizer measurements (which are effectively reversible when conditioned on measurement outcomes) to detect and correct errors without destroying the encoded quantum information.

Reversible Logic Synthesis

Research continues on optimizing quantum circuits for minimal gate count, depth, and other metrics while preserving reversibility. Techniques include:

Template matching and optimization
Quantum circuit rewriting using algebraic identities
Reversible pebble games for space-time tradeoffs

Conclusion

Reversible quantum computation is not merely an interesting theoretical corner - it's the very foundation upon which quantum computing rests. The requirement of unitary, reversible operations emerges directly from the postulates of quantum mechanics and enables the uniquely quantum phenomena of superposition, entanglement, and interference that give quantum computers their potential power.

Understanding reversibility helps us appreciate why quantum computers look so different from classical ones, why quantum error correction is both necessary and possible, and how quantum algorithms achieve their remarkable feats of computation. As we continue to build larger and more reliable quantum computers, the principles of reversible computation will remain central to both theoretical advances and practical engineering breakthroughs.

The next time you encounter a quantum circuit diagram, remember: each gate represents a reversible, unitary transformation - a carefully choreographed dance of quantum states that preserves information while shaping the probabilities that ultimately yield quantum advantage.

*Tags: quantum-computing, reversible-computing, quantum-algorithms, quantum-physics