| name | dart-architecture |
| description | DART Architecture: the DART 7 multi-physics, multi-solver, multi-backend simulation pipeline, the living architecture map that draws it, and where each abstraction is owned |
DART 7 Architecture
Load this skill when working on the DART 7 simulation World, on
solvers/physics domains/compute backends, when a change adds or renames a
dart/simulation module, step-stage slot, or solver family, or whenever a
task needs the big-picture map of how DART 7 is generalized for
multi-physics, multi-solver, and multi-backend simulation.
The design in one sentence
World owns topology, time and composition. A solver may advance one or several
physical domains, using a shared solve or an explicit coupling strategy.
Semantic dependencies, executable plans and runtime adapters separate physics
from scheduling. Users configure DART-owned method/policy values, never solver
registries, component storage or runtime objects.
Why three axes of choice
- Research, apples-to-apples. A new paper's algorithm should be reproducible
and benchmarkable inside DART against baselines on shared foundations, not in
a fork. New methods enter through DART-owned solver families.
- End-user choice. Users pick the solver method and (internally) backend that
fit their accuracy/speed/platform needs.
- Auto-configuration. Defaults are selected from scene content so the easy
path stays trivial; the backend seam is designed for later platform/scene-scale
awareness without changing the public API.
The living architecture map
The published page docs/readthedocs/architecture.md embeds four views that
are rendered at docs-build time from typed JSON under
docs/assets/architecture/. The JSON is the source of truth; rendered HTML is
never committed.
| View | Owns |
|---|
simulation-framework.architecture.json | facade → scene → selection → schedule → solver families → data/collision → compute; every dart/simulation/<dir> except compute/ |
world-step.dataflow.json | the built-in World::step() stage slots as nodes (ids are BuiltInWorldStepStageSlot names in snake case) plus the two listed bookends sync and continuation for the prologue and epilogue outside the schedule, flows named by exchanged data |
compute-graph.architecture.json | semantic graph → executable plan → runtime adapters → evidence; dart/simulation/compute/** |
library-context.architecture.json | every dart/<module>, dartpy, dartsim, external dependencies |
compute-graph.runtime.json | fixture recorded by tests/unit/simulation/compute/test_architecture_probe.cpp for the advisory runtime drift check |
Read the owning view before changing the code it describes: each node cites
up to three sources (path, optional line range), carries a status tag, and
the step-flow view's guided views (meta.views) show which slots run for the
split rigid, fused multibody, and combined IPC schedules.
Status tags are the assessment's labels: Implemented (source path and a
scoped test exist), Partial (useful implementation with uncovered contract
cells), Planned (accepted work without qualifying implementation),
Undecided (open design decision). Dashed relationships lead to planned
work.
Type legend (archify's fixed palette with DART meanings): external =
user-facing facade or third-party library, frontend = dartpy or dartsim
surface, backend = solver, stage, or compute code, database = model,
state, storage, checkpoint, or replay data, messagebus = coupling, exchange,
or the step schedule, cloud = executor or device runtime, security = the
public-API boundary that hides internals.
Update procedure
A change to a dart/simulation module, a BuiltInWorldStepStageSlot, an
enumerator of any public selector enum class in world_options.hpp or
multibody/multibody_options.hpp (the gate sweeps every enum there and
requires each one's Enum: A, B card item in the framework view), a
WorldStepStage subclass, or a dart/<module> directory updates the owning
view in the same change:
- Edit the view JSON: add or retitle the node, cite its
sources (every
architecture component needs at least one; the gate fails otherwise), set the
tag from the assessment, and label new relationships with the exchanged
data (dataflow flows) or the mechanism (architecture connections).
pixi run check-architecture-map (blocking, no Node.js): missing paths,
out-of-range lines, line ranges that no longer hold their labelled
symbol, unresolved symbols in labels, cards, boundaries, and guide notes, uncovered directories or
enumerators, unmapped stage classes, and page embeds. Stage classes that
intentionally have no schedule slot go into STAGE_CLASS_ALLOWLIST in
scripts/check_architecture_map.py with a reason.pixi run render-architecture-map: archify validation with exact geometry
diagnostics (label collisions, crossings, readability). Apply the fixes
hint of each diagnostic; showcase acceptance means zero diagnostics. The
pinned checkout is fetched into .deps/archify on first use.pixi run docs-build when the page prose changed, then review the built
architecture page with pixi run docs-serve (served on port 8000).- Record the change under the packet's or PR's architecture impact line.
Audit procedure
pixi run check-architecture-map for structure, evidence, and coverage.pixi run check-architecture-map-runtime compares the committed fixture
with the views and, when pixi run build has produced the
test_architecture_probe binary, with a fresh probe dump. It is advisory;
pass --strict to fail on drift and --regenerate after an intentional
schedule change (--guided-view <id> when the recorded guided view must
change; it is validated against the step-flow view). Only a profiling-enabled build (the pixi run build
default) records an execution trace; a schedule-only dump is reported
and is refused for regeneration unless --allow-schedule-only is passed.- Compare each node's
tag with the current findings in
docs/design/dart7_architecture_assessment.md; the assessment wins.
- Archify upgrades change
ARCHIFY_TAG and ARCHIFY_COMMIT together in
scripts/render_architecture_map.py, then re-render every view and re-check
the readability diagnostics.
Authoring constraints that archify enforces
- Architecture views: 6 to 12 components; sublabels at most 28 characters
(the sublabel font is capped at 9px and must project to 6px at a 1440px
viewport, so a view stays under about 1390px wide); at most three
sources per component; no crossing connections and no label within 4px of
another route in showcase mode.
- Dataflow views: at most 5 stages and 5 rows on a fixed 215 by 114 grid with
112px nodes, so corridors are 103px wide; every flow needs a label; use
route: "straight" for same-row flows, explicit via for flows spanning
more than one stage, and labelAt in empty cells or beside corridors for
labels longer than six characters.
Design vs current state (read both)
docs/readthedocs/architecture.md is the single-page map of the design and
the options at each seam, with honest status markers.
docs/design/dart7_architecture_assessment.md is the verified record of
where implementation is partial: complete shared-model states, full CUDA World
stepping, portable continuation, and coverage beyond the existing metrics/corpus.
It owns the continuous audit rule and names the map views as affected
artifacts. New families enter through docs/plans/solver-family-intake.md;
docs/plans/040-dart7-release-hardening.md coordinates milestone readiness,
and active subsystem plans own packets. PLAN-091 is completed background.
Recheck source evidence before copying a pattern or repeating an absence claim
from an older audit.
Key owner documents
The architecture page's Source-of-truth map is the single owner of the full
topic → owner-doc mapping (solver, API, extension, compute, differentiable,
clean-break, north-star). The docs an agent most often needs inline:
| Topic | Document |
|---|
| Architecture map views, renderer, and checks | docs/design/architecture_map.md, docs/assets/architecture/, scripts/render_architecture_map.py, scripts/check_architecture_map.py |
| Solver abstraction, domain assignment, coupling, schedule | docs/design/simulation_solver_architecture.md |
| Verified findings, standing rule, competitor lessons | docs/design/dart7_architecture_assessment.md |
| Public C++ / dartpy API shape and promotion rules | docs/design/simulation_cpp_api.md, docs/design/simulation_python_api.md |
| CPU / SIMD / GPU decision framework | docs/design/scalable_compute_decisions.md |
| DART 7 vs DART 6 topology · live progress / readiness gates | docs/design/dart7_clean_break_strategy.md, docs/plans/dashboard.md |
Public-facade rules (do not violate)
- Do not expose
Solver, Coupler, PhysicsDomain, ECS storage, component
types, concrete runtime/backend types, or solver registries as public API.
Existing DART-owned abstract executor/stage extension interfaces are distinct
from concrete runtime implementations.
- Select behavior by documented method-family names and policy value objects.
- A small DART-owned CPU/CUDA preference is accepted public design; library,
pool, stream, kernel and ISA types remain private. WP-040.2 in
docs/plans/040-dart7-release-hardening.md owns checker-transition
requirements and status.
- Keep the easy path (
World + addRigidBody/addMultibody + step) free of
solver vocabulary.
- Fallbacks must never silently substitute algorithms: validate capabilities
at finalize or record the substitution in diagnostics.
Verification
Use docs/ai/verification.md to select the docs-only or code gate set for the
change. Map edits add pixi run check-architecture-map and
pixi run render-architecture-map; the runtime probe runs inside
pixi run test-unit. Implementation work that realizes parts of this
architecture also follows the gates in
docs/design/simulation_solver_architecture.md, the solver-family intake
checklist, and any active owner plan named in docs/plans/dashboard.md.
