.. _install-guide: Installation and Setup ====================== This guide provides step-by-step instructions for installing the Singularity container build of the Cerebras Software Development Kit (SDK). This is the way to use the SDK if you're running the fabric simulator locally on your own machine, or you're using a legacy Cerebras system installation. For information about using the SDK on Cerebras Wafer-Scale Clusters running in appliance mode, see :ref:`appliance-mode`. Summary ------- The files you downloaded from Cerebras will contain the SDK software consisting of several scripts, folders, and other files such as the EULA. The SDK software is composed of a Singularity Image File named ``cbcore_sdk-1.1.0-{build id}.sif``. There are helper scripts to access the relevant functionality of the SIF: ``cslc``, ``cs_python``, ``csdb``, ``cs_readelf``, and ``sdk_debug_shell``. Requirements ------------ - **Apptainer or SingularityCE**: `Apptainer `_, `SingularityCE `_ or another container platform capable of running Singularity containers is required for hosting the Cerebras SDK container image. See the `Apptainer Quick Start `_ or `SingularityCE Quick Start `_ guide for instructions on how to set up Singularity. - **Overlay Filesystem**: The SDK requires that the `overlay filesystem `_ functionality is available on your Linux system. If your Linux kernel version is 3.18 or later then the `overlay filesystem functionality `_ is already available. - **Bash**: The SDK requires `Bash `_ on your Linux system. Make sure your system has the required software before proceeding to the installation. (Optional) Hash check with ``sha256sum`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ After downloading the files on Dropbox, you should have the following files in the same directory: - ``Cerebras-SDK-1.1.0-{build_id}.tar.gz``: The tarball containing the Singularity container. - ``sha256sum.txt``: A text file containing the hash of all the tarball. Verify that the downloaded files are not corrupted. Follow these steps: In the directory where you have downloaded the tar file, verify the checksum: .. code-block:: bash $ cd /my/install/location $ sha256sum --check sha256sum.txt If you see the output that shows ``OK``, then the downloaded files are not corrupted and are good to use. Extract the files ----------------- 1. To extract the SDK contents, first set the following environment variables. The ``SDK_INSTALL_LOCATION`` is the location you want to install the Cerebras SDK. This can be any (writable) directory. ``SDK_INSTALL_LOCATION`` and ``SDK_TAR_PATH`` should be absolute paths. .. code-block:: bash $ SDK_INSTALL_LOCATION=/my/install/location $ SDK_INSTALL_PATH=$SDK_INSTALL_LOCATION/cs_sdk $ SDK_TAR_PATH=/path/to/Cerebras-SDK-1.1.0-{build id}.tar.gz 2. Create the directory where you will install the Cerebras SDK, and extract the files from the downloaded tar file into that directory. .. code-block:: bash $ mkdir -p $SDK_INSTALL_PATH $ tar -C $SDK_INSTALL_PATH -xvf $SDK_TAR_PATH Extracted files ~~~~~~~~~~~~~~~ Verify that the following files are present in the ``$SDK_INSTALL_PATH`` directory: - ``cbcore_sdk-1.1.0-{build id}.sif``: This is the SDK software. This file is about 3GB. - ``cerebras-software-eula.pdf``: This is the End User License Agreement. - ``csdb``: This is a script for running hardware debug tools. - ``cslc``: This is a script for running the CSL compiler. - ``cs_python``: This is a script for running Python code using the version of Python provided in the ``.sif``. - ``cs_readelf``: This is a script for running a Cerebras alternative to ``readelf``. - ``sdk_debug_shell``: This is a script for running simulation debug tools, including the smoke test and the SDK GUI. - ``sdk-gui-LICENSE.txt``: This is the license for the GUI tool included. - ``csl-extras-{build id}.tar.gz``: This is a tarball containing example programs and additional extras. - ``csl_examples/``: This is a folder containing SDK example programs, including tutorials. - ``syntax_highlight/``: This is a folder containing a CSL syntax highlighter for vi/vim and VS Code IDE. Installing the SDK software --------------------------- Continue with the below steps to install the SDK software. .. .. _using-install-script: Using install script ~~~~~~~~~~~~~~~~~~~~ To install using the below script, first check to see that OverlayFS is installed on your Linux system. If it not present, then skip this section and follow the :ref:`using-manual-steps` section. .. attention:: Proceed to use this install script method only if you have the OverlayFS installed on your Linux system. 1. After downloading the SDK, create a Bash script file ``sdk_installation.sh``. .. code-block:: bash $ touch sdk_installation.sh $ chmod +x sdk_installation.sh 2. Copy-paste the following code into the Bash script file you created above. Set SDK_INSTALL_LOCATION and SDK_TAR_PATH to where the downloaded tar file is located. .. code-block:: bash #!/usr/bin/env bash # To prepare for installing the Cerebras SDK, first set the following environment variables. SDK_INSTALL_LOCATION=. # MODIFY THIS AS NEEDED SDK_INSTALL_PATH=$SDK_INSTALL_LOCATION/cs_sdk SDK_TAR_PATH=. # MODIFY THIS AS NEEDED # Create the installation directory and install. mkdir -p $SDK_INSTALL_PATH tar -C $SDK_INSTALL_PATH -xvf $SDK_TAR_PATH # Add the Cerebras SDK to your PATH. PATH_CMD='export PATH='$SDK_INSTALL_PATH':$PATH' eval $PATH_CMD # Add PATH update command to .bashrc: echo $PATH_CMD >> ~/.bashrc # Untar example programs cd $SDK_INSTALL_PATH extras_tarball=$(find -type f -name 'csl-extras-*.tar.gz') tar -xzvf $extras_tarball # Run the smoke test to verify functionality extras_dir=$(find -type d -name 'csl-extras-*') source sdk_debug_shell smoke $extras_dir 3. Run the script: .. code-block:: bash $ ./sdk_installation.sh When completed, your terminal will display: .. code-block:: text SUCCESS! PASSED SMOKE CHECK COMPLETED SUCCESSFULLY A successful smoke test indicates that the package is installed and is setup correctly. .. _using-manual-steps: .. attention:: Follow the below installation steps if you do not have the `OverlayFS filesystem `_ functionality on your Linux system. If your Linux system has the OverlayFS then follow the install script method described in :ref:`using-install-script` section. 3. Add the Cerebras SDK to your PATH. .. code-block:: bash $ PATH_CMD='export PATH='$SDK_INSTALL_PATH':$PATH' $ eval $PATH_CMD 4. Add PATH update command to .bashrc: .. code-block:: bash $ echo $PATH_CMD >> ~/.bashrc .. 6. If OverlayFS is not installed on your machine, then you should apply the following patch: - Update ``$SDK_INSTALL_LOCATION/cs_python`` file (line 20) to: .. code-block:: bash exec singularity exec --containall "--bind=$(pwd):/mnt" "--pwd=/mnt" -- "${SIF}" \ - Also update ``$SDK_INSTALL_LOCATION/sdk_debug_shell`` file (line 21) to: .. code-block:: bash exec singularity exec --containall "--bind=$(pwd):/mnt" "--pwd=/mnt" \ Test ~~~~ 5. Make sure you are in the install directory by running the below command: .. code-block:: bash $ cd $SDK_INSTALL_PATH 6. Untar the examples if you have not done so already, and run a basic smoke test to verify that the included examples compile and run as expected: .. code-block:: bash $ tar -xzvf csl-extras-{build id}.tar.gz $ sdk_debug_shell smoke csl-extras-{build id} You can optionally set the environment variable ``SINGULARITYENV_CSL_SUPPRESS_SIMFAB_TRACE=1`` when running the smoke test to prevent the generation of ``simfab_traces`` for use with the SDK GUI. This will greatly decrease the disk space used by the smoke test. Note that you will need to unset this environment variable before running examples for use with the SDK GUI. This smoke test will run all example programs in the simulator. If successful, your final output should be as below: .. code-block:: text SUCCESS! PASSED SMOKE CHECK COMPLETED SUCCESSFULLY A successful ``smoke`` test indicates that the package is installed and setup correctly. 7. (Optional) Test for verifying SDK Debug GUI tool using the ``gemm-collectives_2d`` example: - Run the ``gemm-collectives_2d`` test: .. code-block:: bash $ cd $SDK_INSTALL_PATH/csl-extras-{build id}/csl_examples/benchmarks/gemm_collectives_2d $ ./commands.sh - Run the SDK Debug GUI: .. code-block:: bash $ sdk_debug_shell visualize This will provide a URL. - Navigate to this URL in your browser: .. code-block:: text Click this link to open URL: http://:8000/sdk-gui?session_id=... Click this link to open URL: http://:/sdk-gui?session_id=... Press Ctrl-C to exit If you navigate to either URL, you will see the following after selecting a PE: .. figure:: images/install-test-gui.png :align: center :width: 750px Apple Silicon Mac Installation ------------------------------ The recommended method for running the Cerebras SDK on an Apple Silicon Mac is via a `Lima `_ Linux virtual machine. The documentation for Lima can be found `here `_. .. warning:: Running the Cerebras SDK on an Apple Silicon Mac or other ARM machine requires x86 emulation. Performance will be sluggish, and emulation bugs are possible. First, install Lima and the QEMU emulator via ``brew``: .. code-block:: bash $ brew install lima qemu Next, create a Lima x86 virtual machine with Singularity or Apptainer installed. The following ``config.yml`` is provided as an example, with your Mac's home directory and ``/tmp/lima`` mounted as writeable directories: .. code-block:: yaml 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" # max/base mean the maximum/minimum features supported by the host system cpuType: x86_64: "max" ssh: loadDotSSHPubKeys: false mounts: - location: "~" writable: true - location: "/tmp/lima" writable: true containerd: system: false user: false provision: - mode: system script: | #!/bin/bash set -eux -o pipefail export DEBIAN_FRONTEND=noninteractive 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 probes: - script: | #!/bin/bash set -eux -o pipefail if ! timeout 30s bash -c "until command -v singularity >/dev/null 2>&1; do sleep 3; done"; then echo >&2 "singularity is not installed yet" exit 1 fi hint: See "/var/log/cloud-init-output.log" in the guest message: | To run `singularity` inside your lima VM: $ limactl shell {{.Name}} singularity run library://alpine Saving the above contents into a file named ``config.yml`` or using your own configuration, create a new Lima virtual machine: .. code-block:: bash # Create a VM named cs_sdk $ limactl start ./config.yml --name cs_sdk Now, untar the Cerebras SDK tarball at any location under your Mac's home directory. We can now start a shell inside the VM, add the SDK to the ``PATH``, and run: .. code-block:: bash # Start shell inside VM $ limactl shell cs_sdk # Add absolute path under Mac home directory containing SDK to PATH # This MUST be absolute path; homedir on VM and Mac are not the same $ export PATH=/User/path/to/sdk:$PATH From this point, you can run the SDK examples within the VM. Lima VMs automatically port forward, so if you launch the SDK GUI within the VM, you can view it in your Mac's browser at ``127.0.0.1:8000/sdk-gui``.