.. _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-0.9.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 ------------ - **Singularity**: `Singularity `__ is required for hosting the Cerebras SDK container image. See the `Singularity 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-0.9.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-0.9.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-0.9.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} 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}/benchmarks/SdkRuntime/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