> ## 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.

# Release 0.1.2840

> Simulator software 4.8.1 · Released 2026-11-04 · Supersedes release 0.1.2544

Simulator software 4.8.1 · Released 2026-11-04 · Supersedes release 0.1.2544

***

## At a glance

The results API adds two new views of network results:

* a ranking of the ports most affected during a run;
* switch buffer-pool usage by tier.

The RoCE transport summary gains a received-packet total. The web application's results view adds charts built on these, and uploading a traceset from the web application is fixed.

Other changes:

* **Parquet result files.** Runs on the optimized execution path also list Parquet copies of their result files, ready to download.
* **Fixes.** The collectives summary now works for runs that contain a Barrier collective. A topology with a switch tier that has no capacity no longer fails validation with a division-by-zero error.
* **Reliability.** Results and log requests now fail quickly with a 503 or 504 when the simulation's state cannot be read. Previously they could wait indefinitely.
* **API specification.** The specification adds the operations and values described below and documents the new statuses.
* **Security.** The release includes security updates.

| Component | Previous | This release |
| - | - | - |
| Platform | 0.1.2544 | **0.1.2840** |
| Simulator software | 4.8.1 | 4.8.1 (updated build) |
| ScalaSwitch model | 3.7.0 | 3.7.0 |
| ScalaRoceNic model | 4.6.0 | 4.6.0 |
| ScalaChakraGenerator model | 4.1.0 (4.0.3 remains available) | 4.1.0 (4.0.3 remains available) |
| ScalaUETNIC400G model | 4.6.0 | 4.6.0 |
| ScalaMrcNic model | 4.0.5 (in testing) | 4.0.5 (in testing) |

The simulator software version stays at 4.8.1. The simulator build in this release updates its base image and carries the configuration-check fixes listed under **Issues resolved**.

> **No results change in this release.** A configuration that ran on 0.1.2544 gives the same simulation results and the same output files. Four changes affect what the results API returns, without changing any existing value:
>
> * **Results listings gain Parquet files.** On the optimized execution path, `GET .../results` lists Parquet copies beside the CSV files. Code that downloads every listed file should filter by `type`.
> * **The RoCE transport summary gains a key.** `transport.columns` gains `numPktsRcvdSum`, and the RoCE time series gains `intervalNumPktsRcvdSum`.
> * **Collectives summaries for runs with a Barrier collective.** These previously failed and now return data. A Barrier has no ideal model, so its ideal ratios are reported as 0.
> * **Cached summaries are recomputed once.** The first summary or time-series request for an existing run after the upgrade can take longer.
>
> No defaults change, and no model versions change.

***

## Issues resolved

### Collectives summary for runs with a Barrier collective

`GET /api/v1/simulations/{sim_id}/results/data?metric=collectives` failed with a server error for any run whose trace contains a Barrier collective. The collectives output writes `NA` in a Barrier's ideal-ratio columns, and the results service could not read it. The summary now returns data for these runs. A Barrier's ideal ratios are reported as 0, because no ideal model exists for a Barrier.

### Topology validation of a tier with no capacity

A topology in which a switch tier has no capacity in use, for example a spine tier with no downlinks, failed validation with `Exception float division by zero` (or `Exception division by zero` for chassis-capacity switches). Such a topology now passes this check, and the per-tier subscription-ratio note reports `n/a` for that tier. If the topology has another configuration error, that error is now reported instead of the division error.

### Clearer error for a rack group with two NIC or host names

A rack group that names more than one NIC, or more than one host, is still refused, but with an error that states the problem. The old error showed only the second name, for example `Exception 'nic2'`. The new errors read:

* `More than one NIC name in <rack>, <group> (<names>): each host can be linked to only one NIC`
* `More than one host name in <rack>, <group> (<names>): a group can hold only one host name`

***

## Top ports and switch buffer pools

### Top ports ranking

`GET /api/v1/simulations/{sim_id}/results/data?metric=nd-stats&mode=topPorts` ranks a run's ports by how much each was affected during the run, and backs the **Top ports by severity class** chart in the web application's results view. `tier` selects the network tier, and `portsPerRanking` sets how many ports each ranking returns, from 3 to 10; the default is 5.

### Switch buffer-pool statistics

The results API now summarizes the switch buffer statistics that every Scala Switch writes (`*-scala-switch-agg-buff-stats-*.csv`). The new metric is `metric=scala-switch-agg-buff-stats`.

* **`mode=summary`** returns `bufferPools.pools`, one entry for each combination of tier, buffer class, direction and pool. Each entry gives:
  * `peakBytes`, `minBytes` and `meanBytes`;
  * `peakUtilPct` and `meanUtilPct`;
  * `bufferLimitBytes`, `switchCount` and `rowCount`.
* **Buffer classes.** `bufferClass` is `sharedBuffer`, `ingressUsage` or `egressQueue`. `direction` is `ul` or `dl`, and it is omitted for shared buffers.
* **`mode=timeSeries`** returns one group for each pool, keyed `{tier}:{bufferClass}:{direction}:{pool}`.
* **Utilization above 100%.** Utilization is computed from bytes and is not clamped, so a lossless egress pool can report more than 100%. The percentage columns of the CSV files are clamped at 100.
* **No buffer rows.** A finished run that has no buffer rows returns a summary without `bufferPools`.
* **`mode=sampled`** returns 501 for this metric.

### RoCE received-packet total

The RoCE transport summary (`metric=roce-transport-stats`, `mode=summary`) gains `numPktsRcvdSum` in `transport.columns`. The RoCE time series gains `intervalNumPktsRcvdSum`.

Both are totals of received packets: the sum of the NIC's received connection packets, ACKs, SACKs, NACKs, RDMA writes, RDMA sends and CNPs. The RoCE NIC records no total of its own. The UET transport summary does not change.

***

## New in this release

### Parquet result files

Runs on the optimized execution path now also provide their result files as Parquet, a compressed columnar format.

* **Listing.** `GET /api/v1/simulations/{sim_id}/results` lists Parquet files as `type: parquet`, beside the CSV files. `type=parquet` lists only the Parquet files.
* **Download.** `GET /api/v1/simulations/{sim_id}/results/download-url` returns a download link for a Parquet file, as it does for a CSV file.
* **Complete or not listed.** Parquet files for a result type, such as `nd-stats`, are listed only when every CSV file of that type in the run has been converted and verified. Otherwise that result type is listed as CSV only. CSV files are always listed.
* **Columns.** A Parquet file holds the columns the results service reads. Use the CSV file for the original columns. A CSV file that holds only a header has no Parquet file.
* **Which runs.** Parquet files are written when a run on the optimized execution path finishes. Runs on the standard path have CSV files only, and so do runs that finished before this release. Runs of more than 4,096 hosts use the standard path.

### API specification changes

* **New query mode and parameter on `GET /api/v1/simulations/{sim_id}/results/data`.**
  * `mode` gains `topPorts`.
  * `metric` gains `scala-switch-agg-buff-stats`.
  * The new query parameter `portsPerRanking` applies only to `mode=topPorts`. Any other request names it in `X-Ignored-Params`.
* **New schemas.**
  * `TopPortsDocument`, with its ranking schemas.
  * `BufferPoolSummary`, `BufferPoolStats`, `BufferClass` and `BufferDirection`.
  * The optional `SimulationSummary.bufferPools`.
* **New response value.** `ResultFile.type`, and the `type` filter of `GET .../results`, gain `parquet`. See **Parquet result files**. A client generated before this release fails on a listing that contains a Parquet file, so regenerate clients.
* **Documented 503 and 504 statuses.** These operations now document both:

  * `GET .../results`;
  * `GET .../results/download-url`;
  * `GET .../logs`.

  `GET .../results/data` documents a 504 for the same cause. See **Platform reliability and stability**.

***

## Web application

### Results view

The results view adds these charts:

* **Summary tab.**
  * **Top ports by severity class** lists the ports most affected during the run, from the top ports ranking.
  * **Fabric link utilization** shows the run's mean transmit and receive utilization of fabric-switch links. It grades each against these bands, with a 70% target:
    * Underused;
    * Healthy;
    * Heavily loaded;
    * Saturated.
* **Throughput tab.** **Scale-out uplink fairness per switch** is a heat map of each switch's uplink fairness (Jain index) over time.
* **Congestion & drops tab.**
  * **Head-of-line blocking severity by tier** is a heat map, by tier, of the largest share of each step that a port spent paused while its egress queue held data.
  * Five buffer-pool charts plot occupancy by tier, from the new buffer-pool statistics. An egress pool can read above 100%.
    * **Shared buffer pool usage by tier**.
    * **Uplink ingress buffer pool usage by tier** and **Downlink ingress buffer pool usage by tier**.
    * **Uplink egress queue pool usage by tier** and **Downlink egress queue pool usage by tier**.
* **Transport tab.** The tab opens with two tables of end-of-run transport statistics, for RoCE and UET runs:
  * **Packets by direction**;
  * **Reliability and latency**.
* **Workload tab.** **Completion time vs simulation time** is a heat map of how many operations completed in each completion-time band across the run.

Other changes:

* **Chart load failures.** A chart that fails to load keeps its title and names the data it could not load.
* **Chart downloads.** The PNG, SVG and CSV downloads of the uplink fairness and head-of-line blocking charts now carry what the chart shows.
* **Raw data files.** The raw data files list shows Parquet files beside CSV files, and it has **Next page** and **First page** controls.

### Traceset upload

Uploading a traceset from the web application is fixed. Uploads did not finish before, whatever the file size.

* Every upload, small or large, now uses the same upload operations as the API.
* An upload now waits while the platform finishes copying a large file, instead of stopping after 10 seconds.

***

## Model catalog changes

No model versions change in this release.

***

## Platform reliability and stability

* **Results and logs no longer wait indefinitely.** Reading a simulation's state is now bounded in time. When the read cannot be completed, these operations return a status instead of holding the request open:
  * Results, result downloads and logs return 503 when the simulation's state cannot be read, and 504 when the read takes too long. Retry with backoff, with a limit on the number of attempts.
  * `GET /api/v1/simulations` and `GET /api/v1/simulations/{sim_id}` return the simulation's last recorded status.
* **Very large summary requests are refused sooner.** Some summary and time-series requests for the largest runs are too large to serve. These now return 413 before any data is read. Requests for the same result that are waiting on a refused request now get the same 413, instead of each one waiting and timing out.
* **Clearer error when a result has no data.** The 404 for a result with no data files now names the simulation, for example `No data files found for metric pfc in simulation sim_…`. It used to say `in simulation unknown`.

***

## Security updates

**This release contains security updates. We recommend upgrading.**

In keeping with our disclosure practice, we do not publish details of security fixes. Customers with a specific compliance question should contact their Scala representative.

***

## Documentation

**API reference.** It is updated for:

* the switch buffer-pool statistics;
* the RoCE received-packet total;
* the `parquet` file type;
* the new 503 and 504 statuses.

***

## Not included in this release

The following remain open and are not addressed by 0.1.2840:

* **Chakra workloads on the Scala MRC NIC.** A Chakra simulation on MRC NICs does not yet run to completion.
* **Mapping files above 4,096 ranks.** Mapping-file support covers simulations of up to 4,096 ranks. A larger simulation with a mapping file attached fails with `Mapping file <name> (<id>) could not be delivered`.
* **Mapping files with the platform's own Chakra tracesets.** A simulation from such a configuration fails before the simulator starts. Mapping files work on tracesets you upload.
* **Summary metrics for the largest result sets.** Summaries for the largest runs, such as 8,192 ranks, can still be refused as too large. Raw result files remain available through the results download operations.
* **Pre-simulation run-time estimation.** There is still no supported way to tell in advance whether a trace will exceed the configured simulation time limit.
* **ECN-marked packet counts received at the NIC.** NIC-side receive counters for ECN-marked packets are not yet reported. Switch-side ECN information remains available.
* **Mixed NIC types in a Chakra simulation.** All servers in a Chakra simulation must use the same NIC type.
* **Parquet files for standard-path and earlier runs.** Runs on the standard path, including runs of more than 4,096 hosts, have CSV result files only. So do runs that finished before this release.

***

## Upgrade notes

* **Automatic updates.** The updated simulator build is applied with the platform upgrade. No configuration changes are needed.
* **First summary requests after the upgrade.** Cached summaries and time series are recomputed once, so the first such request for an existing run can take longer.
* **Regenerate API clients.** Regenerated clients pick up:

  * the top ports mode;
  * the buffer-pool metric and schemas;
  * the `parquet` file type;
  * the documented 503 and 504 statuses.

  A client generated before this release fails on a results listing that contains a Parquet file. A regenerated client may also return the 503 and 504 statuses as typed responses instead of raising an unexpected-status error.
* **Downloading every listed file.** Results listings of optimized-path runs now include Parquet files. Filter by `type` if you want only CSV.
* **Retry on 503 and 504.** Results, download and log requests can now return these statuses when the simulation's state cannot be read in time. Retry with backoff and a bounded number of attempts.
* **RoCE transport readers.** Code that reads `transport.columns` or the RoCE time series by a fixed key set must allow for `numPktsRcvdSum` and `intervalNumPktsRcvdSum`.
* **Collectives readers.** Runs with a Barrier collective now return collectives summaries. A Barrier's ideal ratios are 0, so do not read 0 there as a measured result.


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