dsfb-dscd

Deterministic Structural Causal Dynamics (DSCD) on top of dsfb + dsfb-add.

This crate builds trust-gated causal DAGs from deterministic observer traces, sweeps trust thresholds, and exports finite-size scaling artifacts for certifiable analysis in safety-critical autonomy workflows.

What This Crate Does

dsfb-dscd provides:

A CLI binary (dsfb-dscd) for deterministic end-to-end DSCD runs.
A library API for custom pipelines (DscdConfig, DscdParams, run_dscd_simulation).
Deterministic threshold sweeps rho(tau) and finite-size scaling outputs.
Provenance-rich edge/event exports for auditability and replay.

At a high level:

Generate deterministic event/observer traces from dsfb.
Compute structural descriptors from dsfb-add (AET/IWLT-derived quantities).
Construct local candidate edges with strict temporal/structural locality.
Apply trust gating across a tau grid to produce threshold curves.
Compute scaling summaries (tau*, transition width, max derivative).
Export CSVs used by the DSCD notebooks and paper figures.

Why Use DSCD

DSCD is designed for settings where reproducibility and traceability matter:

Deterministic outputs for a fixed config and toolchain.
Explicit local-causal constraints (temporal lag + structural radius).
Bounded out-degree for certification-friendly graph complexity.
Full edge provenance exports to support post-run audits.
Ready-to-plot CSV artifacts for finite-size threshold analysis.

Quick Start

Demo mode (free Colab / laptop):

cargo run -p dsfb-dscd --release -- --mode demo

Performance mode (workstation):

cargo run -p dsfb-dscd --release -- --mode performance

Custom run (override locality and scaling knobs):

cargo run -p dsfb-dscd --release -- --mode performance \
  --num-events 100000 \
  --tau-min 0.0 \
  --tau-max 1.0 \
  --tau-steps 256 \
  --max-temporal-lag 64 \
  --max-structural-radius 0.1 \
  --temporal-decay-gamma 0.0 \
  --structural-decay-beta 2.0 \
  --max-out-edges 8 \
  --scaling-ns 5000,10000,20000,50000,100000 \
  --root-event-id 0 \
  --output-root output-dsfb-dscd

CLI Parameters

--mode {demo|performance}: select preset scale and tau-grid density.
--num-events <usize>: override event count used for the representative run.
--scaling-ns <csv>: comma-separated N values for scaling curves.
--tau-min <f64>: lower threshold bound.
--tau-max <f64>: upper threshold bound.
--tau-steps <usize>: number of thresholds in the sweep grid.
--max-temporal-lag <usize>: max forward edge span in event index.
--max-structural-radius <f64>: max structural distance for local edges.
--temporal-decay-gamma <f64>: exponential temporal trust decay rate.
--structural-decay-beta <f64>: exponential structural trust decay rate.
--max-out-edges <usize>: per-source out-degree cap.
--output-root <path>: output root containing timestamped run dirs.
--root-event-id <u64>: reachability root used in expansion metrics.

Library API Usage

use dsfb_dscd::{DscdConfig, DscdParams, run_dscd_simulation};
use std::path::PathBuf;

fn main() -> anyhow::Result<()> {
    let cfg = DscdConfig {
        params: DscdParams::demo(),
        root_event_id: 0,
        output_dir: PathBuf::from("output-dsfb-dscd/standalone-run"),
        scaling_ns: vec![5_000, 10_000, 20_000],
    };
    run_dscd_simulation(&cfg)?;
    Ok(())
}

Significant Code Components

src/main.rs: CLI surface, presets (demo/performance), argument parsing, run orchestration.
src/paper.rs: canonical DSCD pipeline used for paper-grade outputs.
- DscdParams: core locality/decay/sweep parameters.
- DscdConfig: runtime configuration including output directory and scaling Ns.
- run_dscd_simulation: deterministic end-to-end simulation + export.
- build_graph_for_tau, effective_trust, expansion_ratio: threshold gating and reachability metrics.
src/integrations.rs: DSFB + ADD integration, observer trust profiles, residual state, rewrite-rule labeling.
src/graph.rs: legacy graph primitives and trust-gated edge insertion utilities.
src/sweep.rs: legacy sweep/scaling workflows and provenance export helpers.
src/config.rs: reusable config validation and timestamped output directory creation.
src/bin/dscd_threshold_scaling.rs: standalone finite-size scaling binary entrypoint.

Output Layout

Each run writes to a new timestamped folder:

output-dsfb-dscd/<YYYYMMDD_HHMMSS>/

Primary CSV artifacts:

threshold_curve_N_<N>.csv: threshold curve samples (tau, expansion_ratio).
threshold_scaling_summary.csv: per-N scaling summary (num_events, tau_star, transition_width, max_derivative).
finite_size_scaling.csv: finite-size scaling table (includes transition width series).
graph_events.csv: event nodes with trust and structural descriptors.
graph_edges.csv: thresholded edge set at representative tau*.
edge_provenance_0.csv and edge_provenance.csv: provenance-focused edge exports.
degree_distribution.csv, interval_sizes.csv, path_lengths.csv: graph shape diagnostics.

Determinism and Validation

All DSCD pipelines in this crate are deterministic.
Config validation rejects non-finite or invalid parameter ranges.
Unit/integration tests in src/paper.rs and src/graph.rs exercise output generation and DAG invariants.

Notebook Reproduction

Use:

crates/dsfb-dscd/dscd_sweep.ipynb
crates/dsfb-dscd/dsfb_dscd_results_replay.ipynb
crates/dsfb-dscd/notebooks/dscd_plots.ipynb

All main paper/replay figures are regenerated from DSCD CSV outputs.

Citation

de Beer, R. (2026). Deterministic Structural Causal Dynamics (DSCD): Trust-Gated Emergence of Certifiable Causal Graphs for Safety-Critical Aerospace Autonomy (v1.0). Zenodo. https://doi.org/10.5281/zenodo.18867217

dsfb-dscd 0.1.0