> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scalacomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Simple

> Simple collective-operation simulation

Simple collective-operation simulation

## Endpoints

| Method | Path | Description |
| - | - | - |
| POST | `/api/v1/simple/simulations` | Submit a collective-operation workload for simple network simulation |
| POST | `/api/v1/simple/simulations/preview` | Preview the derived topology for a simple simulation request |
| GET | `/api/v1/simple/compatibility` | Get the operation/algorithm compatibility matrix |

***

## Submit a collective-operation workload for simple network simulation

POST `/api/v1/simple/simulations`

Validates the workload against operation/algorithm compatibility rules, resolves or synthesizes a topology and traceset, creates a configuration, and launches a simulation. Returns immediately with status `accepted`; poll `GET /api/v1/simulations/{simulationId}` to track progress. Note: the poll response uses a different schema (`SimulationDetails`) — the simulation ID is returned as `id` (not `simulationId`), the workload is not echoed back, and the status transitions from `accepted` to `provisioning` on the next poll. Identical workloads are deduplicated via content-addressed tracesets.

### Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | No | Optional human-readable name for the simulation. Auto-generated when omitted. SECURITY: this value is interpolated into command strings and Slurm entrypoints executed on cluster nodes, so it is restricted to letters, digits, '-' and '*' (1–255 characters), and must start with a letter or digit (no whitespace, other punctuation, or non-ASCII characters, and no leading '-' or '*'). |
| `topology` | string | No | Optional topology reference (reserved for K2 orchestration). |
| `topologyConstraints` | TopologyConstraints | No | Hardware constraints for topology derivation. Mutually exclusive with topology. |
| `topologyConstraints.switchRadix` | string | No | Switch port configuration for TH5-class (51200 Gbps switching capacity). Format: PortsxSpeed (e.g. 128x400G). 64x800G: 64 ports at 800 Gbps. 128x400G: 128 ports at 400 Gbps (default). 256x200G: 256 ports at 200 Gbps. |
| `topologyConstraints.subscriptionRatio` | string | No | Target oversubscription ratio (downlink BW : uplink BW) applied at every switch tier. 1:1: equal uplink and downlink bandwidth (default). 2:1, 3:1, and 4:1: more downlink capacity, fewer uplinks. The ratio is applied to both rack switches (RSW) and fabric switches (FSW) in 3-tier topologies. Actual ratios may differ slightly from the target due to integer port rounding. |
| `topologyConstraints.nicNetworkPortSpeed` | integer | No | NIC network port speed in Gbps. Determines the data rate of each host-to-switch connection. When omitted, defaults to the switch link speed from switchRadix (e.g. 400 for 128x400G). The effective link speed between a NIC and its rack switch is min(nicNetworkPortSpeed, switchLinkSpeed) — the lower of the two is used for both topology capacity planning and the generated configuration. PCIe generation is auto-selected to match the effective NIC speed. Allowed values: 50, 100, 200, 400, 800 Gbps. |
| `workload` | SimpleWorkload | No | Sequential workload: all ranks execute the same phases. Mutually exclusive with groups. |
| `workload.ranks` | integer | Yes, within `workload` | Number of participating ranks. Without topologyConstraints, must be one of the reference topology sizes: 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096. Large sizes (8192, 16384, 32768, 65536) require the enable\_large\_simple\_sim\_topologies flag. With topologyConstraints, any positive value satisfying the constraint solver is accepted. |
| `workload.phases` | array\[SimpleWorkloadPhase] | Yes, within `workload` | Ordered list of collective operation phases (1–16). Operations execute sequentially via ctrlDeps chaining. |
| `groups` | array\[SimpleGroupSpec] | No | Parallel groups: ranks partitioned into independent groups executing concurrently. Mutually exclusive with workload. |

**Example: 128-rank AllReduce with default topology**

```json theme={null}
{
  "workload": {
    "ranks": 128,
    "phases": [
      {
        "operationType": "allReduce",
        "dataSize": 1048576
      }
    ]
  }
}
```

**Example: Custom topology with 192 ranks**

```json theme={null}
{
  "name": "custom-topology-test",
  "topologyConstraints": {
    "switchRadix": "128x400G",
    "subscriptionRatio": "3:1"
  },
  "workload": {
    "ranks": 192,
    "phases": [
      {
        "operationType": "allReduce",
        "algorithm": "ring",
        "dataSize": 1048576
      }
    ]
  }
}
```

**Example: Multiple phases in one submission**

```json theme={null}
{
  "workload": {
    "ranks": 256,
    "phases": [
      {
        "operationType": "allReduce",
        "dataSize": 1024
      },
      {
        "operationType": "allGather",
        "dataSize": 1048576
      },
      {
        "operationType": "reduceScatter",
        "dataSize": 67108864
      }
    ]
  }
}
```

**Example: AllToAll with sequential algorithm**

```json theme={null}
{
  "workload": {
    "ranks": 128,
    "phases": [
      {
        "operationType": "allToAll",
        "algorithm": "sequential",
        "dataSize": 524288
      }
    ]
  }
}
```

**Example: Broadcast followed by scatter**

```json theme={null}
{
  "workload": {
    "ranks": 64,
    "phases": [
      {
        "operationType": "broadcast",
        "algorithm": "interleaved",
        "dataSize": 2097152
      },
      {
        "operationType": "scatter",
        "algorithm": "direct",
        "dataSize": 1048576
      }
    ]
  }
}
```

**Example: Parallel groups executing concurrently**

```json theme={null}
{
  "name": "multi-group-benchmark",
  "groups": [
    {
      "count": 4,
      "groupSize": 64,
      "phases": [
        {
          "operationType": "allReduce",
          "algorithm": "ring",
          "dataSize": 1048576
        }
      ]
    }
  ]
}
```

**Example: Multiple group specs with different operations**

```json theme={null}
{
  "name": "mixed-workload-benchmark",
  "topologyConstraints": {
    "switchRadix": "64x800G",
    "subscriptionRatio": "1:1"
  },
  "groups": [
    {
      "count": 2,
      "groupSize": 128,
      "phases": [
        {
          "operationType": "allReduce",
          "algorithm": "recursiveHalvingDoubling",
          "dataSize": 4194304
        }
      ]
    },
    {
      "count": 4,
      "groupSize": 32,
      "phases": [
        {
          "operationType": "allGather",
          "dataSize": 1048576
        },
        {
          "operationType": "reduceScatter",
          "algorithm": "halving",
          "dataSize": 2097152
        }
      ]
    }
  ]
}
```

### Responses

**202** - Simulation accepted for processing

```json theme={null}
{
  "simulationId": "sim_abc123",
  "status": "accepted",
  "mode": "sequential",
  "workload": {
    "ranks": 128,
    "phases": [
      {
        "operationType": "allReduce",
        "algorithm": "ring",
        "dataSize": 1048576
      }
    ]
  }
}
```

**400** - Validation error — invalid rank count, unsupported operation/algorithm combination, both topology and topologyConstraints set, or constraint solver cannot satisfy the request

*Rank count not in reference set (no constraints):*

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "ranks must be one of [8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096], got 100"
  }
}
```

*Algorithm not valid for operation:*

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "algorithm 'ring' is not compatible with operation 'allToAll'; allowed algorithms: sequential, interleaved"
  }
}
```

*Both topology and topologyConstraints provided:*

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "topologyConstraints and topology are mutually exclusive"
  }
}
```

**401** - Missing or invalid authentication token

***

## Preview the derived topology for a simple simulation request

POST `/api/v1/simple/simulations/preview`

Runs the full validation and topology derivation pipeline against the provided workload or groups, then returns the physical network topology that would be produced — without creating a simulation, traceset, or configuration. The request body is identical to POST /api/v1/simple/simulations. The workload/groups payload is required because the total rank count drives topology derivation (rack count, tier selection, switch allocation), but no workload details are echoed in the response. The response describes only the physical network: tier structure, switch counts, link counts, data rates, and resolved constraint values.

### Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | No | Optional human-readable name for the simulation. Auto-generated when omitted. SECURITY: this value is interpolated into command strings and Slurm entrypoints executed on cluster nodes, so it is restricted to letters, digits, '-' and '*' (1–255 characters), and must start with a letter or digit (no whitespace, other punctuation, or non-ASCII characters, and no leading '-' or '*'). |
| `topology` | string | No | Optional topology reference (reserved for K2 orchestration). |
| `topologyConstraints` | TopologyConstraints | No | Hardware constraints for topology derivation. Mutually exclusive with topology. |
| `topologyConstraints.switchRadix` | string | No | Switch port configuration for TH5-class (51200 Gbps switching capacity). Format: PortsxSpeed (e.g. 128x400G). 64x800G: 64 ports at 800 Gbps. 128x400G: 128 ports at 400 Gbps (default). 256x200G: 256 ports at 200 Gbps. |
| `topologyConstraints.subscriptionRatio` | string | No | Target oversubscription ratio (downlink BW : uplink BW) applied at every switch tier. 1:1: equal uplink and downlink bandwidth (default). 2:1, 3:1, and 4:1: more downlink capacity, fewer uplinks. The ratio is applied to both rack switches (RSW) and fabric switches (FSW) in 3-tier topologies. Actual ratios may differ slightly from the target due to integer port rounding. |
| `topologyConstraints.nicNetworkPortSpeed` | integer | No | NIC network port speed in Gbps. Determines the data rate of each host-to-switch connection. When omitted, defaults to the switch link speed from switchRadix (e.g. 400 for 128x400G). The effective link speed between a NIC and its rack switch is min(nicNetworkPortSpeed, switchLinkSpeed) — the lower of the two is used for both topology capacity planning and the generated configuration. PCIe generation is auto-selected to match the effective NIC speed. Allowed values: 50, 100, 200, 400, 800 Gbps. |
| `workload` | SimpleWorkload | No | Sequential workload: all ranks execute the same phases. Mutually exclusive with groups. |
| `workload.ranks` | integer | Yes, within `workload` | Number of participating ranks. Without topologyConstraints, must be one of the reference topology sizes: 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096. Large sizes (8192, 16384, 32768, 65536) require the enable\_large\_simple\_sim\_topologies flag. With topologyConstraints, any positive value satisfying the constraint solver is accepted. |
| `workload.phases` | array\[SimpleWorkloadPhase] | Yes, within `workload` | Ordered list of collective operation phases (1–16). Operations execute sequentially via ctrlDeps chaining. |
| `groups` | array\[SimpleGroupSpec] | No | Parallel groups: ranks partitioned into independent groups executing concurrently. Mutually exclusive with workload. |

**Example: 128-rank AllReduce — produces 2-tier topology**

```json theme={null}
{
  "workload": {
    "ranks": 128,
    "phases": [
      {
        "operationType": "allReduce",
        "dataSize": 1048576
      }
    ]
  }
}
```

**Example: 8 ranks with constraints — produces 1-tier (single rack)**

```json theme={null}
{
  "topologyConstraints": {
    "switchRadix": "128x400G",
    "subscriptionRatio": "1:1"
  },
  "workload": {
    "ranks": 8,
    "phases": [
      {
        "operationType": "allReduce",
        "dataSize": 1024
      }
    ]
  }
}
```

**Example: 16384 ranks — produces 3-tier pod topology**

```json theme={null}
{
  "topologyConstraints": {
    "switchRadix": "128x400G",
    "subscriptionRatio": "1:1"
  },
  "workload": {
    "ranks": 16384,
    "phases": [
      {
        "operationType": "allReduce",
        "dataSize": 1048576
      }
    ]
  }
}
```

### Responses

**200** - Topology preview computed successfully

```json theme={null}
{
  "topology": {
    "tierCount": 2,
    "totalHosts": 128,
    "ranksPerHost": 1,
    "ranksPerRack": 64,
    "tiers": [
      {
        "name": "RSW",
        "switchCount": 2,
        "downlinksPerSwitch": 64,
        "uplinksPerSwitch": 64,
        "downlinkDataRateGbps": 400,
        "uplinkDataRateGbps": 400,
        "effectiveSubscriptionRatio": "1:1",
        "switchCapacityUtilization": 100.0
      },
      {
        "name": "FSW",
        "switchCount": 1,
        "downlinksPerSwitch": 128,
        "uplinksPerSwitch": 0,
        "downlinkDataRateGbps": 400,
        "uplinkDataRateGbps": 0,
        "switchCapacityUtilization": 100.0
      }
    ],
    "links": {
      "hostToRsw": 128,
      "rswToFsw": 128,
      "fswToSsw": 0
    },
    "resolvedConstraints": {
      "switchRadix": "128x400G",
      "subscriptionRatio": "1:1",
      "nicNetworkPortSpeed": 400,
      "effectiveNicSpeed": 400,
      "switchLinkSpeed": 400,
      "switchingCapacityGbps": 51200
    }
  }
}
```

**400** - Validation error — identical to POST /api/v1/simple/simulations

*Rank count not in reference set (no constraints):*

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "ranks must be one of [8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096], got 100"
  }
}
```

**401** - Missing or invalid authentication token

***

## Get the operation/algorithm compatibility matrix

GET `/api/v1/simple/compatibility`

Returns the full compatibility matrix mapping each collective operation type to its allowed algorithms, platform default, and power-of-two constraints. This is a static reference endpoint — the matrix does not change between requests.

### Responses

**200** - Compatibility matrix

```json theme={null}
{
  "entries": [
    {
      "operationType": "...",
      "allowedAlgorithms": [
        "..."
      ],
      "defaultAlgorithm": "...",
      "powerOfTwoRequired": [
        "..."
      ]
    }
  ]
}
```

**401** - Missing or invalid authentication token

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.