Introduce rate based fluid flow wan workload

CODES-compile-instructions.sh

@@ -21,18 +21,25 @@ fi
 # What to compile
 CUR_DIR="$PWD"
 
+# Prefer Homebrew Bison on macOS because /usr/bin/bison is too old.
+if command -v brew >/dev/null 2>&1; then
+    bison_prefix="$(brew --prefix bison 2>/dev/null || true)"
+    if [ -n "$bison_prefix" ] && [ -x "$bison_prefix/bin/bison" ]; then
+        export PATH="$bison_prefix/bin:$PATH"
+    fi
+fi
 
 
 ##### Downloading everything #####
 
 if [ ! -d codes/.git ]; then
-    git clone https://github.com/codes-org/codes --depth=100 --branch=v1.5.0
+    git clone https://github.com/codes-org/codes --depth=100
 else
     echo "Using existing codes checkout: $(realpath codes)"
 fi
 
 if [ ! -d ross/.git ]; then
-    git clone https://github.com/ross-org/ross --depth=100 --branch=v8.1.0
+    git clone https://github.com/ross-org/ross --depth=100
 else
     echo "Using existing ross checkout: $(realpath ross)"
 fi
@@ -67,6 +74,7 @@ fi
 
 mkdir -p ross/build
 pushd ross/build
+mkdir -p bin
 
 # ---- CODES CUDA arch autodetection from CUDA_HOME ----
 # CUDA is opt-in: set CUDA_HOME to enable GPU/Torch CUDA compilation.
@@ -224,6 +232,7 @@ fi
 
 mkdir -p codes/build
 pushd codes/build
+mkdir -p bin
 
 torch_cmake_prefix=""
 torch_dir=""

doc/example/CMakeLists.txt

@@ -52,3 +52,9 @@ configure_file(kb.dfdally-72-milc-small.workload.conf.in kb.dfdally-72-milc-smal
 configure_file(kb.dfdally-72-milc-small.json kb.dfdally-72-milc-small.json COPYONLY)
 configure_file(kb.dfdally-72-milc-small.alloc.conf kb.dfdally-72-milc-small.alloc.conf COPYONLY)
 configure_file(kb.dfdally-72-zeromq-director.conf.in kb.dfdally-72-zeromq-director.conf)
+
+# Rate-based fluid-flow WAN example.
+configure_file(rate-fluid-wan.yaml.in rate-fluid-wan.yaml @ONLY)
+configure_file(rate-fluid-wan-topology.yaml rate-fluid-wan-topology.yaml COPYONLY)
+configure_file(rate-fluid-wan-flows.csv rate-fluid-wan-flows.csv COPYONLY)
+

doc/example/rate-fluid-wan-flows.csv

@@ -0,0 +1,3 @@
+start_time,flow_id,source_terminal,destination_terminal,size
+0 s,1,0,5,12 GB
+1 s,2,2,5,4 GB

doc/example/rate-fluid-wan-topology.yaml

@@ -0,0 +1,23 @@
+topology:
+  switches:
+    S0:
+      terminals: 2
+      terminal_bandwidth: "100 Gbps"
+      switch_buffer: "8 GB"
+      connections:
+        S1: "25 Gbps"
+
+    S1:
+      terminals: 2
+      terminal_bandwidth: "100 Gbps"
+      switch_buffer: "8 GB"
+      connections:
+        S0: "25 Gbps"
+        S2: "25 Gbps"
+
+    S2:
+      terminals: 2
+      terminal_bandwidth: "100 Gbps"
+      switch_buffer: "8 GB"
+      connections:
+        S1: "25 Gbps"

doc/example/rate-fluid-wan.md

@@ -0,0 +1,154 @@
+# Rate-based fluid WAN model
+
+`model-net-rate-fluid-wan` is an event-driven fluid WAN workload.  It does not
+use a forwarding interval.  Data and control propagation both use the physical
+`link_latency` configured in `RATE_FLUID_WAN`.
+
+## Event workflow
+
+- `FLOW_START`: source-terminal workload event.  Creates a finite source
+  backlog and sends `FLOW_REGISTER` toward the attached switch.
+- `FLOW_REGISTER`: travels downstream one link at a time and creates per-flow
+  state along the path.  The final switch can immediately determine the first
+  end-to-end admissible rate.
+- `RATE_FEEDBACK`: travels upstream and carries the rate that the downstream
+  path currently permits.  A flow start, flow completion, new contention, or a
+  changed downstream constraint can cause new feedback.
+- `DATA_RATE_UPDATE`: travels downstream and carries the *actual* data rate
+  emitted by the upstream terminal/switch.  This is intentionally distinct
+  from `RATE_FEEDBACK`: control information must first reach the source before
+  the physical incoming data rate changes downstream.
+- `BUFFER_THRESHOLD`: switch-wide shared-buffer event used only for predicted
+  HIGH and LOW watermark crossings. Queue occupancy is integrated analytically
+  between state-changing events. Per-flow queue drain timing is handled by an
+  internal `QUEUE_DRAIN` event and is not a buffer-threshold condition.
+- `PAUSE_UPDATE`: flow-selective PAUSE/RESUME propagated upstream using the same
+  link latency. At a HIGH watermark, the switch chooses the largest current
+  incoming-rate contributors until the present buffer-growth rate is arrested;
+  at LOW, it resumes the flows that it paused. Local egress scheduling always
+  enforces link capacity while PAUSE protects the finite shared buffer.
+- `FLOW_COMPLETE`: predicted source completion.  The source emits a zero
+  `DATA_RATE_UPDATE` and propagates completion downstream.  Buffered data is
+  still allowed to drain before the destination is marked complete.
+
+When `debug: 1`, each switch prints its shared-buffer occupancy whenever the
+analytically integrated occupancy changes. These debug messages are observational; HIGH/LOW threshold
+timing remains analytically predicted from the current aggregate queue slope.
+
+Every switch event first advances all queue state from the preceding event time
+to the current ROSS timestamp.  For a flow with constant rates over `dt`,
+
+```
+queue += (incoming_rate - outgoing_rate) * dt
+```
+
+with the rate-to-data conversion determined from the configured rate/data unit
+pair.  The same approach is used by source remaining-data and destination
+received-data accounting.
+
+## Units
+
+Rates accept only `Mbps` and `Gbps`.
+
+Flow sizes accept `MB` and `GB`.  `switch_buffer` accepts `MB`/`GB`; legacy
+`Mb`/`Gb` buffer spellings are also accepted and converted to bytes.
+
+The model preserves homogeneous units:
+
+- all `Gbps` -> rates are simulated/reported in `Gbps`;
+- all `Mbps` -> rates are simulated/reported in `Mbps`;
+- mixed `Gbps`/`Mbps` -> rates are normalized to `Mbps`;
+- all `GB` -> data are simulated/reported in `GB`;
+- all `MB` -> data are simulated/reported in `MB`;
+- mixed `GB`/`MB` -> data are normalized to `MB`.
+
+Flow start times accept `s` and `ms` (the latency parser also accepts `us` and
+`ns`).  If all flow start times use seconds, output times use seconds.  If
+millisecond and second start specifications are mixed, output uses
+milliseconds.
+
+## Files
+
+The topology YAML follows the earlier fluid-flow-WAN layout:
+
+```yaml
+topology:
+  switches:
+    S0:
+      terminals: 2
+      terminal_bandwidth: "100 Gbps"
+      switch_buffer: "8 GB"
+      connections:
+        S1: "25 Gbps"
+```
+
+The flow CSV is one row per finite transfer:
+
+```csv
+start_time,flow_id,source_terminal,destination_terminal,size
+0 s,1,0,5,12 GB
+1 s,2,2,5,4 GB
+```
+
+The preferred current-CODES configuration is YAML.  The LP layout uses the
+`groups` topology escape hatch and model-specific knobs live under `sections`:
+
+```yaml
+schema_version: 1
+
+topology:
+  format: groups
+  params:
+    message_size: 65536
+  groups:
+    RATE_FLUID_WAN_GRP:
+      repetitions: 1
+      lps:
+        rate-fluid-wan-switch-lp: 3
+        rate-fluid-wan-terminal-lp: 6
+
+simulation:
+  end_time: "30s"
+  pe_mem_factor: 1024
+
+sections:
+  rate_fluid_wan:
+    topology_file: rate-fluid-wan-topology.yaml
+    flow_file: rate-fluid-wan-flows.csv
+    link_latency: "1 ms"
+    pause_enabled: 1
+    pause_high_watermark_fraction: 0.80
+    pause_low_watermark_fraction: 0.50
+    debug: 1
+    flow_summary_file: rate-fluid-flow-summary.csv
+```
+
+A legacy `.conf` equivalent is also included as `rate-fluid-wan.conf`; the
+executable uses the normal CODES configuration API and accepts either form.
+
+With `debug="1"`, every event is printed, for example:
+
+```text
+FLOW START(F1) at terminal S0.0 at 0.000000 s
+FLOW REGISTER(F1) at switch S0 at 0.001000 s
+RATE FEEDBACK(F1) at switch S0 at 0.005000 s rate=25.000000 Gbps
+DATA RATE UPDATE(F1) at switch S0 at 0.007000 s rate=25.000000 Gbps
+```
+
+## Build and run
+
+After configuring and rebuilding CODES, run from the build directory:
+
+```bash
+mpirun -np 1 ./src/model-net-rate-fluid-wan --sync=1 -- \
+  doc/example/rate-fluid-wan.yaml
+```
+
+The generated example configuration, topology, and flow CSV are placed in
+`build/doc/example/`. The flow summary is written to
+`build/rate-fluid-flow-summary.csv` when the command above is launched from
+the build directory.
+
+The example uses a generous `message_size` because the event message
+contains rollback metadata for continuous queue/rate state.  The executable
+checks `sizeof(rate_msg)` against the configured ROSS message size at startup.

doc/example/rate-fluid-wan.yaml.in

@@ -0,0 +1,34 @@
+schema_version: 1
+
+topology:
+  format: groups
+  params:
+    message_size: 65536
+  groups:
+    RATE_FLUID_WAN_GRP:
+      repetitions: 1
+      lps:
+        rate-fluid-wan-switch-lp: 3
+        rate-fluid-wan-terminal-lp: 6
+
+simulation:
+  end_time: "30s"
+  pe_mem_factor: 1024
+
+sections:
+  rate_fluid_wan:
+    topology_file: "rate-fluid-wan-topology.yaml"
+    flow_file: "rate-fluid-wan-flows.csv"
+
+    # DATA_RATE_UPDATE, RATE_FEEDBACK, FLOW_REGISTER, FLOW_COMPLETE, and
+    # PAUSE_UPDATE all traverse one physical hop using this latency.
+    link_latency: "1 ms"
+
+    pause_enabled: 1
+    pause_high_watermark_fraction: 0.80
+    pause_low_watermark_fraction: 0.50
+
+    # Print every model event with its flow, LP, timestamp, and rate/state.
+    debug: 1
+
+    flow_summary_file: "rate-fluid-flow-summary.csv"

src/CMakeLists.txt

@@ -229,6 +229,7 @@ if(USE_DUMPI)
     add_executable(model-net-dumpi-traces-dump network-workloads/model-net-dumpi-traces-dump.c)
 endif()
 add_executable(model-net-synthetic network-workloads/model-net-synthetic.c)
+add_executable(model-net-rate-fluid-wan network-workloads/model-net-rate-fluid-wan.cxx)
 add_executable(model-net-synthetic-slimfly network-workloads/model-net-synthetic-slimfly.c)
 add_executable(model-net-synthetic-fattree network-workloads/model-net-synthetic-fattree.c)
 add_executable(model-net-synthetic-dragonfly-all network-workloads/model-net-synthetic-dragonfly-all.c)
@@ -237,6 +238,7 @@ set(CODES_TARGETS
     topology-test
     model-net-mpi-replay
     model-net-synthetic
+    model-net-rate-fluid-wan
     model-net-synthetic-slimfly
     model-net-synthetic-fattree
     model-net-synthetic-dragonfly-all

src/modelconfig/configuration.c

@@ -211,6 +211,16 @@ int configuration_load(const char* filepath, MPI_Comm comm, ConfigHandle* handle
     return rc;
 }
 
+
+int configuration_free(ConfigHandle* handle) {
+    if (handle == NULL || *handle == NULL)
+        return 0;
+
+    cf_free(*handle);
+    *handle = NULL;
+    return 0;
+}
+
 int configuration_get_value(ConfigHandle* handle, const char* section_name, const char* key_name,
                             const char* annotation, char* value, size_t len) {
     SectionHandle section_handle;