Counterfactual Fluid Dynamics

CfdFlow is a language with two levels. At the trajectory level, march advances a coupled run until a predicate fires and hands back a pause you can resume. At the campaign level,study runs a family of cases forked from that pause and ends in a Verdict. Here is the plasma-blackout corridor, condensed:

// Trajectory level: march until the evolved sheath's n_e crosses the GPS L1 cutoff.
let onset = CfdFlow::march(&nominal)
    .couple(world::corridor_coupling(1.0, 0))
    .trigger(trigger)
    .from_field(world::initial_field())
    .until(|field, _| field.regime().map(|r| r.gnss_denied).unwrap_or(false))?;

// Campaign level: fork that pause once per candidate bank command, fly every
// branch concurrently, score the rows — then refine around the coarse winner
// from the same onset, and gate the two-round result.
let corridor = CfdFlow::study("bank-angle corridor")
    .cases(model::coarse_commands())
    .fork(&onset)                            // the shared flow-resolved fork point
    .branch(model::bank_world)               // one alternated world per command
    .continue_for(constants::BRANCH_STEPS)   // concurrent, copy-on-write
    .reduce_all(model::score_branches)
    .refine(&onset, model::fine_candidates)  // second round, same paused onset
    .branch(model::bank_world)
    .continue_for(constants::BRANCH_STEPS)
    .reduce_all(model::score_branches)
    .gates(model::corridor_gates())          // steering beats ballistic; fine >= coarse
    .verdict()?;

The fork itself shares the marched tensor state in O(1) and copies nothing. What follows is copy-on-write: each branch takes a single clone at its first field write, and continuing a march always writes. So the honest per-branch cost is O(cells), not O(1). That clone covers the per-cell scalar vectors, the navigation engine and the provenance log. Each branch then continues in a world of its own.

This is why forking state is not the same as sweeping parameters. A sweep reruns from initial conditions. A fork starts from the plume, the sheath and the filter as they stand at that instant, so the branches answer the decision the vehicle actually faces.

• Fork setup 42 ns; branches enter by reference, with no tensor copied at fork time.
• Powered continuation costs 1.00–1.04× an unforked trunk; a coasting branch is cheaper at 0.67×.
• The corridor commits the best of seventeen worlds (six coarse, eleven fine) mid-descent: 2.07 m off the aim point against 20.00 m ballistic.
• A mid-burn fork of a marched, plume-coupled state departs a frozen-drag prediction by 139.4 m/s.

Branch fan-outs run on scoped threads and produce bits identical to the sequential run. Every branch stamps a!!ContextAlternation!! marker into its provenance log naming the baseline it replaced.

A campaign takes a second form. Instead of forking one pause, it alternates whole worlds from a baseline and flies an ensemble of each:

let table = CfdFlow::study("weather-dispersion table")
    .cases(model::weather_cases())
    .baseline(model::standard_day)
    .alternate(model::weather_world)
    .ensemble(constants::MC_DRAWS)
    .couple(|case, draw| world::corridor_coupling(model::bias_departure(case.d_temp), draw))
    .march_for(constants::STEPS, world::initial_field)
    .reduce_ensemble(model::world_row)
    .gates(model::weather_gates())
    .verdict()?;

Six atmospheres, eight receiver-noise draws apiece, forty-eight descents, one gated table. verdict() returns data; the DSL never prints and never exits, so the caller decides what an exit code means.

Walk 1: how the fork is builtBlueprint: fork a running simulation

A vehicle entering or leaving orbit crosses several regimes on the way, and they do not change together. Three axes are tracked independently.

Flow regime on freestream Knudsen number

RegimeClassify bands the Knudsen number into a governing model: continuum Navier–Stokes, slip-corrected continuum, transitional, or free-molecular. Every transition is logged.Today this is a diagnostic carried on the evolved state. The crate does not switch closures on it, and no slip, transitional or free-molecular closure is implemented.

Dynamics regime on force ratio ε = a_aero/a_grav

While gravity dominates, a trajectory advances on the exact KS-conformal core with aero applied as a between-step kick. Once aero dominates, direct Cowell integration is the accurate choice. This ratio is the criterion for entering and leaving orbit.RegimeSwitch and aero_gravity_ratio are public API, but the shipped navigation engine does not call them. Applying the switch is the caller’s job.

Link regime on evolved electron density

The electron density sets the plasma frequency, and the plasma frequency decides whether the GNSS link exists. The Kalman filter’s measurement gating follows it.

The classifier is a stage in the coupling stack. It re-runs each step and writes its result onto the evolved field, and a march predicate reads it back. A transition is therefore an event the run finds, not a station it was told to stop at:

// RegimeClassify sits in the coupling stack and re-runs every step.
Coupling::between_steps()
    .then(FiniteRateIonizationStage::new(n_tot))   // writes "n_e"
    .then(RegimeClassify::new(l_char, trigger))    // reads it, classifies
    .build()

// field.regime() -> Option<RegimeClass<R>> {
//     model,            // Continuum | Slip | Transitional | FreeMolecular
//     knudsen,          // the Kn the model was selected from
//     plasma_frequency, // omega_p at the peak electron density
//     gnss_denied,      // omega_p above the configured comms band
//     mach_regime, thrust_state, touchdown,   // the powered-descent axes
// }

// A transition is a leg boundary: march until the classification changes.
let onset = CfdFlow::march(&nominal)
    .couple(world::corridor_coupling(1.0, 0))
    .from_field(world::initial_field())
    .until(|f, _| f.regime().map(|r| r.gnss_denied).unwrap_or(false))?;   // link lost

let exit = CfdFlow::march(&nominal)
    .alternate_context(&committed)
    .couple(world::corridor_coupling(1.0, 0))
    .from(peak.state())
    .until(|f, _| f.regime().map(|r| !r.gnss_denied).unwrap_or(false))?;  // link back

Blackout becomes an interval the run discovers. March to the onset event, fly the committed world through the dark, continue to the recovery event. Every transition lands in the provenance log. From a committed corridor run:

regime -> slip (GNSS-available), Kn=0.07829109848665225
regime -> slip (GNSS-denied), Kn=0.012690837165407727
regime -> continuum (GNSS-denied), Kn=0.00993838892165156
regime -> continuum (GNSS-available), Kn=0.0002551442196046344

One descent moves through orbit-like dynamics, slip flow, continuum flow, comms blackout and reacquisition, in one uninterrupted program.

Walk 1: the classifier in the stackBlueprint: handle a regime change

Coupling::between_steps()
    .then(VibrationalLagStage::new(/* Millikan-White bath */))
    .then(FiniteRateIonizationStage::new(n_tot).with_density_field("n_tot"))
    .then(RegimeClassify::new(l_char, trigger))
    .then(BankSteeredLift::new(rho_ref, cda_over_m, l_over_d))
    .then(TrajectoryNav::new(q_diag, gnss_var, optical_var).with_imu(imu))
    .then(CyberneticCorrect::new(SafetyEnvelope::new(q_max, g_max, bank_max)))
    .build()

Vibrational relaxation, reacting plasma chemistry, regime classification, steered aerodynamic force, a 17-state error-state Kalman filter and a bounded-correction safety gate, in one loop body. Stages talk to each other through named fields on the evolved state. An Err from any stage short-circuits the whole step.

Read the loop once and the circuit is visible. The evolved electron density gates which measurements the Kalman filter may fold. The Knudsen number selects the governing model. The safety gate’s clamped bank command is flown by the aero stage, which steers the trajectory that sets the next step’s freestream. Fluid dynamics, estimation and control close one loop, in one process.

That one stack is the loop body at both levels of the language. A trajectory march couples it directly. A campaign couples it per case and per draw, threading the ensemble index into the stack, and flies the whole matrix concurrently:

// Trajectory: couple the stack, march a fixed horizon, get one report.
let report = CfdFlow::march(&world).couple(stack).from_field(field0).run_for(steps)?;

// Campaign: the same stack, coupled per case and per draw, flown concurrently.
let table = CfdFlow::study("weather-dispersion table")
    .cases(model::weather_cases())
    .couple(|case, draw| world::corridor_coupling(model::bias_departure(case.d_temp), draw))
    .march_for(constants::STEPS, world::initial_field)
    .reduce_ensemble(model::world_row)
    .verdict()?;

Configuration is a separate layer from execution. Theflow_config layer holds owned descriptions: grids, schedules, seeds, stop conditions, observables, world-published constants. The flow layer materializes runs from them. A counterfactual is then the same flow handed a different description.

• Plasma-retropulsion descent, blackout exit to touchdown: 2516 coupled steps across 4 legs, 16 gates, 355.6 s wall clock.
• Weather-dispersion table: 6 atmospheres × 8 receiver-noise draws, 48 descents, flown concurrently to one gated table in 184.0 s.
• Precision is a parameter of the whole stack: f32, f64 or 106-bit, changed at one type alias.

The three-walk tutorialBlueprint: couple multiphysicsBlueprint: couple navigation to physics

Every stage that changes the story of a run appends an entry: a regime transition, a navigation mode change, a pause, a re-seed, a world replacement. The corridor descent carries sixteen of them. Here are thirteen, in order, from the committed run:

regime -> slip (GNSS-available), Kn=0.07829109848665225
nav: aided (position fix folded)
regime -> slip (GNSS-denied), Kn=0.012690837165407727
nav: dead reckoning (no usable fix)
march paused at step 131
leg re-seeded from step 131 in world 'fine_bank_08': coupled field carried, ...
!!ContextAlternation!!: world 'nominal_descent' replaced with 'fine_bank_08'
regime -> continuum (GNSS-denied), Kn=0.00993838892165156
march paused at step 96
leg re-seeded from step 96 in world 'fine_bank_08': coupled field carried, ...
!!ContextAlternation!!: world 'nominal_descent' replaced with 'fine_bank_08'
regime -> continuum (GNSS-available), Kn=0.0002551442196046344
nav: aided (position fix folded)

Two things are worth reading closely. First, theregime -> entries and the nav: entries are interleaved in one sequence. That is what "across boundaries" means: the flow regime changed, the link died, the filter fell back to dead reckoning, and it is one chain rather than four logs to correlate afterwards. Second, the !!ContextAlternation!! entries name both sides of the intervention, the world replaced and the world that replaced it, so a counterfactual is auditable rather than implied.

Comparing across a transition

Because the log spans the transition, the same quantity can be read on both sides of it. The corridor's navigation error through the blackout, as committed:

Variance grows by two orders of magnitude in the dark, then comes back once fixes resume. The same structure supports the comparison you usually want across a Mach boundary: the retropulsion descent logs supersonic, transonic and subsonic entries in one sequence with the thrust state on each line, so the flow parameters before and after the transition sit in the same record.

Comparing across branches

Each branch of a fan-out writes its own scenario log, so a variant that failed can be diffed against one that passed rather than re-run under a debugger. The weather table gates on exactly this: every dispersion world must carry the marker naming its baseline. Where a campaign uses the coupled march_for path, an optionalsave_log(path) flushes provenance to disk, one file per branch plus a .main.log naming every spawn and rejoin. Thefork / branch / continue_for chain does not thread that sink and writes no files; those branches still carry their full provenance in the returned report.

• Corridor descent: 16 entries covering four legs, two regime bands and one committed counterfactual.
• Retropulsion descent: 22 entries covering blackout, ignition commit, a carrier rebuild, the stopping burn and touchdown.
• Weather table: 48 descents, each carrying its own log, gated on the alternation marker naming its baseline.

Walk 2: one baseline, six worldsBlueprint: fork a running simulationThe committed run output ↗