SdkLayout API Reference - Cerebras SDK docs

This API is part of the sdkruntimepybind module documented in the SdkRuntime API Reference.

Imports

The classes and enums documented on this page live in cerebras.sdk.runtime.sdkruntimepybind. The canonical import block for an SdkLayout-based host program is:

from cerebras.sdk.runtime.sdkruntimepybind import (
    SdkLayout,
    SdkTarget,
    Color,
    Route,
    Edge,
    RoutingPosition,
)

For host programs that mix SdkLayout with SdkRuntime (the typical case), import SdkRuntime and SdkCompileArtifacts from the same module:

from cerebras.sdk.runtime.sdkruntimepybind import (
    SdkRuntime,
    SdkCompileArtifacts,
)

CodeRegion

class cerebras.sdk.runtime.sdkruntimepybind.CodeRegion

Bases: object

Specifies a code region.

Show content

color(name: str) → Color

Create and return a new color that is scoped within a region.

Show Parameters

name (str)

Name to be assigned to the color.

Returns: A new color scoped within this region.

Return type: Color

color(name: str, value: int) → Color

Create and return a new color (with a value) that is scoped within a region.

Show Parameters

name (str)

Name to be assigned to the color.

value (int)

Value to be assigned to the color.

Returns: A new color scoped within this region.

Return type: Color

create_input_port(color: Color, edge: Edge, routes: List[RoutingPosition], data_size: int, prefix: str = '') → PortHandle

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.

Show Parameters

color (Color)

Color of the input port.

edge (Edge)

Edge on which to create the input port.

routes (List[RoutingPosition])

List of output routes for the input port.

data_size (int)

The size of the port’s data, used to verify port compatibility.

prefix (str)

Optional prefix to port’s name, which allows creation of unique ports with the same color.

Returns: Handle to the created input port.

Return type: PortHandle

create_output_port(color: Color, edge: Edge, routes: List[RoutingPosition], data_size: int, prefix: str = '') → PortHandle

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.

Show Parameters

color (Color)

Color of the output port.

edge (Edge)

Edge on which to create the output port.

routes (List[RoutingPosition])

List of input routes for the output port.

data_size (int)

The size of the port’s data, used to verify port compatibility.

prefix (str)

Optional prefix to port’s name, which allows creation of unique ports with the same color.

Returns: Handle to the created output port.

Return type: PortHandle

paint(coord: IntVector, color: Color, routes: List[RoutingPosition])

Set the routing for a given color on a single PE within this region.

Show Parameters

coord (IntVector)

Coordinate on which color will be painted.

color (Color)

Color to be painted on this coordinate.

routes (List[RoutingPosition])

List of routing positions which will be applied to this color.

paint_all(color: Color, routes: List[RoutingPosition])

Set the routing for a given color on all PEs of the region.

Show Parameters

color (Color)

Color to be painted on this region.

routes (List[RoutingPosition])

List of routing positions which will be applied to this color.

paint_all(color: Color, routes: List[RoutingPosition], edge_routes: List[EdgeRouteInfo])

Set the routing for a given color on all PEs of the region with special routing on one or all region edges.

Show Parameters

color (Color)

Color to be painted on this region.

routes (List[RoutingPosition])

List of routing positions which will be applied to this color.

edge_routes (List[EdgeRouteInfo])

List of routing positions to be applied to this color on the region’s edges.

paint_range(rect: IntRectangle, color: Color, routes: List[RoutingPosition])

Set the routing for a given color on a contiguous rectangular subset of PEs within this region.

Show Parameters

rect (IntRectangle)

Rectangular subset of PEs within this region on which color will be painted.

color (Color)

Color to be painted on this rectangle.

routes (List[RoutingPosition])

List of routing positions which will be applied to this color.

place(x: int, y: int)

Place code region at specific coordinates (x, y).

Show Parameters

x (int)

x-coordinate at which core region will be placed.

y (int)

y-coordinate at which core region will be placed.

set_param(coord: IntVector, name: str, value: int)

Set an unsigned integer parameter on a single PE within this region.

Show Parameters

coord (IntVector)

Coordinate on which parameter will be set.

name (str)

Name of the parameter.

value (int)

Unsigned integer value of the parameter.

set_param(coord: IntVector, color: Color)

Set a color parameter on a single PE within this region.

Show Parameters

coord (IntVector)

Coordinate on which parameter will be set.

color (Color)

Color value of the parameter.

set_param(coord: IntVector, name: str, value: Color)

Set the value of parameter name on a single PE within this region with the value of color value.

Show Parameters

coord (IntVector)

Coordinate on which parameter will be set.

name (str)

Name of the parameter.

color (Color)

Color value of the parameter.

set_param_all(name: str, value: int)

Set an unsigned integer parameter on all PEs of the region.

Show Parameters

name (str)

Name of the parameter.

value (int)

Unsigned integer value of the parameter.

set_param_all(color: Color)

Set a color parameter on all PEs of the region.

Show Parameters

color (Color)

Color value of the parameter.

set_param_all(name: str, value: Color)

Set the value of parameter name on all PEs of the region with the value of color value.

Show Parameters

name (str)

Name of the parameter.

color (Color)

Color value of the parameter.

set_param_range(rect: IntRectangle, name: str, value: int)

Set an unsigned integer parameter on a contiguous rectangular subset of PEs within this region.

Show Parameters

rect (IntRectangle)

Rectangular subset of PEs within this region on which parameter will be set.

name (str)

Name of the parameter.

value (int)

Unsigned integer value of the parameter.

set_param_range(rect: IntRectangle, color: Color)

Set a color parameter on a contiguous rectangular subset of PEs within this region.

Show Parameters

rect (IntRectangle)

Rectangular subset of PEs within this region on which parameter will be set.

color (Color)

Color value of the parameter.

set_param_range(rect: IntRectangle, name: str, value: Color)

Set the value of parameter name on a contiguous rectangular subset of PEs within this region with the value of color value.

Show Parameters

rect (IntRectangle)

Rectangular subset of PEs within this region on which parameter will be set.

name (str)

Name of the parameter.

color (Color)

Color value of the parameter.

set_symbol_all(symbol: str, data: np.ndarray, width: int, height: int)

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.

Show Parameters

symbol (str)

Name of the symbol.

data (np.ndarray)

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.

width (int)

Width of 2D data array.

height (int)

Height of 2D data array.

Color

class cerebras.sdk.runtime.sdkruntimepybind.Color(name: str, value: Optional[int] = None)

Bases: 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.

Show content

Show Parameters

name (str)

Name given to the color.

value (Optional[int])

Physical value given to the color. If not provided, then a value will be allocated automatically by the compiler. The maximum value is 23.

get_global_name() → str

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.

Return type: str

get_local_param_name() → str

Returns the name of the color.

Returns: Name of the color.

Return type: str

get_value() → Optional[int]

Returns the color’s physical value if one has been assigned. Otherwise, returns None.

Returns: Physical value of the color.

Return type: Optional[int]

Edge

class cerebras.sdk.runtime.sdkruntimepybind.Edge

Bases: Enum

Represents edge positions along the boundary of a code region.

Values:

TOP

BOTTOM

LEFT

RIGHT

EdgeRouteInfo

class cerebras.sdk.runtime.sdkruntimepybind.EdgeRouteInfo

Bases: object

For a given code region, represents the routing positions in one of the region’s four edges.

FP16TYPE

class cerebras.sdk.runtime.sdkruntimepybind.FP16TYPE

Bases: Enum

Specifies the 16-bit floating point format for compilation.

Values:

F16: IEEE 754 half-precision (f16)

BF16: Brain floating point (bf16)

CB16: Cerebras 16-bit floating point (cb16)

SdkLayout

class cerebras.sdk.runtime.sdkruntimepybind.SdkLayout(platform: SdkExecutionPlatform, **kwargs)

Bases: object

Specifies a program layout. This API allows the user to define rectangular code regions, define color routing and switching, automatically allocate colors, and automatically route between code regions.

Show content

Show Parameters

platform (SdkExecutionPlatform)

Execution platform specification.

Show Keyword Arguments

msg_level (str)

Message logging output level. Available output levels are DEBUG, INFO, WARNING, and ERROR. Default value is WARNING.

__init__(path: Union[pathlib.Path, str], **kwargs)

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.

Show Parameters

path (Union[pathlib.Path, str])

Path to a fabric JSON file.

__init__(target: SdkTarget, **kwargs)

Constructor variant that takes a target architecture. Takes same kwargs as above.

Show Parameters

target (SdkTarget)

Target architecture for compilation.

compile(out_prefix: str, libs: List[str] = [], cslc_prefix: str = "", save_port_map: bool = False, f16_type: FP16TYPE = FP16TYPE.F16) → SdkCompileArtifacts

Compile this layout and produce artifacts with a given path prefix.

Show Parameters

out_prefix (str)

Path to which artifacts will be produced.

libs (List[str])

List of additional library search paths for the compiler.

cslc_prefix (str)

Path prefix for the CSL compiler. If empty, the default compiler is used.

save_port_map (bool)

If True, saves the port mapping to a file.

f16_type (FP16TYPE)

Specifies the 16-bit floating point format for compilation.

Returns: Compilation artifacts.

Return type: SdkCompileArtifacts

connect(tx: PortHandle, rx: PortHandle)

Automatically connect two ports.

Show Parameters

tx (PortHandle)

Transmitting output data port which will send data to rx.

rx (PortHandle)

Receiving input data port which will receive data from tx.

create_code_region(source: str, name: str, width: int, height: int) → CodeRegion

Create a code region.

Show Parameters

source (str)

Path to code source file.

name (str)

Name of the created code region.

width (int)

Width in PEs of the created code region.

height (int)

Height in PEs of the created code region.

Returns: The created code region object.

Return type: CodeRegion

create_input_stream(port: PortHandle, io_loc: Optional[IntVector] = None, io_buffer_size: int = 1024) → str

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 SdkRuntime direct link API method SdkRuntime.send().

Show Parameters

port (PortHandle)

Handle to input port.

io_loc (Optional[IntVector])

PE location on wafer which receives input stream data. If not provided, a location is automatically chosen.

io_buffer_size (int)

Buffer size allocated at io_loc. Default is 1024.

Returns: Name of created input stream’s port.

Return type: str

create_input_stream_from_loc(loc: IntVector, color: Color, prefix: str = '') → str

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 SdkRuntime direct link API method SdkRuntime.send().

Show Parameters

loc (IntVector)

PE location of existing input port into which data will be streamed.

color (Color)

Color on which stream transmits data.

prefix (str)

Optional prefix prepended to created stream’s name.

Returns: Name of created input stream’s port.

Return type: str

create_output_stream(port: PortHandle, io_loc: IntVector = None, io_buffer_size: int = 1024) → str

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 SdkRuntime direct link API methods SdkRuntime.receive() and SdkRuntime.receive_tofile().

Show Parameters

port (PortHandle)

Handle to output port.

io_loc (Optional[IntVector])

PE location on wafer which sends out output stream data. If not provided, a location is automatically chosen.

io_buffer_size (int)

Buffer size allocated at io_loc. Default is 1024.

Returns: Name of created output stream’s port.

Return type: str

create_output_stream_from_loc(loc: IntVector, color: Color, prefix: str = '') → str

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 SdkRuntime direct link API methods SdkRuntime.receive() and SdkRuntime.receive_tofile().

Show Parameters

loc (IntVector)

PE location of existing output port from which data will be streamed.

color (Color)

Color on which stream transmits data.

prefix (str)

Optional prefix prepended to created stream’s name.

Returns: Name of created output stream’s port.

Return type: str

hstack(children: List[CodeRegion]) → int

Place child code regions horizontally and relative to the first child in the given list, and return the width of the resulting code region.

Show Parameters

children (List[CodeRegion])

Code regions to be placed.

Returns: Width of resulting code region.

Return type: int

hstack(children: List[CodeRegion], origin: IntVector) → int

Place child code regions horizontally and relative to a specified origin, and return the width of the resulting code region.

Show Parameters

children (List[CodeRegion])

Code regions to be placed.

origin (IntVector)

PE coordinate which serves as origin for placed code regions.

Returns: Width of resulting code region.

Return type: int

vstack(children: List[CodeRegion]) → int

Place child code regions vertically and relative to the first child in the given list, and return the height of the resulting code region.

Show Parameters

children (List[CodeRegion])

Code regions to be placed.

Returns: Height of resulting code region.

Return type: int

vstack(children: List[CodeRegion], origin: IntVector) → int

Place child code regions vertically and relative to a specified origin, and return the height of the resulting code region.

Show Parameters

children (List[CodeRegion])

Code regions to be placed.

origin (IntVector)

PE coordinate which serves as origin for placed code regions.

Returns: Height of resulting code region.

Return type: int

PortHandle

class cerebras.sdk.runtime.sdkruntimepybind.PortHandle

Bases: object

Handle to a program input or output data port.

Route

class cerebras.sdk.runtime.sdkruntimepybind.Route

Bases: Enum

Represents route directions.

Values:

RAMP

EAST

WEST

NORTH

SOUTH

RoutingPosition

class cerebras.sdk.runtime.sdkruntimepybind.RoutingPosition

Bases: 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.

Show content

set_input(routes: List[Route])

Set a list of routes as the input route position.

Show Parameters

routes (List[Route])

List of routes to be set as the input route position.

set_output(routes: List[Route])

Set a list of routes as the output route position.

Show Parameters

routes (List[Route])

List of routes to be set as the output route position.

add_input(route: Route)

Add a route to the input route position.

Show Parameters

route (Route)

Route to be added to the input route position.

add_output(route: Route)

Add a route to the output route position.

Show Parameters

route (Route)

Route to be added to the output route position.

get_input() → List[Route]

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.

Return type: List[Route]

get_output() → List[Route]

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.

Return type: List[Route]

get_edge_routing

cerebras.sdk.runtime.sdkruntimepybind.get_edge_routing(edge: Edge, routes: List[RoutingPosition]) → EdgeRouteInfo

Construct an edge routing info object from a given edge and routing positions.

Show Parameters

edge (Edge)

Edge of code region.

routes (List[RoutingPosition])

List of routing positions to be applied to edge.

Returns: Object containing edge routing info.

Return type: EdgeRouteInfo

Geometry

IntRectangle

class cerebras.geometry.geometry.IntRectangle(origin: IntVector, dims: IntVector)

Bases: object

Defines a rectangle of values.

Show Parameters

origin (IntVector)

Origin of rectangle’s northwest corner.

dims (IntVector)

Width and height of rectangle.

IntVector

class cerebras.geometry.geometry.IntVector(x: int, y: int)

Bases: object

Wraps a tuple of two integer values, often used to specify coordinates or offsets.

Show Parameters

x (int)

x-coordinate

y (int)

y-coordinate

​Imports

​CodeRegion

​Color

​Edge

​EdgeRouteInfo

​FP16TYPE

​SdkLayout

​PortHandle

​Route

​RoutingPosition

​get_edge_routing

​Geometry

​IntRectangle

​IntVector

Imports

CodeRegion

Color

Edge

EdgeRouteInfo

FP16TYPE

SdkLayout

PortHandle

Route

RoutingPosition

get_edge_routing

Geometry

IntRectangle

IntVector