.. _sdk-appliance-api-reference: SDK Appliance API Reference =========================== This section presents the SDK Appliance API reference for running SDK programs on a Cerebras Wafer-Scale Cluster (WSC). See :ref:`appliance-mode` for an introduction to running in appliance mode on a Wafer-Scale Cluster. .. _sdk-appliance-sdkcompiler: SdkCompiler ----------- .. py:module:: cerebras.sdk.client Python API for compiling SDK programs on a Cerebras Wafer-Scale Cluster. .. py:class:: SdkCompiler(**kwargs) :module: cerebras.sdk.client Bases: :class:`object` Manages the generation of compile artifacts on a Cerebras Wafer-Scale Cluster using the CSL compiler. :py:class:`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 :py:class:`SdkCompiler` object is instantiated via a context manager. The :py:meth:`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. .. code-block:: python 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) .. py:method:: compile(codedir: str, layout: str, args: str, outdir: str) -> str :module: cerebras.sdk.client Generates compile artifacts using the CSL compiler. :param codedir: Directory containing CSL code files. :type codedir: ``str`` :param layout: Top-level CSL file containing the layout block. :type layout: ``str`` :param args: Arguments passed to the CSL compiler. :type args: ``str`` :param outdir: Output directory or file for compile artifacts. :type outdir: ``str`` :returns: String containing local path to compile artifacts. :rtype: ``str`` .. _sdk-appliance-sdklauncher: SdkLauncher ----------- .. py:class:: SdkLauncher(artifact_path: str, **kwargs) :module: cerebras.sdk.client Bases: :class:`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. :param artifact_path: Path to a compiled artifact which will be transferred. and extracted in the appliance. :type artifact_path: ``str`` :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 :py:class:`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. .. code-block:: python 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") .. py:method:: download_artifact(artifact_name: str, out_path: str) -> str :module: cerebras.sdk.client Downloads an artifact from the appliance. If the artifact is a directory, a tarball of that directory will be created and transferred. :param artifact_name: Name of the artifact to download. :type artifact_name: ``str`` :param out_path: Top-level CSL file containing the layout block. :type out_path: ``str`` :returns: The name of the file that has been written (can contain a ``.tar.gz`` extension if the ``artifact_name`` was a directory.) :rtype: ``str`` .. py:method:: stage(artifact_path: str): :module: cerebras.sdk.client Stages additional artifacts in the remote working directory within the appliance. :param artifact_path: Local path to the artifact to be staged on the appliance. :type artifact_path: ``str`` .. py:method:: run(*commands) Run one or more shell commands on the appliance. :param \*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. :type commands: ``str`` (variadic) .. _sdk-appliance-sdkruntime: SdkRuntime ---------- .. py:class:: SdkRuntime(artifact_path: str, **kwargs) :module: cerebras.sdk.client Bases: :class:`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. :py:class:`SdkRuntime` must be used via a context manager. :param artifact_path: Path to ELF files compiled by :py:class:`SdkCompiler`. The runtime collects the I/O and fabric parameters automatically, including height, width, number of channels, width of buffers,... etc. :type artifact_path: ``str`` :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. .. code-block:: 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) 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) .. py:method:: get_id(symbol: str) :module: cerebras.sdk.client See :ref:`sdkruntime-api-reference`. .. py:method:: is_task_done(task_handle: Task) -> bool :module: cerebras.sdk.client See :ref:`sdkruntime-api-reference`. .. py:method:: launch(symbol: str, *args, **kwargs) -> Task :module: cerebras.sdk.client See :ref:`sdkruntime-api-reference`. .. py:method:: memcpy_d2h(dest: numpy.ndarray, src: int, px: int, py: int, w: int, h: int, elem_per_pe: int, **kwargs) -> Task :module: cerebras.sdk.client See :ref:`sdkruntime-api-reference`. .. py:method:: memcpy_h2d(dest: int, src: numpy.ndarray, px: int, py: int, w: int, h: int, elem_per_pe: int, **kwargs) -> Task :module: cerebras.sdk.client See :ref:`sdkruntime-api-reference`. .. py:method:: task_wait(task_handle: Task) :module: cerebras.sdk.client See :ref:`sdkruntime-api-reference`. .. py:class:: Task :module: cerebras.sdk.client Handle to a task launched by :py:class:`SdkRuntime`. .. py:class:: MemcpyDataType :module: cerebras.appliance.pb.sdk.sdk_common_pb2 Bases: :class:`Enum` Specifies the data size for transfers using :py:meth:`SdkRuntime.memcpy_d2h` and :py:meth:`SdkRuntime.memcpy_h2d` copy mode. :Values: * **MEMCPY_16BIT** * **MEMCPY_32BIT** .. py:class:: MemcpyOrder :module: cerebras.appliance.pb.sdk.sdk_common_pb2 Bases: :class:`Enum` Specifies mapping of data for transfers using :py:meth:`SdkRuntime.memcpy_d2h` and :py:meth:`SdkRuntime.memcpy_h2d`. :Values: * **ROW_MAJOR** * **COL_MAJOR** .. _sdk-appliance-sdk-utils: sdk_utils --------- Utility functions for common operations with :py:class:`SdkRuntime`. Import from ``cerebras.sdk.client.sdk_utils``. .. py:module:: cerebras.sdk.client.sdk_utils See :ref:`sdkruntime-sdk-utils`. .. _sdk-appliance-debug-util: debug_util ---------- Utilities for parsing debug output and core files of a simulator run. Import from ``cerebras.sdk.client.debug_util``. .. py:module:: cerebras.sdk.client.debug_util See :ref:`sdkruntime-debug-util`.