.. _sdklayout-api-reference: SdkLayout API Reference ======================= This section presents the ``SdkLayout`` program layout specification Python API. Note that this API is part of the ``sdkruntimepybind`` module documented in :ref:`sdkruntime-api-reference`. CodeRegion ^^^^^^^^^^ .. py:class:: CodeRegion :module: cerebras.sdk.runtime.sdkruntimepybind Bases: :class:`object` Specifies a code region. .. py:method:: color(name: str) -> Color :module: cerebras.sdk.runtime.sdkruntimepybind Create and return a new color that is scoped within a region. :param name: Name to be assigned to the color. :type name: ``str`` :returns: A new color scoped within this region. :rtype: :py:class:`Color` .. py:method:: color(name: str, value: int) -> Color :module: cerebras.sdk.runtime.sdkruntimepybind :noindex: Create and return a new color (with a value) that is scoped within a region. :param name: Name to be assigned to the color. :type name: ``str`` :param value: Value to be assigned to the color. :type value: ``int`` :returns: A new color scoped within this region. :rtype: :py:class:`Color` .. py:method:: create_input_port(color: Color, edge: Edge, routes: List[RoutingPosition], data_size: int, prefix: str = "") -> PortHandle :module: cerebras.sdk.runtime.sdkruntimepybind Given a color, an orientation (i.e., ``edge``), a set of output routes, a size, and an optional prefix, create and return a new input communication port. The optional prefix can be used to create unique ports with the same color. Ports must be unique, otherwise an exception is thrown. :param color: Color of the input port. :type color: :py:class:`Color` :param edge: Edge on which to create the input port. :type edge: :py:class:`Edge` :param routes: List of output routes for the input port. :type routes: List[:py:class:`RoutingPosition`] :param data_size: The size of the port's data, used to verify port compatibility. :type data_size: ``int`` :param prefix: Optional prefix to port's name, which allows creation of unique ports with the same color. :type prefix: ``str`` :returns: Handle to the created input port. :rtype: :py:class:`PortHandle` .. py:method:: create_output_port(color: Color, edge: Edge, routes: List[RoutingPosition], data_size: int, prefix: str = "") :module: cerebras.sdk.runtime.sdkruntimepybind Given a color, an orientation (i.e., ``edge``), a set of input routes, a size, and an optional prefix, create and return a new output communication port. The optional prefix can be used to create unique ports with the same color. Ports must be unique, otherwise an exception is thrown. :type color: :py:class:`Color` :param edge: Edge on which to create the output port. :type edge: :py:class:`Edge` :param routes: List of input routes for the output port. :type routes: List[:py:class:`RoutingPosition`] :param data_size: The size of the port's data, used to verify port compatibility. :type data_size: ``int`` :param prefix: Optional prefix to port's name, which allows creation of unique ports with the same color. :type prefix: ``str`` :returns: Handle to the created output port. :rtype: :py:class:`PortHandle` .. py:method:: paint(coord: IntVector, color: Color, routes: List[RoutingPosition]) :module: cerebras.sdk.runtime.sdkruntimepybind Set the routing for a given color on a single PE within this region. :param coord: Coordinate on which color will be painted. :type coord: :py:class:`~cerebras.geometry.geometry.IntVector` :param color: Color to be painted on this coordinate. :type color: :py:class:`Color` :param routes: List of routing positions which will be applied to this color. :type routes: List[:py:class:`RoutingPosition`] .. py:method:: paint_all(color: Color, routes: List[RoutingPosition]) :module: cerebras.sdk.runtime.sdkruntimepybind Set the routing for a given color on all PEs of the region. :param color: Color to be painted on this region. :type color: :py:class:`Color` :param routes: List of routing positions which will be applied to this color. :type routes: List[:py:class:`RoutingPosition`] .. py:method:: paint_all(color: Color, routes: List[RoutingPosition], edge_routes: List[EdgeRouteInfo]) :module: cerebras.sdk.runtime.sdkruntimepybind :noindex: Set the routing for a given color on all PEs of the region with special routing on one or all region edges. :param color: Color to be painted on this region. :type color: :py:class:`Color` :param routes: List of routing positions which will be applied to this color. :type routes: List[:py:class:`RoutingPosition`] :param edge_routes: List of routing positions to be applied to this color on the region's edges. :type edge_routes: List[:py:class:`EdgeRouteInfo`] .. py:method:: paint_range(rect: IntRectangle, color: Color, routes: List[RoutingPosition]) :module: cerebras.sdk.runtime.sdkruntimepybind Set the routing for a given color on a contiguous rectangular subset of PEs within this region. :param rect: Rectangular subset of PEs within this region on which color will be painted. :type rect: :py:class:`~cerebras.geometry.geometry.IntRectangle` :param color: Color to be painted on this rectangle. :type color: :py:class:`Color` :param routes: List of routing positions which will be applied to this color. :type routes: List[:py:class:`RoutingPosition`] .. py:method:: place(x: int, y: int) :module: cerebras.sdk.runtime.sdkruntimepybind Place code region at specific coordinates ``(x, y)``. :param x: x-coordinate at which core region will be placed. :type x: ``int`` :param y: y-coordinate at which core region will be placed. :type y: ``int`` .. py:method:: set_param(coord: IntVector, name: str, value: int) :module: cerebras.sdk.runtime.sdkruntimepybind Set an unsigned integer parameter on a single PE within this region. :param coord: Coordinate on which parameter will be set. :type coord: :py:class:`~cerebras.geometry.geometry.IntVector` :param name: Name of the parameter. :type name: ``str`` :param value: Unsigned integer value of the parameter. :type value: ``int`` .. py:method:: set_param(coord: IntVector, color: Color) :module: cerebras.sdk.runtime.sdkruntimepybind :noindex: Set a color parameter on a single PE within this region. :param coord: Coordinate on which parameter will be set. :type coord: :py:class:`~cerebras.geometry.geometry.IntVector` :param color: Color value of the parameter. :type color: :py:class:`Color` .. py:method:: set_param(coord: IntVector, name: str, value: Color) :module: cerebras.sdk.runtime.sdkruntimepybind :noindex: Set the value of parameter ``name`` on a single PE within this region with the value of color ``value``. :param coord: Coordinate on which parameter will be set. :type coord: :py:class:`~cerebras.geometry.geometry.IntVector` :param color: Name of the parameter. :type color: ``str`` :param color: Color value of the parameter. :type color: :py:class:`Color` .. py:method:: set_param_all(name: str, value: int) :module: cerebras.sdk.runtime.sdkruntimepybind Set an unsigned integer parameter on all PEs of the region. :param name: Name of the parameter. :type name: ``str`` :param value: Unsigned integer value of the parameter. :type value: ``int`` .. py:method:: set_param_all(color: Color) :module: cerebras.sdk.runtime.sdkruntimepybind :noindex: Set a color parameter on all PEs of the region. :param color: Color value of the parameter. :type color: :py:class:`Color` .. py:method:: set_param_all(name: str, value: Color) :module: cerebras.sdk.runtime.sdkruntimepybind :noindex: Set the value of parameter ``name`` on all PEs of the region with the value of color ``value``. :param name: Name of the parameter. :type name: ``str`` :param color: Color value of the parameter. :type color: :py:class:`Color` .. py:method:: set_param_range(rect: IntRectangle, name: str, value: int) :module: cerebras.sdk.runtime.sdkruntimepybind Set an unsigned integer parameter on a contiguous rectangular subset of PEs within this region. :param rect: Rectangular subset of PEs within this region on which parameter will be set. :type rect: :py:class:`~cerebras.geometry.geometry.IntRectangle` :param name: Name of the parameter. :type name: ``str`` :param value: Unsigned integer value of the parameter. :type value: ``int`` .. py:method:: set_param_range(rect: IntRectangle, color: Color) :module: cerebras.sdk.runtime.sdkruntimepybind :noindex: Set a color parameter on a contiguous rectangular subset of PEs within this region. :param rect: Rectangular subset of PEs within this region on which parameter will be set. :type rect: :py:class:`~cerebras.geometry.geometry.IntRectangle` :param color: Color value of the parameter. :type color: :py:class:`Color` .. py:method:: set_param_range(rect: IntRectangle, name: str, value: Color) :module: cerebras.sdk.runtime.sdkruntimepybind :noindex: Set the value of parameter ``name`` on a contiguous rectangular subset of PEs within this region with the value of color ``value``. :param rect: Rectangular subset of PEs within this region on which parameter will be set. :type rect: :py:class:`~cerebras.geometry.geometry.IntRectangle` :param name: Name of the parameter. :type name: ``str`` :param color: Color value of the parameter. :type color: :py:class:`Color` .. py:method:: set_symbol_all(symbol: str, data: np.ndarray, width: int, height: int) :module: cerebras.sdk.runtime.sdkruntimepybind Given a symbol name ``symbol`` and ``data`` with a given 2D shape specified by ``width`` and ``height``, store ``data`` uniformly across the PEs of this code region. The 2D shape of ``data`` must be a multiple of the code region's dimensions or an error will be emitted. :param symbol: Name of the symbol. :type symbol: ``str`` :param data: 2D data array to be applied to the symbol. Data must be of type ``np.int32``, ``np.uint32``, ``np.float32``, ``np.int16``, or ``np.uint16``. :type data: ``np.ndarray`` :param width: Width of 2D data array. :type width: ``int`` :param height: Height of 2D data array. :type height: ``int`` Color ^^^^^ .. py:class:: Color(name: str, value: Optional[int] = None) :module: cerebras.sdk.runtime.sdkruntimepybind Bases: :class:`object` Represents a color with an optional user-specified physical value. Objects of this class can be used for routing and can also be used to set microcode parameter values. If a physical value is not provided, then a physical value will be allocated automatically by the compiler. :param name: Name given to the color. :type name: ``str`` :param value: Physical value given to the color. If not provided, then a value will be allocated automatically by the compiler. The maximum value is 23. :type value: ``Optional[int]`` .. py:method:: get_global_name() -> str :module: cerebras.sdk.runtime.sdkruntimepybind Returns the global name of the color. If this color is attached to a region, then the name returned takes the form ``region_name`` + ``_`` + ``name``. :returns: Global name of the color. :rtype: ``str`` .. py:method:: get_local_param_name() -> str :module: cerebras.sdk.runtime.sdkruntimepybind Returns the name of the color. :returns: Name of the color. :rtype: ``str`` .. py:method:: get_value() -> Optional[int] :module: cerebras.sdk.runtime.sdkruntimepybind Returns the color's physical value if one has been assigned. Otherwise, returns ``None``. :returns: Physical value of the color. :rtype: ``Optional[int]`` Edge ^^^^ .. py:class:: Edge :module: cerebras.sdk.runtime.sdkruntimepybind Bases: :class:`Enum` Represents edge positions along the boundary of a code region. :Values: * **TOP** * **BOTTOM** * **LEFT** * **RIGHT** EdgeRouteInfo ^^^^^^^^^^^^^ .. py:class:: EdgeRouteInfo :module: cerebras.sdk.runtime.sdkruntimepybind Bases: :class:`object` For a given code region, represents the routing positions in one of the region's four edges. SdkLayout ^^^^^^^^^ .. py:class:: SdkLayout(platform: SdkExecutionPlatform, **kwargs) :module: cerebras.sdk.runtime.sdkruntimepybind Bases: :class:`object` Specifies a program layout. This API allows the user to define retangular code regions, define color routing and switching, automatically allocate colors, and automatically route between code regions. :param platform: Execution platform specification. :type platform: :py:class:`SdkExecutionPlatform` :Keyword Arguments: * **msg_level** (``str``) -- Message logging output level. Available output levels are ``DEBUG``, ``INFO``, ``WARNING``, and ``ERROR``. Default value is ``WARNING``. .. py:method:: __init__(fabric_file: Union[pathlib.Path, str], **kwargs) :module: cerebras.sdk.runtime.sdkruntimepybind Constructor variant that takes a path to a fabric JSON file which is used to define the compile target and execution platform. Takes same kwargs as above. :param fabric_file: Path to a fabric JSON file. :type fabric_file: ``Union[pathlib.Path, str]`` .. py:method:: __init__(target: SdkTarget, **kwargs) :module: cerebras.sdk.runtime.sdkruntimepybind :noindex: Constructor variant that takes a target architecture. Takes same kwargs as above. :param target: Target architecture for compilation. :type target: :py:class:`SdkTarget` .. py:method:: compile(out_prefix: str) -> SdkCompileArtifacts :module: cerebras.sdk.runtime.sdkruntimepybind Compile this layout and produce artifacts with a given path prefix. :param out_prefix: Path to which artifacts will be produced. :type out_prefix: ``str`` .. py:method:: connect(tx: PortHandle, rx: PortHandle) :module: cerebras.sdk.runtime.sdkruntimepybind Automatically connect two ports. :param tx: Transmitting output data port which will send data to ``rx``. :type tx: :py:class:`PortHandle` :param rx: Receiving input data port which will receive data from ``tx``. :type rx: :py:class:`PortHandle` .. py:method:: create_code_region(source: str, name: str, width: int, height: int) -> CodeRegion :module: cerebras.sdk.runtime.sdkruntimepybind Create a code region. :param source: Path to code source file. :type source: ``str`` :param name: Name of the created code region. :type name: ``str`` :param width: Width in PEs of the created code region. :type width: ``int`` :param height: Height in PEs of the created code region. :type height: ``int`` :returns: The created code region object. :rtype: :py:class:`CodeRegion` .. py:method:: create_input_stream(port: PortHandle, io_loc: Optional[IntVector] = None, io_buffer_size: int = 1024) -> str :module: cerebras.sdk.runtime.sdkruntimepybind Sets up an input stream from the host to a 1-PE region at ``io_loc`` and then to input port ``port``. If ``io_loc`` is not provided, an available location will be automatically picked. ``io_buffer_size`` can be provided to specify the buffer size at ``io_loc``. Returns the name of the stream's port which can be used by the :py:class:`SdkRuntime` direct link API method :py:meth:`SdkRuntime.send`. :param port: Handle to input port. :type port: :py:class:`PortHandle` :param io_loc: PE location on wafer which receives input stream data. If not provided, a location is automatically chosen. :type io_loc: Optional[:py:class:`~cerebras.geometry.geometry.IntVector`] :param io_buffer_size: Buffer size allocated at ``io_loc``. Default is 1024. :type io_buffer_size: ``int`` :returns: Name of created input stream's port. :rtype: ``str`` .. py:method:: create_input_stream_from_loc(loc: IntVector, color: Color, prefix: str = "") -> str :module: cerebras.sdk.runtime.sdkruntimepybind Sets up an input stream from the host to ``loc`` on a given color ``color`` assuming that a code region is already defined at ``loc`` to consume the incoming data. An optional prefix can be provided to uniquely identify the stream in case of naming conflicts. Returns the name of the stream's port which can be used by the :py:class:`SdkRuntime` direct link API method :py:meth:`SdkRuntime.send`. :param loc: PE location of existing input port into which data will be streamed. :type loc: :py:class:`~cerebras.geometry.geometry.IntVector` :param color: Color on which stream transmits data. :type color: :py:class:`Color` :param prefix: Optional prefix prepended to created stream's name. :type prefix: ``str`` :returns: Name of created input stream's port. :rtype: ``str`` .. py:method:: create_output_stream(port: PortHandle, io_loc: IntVector = None, io_buffer_size: int = 1024) -> str :module: cerebras.sdk.runtime.sdkruntimepybind Sets up an output stream from output port ``port`` to a 1-PE region at ``io_loc`` and then to the host. If ``io_loc`` is not provided, an available location will be automatically picked. ``io_buffer_size`` can be provided to specify the buffer size at ``io_loc``. Returns the name of the stream's port which can be used by the :py:class:`SdkRuntime` direct link API methods :py:meth:`SdkRuntime.receive` and :py:meth:`SdkRuntime.receive_tofile`. :param port: Handle to output port. :type port: :py:class:`PortHandle` :param io_loc: PE location on wafer which send out output stream data. If not provided, a location is automatically chosen. :type io_loc: Optional[:py:class:`~cerebras.geometry.geometry.IntVector`] :param io_buffer_size: Buffer size allocated at ``io_loc``. Default is 1024. :type io_buffer_size: ``int`` :returns: Name of created output stream's port. :rtype: ``str`` .. py:method:: create_output_stream_from_loc(loc: IntVector, color: Color, prefix: str = "") -> str :module: cerebras.sdk.runtime.sdkruntimepybind Sets up an output stream to the host from ``loc`` on a given color ``color`` assuming that a code region is already defined at ``loc`` to produce the outgoing data. An optional prefix can be provided to uniquely identify the stream in case of naming conflicts. Returns the name of the stream's port which can be used by the :py:class:`SdkRuntime` direct link API methods :py:meth:`SdkRuntime.receive` and :py:meth:`SdkRuntime.receive_tofile`. :param loc: PE location of existing output port from which data will be streamed. :type loc: :py:class:`~cerebras.geometry.geometry.IntVector` :param color: Color on which stream transmits data. :type color: :py:class:`Color` :param prefix: Optional prefix prepended to created stream's name. :type prefix: ``str`` :returns: Name of created output stream's port. :rtype: ``str`` .. py:method:: hstack(children: List[CodeRegion]) -> int :module: cerebras.sdk.runtime.sdkruntimepybind Place child code regions horizontally and relative to the first child in the given list, and return the width of the resulting code region. :param children: Code regions to be placed. :type children: List[:py:class:`CodeRegion`] :returns: Width of resulting code region. :type: ``int`` .. py:method:: hstack(children: List[CodeRegion], origin: IntVector) -> int :module: cerebras.sdk.runtime.sdkruntimepybind :noindex: Place child code regions horizontally and relative to a specified origin, and return the width of the resulting code region. :param children: Code regions to be placed. :type children: List[:py:class:`CodeRegion`] :param origin: PE coordinate which serves as origin for placed code regions. :type origin: :py:class:`~cerebras.geometry.geometry.IntVector` :returns: Width of resulting code region. :type: ``int`` .. py:method:: vstack(children: List[CodeRegion]) -> int :module: cerebras.sdk.runtime.sdkruntimepybind Place child code regions vertically and relative to the first child in the given list, and return the height of the resulting code region. :param children: Code regions to be placed. :type children: List[:py:class:`CodeRegion`] :returns: Height of resulting code region. :type: ``int`` .. py:method:: vstack(children: List[CodeRegion], origin: IntVector) -> int :module: cerebras.sdk.runtime.sdkruntimepybind :noindex: Place child code regions vertically and relative to a specified origin, and return the height of the resulting code region. :param children: Code regions to be placed. :type children: List[:py:class:`CodeRegion`] :param origin: PE coordinate which serves as origin for placed code regions. :type origin: :py:class:`~cerebras.geometry.geometry.IntVector` :returns: Height of resulting code region. :type: ``int`` PortHandle ^^^^^^^^^^ .. py:class:: PortHandle :module: cerebras.sdk.runtime.sdkruntimepybind Bases: :class:`object` Handle to a program input or output data port. Route ^^^^^ .. py:class:: Route :module: cerebras.sdk.runtime.sdkruntimepybind Bases: :class:`Enum` Represents route directions. :Values: * **RAMP** * **EAST** * **WEST** * **NORTH** * **SOUTH** RoutingPosition ^^^^^^^^^^^^^^^ .. py:class:: RoutingPosition :module: cerebras.sdk.runtime.sdkruntimepybind Bases: :class:`object` Represents a single routing position, which can consist of one or more route values for input and one or more route values for output. .. py:method:: set_input(routes: List[Route]) :module: cerebras.sdk.runtime.sdkruntimepybind Set a list of routes as the input route position. :param routes: List of routes to be set as the input route position. :type routes: List[:py:class:`Route`] .. py:method:: set_output(routes: List[Route]) :module: cerebras.sdk.runtime.sdkruntimepybind Set a list of routes as the output route position. :param routes: List of routes to be set as the output route position. :type routes: List[:py:class:`Route`] .. py:method:: add_input(route: Route) :module: cerebras.sdk.runtime.sdkruntimepybind Add a route to the input route position. :param route: Route to be added to the input route position. :type route: :py:class:`Route` .. py:method:: add_output(route: Route) :module: cerebras.sdk.runtime.sdkruntimepybind Add a route to the output route position. :param route: Route to be added to the output route position. :type route: :py:class:`Route` .. py:method:: get_input() -> List[Route] :module: cerebras.sdk.runtime.sdkruntimepybind For this routing position object, return a list of all input routes in the input route position. :returns: List of all routes in the input route position. :rtype: List[:py:class:`Route`] .. py:method:: get_output() -> List[Route] :module: cerebras.sdk.runtime.sdkruntimepybind For this routing position object, return a list of all output routes in the output route position. :returns: List of all routes in the output route position. :rtype: List[:py:class:`Route`] get_edge_routing ^^^^^^^^^^^^^^^^ .. py:function:: get_edge_routing(edge: Edge, routes: List[RoutingPosition]) -> EdgeRouteInfo :module: cerebras.sdk.runtime.sdkruntimepybind Construct an edge routing info object from a given edge and routing positions. :param edge: Edge of code region. :type edge: :py:class:`Edge` :param routes: List of routing positions to be applied to edge. :type routes: List[:py:class:`RoutingPosition`] :returns: Object containing edge routing info. :rtype: :py:class:`EdgeRouteInfo` Geometry ^^^^^^^^ .. py:module:: cerebras.geometry.geometry .. py:class:: IntRectangle(origin: IntVector, dims: IntVector) :module: cerebras.geometry.geometry Bases: :class:`object` Defines a rectangle of values. :param origin: Origin of rectangle's northwest corner. :type origin: :py:class:`IntVector` :param dims: Width and height of rectangle. :type dims: :py:class:`IntVector` .. py:class:: IntVector(x: int, y: int) :module: cerebras.geometry.geometry Bases: :class:`object` Wraps a tuple of two integer values, often used to specify coordinates or offsets. :param x: x-coordinate :type x: ``int`` :param y: y-coordinate :type y: ``int``