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

# SDK Appliance API Reference

> Compile and run Cerebras SDK programs on a Wafer-Scale Cluster using the Appliance API — covers `SdkCompiler`, `SdkLauncher`, job submission, and appliance mode execution.

See [Running SDK on a Wafer-Scale Cluster](/appliance-mode) for an introduction to appliance mode.

## SdkCompiler

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

<span id="SdkCompiler" />

<ParamField body={<><span className="sig-kw">class </span>cerebras.sdk.client.<span className="sig-name">SdkCompiler</span><span className="sig-param">(**kwargs)</span></>} type="Bases: object">
  Manages the generation of compile artifacts on a Cerebras Wafer-Scale
  Cluster using the CSL compiler.

  [`SdkCompiler`](#sdkcompiler) must be used via a context manager.

  <Expandable title="content">
    <Expandable title="Keyword Arguments">
      <ParamField body="mgmt_namespace (str)">
        Appliance cluster namespace to which the job is submitted. Default is
        the default namespace.
      </ParamField>

      <ParamField body="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)
      </ParamField>

      <ParamField body="resource_mem (int)">
        Memory in bytes requested from the management node for the compile job
        (default: `67 << 30`, or 67 GiB)
      </ParamField>

      <ParamField body="disable_version_check (bool)">
        If `True`, ignore version differences between appliance client and server.
      </ParamField>
    </Expandable>

    **Example**:

    In the following example, an [`SdkCompiler`](#sdkcompiler) object is instantiated
    via a context manager.
    The [`SdkCompiler.compile()`](#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.

    ```python theme={"languages":{"custom":["/languages/csl-tmlanguage.json"]}}
    import json
    from cerebras.sdk.client import SdkCompiler

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

    <span id="compile" />

    <ParamField body={<><span className="sig-name">compile</span><span className="sig-param">(codedir: str, layout: str, args: str, outdir: str) → str</span></>}>
      Generates compile artifacts using the CSL compiler.

      <Expandable title="Parameters">
        <ParamField body="codedir (str)">
          Directory containing CSL code files.
        </ParamField>

        <ParamField body="layout (str)">
          Top-level CSL file containing the layout block.
        </ParamField>

        <ParamField body="args (str)">
          Arguments passed to the CSL compiler.
        </ParamField>

        <ParamField body="outdir (str)">
          Output directory or file for compile artifacts.
        </ParamField>
      </Expandable>

      > * **Returns**: String containing local path to compile artifacts.
      > * **Return type**: `str`
    </ParamField>
  </Expandable>
</ParamField>

## SdkLauncher

<span id="SdkLauncher" />

<ParamField body={<><span className="sig-kw">class </span>cerebras.sdk.client.<span className="sig-name">SdkLauncher</span><span className="sig-param">(artifact_path: str, **kwargs)</span></>} type="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.

  <Expandable title="content">
    <Expandable title="Parameters">
      <ParamField body="artifact_path (str)">
        Path to a compiled artifact which will be transferred
        and extracted in the appliance.
      </ParamField>
    </Expandable>

    <Expandable title="Keyword Arguments">
      <ParamField body="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.
      </ParamField>

      <ParamField body="mgmt_namespace (str)">
        Appliance cluster namespace to which the job is submitted. Default is
        the default namespace.
      </ParamField>

      <ParamField body="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)
      </ParamField>

      <ParamField body="resource_mem (int)">
        Memory in bytes requested from the management node for the compile job
        (default: `67 << 30`, or 67 GiB)
      </ParamField>

      <ParamField body="disable_version_check (bool)">
        If `True`, ignore version differences between appliance client and server.
      </ParamField>
    </Expandable>

    **Example**:

    In the following example, an [`SdkLauncher`](#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.

    ```python theme={"languages":{"custom":["/languages/csl-tmlanguage.json"]}}
    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, disable_version_check=True) 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")
    ```

    <span id="download_artifact" />

    <ParamField body={<><span className="sig-name">download_artifact</span><span className="sig-param">(artifact_name: str, out_path: str) → str</span></>}>
      Downloads an artifact from the appliance. If the artifact is a directory,
      a tarball of that directory will be created and transferred.

      <Expandable title="Parameters">
        <ParamField body="artifact_name (str)">
          Name of the artifact to download.
        </ParamField>

        <ParamField body="out_path (str)">
          Local path where the artifact will be saved.
        </ParamField>
      </Expandable>

      > * **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`
    </ParamField>

    <span id="stage" />

    <ParamField body={<><span className="sig-name">stage</span><span className="sig-param">(artifact_path: str)</span></>}>
      Stages additional artifacts in the remote working directory within the appliance.

      <Expandable title="Parameters">
        <ParamField body="artifact_path (str)">
          Local path to the artifact to be staged on the appliance.
        </ParamField>
      </Expandable>
    </ParamField>

    <span id="run" />

    <ParamField body={<><span className="sig-name">run</span><span className="sig-param">(*commands)</span></>}>
      Run one or more shell commands on the appliance.

      <Expandable title="Parameters">
        <ParamField body="*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.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## SdkRuntime

<Note>
  **Note**<br />
  The [`SdkRuntime`](#sdkruntime) appliance bindings are deprecated. Use [`SdkLauncher`](#sdklauncher) to
  wrap an SDK host Python script instead.
</Note>

<span id="SdkRuntime" />

<ParamField body={<><span className="sig-kw">class </span>cerebras.sdk.client.<span className="sig-name">SdkRuntime</span><span className="sig-param">(artifact_path: str, **kwargs)</span></>} type="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`](#sdkruntime) must be used via a context manager.

  <Expandable title="content">
    <Expandable title="Parameters">
      <ParamField body="artifact_path (str)">
        Path to ELF files compiled by [`SdkCompiler`](#sdkcompiler).
        The runtime collects the I/O and fabric parameters
        automatically, including height, width, number of
        channels, width of buffers, etc.
      </ParamField>
    </Expandable>

    <Expandable title="Keyword Arguments">
      <ParamField body="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.
      </ParamField>

      <ParamField body="mgmt_namespace (str)">
        Appliance cluster namespace to which the job is submitted. Default is
        the default namespace.
      </ParamField>

      <ParamField body="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)
      </ParamField>

      <ParamField body="resource_mem (int)">
        Memory in bytes requested from the management node for the compile job
        (default: `67 << 30`, or 67 GiB)
      </ParamField>

      <ParamField body="disable_version_check (bool)">
        If `True`, ignore version differences between appliance client and server.
      </ParamField>
    </Expandable>

    **Example**:

    In the following example, an [`SdkRuntime`](#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.

    ```python theme={"languages":{"custom":["/languages/csl-tmlanguage.json"]}}
    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)
    ```

    <span id="call" />

    <ParamField body={<><span className="sig-name">call</span><span className="sig-param">(name: str, args: List[int], **kwargs) → Optional[<a href="#task">Task</a>]</span></>}>
      Like [`launch`](#launch), but without type checking on the arguments. The caller passes a list of integer-castable arguments which are packed as `uint32` before transfer.

      <Expandable title="Parameters">
        <ParamField body="name (str)">
          The exported name of the symbol corresponding to a host-callable function.
        </ParamField>

        <ParamField body="args (List[int])">
          List of arguments to pass to the function, cast to integers.
        </ParamField>
      </Expandable>

      <Expandable title="Keyword Arguments">
        <ParamField body="nonblock (bool)">
          Nonblocking if `True`, blocking otherwise. This kwarg is required.
        </ParamField>
      </Expandable>

      > * **Returns**: Handle to the task if `nonblock=True`, else `None`.
      > * **Return type**: `Optional[Task]`
    </ParamField>

    <span id="download_artifact_runtime" />

    <ParamField body={<><span className="sig-name">download_artifact</span><span className="sig-param">(artifact_name: str, out_path: str) → str</span></>}>
      Downloads an artifact from the appliance worker node to the local host. If the artifact is a directory, a tarball of that directory will be created and transferred.

      <Expandable title="Parameters">
        <ParamField body="artifact_name (str)">
          Name of the artifact to download.
        </ParamField>

        <ParamField body="out_path (str)">
          Local path where the artifact will be saved.
        </ParamField>
      </Expandable>

      > * **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`
    </ParamField>

    <span id="get_id" />

    <ParamField body={<><span className="sig-name">get_id</span><span className="sig-param">(symbol: str)</span></>}>
      See [SdkRuntime API Reference](/api-docs/sdkruntime-api#sdkruntime).
    </ParamField>

    <span id="is_simulator" />

    <ParamField body={<><span className="sig-name">is_simulator</span><span className="sig-param">() → bool</span></>}>
      Returns `True` if this runtime is running on the appliance simulator, `False` if running on a real CS system.
    </ParamField>

    <span id="is_task_done" />

    <ParamField body={<><span className="sig-name">is_task_done</span><span className="sig-param">(task_handle: <a href="#task">Task</a>) → bool</span></>}>
      See [SdkRuntime API Reference](/api-docs/sdkruntime-api#sdkruntime).
    </ParamField>

    <span id="launch" />

    <ParamField body={<><span className="sig-name">launch</span><span className="sig-param">(symbol: str, *args, **kwargs) → <a href="#task">Task</a></span></>}>
      See [SdkRuntime API Reference](/api-docs/sdkruntime-api#sdkruntime).
    </ParamField>

    <span id="memcpy_d2h" />

    <ParamField body={<><span className="sig-name">memcpy_d2h</span><span className="sig-param">(dest: numpy.ndarray, src: int, px: int, py: int, w: int, h: int, elem_per_pe: int, **kwargs) → <a href="#task">Task</a></span></>}>
      See [SdkRuntime API Reference](/api-docs/sdkruntime-api#sdkruntime).
    </ParamField>

    <span id="memcpy_h2d" />

    <ParamField body={<><span className="sig-name">memcpy_h2d</span><span className="sig-param">(dest: int, src: numpy.ndarray, px: int, py: int, w: int, h: int, elem_per_pe: int, **kwargs) → <a href="#task">Task</a></span></>}>
      See [SdkRuntime API Reference](/api-docs/sdkruntime-api#sdkruntime).
    </ParamField>

    <span id="start" />

    <ParamField body={<><span className="sig-name">start</span><span className="sig-param">()</span></>}>
      Start program execution on the CS system or simulator. This step also encompasses loading the program. May be called at most once per [`SdkRuntime`](#sdkruntime) object.

      When using the context-manager form (`with SdkRuntime(...) as runner:`), `start()` is invoked implicitly on entry and explicit calls are unnecessary.
    </ParamField>

    <span id="stop" />

    <ParamField body={<><span className="sig-name">stop</span><span className="sig-param">()</span></>}>
      Stop program execution. Must follow [`start()`](#start). Pending nonblocking operations are flushed before this call returns, so D2H destination buffers are guaranteed populated after `stop()` returns.

      When using the context-manager form, `stop()` is invoked implicitly on exit; calling it again afterwards is an error.
    </ParamField>

    <span id="task_wait" />

    <ParamField body={<><span className="sig-name">task_wait</span><span className="sig-param">(task_handle: <a href="#task">Task</a>)</span></>}>
      See [SdkRuntime API Reference](/api-docs/sdkruntime-api#sdkruntime).
    </ParamField>
  </Expandable>
</ParamField>

## Task

<span id="Task" />

<ParamField body={<><span className="sig-kw">class </span>cerebras.sdk.client.<span className="sig-name">Task</span></>}>
  Handle to a task launched by [`SdkRuntime`](#sdkruntime).
</ParamField>

## MemcpyDataType

<span id="MemcpyDataType" />

<ParamField body={<><span className="sig-kw">class </span>cerebras.appliance.pb.sdk.sdk_common_pb2.<span className="sig-name">MemcpyDataType</span></>} type="Bases: Enum">
  Specifies the data size for transfers using [`SdkRuntime.memcpy_d2h()`](/api-docs/sdkruntime-api#memcpy_d2h) and
  [`SdkRuntime.memcpy_h2d()`](/api-docs/sdkruntime-api#memcpy_h2d) copy mode.

  > **Values**:
  >
  > * MEMCPY\_16BIT
  > * MEMCPY\_32BIT
</ParamField>

## MemcpyOrder

<span id="MemcpyOrder" />

<ParamField body={<><span className="sig-kw">class </span>cerebras.appliance.pb.sdk.sdk_common_pb2.<span className="sig-name">MemcpyOrder</span></>} type="Bases: Enum">
  Specifies mapping of data for transfers using [`SdkRuntime.memcpy_d2h()`](/api-docs/sdkruntime-api#memcpy_d2h) and
  [`SdkRuntime.memcpy_h2d()`](/api-docs/sdkruntime-api#memcpy_h2d).

  > **Values**:
  >
  > * ROW\_MAJOR
  > * COL\_MAJOR
</ParamField>

## sdk\_utils

Utility functions for common operations with [`SdkRuntime`](#sdkruntime).
Import from `cerebras.sdk.client.sdk_utils`.

See [sdk\_utils module](/api-docs/sdkruntime-api#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](/api-docs/sdkruntime-api#debug_util-module).