Skip to content

Argonne Leadership Computing Facility

Getting Started with Cerebras CSL

Cerebras CSL (Cerebras System Language) is a low-level kernel programming language designed for the Cerebras system. It enables users to write code that runs on individual Processing Elements (PEs) and to define the placement of programs and the routing of data on the Wafer-Scale Engine (WSE).

To develop programs for the Cerebras system, users create two main components:

  1. Device Code: Written in CSL, this code executes directly on the Cerebras system.
  2. Host Code: Written in Python, this code leverages Cerebras APIs to facilitate data movement and execute functions on the Cerebras system. CSL includes libraries for a variety of commonly used primitive operations, such as broadcasting, gathering, and scattering data across rows or columns of PEs.

The Cerebras SDK can be utilized in two primary modes: 1. Simulator Mode: For testing and debugging programs without access to physical hardware. 2. Appliance Mode: For executing programs on the actual Cerebras hardware.

For a comprehensive overview of the Cerebras SDK, refer to the Cerebras SDK Documentation.

SDK with Simulator

The Cerebras SDK relies on a Singularity container and associated scripts to execute CSL code on a simulator.

On a user node, the Cerebras SDK is available at /software/cerebras/cs_sdk for your convenience. You can copy it to your $HOME directory, add it to your $PATH, and you’re ready to get started.

1
2
cp -r /software/cerebras/cs_sdk-1.4.0 ~
export PATH=~/cs_sdk-1.4.0:$PATH

To verify that the SDK is installed correctly, execute the command: cslc --help

Examples

We will use examples from the csl-examples repository provided by Cerebras. To get these examples, clone the repository into your desired directory:

1
2
3
4
5
6
export HTTPS_PROXY=http://proxy.alcf.anl.gov:3128
git clone https://github.com/Cerebras/csl-examples.git
cd csl-examples
git checkout rel-sdk-1.4.0
cd ~/csl-examples/benchmarks/gemm-collectives_2d
bash commands_wse3.sh

Note: to access any external web resources from a Cerebras user node, you will need to have a proxy environment variable set (or equivalent). wget needs the lower-case proxy environment variable. 

export HTTPS_PROXY=http://proxy.alcf.anl.gov:3128
export https_proxy=http://proxy.alcf.anl.gov:3128

Sample output: 
$ bash commands_wse3.sh
[INFO] === Beginning compilation ===
[INFO] Using SIF: ~/cs_sdk-1.4.0/sdk-cbcore-202505010205-2-ef181f81.sif
[INFO] CSL_IMPORT_PATH is not set
[INFO] CSL_IMPORT_PATH accepts colon separated list of paths generated by 'realpath <path>'
[INFO] Compilation successful
[INFO] === Calling container-hosted python ===
[INFO] Using SIF: ~/cs_sdk-1.4.0/sdk-cbcore-202505010205-2-ef181f81.sif
SUCCESS

SDK GUI

You can use the SDK Debug GUI to analyze and gain insights into your code execution. For detailed instructions, refer to the SDK GUI documentation.

To launch the SDK Debug GUI, run the following commands: 

1
2
cd ~/csl-examples/benchmarks/gemm-collectives_2d
sdk_debug_shell visualize

Sample output: 
[INFO] Using SIF: /home/vsastry/CS3_system/cs_sdk-1.4.0/sdk-cbcore-202505010205-2-ef181f81.sif
[INFO] CSL_IMPORT_PATH is not set
[INFO] CSL_IMPORT_PATH accepts colon separated list of paths generated by 'realpath <path>'
Click this link to open URL:  http://cer-anl-net001-us-sr01:8000/sdk-gui
Click this link to open URL:  http://10.125.11.2:8000/sdk-gui
Press Ctrl-C to exit

To access the GUI from your local computer, forward port 8000 from the user node through a login node to a local machine port 8008.

Adjust one or both port numbers if they are already in use.

Example script to forward port 8000 to localhost 8008: 

export SDK_PORT=8000
export LOCAL_PORT=8008
export ALCFUserID=<your alcf username>
ssh -L $LOCAL_PORT:localhost:$LOCAL_PORT $ALCFUserID@cer-login-04.ai.alcf.anl.gov -t ssh -L $LOCAL_PORT:localhost:$SDK_PORT -N cer-anl-net001-us-sr01

Then open the following URL in your web browser: http://localhost:8008/sdk-gui/

CS-3 connection diagram

SDK with Appliance Mode

Appliance Mode enables running code directly on the Cerebras Wafer-Scale Cluster. In addition to the containerized Singularity build of the Cerebras SDK, the SDK also supports operations on Cerebras Wafer-Scale Clusters running in appliance mode. Please note that the compilation is performed on the worker/management node, hence there might not be enough resourses while compiling a model along with other jobs running. For more information on differences between the simulator code and changes needed to run on appliance, refer to Appliance Mode.

Setup

Create Virtual Environment: Follow these steps to set up the virtual environment for the Cerebras SDK: 

1
2
3
4
5
rm -r cs_appliance_sdk
deactivate
/usr/bin/python3.11 -m venv cs_appliance_sdk
source cs_appliance_sdk/bin/activate
pip install --upgrade pip

Install SDK Packages: Install the cerebras_appliance and cerebras_sdk Python packages in the virtual environment, specifying the appropriate Cerebras Software release: 

1
2
pip install cerebras_appliance==2.6.0
pip install cerebras_sdk==2.6.0

Examples

We will use examples from the csl-examples repository provided by Cerebras. To access these examples, clone the repository into your desired directory:

1
2
3
4
5
export HTTPS_PROXY=http://proxy.alcf.anl.gov:3128
git clone https://github.com/Cerebras/csl-examples.git
cd csl-examples
git checkout rel-sdk-1.4.0
cd ~/csl-examples/tutorials/gemv-01-complete-program/

Compile Code

Use the following appliance_compile.py script to compile the code in the respective example directory:

compile.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import json
from cerebras.sdk.client import SdkCompiler
import logging
from cerebras.appliance import logger
logging.basicConfig(level=logging.INFO)

# Instantiate copmiler using a context manager
# Disable version check to ignore appliance client and server version differences.
with SdkCompiler(disable_version_check=True) as compiler:

    # Launch compile job
    artifact_path = compiler.compile(
        ".",
        "layout.csl",
        "--fabric-dims=8,3 --fabric-offsets=4,1 --memcpy --channels=1 -o out",
        "."
    )

# Write the artifact_path to a JSON file
with open("artifact_path.json", "w", encoding="utf8") as f:
    json.dump({"artifact_path": artifact_path,}, f)
Sample output: 
$ python appliance_compile.py
INFO:cerebras.cluster.client:Appliance client semantic version: 1.1.0, cluster server semantic version: 1.1.2, job operator semantic version: 1.1.2
INFO:cerebras.cluster.client:Initiating a new SDK compile job against the cluster server
INFO:cerebras.cluster.client:Job id: wsjob-4mhdefdzswskmakfcp9hfe, workflow id: wflow-2ullyamqmrdi7nxodyl6f77xbi, namespace: job-operator, remote log path:
/n1/wsjob/workdir/job-operator/wsjob-4mhdefdzswskmakfcp9hfe
INFO:cerebras.cluster.client:Poll ingress status: Waiting for all Coordinator pods to be running, current running: 0/1.
INFO:cerebras.cluster.client:Recording the timestamp when jobs is scheduled.
WARNING:cerebras.cluster.client:Event 2025-10-23 19:49:54 +0000 UTC reason=InconsistentVersion wsjob=wsjob-4mhdefdzswskmakfcp9hfe message='Warning: client semantic         version 1.1.0 is inconsistent with cluster server semantic version 1.1.2, there's a risk job could fail due to inconsistent setup.'
INFO:cerebras.cluster.client:Poll ingress status: Waiting for job ingress readiness.
INFO:cerebras.cluster.client:Poll ingress status: Job ingress ready, dashboard: https://grafana.anl0.cerebras.internal/d/WebHNShVz/wsjob-dashboard?orgId=1&var-wsjob=wsjob-
4mhdefdzswskmakfcp9hfe&from=1761248404000&to=now
INFO:cerebras.cluster.client:Poll ingress success: Job ingress ready, dashboard: https://grafana.anl0.cerebras.internal/d/WebHNShVz/wsjob-dashboard?orgId=1&var-
wsjob=wsjob-4mhdefdzswskmakfcp9hfe&from=1761248404000&to=now
2025-10-23 19:50:44,583 INFO     CSL compiler output:
CSL compiler produced no messages. Compilation successful.
INFO:cerebras.sdk.client.sdk_appliance_client:CSL compiler output:
CSL compiler produced no messages. Compilation successful.

The only difference between CS-3 and simuator run is the fabric_dims. It should be set to minimum required for simulatored runs. Above script generates artifact.json which is used by the appliance_run.py script.

Run Code

Use the following appliance_run.py script to run the code in the respective example directory:

run.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
#!/usr/bin/env cs_python

import argparse
import numpy as np
import json
#from cerebras.sdk.runtime.sdkruntimepybind import SdkRuntime, MemcpyDataType, MemcpyOrder # pylint: disable=no-name-in-module
import logging
from cerebras.appliance import logger
logging.basicConfig(level=logging.INFO)

from cerebras.appliance.pb.sdk.sdk_common_pb2 import MemcpyDataType, MemcpyOrder
from cerebras.sdk.client import SdkRuntime

# Matrix dimensions
M = 4
N = 6

# Construct A, x, b
A = np.arange(M*N, dtype=np.float32).reshape(M, N)
x = np.full(shape=N, fill_value=1.0, dtype=np.float32)
b = np.full(shape=M, fill_value=2.0, dtype=np.float32)

# Calculate expected y
y_expected = A@x + b

# 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"]

with SdkRuntime(artifact_path, simulator=True, disable_version_check=True) as runner:
    # Launch the init_and_compute function on device
    runner.launch('init_and_compute', nonblock=False)

    # Copy y back from device
    y_symbol = runner.get_id('y')
    y_result = np.zeros([1*1*M], dtype=np.float32)
    runner.memcpy_d2h(y_result, y_symbol, 0, 0, 1, 1, M, streaming=False,
    order=MemcpyOrder.ROW_MAJOR, data_type=MemcpyDataType.MEMCPY_32BIT, nonblock=False)
# Ensure that the result matches our expectation
np.testing.assert_allclose(y_result, y_expected, atol=0.01, rtol=0)
print("SUCCESS!")
Sample output: 
$ python appliance_run.py
INFO:cerebras.cluster.client:Appliance client semantic version: 1.1.0, cluster server semantic version: 1.1.2, job operator semantic version: 1.1.2
INFO:cerebras.cluster.client:Initiating a new SDK compile job against the cluster server
INFO:cerebras.cluster.client:Job id: wsjob-qqcsg8g5z66nknmk4d48gp, workflow id: wflow-kcrf2anv7zconl7xq2idceztdq, namespace: job-operator, remote log path:
/n1/wsjob/workdir/job-operator/wsjob-qqcsg8g5z66nknmk4d48gp
INFO:cerebras.cluster.client:Poll ingress status: Waiting for all Coordinator pods to be running, current running: 0/1.
INFO:cerebras.cluster.client:Recording the timestamp when jobs is scheduled.
WARNING:cerebras.cluster.client:Event 2025-10-23 19:54:55 +0000 UTC reason=InconsistentVersion wsjob=wsjob-qqcsg8g5z66nknmk4d48gp message='Warning: client semantic version    1.1.0 is inconsistent with cluster server semantic version 1.1.2, there's a risk job could fail due to inconsistent setup.'
INFO:cerebras.cluster.client:Poll ingress status: Waiting for job ingress readiness.
INFO:cerebras.cluster.client:Poll ingress status: Job ingress ready, dashboard: https://grafana.anl0.cerebras.internal/d/WebHNShVz/wsjob-dashboard?orgId=1&var-wsjob=wsjob-    qqcsg8g5z66nknmk4d48gp&from=1761248705000&to=now
INFO:cerebras.cluster.client:Poll ingress success: Job ingress ready, dashboard: https://grafana.anl0.cerebras.internal/d/WebHNShVz/wsjob-dashboard?orgId=1&var-
wsjob=wsjob-   qqcsg8g5z66nknmk4d48gp&from=1761248705000&to=now
SUCCESS!