Step-by-step course guide

Audience: engineers who want physics-inspired primitives — consensus, routing, sampling, risk, thermodynamics — as ready-to-call AIMarket oracles. Languages: COURSE_LANG=en|ru|es|fr|zh · UI strings in i18n/ · this guide in English. Русский · Español · Français · 中文

Check against the current ecosystem

Use Hub discovery to inspect a current capability ID, source and advertised price before any live invocation. Save the exact input used for the deterministic lab, then separate the algorithm’s verification output from any signed work receipt a live execution provides. An empty discovery result means this query returned no match at the time.

Why this course

Most "AI" courses stop at prompting. This one teaches deterministic, physics-inspired computation that you can verify, certify, and bill — the kind of primitive that sits underneath an agent, not on top of it. Each module wraps a real AIMarket oracle: Murmuration (robust swarm consensus), Colony (TSP tours with an admissible optimality-gap certificate), Turing (blue-noise sampling), Ablation (systemic-risk cascades as a self-organised-critical sandpile), and Landauer (the kT·ln2 thermodynamic floor on irreversible compute).

Every lab is reproducible (seeded, no LLM by default) and prints a Trace you can inspect. By the end you can call any of these five oracles, read its output, and earn a course certificate.

Choose your track
Setup (10 minutes)
Module M1 — Murmuration consensus
Module M2 — Colony TSP certificate
Module M3 — Turing blue-noise
Module M4 — Ablation cascade risk
Module M5 — Landauer thermodynamic audit (advanced)
Tracing in every lab
Exercises & certificate
Bridge: from course to AIMarket
Self-check checklist
Troubleshooting

Choose your track

Track	Modules	Time	NumPy	LLM
Basic	M1 → M2 → M3 → M4	~2 h	Yes (`[oracles]`)	No
Advanced	Basic + M5	+45 min	Yes	No

Every lab is deterministic — there is no LLM in this course. The "intelligence" is in the physics: robust statistics, combinatorial bounds, criticality, thermodynamics. Read the Tracing note after each lab — every script prints a Trace block.

Setup (10 minutes)

Step 1 — Clone and install

git clone https://github.com/alexar76/aimarket-courses.git
cd aimarket-courses/physics-inspired-computing-course
pip install -e ".[oracles,dev]"

The [oracles] extra pulls in NumPy (the only runtime dependency); [dev] adds pytest. Python 3.11+ is required.

Inside the aicom monorepo? You can skip the oracle wheels — the labs resolve murmuration, colony, turing, ablation, and landauer straight from oracles/oracles/* via courselib/oracle_paths.py. Outside the monorepo, [oracles] is what makes the imports work.

Step 2 — Verify tests

pytest -q

Expected: all tests pass (i18n parity across en/ru/es/fr/zh, oracle bridges, certificate, exercises).

Step 3 — Pick a language (optional)

export COURSE_LANG=ru   # or es, default en
python labs/lab01_murmuration_consensus.py

COURSE_LANG switches every lab's printed strings (titles, concepts, labels) via courselib/i18n.py. Numbers, oracle names, and trace kinds stay the same — only the prose is localized. Unknown values fall back to English, never crash.

Step 4 — Colab alternative

Open the course site → Open in Colab on any lab.
Run the setup cell (clone + pip install -e ".[oracles,dev]").
Set os.environ["COURSE_LANG"] = "ru" in the setup cell if needed.
Run the lab cell.

Module M1 — Murmuration consensus

Concept: robust DeGroot consensus and Tukey-biweight aggregation over noisy agent estimates. Lab: labs/lab01_murmuration_consensus.py · Oracle: Murmuration · Time: ~15 min · Track: basic

Steps

Open labs/lab01_murmuration_consensus.py and read the docstring (industry map: swarm intelligence, robust stats).

Run it:

python labs/lab01_murmuration_consensus.py

The lab feeds six estimates — five near 2.0 plus one wild outlier 50.0 — into the oracle and prints:
- median, trimmed_mean, biweight
- converged value and the number of DeGroot iterations
- a Trace block at the end
Note that biweight ≈ 2.0 even though the raw mean would be ~10 — the outlier is resisted, not averaged in.
Skim courselib/physics.py::murmuration_aggregate and the oracle's murmuration.consensus.aggregate.

What it proves

A single bad sensor (or a malicious agent) cannot drag the consensus. The biweight estimator down-weights far-out points, so the swarm agrees on the truth, not the noise.

Self-check

[ ] You can explain why biweight < mean for this input
[ ] You see why the lab is deterministic (no LLM, seeded data)

Module M2 — Colony TSP certificate

Concept: nearest-neighbour + 2-opt tour with an admissible optimality-gap bound. Lab: labs/lab02_colony_tsp.py · Oracle: Colony · Time: ~20 min · Track: basic · Prerequisites: M1

Steps

Run:
```
python labs/lab02_colony_tsp.py
```
The lab solves a 6-city tour and prints:
- tour (the visiting order)
- length of the tour
- lower_bound (a provable floor on the optimal length)
- gap as a percentage — how far the tour could be from optimal
Read the Trace block — the tsp event logs length and gap.
The key idea: length ≥ lower_bound always, so gap is a certificate. You ship the tour and a guarantee on its quality.

What it proves

You don't need the exact optimum to act — a small gap (say < 5%) is often a good-enough answer with a number attached. This is how you make heuristics accountable.

Self-check

[ ] You can read the gap and say "this tour is at most X% worse than optimal"
[ ] You understand why length is never below lower_bound

Module M3 — Turing blue-noise

Concept: Mitchell best-candidate sampling for even-but-irregular point sets. Lab: labs/lab03_turing_bluenoise.py · Oracle: Turing · Time: ~20 min · Track: basic · Prerequisites: M1

Steps

Run:
```
python labs/lab03_turing_bluenoise.py
```
The lab requests 64 points (candidates=12, seed=2026) and prints:
- count
- min_distance — the smallest gap between any two points
- seed and its seed_source
- a 3-point sample of the coordinates
Compare to a uniform-random scatter: blue-noise maximises the minimum distance, so there are no clumps and no gaps.
Re-run with a different seed (edit the lab) — the layout changes but min_distance stays high.

What it proves

Blue-noise sampling beats naive random sampling for Monte Carlo, dithering, and procedural placement: even coverage with no visible structure.

Self-check

[ ] You can explain why a high min_distance is the goal, and that seed makes the sample reproducible

Module M4 — Ablation cascade risk

Concept: Abelian sandpile self-organised criticality — power-law avalanche sizes and tail risk. Lab: labs/lab04_ablation_cascade.py · Oracle: Ablation · Time: ~20 min · Track: basic · Prerequisites: M1

Steps

Run:
```
python labs/lab04_ablation_cascade.py
```
The lab builds a small directed exposure graph (demo_exposure_graph() — banks A→D plus a sink), drops 1200 grains, and prints:
- tau — the power-law exponent of the avalanche-size distribution
- max_avalanche — the largest cascade observed
- cvar95 — the 95% conditional value-at-risk (expected size of the worst 5% of cascades)
- topple_total
Read the Trace block — the cascade event logs tau and max_avalanche.
The intuition: in a critical system, small perturbations occasionally trigger system-wide cascades. tau and cvar95 quantify that tail.

What it proves

Average behaviour hides the danger. A heavy-tailed (tau-governed) distribution means rare-but-huge cascades dominate the risk — exactly the failure mode of interconnected financial or infrastructure networks.

Self-check

[ ] You can explain why a mean avalanche size understates the risk
[ ] You know what cvar95 measures versus a simple average

Module M5 — Landauer thermodynamic audit (advanced)

Concept: the kT·ln2 bit-erasure energy floor over an operation DAG. Lab: labs/lab05_landauer_audit.py · Oracle: Landauer · Time: ~30 min · Track: advanced

Steps

Run:
```
python labs/lab05_landauer_audit.py
```
The lab audits a small irreversible circuit (demo_circuit_ops() — two inputs, an AND gate, an output) at temperature_k=300.0 and prints:
- irreversible_bits — bits destroyed by the logic
- energy_floor_j — the Landauer floor in joules (kT·ln2 per erased bit)
- efficiency
- circuit_commitment — a hash committing to the audited circuit
Read the Trace block — the landauer event logs bits and floor_j.
The physics: erasing one bit at temperature T costs at least kT·ln2 joules. An AND gate destroys information (two inputs → one output), so it has a non-zero floor.

What it proves

There is a hard, temperature-dependent lower bound on the energy any irreversible computation must dissipate. The audit turns that physical law into a number you can attribute to a circuit — and the circuit_commitment makes the audit tamper-evident.

Self-check

[ ] You can name the kT·ln2 floor and what each term means
[ ] You understand why the AND gate has irreversible_bits ≥ 1

Tracing in every lab

Concept: every lab logs a Trace so its behaviour is inspectable, not magic. Covered in: all five labs · Time: 5 min after each lab

Every script builds a courselib.trace.Trace and calls trace.log(kind, **fields). The lab prints how many events it recorded; the kind (consensus, tsp, bluenoise, cascade, landauer) tells you which physics primitive ran and the fields capture the headline numbers.

Steps (repeat after each lab)

Scroll to the trace / events line at the end of the lab output.
Map the logged kind and fields to the result block you just read.
Treat the trace as the lab's "unit-test log" — in production these become billing receipts and audit records.

Self-check

[ ] You can match each trace event to a printed result
[ ] You see the trace as the bridge from lab output to a verifiable receipt

Exercises & certificate

After the labs, run the DIY checks:

python labs/run_exercises.py

This runs all five module exercises (m1–m5) and prints a ✓/✗ per module. Run one at a time while iterating:

python labs/run_exercises.py --module m4

Each exercise asserts the property the lab teaches — e.g. m1 checks that biweight resists an outlier, m2 that length ≥ lower_bound, m4 that tau > 0.5.

Once all five pass, generate your certificate:

python labs/run_exercises.py --certificate "Your Name" --lang en

This writes certificate.html (use --lang ru or --lang es for a localized credential). Open it in a browser and Print → Save as PDF. The credential ID is a hash of name + date, so it is stable and verifiable. Pass --skip-check only if you want the HTML without re-running the exercises.

Bridge: from course to AIMarket

The five oracles you called locally are the same packages served live in the AIMarket ecosystem. To go from "I ran the lab" to "I called a hosted oracle":

Course (local lab)	AIMarket (hosted oracle)
M1 `murmuration_aggregate`	Murmuration oracle — consensus capability
M2 `colony_tsp`	Colony oracle — routing + certificate
M3 `turing_bluenoise`	Turing oracle — sampling capability
M4 `ablation_cascade`	Ablation oracle — systemic-risk capability
M5 `landauer_audit`	Landauer oracle — thermodynamic audit
Lab `Trace`	Hosted invoke receipt + provenance

The circuit_commitment (M5) and the gap certificate (M2) are exactly the kind of verifiable output that lets a buyer trust an oracle's answer without re-running it.

Self-check checklist

After the basic track you should be able to:

[ ] Run lab01–lab04 locally and in Colab
[ ] Explain robust consensus (M1) and why the outlier is resisted
[ ] Read a TSP gap certificate (M2) as a quality guarantee
[ ] Say why blue-noise (M3) beats uniform random for coverage
[ ] Describe what tau/cvar95 capture about cascade risk (M4)
[ ] Read a Trace block and match each event to a result

After the advanced track add:

[ ] Run lab05 and state the kT·ln2 floor in words
[ ] Pass all five exercises and generate a certificate

Troubleshooting

Problem	Fix
`ModuleNotFoundError: courselib`	Run from the repo root; labs prepend the parent dir to `sys.path`
`ImportError: Oracle package '…' not installed`	Run `pip install -e ".[oracles]"`, or run from inside the aicom monorepo so `oracles/oracles/*` resolves
`ModuleNotFoundError: numpy`	The `[oracles]` extra installs NumPy — re-run `pip install -e ".[oracles,dev]"`
Python version error	Course requires Python 3.11+
Empty / English strings under another language	Set `COURSE_LANG`; check the key exists in `i18n/ru.json` / `i18n/es.json`
pytest i18n parity failure	Add the missing key to all three of `i18n/en.json`, `ru.json`, `es.json`
Certificate refuses to generate	Exercises must pass first; run `python labs/run_exercises.py`, or pass `--skip-check`
Colab running old code	Re-run the setup cell; pin the `main` branch

Regenerate site & notebooks

After editing labs or i18n/:

python3 scripts/build_course_assets.py

Guides in docs/ are hand-maintained — update EN first, then mirror the RU/ES versions.

Step-by-step course guide

Check against the current ecosystem

Why this course

Table of contents

Choose your track

Setup (10 minutes)

Step 1 — Clone and install

Step 2 — Verify tests

Step 3 — Pick a language (optional)

Step 4 — Colab alternative

Module M1 — Murmuration consensus

Steps

What it proves

Self-check

Module M2 — Colony TSP certificate

Steps

What it proves

Self-check

Module M3 — Turing blue-noise

Steps

What it proves

Self-check

Module M4 — Ablation cascade risk

Steps

What it proves

Self-check

Module M5 — Landauer thermodynamic audit (advanced)

Steps

What it proves

Self-check

Tracing in every lab

Steps (repeat after each lab)

Self-check

Exercises & certificate

Bridge: from course to AIMarket

Self-check checklist

Troubleshooting

Regenerate site & notebooks