lecture_5/README.md

# Lecture 5: Discrete Flow Matching (Chapter 5)

Chapter 4 fixed a corruption process and solved for its reverse. In this lecture we reverse that
order, picking the probability path first, writing down a velocity that generates it, and reading
the sampler off the velocity. On tokens the velocity is a rate matrix read from the destination's
side, and the master equation is the condition under which it generates a path. The mixture path
`(1 - kappa_t) delta_{x_0} + kappa_t delta_{x_1}` at each position has a conditional velocity, which
a posterior average turns into the schedule factor times a denoiser, and we recover that denoiser
with cross-entropy on the data token. Everything after that is a choice made inside the same
construction: a schedule, a corrector, a kinetic-optimal path, edits that change the length, a
relaxation of the token into a point of the simplex or of a sphere, a guidance tilt, or a different
coupling.

Two conventions hold in every file, and we state them at the top of each. Time runs from the
source at `t = 0` to the data at `t = 1`, so `kappa_t` here equals the survival probability
`alpha_{1-t}` of Chapter 4. The probability velocity `u_t(y, x)` is the same number Chapter 4
writes as the rate `R_t(x, y)`, with the two arguments exchanged.

## The files

Every script here runs on the synthetic DNA that `cis6270.data` generates, 512 sequences of length
16 over A, C, G, T, with a GC-rich background and the motif ACGT planted in three quarters of them
at one of three positions. Those sequences have GC fraction 0.577, motif fraction 0.777 and token
entropy 1.374 of `log 4 = 1.386`, and we measure a trained sampler against those three numbers.

| File | Command | What it does |
| --- | --- | --- |
| `dfm.py` | `python lecture_5/dfm.py` | The coupling, the mixture path, the conditional velocity, the posterior average, the cross-entropy loss and the two-part Euler rule. Trains a denoiser and generates DNA from either source, `--source uniform` or `--source mask`. |
| `velocity.py` | `python lecture_5/velocity.py` | Works the mathematics with nothing learned: a jump rate written as a velocity, the two rules, the master equation, the worked DNA velocity, survival and hazard, and the continuous and discrete velocities side by side. |
| `corrector.py` | `python lecture_5/corrector.py` | Velocities with zero net flux, the three-state example, the corrector for the mask source, the jump counts at three corrector strengths, and the parallel-step error. |
| `kinetic_optimal.py` | `python lecture_5/kinetic_optimal.py` | The flux and its energy, the velocity of least energy, the kinetic optimality of the mixture path, the transition distance on DNA, the worked metric path, and the energy of the linear and geodesic schedules. |
| `edit_flows.py` | `python lecture_5/edit_flows.py` | Insertions, deletions and substitutions; alignments and the column-wise path; the posterior over two alignments; the rate loss; one sampler step; and the length statistics of a run on DNA pairs of different lengths. |
| `dirichlet.py` | `python lecture_5/dirichlet.py` | The Dirichlet family as a conditional path, the speed from the flux across a cut, the two-letter closed form, the worked speeds on a DNA base, and the posterior average. Trains a denoiser on the simplex and integrates to `t = 8`. |
| `fisher.py` | `python lecture_5/fisher.py` | The Fisher information as a metric, the square-root map to the sphere, geodesics, the tangent projection and the regression loss. Trains a velocity field and samples with exponential-map steps. |
| `gumbel.py` | `python lecture_5/gumbel.py` | The Gumbel-max trick, the cooling temperature, the annealed path, the replicator equation, the inference-time velocity, and training against the marginal velocity. |
| `guidance.py` | `python lecture_5/guidance.py` | Guidance as a tilt of the rates, the h-transform, the reachable set, the guidance strength, the classifier-free form, the Taylor expansion of the log ratio, and the guided sampler. Steers toward the GC label with `--gamma`. |
| `multi_objective.py` | `python lecture_5/multi_objective.py` | The Pareto front, MOG-DFM's rank, direction and cone with the controller that widens it, and pCoMole's worst-objective utility with a rollout of the base flow on DNA. |
| `rectify.py` | `python lecture_5/rectify.py` | Total correlation on two bases, ReDi's recoupling rounds run on the exact sampler, and AReUReDi's Tchebycheff tilt with its Metropolis acceptance step. |

Every file takes the shared flags of `cis6270.runner`. `--steps 20 --quiet` runs each one in a few
seconds, and `--steps` controls the training steps in the five files that train, the grid in the
five that integrate, and the number of rollouts in `multi_objective.py`.

## The numbers a default run produces

At seed 0 on one core, the five files that train take under half a minute each, and the other six
take one to seven seconds. The worked numbers are exact and repeat on any machine; the trained
numbers move a little with the hardware's floating point.

| File | Headline numbers |
| --- | --- |
| `dfm.py` | loss 0.876 nats, GC fraction 0.578, motif fraction 0.672, token entropy 1.374 of `log 4 = 1.386` |
| `velocity.py` | `p_dot = (-0.1, -0.2, 0.7, -0.4)`, Euler step `(0.09, 0.18, 0.37, 0.36)`, hazard 2 at `t = 0.5` and 10 at `t = 0.9`, Euler error 0.0002 against the closed form |
| `corrector.py` | masked fraction 0.500 at `t = 0.5` for every `eta`, jumps per position 1.000, 2.991 and 10.934 at `eta = 0, 2, 10`, pair survival 0.133 measured against the predicted 0.135 at `eta = 2` |
| `kinetic_optimal.py` | rate out of C 5.780, `p_dot = (-0.3997, -0.4774, 1.3546, -0.4774)` from the velocity and from the path, energy 27.63 and 41.45 for the linear schedule, `pi^2 = 9.8696` for the geodesic one |
| `edit_flows.py` | averaged edit rates 0.667, 1.333 and 0.667 for a total of 2.667, example loss 3.446, untouched 0.8452 against the first-order 0.8350, DNA length 13.945 at `t = 0.5` against the predicted 13.941 |
| `dirichlet.py` | speeds 0.232, 0.199, 0.159, 0.104 at `t = 1`, continuity residual `2.5e-08`, loss 1.027 nats, GC fraction 0.532, motif fraction 0.547 |
| `fisher.py` | Fisher-Rao distance 1.485 against the Euclidean 0.141 and 0.013 on the two moves, arc 0.3713 from the midpoint, loss 0.278, GC fraction 0.576, motif fraction 0.203 |
| `gumbel.py` | path `(0.0528, 0.0214, 0.8781, 0.0477)` at `t = 1`, replicator velocity `(-0.136, -0.217, 0.500, -0.147)`, loss 0.672 nats, GC fraction 0.572, motif fraction 0.516 |
| `guidance.py` | guided destination `(0.029, 0.203, 0.478, 0.290)`, exit rate 2.50 at the exact `h`, GC fraction 0.531 unguided, 0.657 at `gamma = 2` and 0.698 at `gamma = 5` |
| `multi_objective.py` | combined score `(-1.511, 1.541, 2.297, -2.327)`, cone angles 47.7, 37.9 and 107.7 degrees, selection `(0.371, 0.629, 0)` after the chapter's rollouts, and on DNA a base selection of `(0.417, 0.583)` that the rollout value turns into `(0.962, 0.038)` |
| `rectify.py` | total correlation 1.386, 1.101, 0.843, 0.696 and 0.616 over rounds 0 to 4 against the limit 0.520; one-step success 25.0%, 40.3%, 52.5%, 58.0% and 60.4% against the limit 62.5% |

With four thousand training steps, about two minutes a file, we get a sampler that reaches the
planted motif more often: `dfm.py` goes from 0.672 to 0.734 against the data's 0.777, and
`fisher.py` from 0.203 to 0.453, while the other numbers in each report stay where the table has
them.

`tests/test_lecture_5.py` asserts the chapter's worked numbers against these files, including the
posterior 0.625 and 0.375 at a masked position, the entropy 0.6616 that bounds the loss there, the
velocity `(0.2, 1.2, -1.6, 0.2)` out of G, the metric-path rates 0.898 and 4.882 out of C, the
Dirichlet speeds, the Fisher-Rao arc, the Gumbel-softmax path at four times, the guided destination
distribution, the Pareto front, and the ReDi rounds.

## What is simplified

- The corrector simulation uses 40,000 positions where the chapter uses 200,000. Pass
  `--positions 200000` to reproduce the chapter's figures exactly.
- The parallel-step section measures the survival probability of a jointly revealed pair, which is
  the quantity the chapter computes in closed form. At a fine grid the end-to-end error of the
  corrector stays at or above its value at `eta = 0`, because the admissible step shrinks with
  `eta`.
- `edit_flows.py` runs the column-wise path on one sampled alignment per pair, which the chapter's
  marginalization theorem permits, and trains nothing, so the edit intensities of its sampler
  section are the chapter's own numbers.
- `dirichlet.py` evaluates the derivative of the regularized incomplete beta function by a central
  difference on `scipy.special.betainc`, in double precision whatever the ambient dtype, since the
  two values agree to six decimals. For the continuity check we differentiate the flux with a
  five-point stencil.
- `rectify.py` runs ReDi with the exact marginal velocity of the current coupling on a
  two-position state space, so it trains nothing, and its AReUReDi section works one Metropolis
  iteration and stops there.
- `guidance.py` trains the denoiser and the property model under one optimizer, and the property is
  the GC label of `cis6270.data`, not a biological measurement.
- `multi_objective.py` trains nothing. Its two DNA objectives are the GC fraction and the AT
  fraction of a finished sequence, its feasible set is the sequences carrying the planted motif,
  and the base flow a rollout continues is the mask-source sampler with the data's letter frequency
  as its denoiser.
- The relaxed paths replace the token lookup of `cis6270.nets.SequenceDenoiser` with a linear map on
  the relaxed token, and leave the rest of the network untouched.