Cerebras SDK

https://sdk.cerebras.net/
Admin
Cerebras SDK is a software development kit for programming and deploying applications on Cerebras...
Tokens:707,744
Snippets:5,008
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example Rectangle Select Command

Source: https://sdk.cerebras.net/debug/debugging

Example of selecting a rectangle starting at (1,2) with a width of 3 and height of 4.

```bash
(csdb) rectangle select 1,2,3,4

```

--------------------------------

### Execute Python Package Installation Script

Source: https://sdk.cerebras.net/installation-guide

Example of how to use the 'sdk_install_python_package.sh' script to install a Python package ('MY_PIP_PACKAGE_NAME') into a local directory ('./MY_LOCAL_PY_PATH').

```bash
mkdir MY_LOCAL_PY_PATH
bash /PATH/TO/sdk_install_python_package.sh ./MY_LOCAL_PY_PATH MY_PIP_PACKAGE_NAME
```

--------------------------------

### Bind Rotating Tasks in CSL (Basic Example)

Source: https://sdk.cerebras.net/_sources/csl/Language/Builtins_wse3.rst.txt

This example demonstrates binding a data task 'main' and a control task 'alt' for rotation. 'alt' will start after 'main' has started 10 times. The input queue must be initialized, and control task tables must be set up to prevent task conflicts.

```csl
const iq = @get_input_queue(0);
const main_id = @get_data_task_id(iq);

task main(data: u32) void {}
task alt() void {}

comptime {

  // Task 'alt' will start after '10' starts of task 'main'.
  // Task 'alt' is bound to control task id '0' (see 'semantics' for
  // more details).
  @bind_rotating_tasks(main, alt, main_id, .{.limit = 10});

  // Input queue must be initialized to allow us to bind 'main'
  // to 'main_id'.
  @initialize_queue(iq, .{.color = c});

  // Must be called to prevent 'main' and 'alt' from clashing.
  @set_control_task_table();
}
```

--------------------------------

### Start Lima VM from Configuration

Source: https://sdk.cerebras.net/installation-guide

Command to create and start a new Lima virtual machine named 'cs_sdk' using a local configuration file named 'config.yml'.

```bash
# Create a VM named cs_sdk
$ limactl start ./config.yml --name cs_sdk
```

--------------------------------

### Instantiate and Run SdkRuntime

Source: https://sdk.cerebras.net/_sources/api-docs/appliance-api.rst.txt

Instantiate an SdkRuntime runner object using a context manager to load and start a compiled program. This example shows how to launch a function and copy data back from the device.

```python
import json
import os

from cerebras.sdk.client import SdkRuntime

# Read the artifact_path from the JSON file
with open("artifact_path.json", "r", encoding="utf8") as f:
    data = json.load(f)
    artifact_path = data["artifact_path"]

# Instantiate a runner object using a context manager.
# Set simulator=False if running on CS system within appliance.
with SdkRuntime(artifact_path, simulator=False, disable_version_check=True) as runner:
    # Launch my_fn on device
    runner.launch('my_fn', nonblock=False)

    # Copy A back from device
    symbol_A = runner.get_id("A")
    runner.memcpy_d2h(data, symbol_A, px, py, w, h, l,
                     streaming=False, data_type=memcpy_dtype,
                     order=memcpy_order, nonblock=False)
```

--------------------------------

### Example usage of CSL color_config functions

Source: https://sdk.cerebras.net/csl/language/libraries

Demonstrates how to use `color_config` functions to get color addresses, set I/O directions, and reset routes for colors.

```csl
param red: color;
var blue: color;
const tile_config = @import_module("<tile_config>");
const color_config = tile_config.color_config;
const red_addr = color_config.get_color_config_addr(red);

task teardown() void {
  // Color `blue` is a `var` and therefore not known until runtime.
  const addr = color_config.get_color_config_addr(blue);

  // We can manipulate the I/O routing configuration for a
  // comptime-known color, a runtime color or an address to a
  // color configuration register.
  const offramp = color_config.fabric_io.TX_RAMP;
  const onramp = color_config.fabric_io.RX_RAMP;
  const rx_north = color_config.fabric_io.RX_NORTH;
  color_config.set_io_direction(red, offramp);
  color_config.set_io_direction(blue, onramp);
  color_config.set_io_direction(addr, rx_north);

  // Reset the routes for color `red` using multiple directions.
  color_config.reset_routes(red, .{.tx = [3]direction{NORTH, SOUTH, WEST},
                                   .rx = [2]direction{RAMP, EAST}
                                  });
  // Reset the routes for color `red` using single directions.
  color_config.reset_routes(red, .{.tx = NORTH, .rx = EAST});
}

```

--------------------------------

### Set up Python Virtual Environment

Source: https://sdk.cerebras.net/_sources/appliance-mode.rst.txt

Set up a Python virtual environment on the user node before installing SDK components.

```bash
$ python3.8 -m venv sdk_venv
$ source sdk_venv/bin/activate
```

--------------------------------

### Example Memory Read Output

Source: https://sdk.cerebras.net/debug/debugging

Example output from reading tile (4,1) on address 0x09e0 with a length of 4. Addresses and lengths are in 16-bit units.

```text
(4,1) 09e0: 06af 8af0 06af 8060

```

--------------------------------

### Example: Select Workdir

Source: https://sdk.cerebras.net/debug/debugging

Command to select a specific directory for output files.

```bash
(csdb) workdir select path/to/workdir

```

--------------------------------

### Example: Select Current Run Directory for Traces

Source: https://sdk.cerebras.net/debug/debugging

Command to select the current directory as the location for simfab_traces.

```bash
(csdb) trace select .

```

--------------------------------

### Shell Commands to Run Example

Source: https://sdk.cerebras.net/_sources/csl/code-examples/tutorial-topic-03-streaming-wavelet-data.rst.txt

Shell commands to set up the environment and run the Python script for the wavelet data streaming tutorial.

```shell
# Ensure you are in the directory containing layout.csl, pe_program.csl, and run.py

# Create dummy CSL files if they don't exist (for demonstration purposes)
# In a real scenario, these files would be generated or provided
cat << EOF > layout.csl
{
  "layout": {
    "input_streams": [
      {
        "name": "wavelet_stream",
        "data_type": "float",
        "shape": [1, 1, 1024]
      }
    ],
    "output_streams": [
      {
        "name": "processed_wavelet",
        "data_type": "float",
        "shape": [1, 1, 1024]
      }
    ]
  }
}
EOF

cat << EOF > pe_program.csl
{
  "program": [
    {
      "name": "process_wavelet",
      "inputs": {
        "wavelet_stream": "wavelet_stream"
      },
      "outputs": {
        "processed_wavelet": "processed_wavelet"
      },
      "operation": {
        "type": "elementwise_multiply",
        "scalar": 2.0
      }
    }
  ]
}
EOF

cat << EOF > run.py
import os
import sys
import numpy as np

from cerebras.sdk.runtime import SDKRuntime

# Define paths to CSL files
layout_path = "layout.csl"
program_path = "pe_program.csl"

# Initialize SDKRuntime
runtime = SDKRuntime(layout=layout_path, program=program_path)

# Prepare input data (example: a single wavelet)
input_data = np.random.rand(1, 1, 1024).astype(np.float32)

# Run the simulation
# The runtime expects a dictionary of input stream names and their data
# The output will be a dictionary of output stream names and their data
output_data = runtime.run(wavelet_stream=input_data)

# Access the processed data
processed_wavelet = output_data["processed_wavelet"]

print("Input data shape:", input_data.shape)
print("Output data shape:", processed_wavelet.shape)
print("First 10 elements of processed data:", processed_wavelet[0, 0, :10])

# Clean up runtime resources
del runtime
EOF

# Execute the Python script
python run.py

```

--------------------------------

### Example: List and Load Core File

Source: https://sdk.cerebras.net/debug/debugging

Demonstrates listing available core files and then loading a specific core file for post-mortem debugging.

```bash
(csdb) target list
INFO:csdb: [0] core-ckpt
INFO:csdb: [1] my_try1-ckpt
(csdb) target create --core-file core-ckpt

```

--------------------------------

### Instruction Trace Log Example

Source: https://sdk.cerebras.net/debug/debugging

An example of an instruction trace log showing PE activity, instruction decoding, and execution. Use SINGULARITYENV_SIMFABRIC_DEBUG=inst_trace to generate.

```text
@497 P4.1: Id: 12, Instr: 225, Seq: 0, Pipe: 3, Msg: [IS OP] 0x021c: T01                  FMACS          Dest:[DDS1]       Src0:[S0DS1]       Src1:[S1DS1]       Src2:R13,R12
@500 P4.1: Id: 12, Instr: 225, Seq: 0, Pipe: 6, Msg: [EX OP] 0x021c: T01                  FMACS          Dest:3f800000               Src0:00000000      Src1:3f800000      Src2:3f800000                                   [     ] U0
@501 P4.1: Id: 12, Instr: 225, Seq: 1, Pipe: 6, Msg: [EX OP] 0x021c: T01                  FMACS          Dest:41500000               Src0:40c00000      Src1:41500000      Src2:3f800000                                   [     ] U0
@502 P4.1: Id: 12, Instr: 225, Seq: 2, Pipe: 6, Msg: [EX OP] 0x021c: T01                  FMACS          Dest:41c80000               Src0:41400000      Src1:41500000      Src2:3f800000                                   [     ] U0
@503 P4.1: Id: 12, Msg: [EX OP] IDLE
@504 P4.1: Id: 12, Instr: 225, Seq: 3, Pipe: 6, Msg: [EX OP] 0x021c: T01                  FMACS          Dest:42140000               Src0:41900000      Src1:41980000      Src2:3f800000                                   [     ] U0

```

--------------------------------

### GEMV Example

Source: https://sdk.cerebras.net/sdk-release-notes/sdk-doc-updates

A basic example demonstrating the General Matrix-Vector Multiplication (GEMV) operation.

```csl
from cerebras.sdk.runtime import CSLContext

def gemv_basic(matrix, vector):
    with CSLContext() as ctx:
        result = ctx.gemv(matrix, vector)
        return result
```

--------------------------------

### Lima Configuration for QEMU

Source: https://sdk.cerebras.net/installation-guide

Example `config.yml` for creating an x86_64 Lima VM with Apptainer, intended for QEMU-based SDK execution.

```yaml
vmType: "qemu"

images:
- location: "https://cloud-images.ubuntu.com/releases/22.04/release-20231130/ubuntu-22.04-server-cloudimg-amd64.img"
  arch: "x86_64"
  digest: "sha256:7edc2eccf1e34df23d9561b721b6fed381c3b6e8c916c91c71bbce7b8488b496"

arch: "x86_64"

```

--------------------------------

### Hadamard Product Example for Batched Execution

Source: https://sdk.cerebras.net/sdk-release-notes/sdk-doc-updates

Illustrates the Hadamard product using batched execution mode in the CSELFRunner runtime.

```csl
from cerebras.sdk.runtime import CSELFRunner

def hadamard_product(a, b):
    runner = CSELFRunner()
    result = runner.run(lambda x, y: x * y, a, b)
    return result
```

--------------------------------

### Set DSD Base Address Example

Source: https://sdk.cerebras.net/csl/language/dsds

An example demonstrating how to set the base address for a DSD named 'my_dsd' to a specific memory address.

```csl
my_dsd @set_dsd_base_addr 0x1000
```

--------------------------------

### Example Usage of Main Thread Priority

Source: https://sdk.cerebras.net/csl/language/libraries

Demonstrates how to import the tile_config module and update main thread priority at comptime and runtime.

```csl
const config = @import_module("<tile_config>");
const mt_priority = config.main_thread_priority;

comptime {
  mt_priority.update_main_thread_priority(mt_priority.level.MEDIUM);
}

task main() void {
  mt_priority.update_main_thread_priority(mt_priority.level.MEDIUM_HIGH);
}
```

--------------------------------

### Basic CSL Syntax Example

Source: https://sdk.cerebras.net/_sources/csl/code-examples/tutorial-gemv-00-basic-syntax.rst.txt

This snippet demonstrates the basic syntax of CSL. It is intended for introductory purposes.

```csl
gemv(A, x, y)
{
  y = A * x;
}

```

--------------------------------

### Shell Commands for WSE3

Source: https://sdk.cerebras.net/_sources/csl/code-examples/tutorial-gemv-05-multiple-pes.rst.txt

Shell commands to execute the GEMV example on a WSE3 system.

```shell
#!/bin/bash

# Navigate to the directory containing the Python script
cd $(dirname $0)

# Execute the Python script to run the GEMV operation
python3 run.py

```

--------------------------------

### Cholesky Decomposition Example

Source: https://sdk.cerebras.net/sdk-release-notes/sdk-doc-updates

Demonstrates the Cholesky decomposition functionality within the SDK.

```csl
import numpy as np

def cholesky_decomposition(matrix):
    if not np.allclose(matrix, matrix.T):
        raise ValueError("Input matrix must be symmetric.")
    if not np.all(np.linalg.eigvalsh(matrix) > 0):
        raise ValueError("Input matrix must be positive-definite.")
    return np.linalg.cholesky(matrix)
```

--------------------------------

### Debug Library Usage Example

Source: https://sdk.cerebras.net/csl/language/libraries

This example shows how to import and use the <debug> module to record timestamps, compile-time strings, and variable values within a PE program. It requires specifying a key and buffer size during module import.

```csl
// pe_program.csl
// When importing an instance of the <debug> module, two things must be
// specified:
//
//   * (key: comptime_string) user-specified key that can be used to
//       retrieve the contents of the trace buffer after execution
//   * (buffer_size: comptime_int) size of buffer for recording traces
const trace = @import_module(
  "<debug>",
  .வுகளை = {
     .key = "debug_example",
     .buffer_size = 100,
   }
);

var global : i16 = 0;

task main_task() void {
  // Record timestamp for beginning of task
  trace.trace_timestamp();

  // Record a compile-time string
  trace.trace_string("Hello, world");

  // Update global variable and record
  global = 5;
  trace.trace_i16(global);

  // Record timestamp for end of task
  trace.trace_timestamp();
}

```

--------------------------------

### Shell Commands for WSE3

Source: https://sdk.cerebras.net/_sources/csl/code-examples/tutorial-gemv-08-routes-3.rst.txt

Shell commands to build and run the GEMV example on a WSE3 system. Includes compilation and execution steps.

```shell
# Build the GEMV application
csbuild -j $(nproc) --runtime-only

# Run the GEMV application
run.py --model-path $(pwd)/build/gemv.model --input-data $(pwd)/input.data --output-data $(pwd)/output.data
```

--------------------------------

### Load and Run Program on Device

Source: https://sdk.cerebras.net/csl/tutorials/gemv-01-complete-program

Loads the compiled program onto the device and starts its execution. This is a prerequisite for launching kernels.

```python
runner.load()
runner.run()

```

--------------------------------

### Gemv Execution Commands (Shell)

Source: https://sdk.cerebras.net/_sources/csl/code-examples/tutorial-gemv-06-routes-1.rst.txt

Shell commands to set up and run the Gemv example, potentially involving environment variables and execution commands.

```shell
#!/bin/bash

# Commands to run Gemv example
export CSL_ROOT="/path/to/csl"
export PATH="$CSL_ROOT/bin:$PATH"

python run.py
```

--------------------------------

### Initialize SdkRuntime and Get Symbols

Source: https://sdk.cerebras.net/csl/code-examples/tutorial-gemv-07-routes-2

Initializes the SdkRuntime and retrieves device symbols for matrices A, x, and y.

```python
# Size of N dimension on each PE
N_per_PE = N // 2
M_per_PE = M // 2

# Construct a runner using SdkRuntime
runner = SdkRuntime(args.name, cmaddr=args.cmaddr)

# Get symbols for A, x, y on device
A_symbol = runner.get_id('A')
x_symbol = runner.get_id('x')
y_symbol = runner.get_id('y')
```

--------------------------------

### Lima Configuration for Rosetta

Source: https://sdk.cerebras.net/installation-guide

Example `config.yml` for creating an aarch64 Lima VM with Apptainer, suitable for Rosetta-based SDK execution.

```yaml
minimumLimaVersion: 2.0.0

containerd:
  system: false
  user: false
provision:
- mode: system
  script: |
    #!/bin/bash
    set -eux -o pipefail
    command -v apptainer >/dev/null 2>&1 && exit 0
    # Workaround for https://github.com/apptainer/apptainer/issues/2027
    echo "kernel.apparmor_restrict_unprivileged_userns = 0" >/etc/sysctl.d/99-userns.conf
    sysctl --system
    # add the "Official PPA for Apptainer" 
    add-apt-repository -y ppa:apptainer/ppa
    apt-get update
    apt-get install -y apptainer
probes:
- script: |
    #!/bin/bash
    set -eux -o pipefail
    if ! timeout 30s bash -c "until command -v apptainer >/dev/null 2>&1; do sleep 3; done"; then
      echo >&2 "apptainer is not installed yet"
      exit 1
    fi
  hint: See "/var/log/cloud-init-output.log" in the guest

images:
# Try to use release-yyyyMMdd image if available. Note that release-yyyyMMdd will be removed after several months.
- location: "https://cloud-images.ubuntu.com/releases/noble/release-20251213/ubuntu-24.04-server-cloudimg-arm64.img"
  arch: "aarch64"
  digest: "sha256:a40713938d74aaec811f74cb1fa8bfcb535d22e26b2a0ca1cc90ad9db898feb9"
- location: https://cloud-images.ubuntu.com/releases/noble/release/ubuntu-24.04-server-cloudimg-arm64.img
  arch: aarch64

mounts:
- location: "~"
  writable: true
- location: "/tmp/lima"
  writable: true

mountType: "virtiofs"

vmOpts:
  vz:
    rosetta:
      enabled: true
      binfmt: true

```

--------------------------------

### Shell Commands for WSE3

Source: https://sdk.cerebras.net/_sources/csl/code-examples/tutorial-gemv-03-memcpy.rst.txt

Shell commands to execute the GEMV example on a WSE3 device. This includes setting up the environment and running the Python script.

```shell
#!/bin/bash

# Set up the environment variables for the Cerebras SDK
# Adjust the path to your SDK installation if necessary
export CEREBRAS_SDK_HOME=/usr/local/cerebras/sdk
export PATH=$CEREBRAS_SDK_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CEREBRAS_SDK_HOME/lib:$LD_LIBRARY_PATH

# Navigate to the directory containing the Python script
# Adjust the path to your project structure if necessary
cd /path/to/your/project/sources/csl/code-examples

# Run the Python script
python3 tutorial-gemv-03-memcpy.rst.md/run.py

echo "GEMV example execution complete."

```

--------------------------------

### Example: Create Interactive Debug Session

Source: https://sdk.cerebras.net/debug/debugging

Command to create an interactive debug session by connecting to a specified CM IP address and port.

```bash
(csdb) target create --cmaddr 12.34.56.78:9000

```

--------------------------------

### Run Add2vec Example with SDK

Source: https://sdk.cerebras.net/csl/code-examples/tutorial-sdklayout-04-h2d-d2h

Sets up the simulation environment, defines the layout, compiles the CSL code, and runs the add2vec computation. It includes data generation, device communication, and verification of results.

```python
#!/usr/bin/env cs_python

import argparse

import numpy as np

from cerebras.sdk.runtime.sdkruntimepybind import (
    Color,
    Edge,
    Route,
    RoutingPosition,
    SdkLayout,
    SdkTarget,
    SdkRuntime,
    SimfabConfig,
    get_platform,
)

parser = argparse.ArgumentParser()
parser.add_argument('--cmaddr', help='IP:port for CS system')
parser.add_argument(
    '--arch',
    choices=['wse2', 'wse3'],
    default='wse3',
    help='Target WSE architecture (default: wse3)'
)
parser.add_argument(
    '--cslc-prefix',
    type=str,
    default='',
    help='Optional path to bin/cslc-driver'
)
args = parser.parse_args()

###########
### Layout
###########
# If 'cmaddr' is empty then we create a default simulation layout.
# If 'cmaddr' is not empty then 'config' and 'target' are ignored.
config = SimfabConfig(dump_core=True)
target = SdkTarget.WSE3 if (args.arch == 'wse3') else SdkTarget.WSE2
platform = get_platform(args.cmaddr, config, target)
layout = SdkLayout(platform)

######################
### Common invariants
######################
size = 10
sender_routes = RoutingPosition().set_input([Route.RAMP])
receiver_routes = RoutingPosition().set_output([Route.RAMP])

############
### Add2vec
############
add2vec = layout.create_code_region('./add2vec.csl', 'add2vec', 1, 1)
rx1 = Color('rx1')
rx2 = Color('rx2')
tx = Color('tx')
add2vec.set_param_all('size', size)
add2vec.set_param_all(rx1)
add2vec.set_param_all(rx2)
add2vec.set_param_all(tx)
rx1_port = add2vec.create_input_port(rx1, Edge.RIGHT, [receiver_routes], size,)
rx2_port = add2vec.create_input_port(rx2, Edge.RIGHT, [receiver_routes], size,)
tx_port = add2vec.create_output_port(tx, Edge.LEFT, [sender_routes], size,)
add2vec.place(7, 4)

#############################
### Input and output streams
#############################
in_stream1 = layout.create_input_stream(rx1_port)
in_stream2 = layout.create_input_stream(rx2_port)
out_stream = layout.create_output_stream(tx_port)

#################
### Compilation
#################
# Compile the layout and use 'out' as the prefix for all
# produced artifacts.
compile_artifacts = layout.compile(out_prefix='out', cslc_prefix=args.cslc_prefix)

#############
### Runtime
#############
# Create the runtime using the compilation artifacts and the execution platform.
runtime = SdkRuntime(compile_artifacts, platform, memcpy_required=False)
runtime.load()
runtime.run()

# Data to be sent to the device and buffer to accept the result from
# the device.
data1 = np.random.randint(0, 1000, size=size, dtype=np.uint32)
data2 = np.random.randint(1000, 2000, size=size, dtype=np.uint32)
actual = np.empty(size, dtype=np.uint32)

# Send and receive to/from the device.
runtime.send(in_stream1, data1, nonblock=True)
runtime.send(in_stream2, data2, nonblock=True)
runtime.receive(out_stream, actual, size, nonblock=True)

runtime.stop()

#################
### Verification
#################
# Verify that the received data is correct.
expected = data1 + data2
assert np.array_equal(expected, actual)
print("SUCCESS!")

```

--------------------------------

### Python Script to Run GEMV Example

Source: https://sdk.cerebras.net/_sources/csl/code-examples/tutorial-gemv-02-memory-dsds.rst.txt

Python script to configure and run the GEMV computation on the Cerebras system. Ensure the 'cerebras.sdk.sdk_runtime' is installed.

```python
import numpy as np
from cerebras.sdk.sdk_runtime import CsbGraph

def run_gemv_example():
    graph = CsbGraph()
    graph.load_layout("layout.csl")
    graph.load_pe_program("pe_program.csl")

    # Initialize input matrices
    A = np.random.rand(1024, 1024).astype(np.float16)
    B = np.random.rand(1024, 1024).astype(np.float16)
    C = np.zeros((1024, 1024)).astype(np.float16)

    # Add matrices to the graph
    graph.add_matrix("A", A)
    graph.add_matrix("B", B)
    graph.add_matrix("C", C)

    # Compile and run the graph
    graph.compile()
    graph.run()

    # Retrieve the result
    C_result = graph.get_matrix("C")
    print("GEMV computation complete.")
    # print("Result matrix C:\n", C_result)

if __name__ == "__main__":
    run_gemv_example()

```

--------------------------------

### Instantiate SdkRuntime and Run

Source: https://sdk.cerebras.net/tensor-streaming

Import necessary modules, instantiate SdkRuntime with ELF directory and WSE IP, load, run, perform operations, and finally stop the runtime.

```python
from cerebras.sdk.runtime.sdkruntimepybind import SdkRuntime
from cerebras.sdk.runtime.sdkruntimepybind import MemcpyDataType
from cerebras.sdk.runtime.sdkruntimepybind import MemcpyOrder

simulator = SdkRuntime(args.name, cmaddr=args.cmaddr)
simulator.load()
simulator.run()
# a sequence of operations
simulator.stop()

```

--------------------------------

### Allreduce PE Setup and Parameters

Source: https://sdk.cerebras.net/csl/code-examples/benchmark-7pt-stencil-spmv

Defines parameters, queues, DSR IDs, and imported modules for the Allreduce PE implementation. Includes constants for binary operations and state definitions.

```csl
const width = reduce_params.width;
const height = reduce_params.height;

// f_callback = sys_mod.unblock_cmd_stream, to continue next command
param f_callback: fn ()void;

// last PE uses this ID as the input queue
// others use this ID as the output queue
param queues:[1]u16;

// explicit DSR allocation
param dest_dsr_ids: [1]u16;
param src0_dsr_ids: [1]u16;
param src1_dsr_ids: [1]u16;

const timestamp = @import_module("<time>");

const math_lib = @import_module("<math>");

// A new type for binary operators
// compiler assigns ADD=0 and MAX=1
const TYPE_BINARY_OP = enum(u16) {
    ADD,
    MAX
};

// tsc_size_words = 3
var tscRefBuffer = @zeros([timestamp.tsc_size_words]u16);

////////////////////////////////////////////////////////////////////////////////
// Main memory (48KB)
////////////////////////////////////////////////////////////////////////////////

var x: [*]f32;

var functor: TYPE_BINARY_OP = TYPE_BINARY_OP.ADD;

const STATE_ROW_REDUCE: i16 = 0;
const STATE_COL_REDUCE: i16 = 1;
const STATE_BCAST: i16 = 2;
const STATE_SCALE_AND_SQUARE: i16 = 3;
const STATE_NRM2: i16 = 4;
const STATE_DONE: i16 = 5;

// allreduce(ADD/MAX) has four states
// allreduce_nrm2 has 9 states
// "+1" is to avoid out-of-bound if
// STATE_DONE also dereference next state
var state_seq = @zeros([9+1]i16);
var state_idx: i16 = 0;
var cur_state: i16 = 0;
var next_state: i16 = 0;

// record the reduction length from the caller
var wvlts_per_pe: u16 = 0;

// number of PEs involed in the reduction: last PE needs to count number of received neighbors
// WARNING: reduce_pes only records number of received PEs
//   row reduction: width-1
//   column reduction: height-1
// If reduce_pes is wrong, simfab shows re-entry error of UT when row reduction and col reduction
// are combined because row reduction has extra UT1 waiting for wavelets
var reduce_pes: i16 = 0;
// 1st PE during the reduction: send TD to others
//   row reduction: {px = 0}
//   column reduction: {py = 0}
var reduce_first_pe: bool;
// last PE during the reduction: receive data from w-1 or h-1 neighbors
//   row reduction: {px = w-1}
//   column reduction: {py = h-1}
var reduce_last_pe: bool;

// last PE uses count_recv_or_send to receive data from w-1 neighbors
// other PEs use count_recv_or_send to send data and control
var count_recv_or_send: i16 = 0;


const dest_dsr = @get_dsr(dsr_dest, dest_dsr_ids[0]);
const src0_dsr = @get_dsr(dsr_src0, src0_dsr_ids[0]);
const src1_dsr = @get_dsr(dsr_src1, src1_dsr_ids[0]);

const iq_route = @get_input_queue(queues[0]);
const oq_route = @get_output_queue(queues[0]);

```

--------------------------------

### Increment DSD Offset Example

Source: https://sdk.cerebras.net/csl/language/dsds

This example shows how to increment the offset of 'my_dsd' by 16 bytes.

```csl
my_dsd @increment_dsd_offset 16
```

--------------------------------

### Install Python Packages in Lima VM Environment

Source: https://sdk.cerebras.net/installation-guide

This script installs a specified Python package into a local directory within the Lima VM and sets the PYTHONPATH environment variable. It uses 'cs_python' to run pip install.

```bash
#!/bin/bash

py_path=$(realpath $1)
package_name=$2
SINGULARITYENV_PYTHONPATH="$(realpath $py_path)"
cs_python -c "
import subprocess
import sys
package='$2'
subprocess.check_call([sys.executable, '-m', 'pip', 'install', '--target=$py_path', package])
"
echo -e "Please do\nexport SINGULARITYENV_PYTHONPATH \"$SINGULARITYENV_PYTHONPATH\"
before using cs_python"
```

--------------------------------

### GEMV Example with Collective Communications

Source: https://sdk.cerebras.net/sdk-release-notes/sdk-doc-updates

Showcases the General Matrix-Vector Multiplication (GEMV) operation, including an example that utilizes collective communications.

```csl
from cerebras.sdk.runtime import CSLContext

def gemv_collective(matrix, vector):
    with CSLContext() as ctx:
        # Example demonstrating collective communication within GEMV
        # This is a conceptual representation and may vary based on actual implementation
        result = ctx.gemv(matrix, vector, comm_pattern='collective')
        return result
```

--------------------------------

### Run GEMV Example with SDK Layout

Source: https://sdk.cerebras.net/csl/code-examples/tutorial-sdklayout-05-gemv

This Python script sets up the SDK layout for a GEMV operation. It configures data streams, connects components like demux, mux, and the GEMV kernel, compiles the design, and executes it on the target hardware. Data is sent asynchronously to prevent deadlocks. Includes verification against NumPy's dot product.

```python
#!/usr/bin/env cs_python

import argparse

import numpy as np

from cerebras.sdk.runtime.sdkruntimepybind import (
    SdkLayout,
    SdkTarget,
    SdkRuntime,
    SimfabConfig,
    get_platform,
)

from demux import get_demux_adaptor, get_x_demux, get_b_demux
from mux import get_mux
from gemv import get_gemv


def get_random_data(size):
  return np.random.uniform(0.0, 1.0, size).astype(np.float32)


def main():
  parser = argparse.ArgumentParser()
  parser.add_argument('--cmaddr', help='IP:port for CS system')
  parser.add_argument(
      '--arch',
      choices=['wse2', 'wse3'],
      default='wse3',
      help='Target WSE architecture (default: wse3)'
  )
  parser.add_argument(
      '--cslc-prefix',
      type=str,
      default='',
      help='Optional path to bin/cslc-driver'
  )
  args = parser.parse_args()

  ###########
  ### Layout
  ###########
  # If 'cmaddr' is empty then we create a default simulation layout.
  # If 'cmaddr' is not empty then 'config' and 'target' are ignored.
  config = SimfabConfig(dump_core=True)
  target = SdkTarget.WSE3 if (args.arch == 'wse3') else SdkTarget.WSE2
  platform = get_platform(args.cmaddr, config, target)
  layout = SdkLayout(platform)

  ######################
  ### Common invariants
  ######################
  data_width = 16
  data_height = 32
  pe_width = 4
  pe_height = 4
  batch_width = data_width // pe_width
  batch_height = data_height // pe_height
  control_ep = 40

  #########
  ### Data
  #########
  x = get_random_data(data_width)
  b = get_random_data(data_height)
  A = get_random_data(data_width * data_height)
  y = np.empty(data_height, dtype=np.float32)

  #############
  ### Vector X
  #############
  (x_port, x_adaptor_port, x_adaptor) = get_demux_adaptor(
      layout, 'x_demux_adaptor', batch_width, pe_width
  )
  x_adaptor.place(1, 0)

  (x_demux_port, x_out_port, x_demux) = get_x_demux(
      layout, 'x_demux', batch_width, pe_width, 1, control_ep
  )
  x_demux.place(5, 0)
  layout.connect(x_adaptor_port, x_demux_port)

  #############
  ### Vector b
  #############
  (b_port, b_adaptor_port, b_adaptor) = get_demux_adaptor(
      layout, 'b_demux_adaptor', batch_height, pe_height
  )
  b_adaptor.place(1, 2)

  (b_demux_port, b_out_port, b_demux) = get_b_demux(
      layout, 'b_demux', batch_height, 1, pe_height
  )
  b_demux.place(3, 2)
  layout.connect(b_adaptor_port, b_demux_port)

  #########
  ### GEMV
  #########
  (gemv_x_port, gemv_b_port, gemv_y_port, gemv) = get_gemv(
      layout, 'gemv', pe_width, pe_height, batch_width, batch_height, control_ep, A
  )
  gemv.place(5, 2)

  #############
  ### Vector y
  #############
  (y_in_port, y_port, y_mux) = get_mux(layout, 'y_mux', batch_height, 1, pe_height)
  y_mux.place(10, 2)

  #####################
  ### Port connections
  #####################
  layout.connect(x_out_port, gemv_x_port)
  layout.connect(b_out_port, gemv_b_port)
  layout.connect(gemv_y_port, y_in_port)

  ################
  ### I/O streams
  ################
  x_stream = layout.create_input_stream(x_port)
  b_stream = layout.create_input_stream(b_port)
  y_stream = layout.create_output_stream(y_port)

  ################
  ### Compilation
  ################
  compile_artifacts = layout.compile(out_prefix='out', cslc_prefix=args.cslc_prefix)

  ##############
  ### Execution
  ##############
  runtime = SdkRuntime(compile_artifacts, platform, memcpy_required=False)
  runtime.load()
  runtime.run()

  ##################################
  ### Send 'x' and 'b'. Receive 'y'
  ##################################
  # Vectors 'x' and 'b' must be sent asynchronously (i.e., in a
  # non-blocking fashion) to prevent a deadlock due to their
  # inter-dependence in the core gemv computation kernel.
  runtime.send(x_stream, x, nonblock=True)
  runtime.send(b_stream, b, nonblock=True)
  runtime.receive(y_stream, y, data_height, nonblock=True)

  runtime.stop()

  #################
  ### Verification
  #################
  A_matrix = A.reshape(data_height, data_width)
  expected = np.dot(A_matrix, x) + b
  assert np.allclose(expected, y, atol=1e-6)
  print("SUCCESS!")


if __name__ == '__main__':
  main()

```

--------------------------------

### Install Cerebras SDK Wheels

Source: https://sdk.cerebras.net/_sources/appliance-mode.rst.txt

Install the cerebras_appliance and cerebras_sdk Python wheels in the virtual environment, specifying the correct Cerebras Software release.

```bash
(sdk_venv) $ pip install --upgrade pip
(sdk_venv) $ pip install cerebras_appliance==2.5.0
(sdk_venv) $ pip install cerebras_sdk==2.5.0
```

--------------------------------

### Set SDK Installation Environment Variables

Source: https://sdk.cerebras.net/installation-guide

Define environment variables for the SDK installation location and tarball path. `SDK_INSTALL_LOCATION` and `SDK_TAR_PATH` should be absolute paths.

```bash
SDK_INSTALL_LOCATION=/my/install/location
SDK_INSTALL_PATH=$SDK_INSTALL_LOCATION/cs_sdk
SDK_TAR_PATH=/path/to/Cerebras-SDK-2.10.0-{build id}.tar.gz
```

--------------------------------

### Set PYTHONPATH for Installed Python Packages

Source: https://sdk.cerebras.net/installation-guide

Command to set the 'SINGULARITYENV_PYTHONPATH' environment variable to the real path of the directory containing installed Python packages, enabling 'cs_python' to find them.

```bash
export SINGULARITYENV_PYTHONPATH=$(realpath $MY_LOCAL_PY_PATH)
```

--------------------------------

### Generate a sequence of evenly spaced numbers

Source: https://sdk.cerebras.net/csl/language/builtins

Use @range to create sequences of numbers. Specify element type, start, stop, and step, or just element type and stop for a sequence starting from 0.

```c
@range(i16, 1, 5, 1)       // generates the sequence 1, 2, 3, 4. Note that 5
                           // is not included
```

```c
@range(i32, 2, -3, 1)      // generates 2, 1, 0, -1, -2
```

```c
@range(u16, 2, 7, -1)      // empty sequence
```

```c
@range(comptime_int, 4)    // generates 0, 1, 2, 3
```

--------------------------------

### Provision Lima VM with Singularity

Source: https://sdk.cerebras.net/installation-guide

This script installs Singularity CE within a Lima VM during provisioning. It updates package lists, installs necessary tools, and downloads/installs the Singularity CE .deb package.

```bash
#!/bin/bash
set -eux -o pipefail
export DEBIAN_FRONTEND=noninteractive
apt-get update -y && apt install -y squashfs-tools-ng
wget https://github.com/sylabs/singularity/releases/download/v4.0.2/singularity-ce_4.0.2-jammy_amd64.deb
apt install -y ./singularity-ce_4.0.2-jammy_amd64.deb
```

--------------------------------

### Set and Get Configuration Values

Source: https://sdk.cerebras.net/csl/language/builtins

Demonstrates setting configuration values at compile time and retrieving them at runtime. Use `@set_config` to write values to specific addresses before execution and `@get_config` to read them.

```csl
comptime {
  // The value '42' will be stored in the configuration address '0x7e00'
  // before the program begins execution.
  @set_config(0x7e00, 42);

  // The previously-set value '42' will be retrieved from the configuration
  // address '0x7e00'.
  const old_value = @get_config(0x7e00);

  // This call will overwrite the previously set value in the configuration
  // address `0x7e00`.
  const new_value = old_value + 3;
  @set_config(0x7e00, new_value);
}

var config: [N]u16;
const base_addr = 0x7e00;
task foo(i: u16) void {
  // Read a configuration register at runtime.
  config[i] = @get_config(base_addr + i);

  // Read a configuration register that is known to occur within the range
  // [base_addr, base_addr + N].
  config[i] = @get_config(base_addr + i, .{base_addr, base_addr + N});

  // Read a configuration register that is known to occur within the ranges
  // [base_addr, base_addr + 4] or [base_addr + 8, base_addr + N].
  config[i] = @get_config(base_addr + i, .{.{base_addr, base_addr + 4},
                                           .{base_addr + 8, base_addr + N}});
}

```

--------------------------------

### Shell Script for Running the Example

Source: https://sdk.cerebras.net/_sources/csl/code-examples/tutorial-sdklayout-04-h2d-d2h.rst.txt

This shell script provides the commands to compile and run the Python script that executes the CSL kernel. It assumes the necessary SDK environment is set up.

```shell
#!/bin/bash

# Ensure the script is run from the directory containing the CSL and Python files
# cd /path/to/your/project

# Compile the CSL kernel (if not already compiled)
# csi compile add2vec.csl -o add2vec.csi

# Run the Python script
python run.py

```

--------------------------------

### Non-Generic Math Library Example in CSل

Source: https://sdk.cerebras.net/csl/language/libraries

Shows an equivalent example using non-generic f16 math functions. This version explicitly calls functions like `isFinite_f16`, `pow_f16`, `sin_f16`, `cos_f16`, `log_f16`, `abs_f16`, and `NaN_f16`.

```csl
task t() void {
  if (!math.isFinite_f16(x)) {
    x = 0.0;
  }
  var one = math.pow_f16(math.sin_f16(x), 2.0) +
    math.pow_f16(math.cos_f16(x), 2.0);
  if (math.abs_f16(math.log_f16(one) - 1.0) > 0.001) {
    x = math.NaN_f16;
  }
}
```

--------------------------------

### Load and Run SpMV Benchmark

Source: https://sdk.cerebras.net/csl/code-examples/benchmark-7pt-stencil-spmv

This snippet initializes the runtime, loads the compiled application, and executes the SpMV benchmark. It includes steps for copying input data (x and stencil coefficients) to the device and launching the core computation kernels.

```python
memcpy_dtype = MemcpyDataType.MEMCPY_32BIT
runner = SdkRuntime(dirname, cmaddr=args.cmaddr)

symbol_x = runner.get_id("x")
symbol_y = runner.get_id("y")
symbol_stencil_coeff = runner.get_id("stencil_coeff")
symbol_time_buf_u16 = runner.get_id("time_buf_u16")
symbol_time_ref = runner.get_id("time_ref")

runner.load()
runner.run()

print("copy vector x of type f32")
# the size of x per PE is pe_length
runner.memcpy_h2d(
    symbol_x,
    x_1d,
    0,
    0,
    width,
    height,
    pe_length,
    streaming=False,
    data_type=memcpy_dtype,
    order=MemcpyOrder.COL_MAJOR,
    nonblock=True,
)

print("copy coefficients of type f32")
# each PE holds 7 coefficients
runner.memcpy_h2d(
    symbol_stencil_coeff,
    stencil_coeff_1d,
    0,
    0,
    width,
    height,
    7,
    streaming=False,
    data_type=memcpy_dtype,
    order=MemcpyOrder.COL_MAJOR,
    nonblock=True,
)

print("step 1: sync all PEs")
runner.launch("f_sync", np.int16(1), nonblock=False)

print("step 2: tic() records time_start")
runner.launch("f_tic", nonblock=True)

print(f"step 3: compute y = A*x with zDim = {zDim}")
# positive zDim can be smaller than pe_length
runner.launch("f_spmv", np.int16(zDim), nonblock=False)

print("step 4: toc() records time_end")
runner.launch("f_toc", nonblock=False)

print("step 5: prepare (time_start, time_end)")
runner.launch("f_memcpy_timestamps", nonblock=False)

print("step 6: D2H (time_start, time_end)")
```

--------------------------------

### Load and Run CSL Program

Source: https://sdk.cerebras.net/csl/code-examples/tutorial-topic-10-map-builtin

Initializes the SDK runtime, loads the compiled CSL program, and executes the main kernel. This sets up the environment for subsequent operations.

```python
memcpy_dtype = MemcpyDataType.MEMCPY_32BIT

runner = SdkRuntime(dirname, cmaddr=args.cmaddr)

sym_weight = runner.get_id("weight")
sym_sqrt_diag_A = runner.get_id("sqrt_diag_A")
sym_A = runner.get_id("A")
sym_sum = runner.get_id("sum")

runner.load()
runner.run()
```

--------------------------------

### CSL Empty Configuration

Source: https://sdk.cerebras.net/_sources/csl/code-examples/tutorial-topic-06-switches.rst.txt

An example of an empty CSL configuration. This can serve as a base or for testing.

```csl
switch_id 0
{
  ports {}
  switches {}
  send {}
  recv {}
}
```

--------------------------------

### Instantiate memcpy in Top-Level CSL and PE Program

Source: https://sdk.cerebras.net/tensor-streaming

This example shows how to import memcpy parameters in the top-level CSL file and instantiate the memcpy module in the PE program CSL file.

```csl
const memcpy = @import_module("<memcpy/get_params>", .{
    .width = width,
    .height = height
});

layout {
  @set_rectangle(1, 1);
  @set_tile_code(0, 0, "pe_program.csl", .{ .memcpy_params = memcpy.get_params(0) });
}
```

```csl
param memcpy_params: comptime_struct;

const sys_mod = @import_module("<memcpy/memcpy>", memcpy_params);
```
Tokens:
Raw