Merge latest changes

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - llm-dev
+  pull_request:
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install AstraSim system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            gcc-11 g++-11 make cmake \
+            clang-format \
+            libboost-dev libboost-program-options-dev \
+            libprotobuf-dev protobuf-compiler \
+            openmpi-bin openmpi-doc libopenmpi-dev
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v2
+
+      - name: Sync Python dependencies
+        run: uv sync
+
+      - name: Determine AstraSim commit
+        run: echo "ASTRASIM_SHA=$(git -C astra-sim rev-parse HEAD)" >> $GITHUB_ENV
+
+      - name: Restore AstraSim build cache
+        id: ascache
+        uses: actions/cache@v4
+        with:
+          path: astra-sim/build/astra_analytical/build
+          key: astra-${{ env.ASTRASIM_SHA }}
+
+      - name: Build AstraSim (cache miss)
+        if: steps.ascache.outputs.cache-hit != 'true'
+        run: |
+          chmod +x scripts/install_astrasim.sh
+          scripts/install_astrasim.sh
+
+      - name: Run pytest
+        env:
+          DEEPFLOW_VALIDATION_WORKERS: "1"
+        run: uv run pytest

.gitignore

@@ -1,8 +1,19 @@
 *.swp
 *.swo
+.cursor/
 __pycache__/
 output/
 venv/
 astra_cache/
 log/*.log
-tmp/
+tmp/
+output*/
+dbg_hw_conf/
+tools/fault_sweep_results*
+tools/*.png
+tools/*.tsv
+tools/*.json
+tools/gmap_artifacts/
+*.md
+*.et
+tools/comp/wrapper_outputs/*

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "astra-sim"]
 	path = astra-sim
 	url = https://github.com/gkarfakis19/astra-sim
+[submodule "extern/graph_frontend/param"]
+	path = extern/graph_frontend/param
+	url = https://github.com/facebookresearch/param.git

AGENTS.md

@@ -0,0 +1,12 @@
+DeepFlow quick brief for future agents
+
+- Purpose: Python simulator for LSTM/GEMM/LLM performance, memory, and (rudimentary) energy. Entry point `run_perf.py` loads YAML configs (hardware + model) and builds compute/comm graphs, then simulates analytically or via AstraSim.
+- Execution backends (set in hardware config `execution_backend`): analytical (ring-only, no congestion); hybrid (AstraSim for transformer block graph, analytical pipeline); full_astrasim_hierarchical (AstraSim separately for transformer and pipeline graphs, assumes no congestion between them); full_astrasim_flattened (one big combined graph in AstraSim, slowest/most detailed).
+- Parallelism model: supports DP, TP (+optional sequence parallel), CP, GPipe-style pipeline (`lp` stages), and hybrid TP+CP. Pipeline graph assumes uniform per-layer timing and GPipe scheduling; gradient accumulation builds a no-DP variant so only the last accumulation step does DP all-reduce.
+- Communication assumptions: blocking collectives; analytical path uses ring formulas; AstraSim collectives flatten 2D topologies to 1D for collectives. Hierarchical mode requires the first active network dimension map exactly to {tp,cp}; non-ring topologies are rejected in analytical mode. Faulty links only valid in full AstraSim modes.
+- ZeRO assumptions: stage 0/1 ≈ DDP; stage 2 adds per-layer param AG + grad RS sizes; stage 3 adds per-layer param materialization (counted as comm + ephemeral memory, no overlap). MoE assumes perfect balance and TP all-to-all; multi-GPU MoE is WIP.
+- Attention: dense by default. FlashAttention supported for training forward/prefill when `attention.use_flashattention=true` and tile size is set manually; decode path ignores FlashAttention. Sliding-window/MLA are WIP.
+- Memory model: static formulas for activations/weights/optimizer; KV-cache memory estimation WIP. Peak memory compared to DRAM per device; ZeRO-3 ephemeral gather tracked separately. No fragmentation/eviction modeling.
+- Inference: `TimeCalculationLLMInference` handles prefill + sampled decode steps (linear interpolation between samples). DP acts as replica multiplier only; CP decode is noted WIP. FlashAttention disabled for decode.
+- Artifacts/logs: outputs under `output/` (mode subdir). AstraSim artifacts live in `astra_cache/` and optionally `output/LLM/astra_hier` or `astra_flat` when persistence flags are set. Current logs/marker: `log/this_folder_contains_astrasim_logs`, `log/log.log` hold prior runs. Debug hardware snapshots in `dbg_hw_conf/20251105_173209/` (e.g., `baseline_001_tp64_cp1_dp1_lp1.yaml`, `baseline_053_tp1_cp1_dp64_lp1.yaml`).
+- Key environment flags: `DEEPFLOW_VISUALIZE_GRAPHS`, `DEEPFLOW_PERSIST_ASTRASIM_ARTIFACTS`, `DEEPFLOW_PERSIST_ARTIFACT_VIZ`, `DEEPFLOW_ASTRA_CACHE_MODE` (default CACHE_READWRITE).