.. _working-with-code-samples:

Working With Code Samples
=========================

The :ref:`csl-examples` section contains CSL programs, the ``.csl`` files, that each either demonstrate individual features of the language, or solve a larger application problem.
Each program is accompanied by a Python script, the ``run.py`` file, to run that program with the simulator.

The source for these code samples can be found inside the ``csl-extras-{build id}.tar.gz`` tarball within the release,
or at the `CSL examples GitHub repository <https://github.com/Cerebras/csl-examples>`_
(request access from developer@cerebras.net). 

For the GEMV tutorial code samples, we additionally provide
step-by-step explanations of the code in the :ref:`csl-tutorials` section.

.. warning::

   If you're just getting started, we recommend walking through the step-by-step
   tutorials in :ref:`csl-tutorials` to get a fuller explanation of these programs.

Compiling the code samples
--------------------------

Each code sample contains a CSL file as the top-level source file, typically named ``layout.csl``.
This file may reference additional CSL source files in that directory.

Each code sample also contains a ``commands.sh`` script, which contains the
commands required to compile and run the example.

For example, the ``tutorials/gemv-01-complete-program/commands.sh``
at :ref:`sdkruntime-gemv-01-complete-program` contains:

    .. code-block:: bash

          cslc ./layout.csl --fabric-dims=8,3 \
            --fabric-offsets=4,1 -o out --memcpy --channels 1
          cs_python run.py --name out 

    .. seealso:: See :ref:`csl-compiler` for the compiler options documentation.

To compile the program:

    1. First cd into the directory that contains the CSL files.
    2. Then run the ``cslc`` command shown in the ``commands.sh`` file to compile the program.
       Note, this command may span multiple lines. This command execution will produce files with the ``elf`` extension.
       For example:

        .. code-block:: bash

              $ cd tutorials/gemv-01-complete-program/
              $ cslc ./layout.csl --fabric-dims=8,3 --fabric-offsets=4,1 -o out --memcpy --channels 1
              $ ls out
              bin  east  generated  out.json  west
              $ ls out/bin
              out_0_0.elf  out_rpc.json

Running the program
-------------------

Use the ``run.py`` Python script that is in the code sample directory to execute the compiled program. For example, to run the above compiled program, execute the following command in the ``gemv-01-complete-program`` directory:

.. code-block:: bash

      $ cs_python run.py --name out

If the program runs correctly, you will see the message ``SUCCESS!`` near the end of the output.

Debugging
---------

See :ref:`debugging-guide` and :ref:`sdk-gui`.

.. 
   # This needs to be rewritten for SdkRuntime
           
       The file containing the memory output of the execution can also be used to inspect the state of the PE memory at the end of the execution via the ``ELFLoader`` class. This can be used to inspect memory contents of past runs without re-running the simulation.
   
       For example, to read the value of global variable ``x:u32`` from every PE:
   
           .. code-block:: python
   
             from cerebras.elf.cself import ELFLoader, ELFMemory
   
             ...
   
             runner = CSELFRunner(elfs)
             
             # Tell CSELFRunner to generate a dump of the
             # memory contents at the end of the run by
             # specifying the name of an output file.
             runner.connect_and_run('memory-core.out')
   
             loader = ELFLoader(core_file='memory-core.out')
             for elf in elfs:
               loader.set_elf(elf)
               for col, row in ELFMemory(elf).iter_coordinates():
                 x = loader.get_as_array_from(col, row, "x", np.uint32)
                 print(f"value of x on PE {col},{row} is {x}")

Moving From Simulation To Hardware
----------------------------------

After successfully simulating your CSL program, you can run it
on hardware by following the below guidelines when using ``cslc``:

Pass ``--arch`` flag
~~~~~~~~~~~~~~~~~~~~

Use the ``--arch`` flag with ``cslc``. This will ensure that the appropriate Cerebras system is targeted.

Allowed values are ``--arch=wse2`` for WSE-2 architecture and ``--arch=wse3`` for WSE-3 architecture.
The default value is ``wse2``.
For example:

.. code-block:: bash

      cslc --arch=wse2 ./layout.csl --fabric-dims=8,3 \
        --fabric-offsets=4,1 -o out --memcpy --channels 1

Note that ``wse3`` is not yet supported for all example programs.

Provide ``--fabric-dims``
~~~~~~~~~~~~~~~~~~~~~~~~~

When compiling for simulation with ``cslc``, the ``--fabric-dims`` flag can be any bounding box large enough to contain your program's PEs. However, when compiling for hardware, these dimensions must match your Cerebras system's fabric dimensions. For example:

.. code-block:: bash

      cslc --arch=wse2 ./layout.csl --fabric-dims=757,996 \
        --fabric-offsets=4,1 -o out --memcpy --channels 1

Provide IP address to SdkRuntime
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To run on the Cerebras system hardware, you must pass the IP and port address of the network-attached Cerebras system to the ``cmaddr`` argument of the ``SdkRuntime`` constructor in your ``run.py``:

.. code-block:: python

    runner = SdkRuntime(compile_dir, cmaddr="1.2.3.4:9000")