SDK Appliance API Reference¶

This section presents the SDK Appliance API reference for running SDK programs on a Cerebras Wafer-Scale Cluster (WSC).

See Running SDK on a Wafer-Scale Cluster for an introduction to running in appliance mode on a Wafer-Scale Cluster.

SdkCompiler¶

Python API for compiling SDK programs on a Cerebras Wafer-Scale Cluster.

class cerebras.sdk.client.SdkCompiler(**kwargs)¶

Bases: object

Manages the generation of compile artifacts on a Cerebras Wafer-Scale Cluster using the CSL compiler.

SdkCompiler must be used via a context manager.

Keyword Arguments

mgmt_namespace (str) – Appliance cluster namespace to which the job is submitted. Default is the default namespace.
resource_cpu (int) – CPU cores on the WSC management node used by the compile job in units of 1/1000 CPU (default: 24000, or 24 cores)
resource_mem (int) – Memory in bytes requested from the management node for the compile job (default: 64 << 30, or 64 GiB)

Example:

In the following example, an SdkCompiler object is instantiated via a context manager. The SdkCompiler.compile() function takes four arguments:

the directory containing the CSL code files,

the name of the top level CSL code file that contains the layout block,

the compiler arguments,

and the output directory or output file for the compile artifacts.
import json
from cerebras.sdk.client import SdkCompiler

# Instantiate compiler using a context manager
with SdkCompiler() 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)

compile(codedir: str, layout: str, args: str, outdir: str) → str¶

Generates compile artifacts using the CSL compiler.

Parameters

codedir (str) – Directory containing CSL code files.
layout (str) – Top-level CSL file containing the layout block.
args (str) – Arguments passed to the CSL compiler.
outdir (str) – Output directory or file for compile artifacts.

Returns

String containing local path to compile artifacts.

Return type

str

SdkLauncher¶

class cerebras.sdk.client.SdkLauncher(artifact_path: str, **kwargs)¶

Bases: object

The SdkLauncher API can be used to upload artifacts, run custom commands in the appliance, and use custom scripts written as if the system was not in appliance mode and the user were running directly from a worker node.

The user must use the %CMADDR% template string to pass the system address to a run script.

Parameters

artifact_path (str) – Path to a compiled artifact which will be transferred. and extracted in the appliance.

Keyword Arguments

simulator (bool) – If True, runs the program on the simulator using a worker node of the Wafer-Scale Cluster. Default value is False, i.e., allocates and runs on a WSE.
mgmt_namespace (str) – Appliance cluster namespace to which the job is submitted. Default is the default namespace.
resource_cpu (int) – CPU cores on the WSC management node used by the compile job in units of 1/1000 CPU (default: 24000, or 24 cores)
resource_mem (int) – Memory in bytes requested from the management node for the compile job (default: 64 << 30, or 64 GiB)

Example:

In the following example, an SdkLauncher object is instantiated via a context manager, with path to compile artifacts given by artifact_path. launcher.stage transfers an additional file additional_artifact.txt to the appliance. Next, launcher.run runs a command on the appliance worker node which writes the contents of that file to stdout. We then use launcher.run to run a host Python script run.py. Notice that we specify the system’s CM address passed to this script via the template string %CMADDR, which will be evaluated at runtime based on the system allocated to this job. We then use download_artifact to transfer a file back from the appliance.

import json
import os

from cerebras.sdk.client import SdkLauncher

# read the compile 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"]

# artifact_path contains the path to the compiled artifact.
# It will be transferred and extracted in the appliance.
# The extracted directory will be the working directory.
# Set simulator=False if running on CS system within appliance.
with SdkLauncher(artifact_path, simulator=False) as launcher:

    # Transfer an additional file to the appliance,
    # then write contents to stdout on appliance
    launcher.stage("additional_artifact.txt")
    response = launcher.run(
        "echo \"ABOUT TO RUN IN THE APPLIANCE\"",
        "cat additional_artifact.txt",
    )
    print("Test response: ", response)

    # Run the original host code as-is on the appliance,
    # using the same cmd as when using the Singularity container
    response = launcher.run("cs_python run.py --name out --cmaddr %CMADDR%")
    print("Host code execution response: ", response)

    # Fetch files from the appliance
    launcher.download_artifact("out.txt", "./output_dir/out.txt")

download_artifact(artifact_name: str, out_path: str) → str¶

Downloads an artifact from the appliance. If the artifact is a directory, a tarball of that directory will be created and transferred.

Parameters

artifact_name (str) – Name of the artifact to download.
out_path (str) – Top-level CSL file containing the layout block.

Returns

The name of the file that has been written (can contain a .tar.gz extension if the artifact_name was a directory.)

Return type

str

stage(artifact_path: str):

Stages additional artifacts in the remote working directory within the appliance.

Parameters: artifact_path (str) – Local path to the artifact to be staged on the appliance.

run(*commands)¶

Run one or more shell commands on the appliance.

Parameters: *commands – One or more command strings. Use the special placeholder %CMADDR% wherever a CS system address should be substituted. All positional arguments must be strings.

SdkRuntime¶

class cerebras.sdk.client.SdkRuntime(artifact_path: str, **kwargs)¶

Bases: object

Manages the execution of SDK programs on the Cerebras Wafer-Scale Cluster appliance. The constructor analyzes the WSE ELFs in the bindir and prepares the WSE or simfabric for a run.

SdkRuntime must be used via a context manager.

Parameters

artifact_path (str) – Path to ELF files compiled by SdkCompiler. The runtime collects the I/O and fabric parameters automatically, including height, width, number of channels, width of buffers,… etc.

Keyword Arguments

simulator (bool) – If True, runs the program on simulator using a worker node of the Wafer-Scale Cluster. Default value is False, i.e., allocates and runs on a WSE.
mgmt_namespace (str) – Appliance cluster namespace to which the job is submitted. Default is the default namespace.
resource_cpu (int) – CPU cores on the WSC management node used by the compile job in units of 1/1000 CPU (default: 24000, or 24 cores)
resource_mem (int) – Memory in bytes requested from the management node for the compile job (default: 64 << 30, or 64 GiB)

Example:

In the following example, an SdkRuntime runner object is instantiated via a context manager, with path to compile artifacts given by artifact_path. The compiled kernel code has exported symbols my_fn, which names a function defined on all PEs in the program, and A, which points to an array on all PEs. The context manager loads and starts the program. Then, the function my_fn is launched. After this function is launched, A on the device is copied back into data on the host.
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) 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)

get_id(symbol: str)¶: See SdkRuntime API Reference.

is_task_done(task_handle: Task) → bool¶: See SdkRuntime API Reference.

launch(symbol: str, *args, **kwargs) → Task ¶: See SdkRuntime API Reference.

memcpy_d2h(dest: numpy.ndarray, src: int, px: int, py: int, w: int, h: int, elem_per_pe: int, **kwargs) → Task ¶: See SdkRuntime API Reference.

memcpy_h2d(dest: int, src: numpy.ndarray, px: int, py: int, w: int, h: int, elem_per_pe: int, **kwargs) → Task ¶: See SdkRuntime API Reference.

task_wait(task_handle: Task)¶: See SdkRuntime API Reference.

class cerebras.sdk.client.Task¶: Handle to a task launched by SdkRuntime.

class cerebras.appliance.pb.sdk.sdk_common_pb2.MemcpyDataType¶

Bases: Enum

Specifies the data size for transfers using SdkRuntime.memcpy_d2h() and SdkRuntime.memcpy_h2d() copy mode.

Values

MEMCPY_16BIT
MEMCPY_32BIT

class cerebras.appliance.pb.sdk.sdk_common_pb2.MemcpyOrder¶

Bases: Enum

Specifies mapping of data for transfers using SdkRuntime.memcpy_d2h() and SdkRuntime.memcpy_h2d().

Values

ROW_MAJOR
COL_MAJOR

sdk_utils¶

Utility functions for common operations with SdkRuntime. Import from cerebras.sdk.client.sdk_utils.

See sdk_utils module.

debug_util¶

Utilities for parsing debug output and core files of a simulator run. Import from cerebras.sdk.client.debug_util.

See debug_util module.

SDK Documentation (1.4.0)

SDK Appliance API Reference

Contents

SDK Appliance API Reference¶

SdkCompiler¶

SdkLauncher¶

SdkRuntime¶

sdk_utils¶

debug_util¶