Skip to main content

/

Docs

Nightly
v24.5
Log in

Mojo struct

Symbol

Represents a symbolic value within a Graph.

A Symbol can represent the output of a node, the arguments of a Graph (as seen from within its body), and more generally any symbolic value available within the Graph. Other nodes receive Symbol values as inputs to form a computation graph.

A Symbol may also refer to an existing input or output of a node, and you can change them, such as by swapping a new Symbol.

Conceptually, a Symbol is the equivalent of a variable in Mojo. A Symbol can also be thought of as the end of an edge in the dataflow graph (the other end being one use of that symbol).

Similar to a regular variable, a Symbol has a data type.

Note: All the methods in this type are documented as "Creates foo". This is a shorthand notation for "Adds a node representing an op that returns foo".

Fields​

  • ​handle (Value): A handle to this Symbol's internal representation.

Implemented traits​

AnyType, CollectionElement, Copyable, Movable, Stringable, Writable

Methods​

__getitem__​

__getitem__(self, i: Variant[Symbol, Int], axis: Int = 0, keep_dims: Bool = 0) -> Self

Symbolic slicing - indexes a value by a single index.

Uses the mo.slice op.

Args:

  • ​i (Variant[Symbol, Int]): The index value.
  • ​axis (Int): The axis to index at.
  • ​keep_dims (Bool): Returns a tensor with the same rank as the input if set.

Returns:

The slicing result.

__getitem__(self, *s: SymbolicSlice, *, out_dims: List[Dim]) -> Self

Range-based slicing.

Uses the mo.slice op. Slicing along multiple dimensions is supported.

Args:

  • ​*s (SymbolicSlice): The slice values. The ith SymbolicSlice in the variadic list represents the begin:end:step triple for axis i.
  • ​out_dims (List[Dim]): The expected output dimensions returned by slicing. These will be assert at graph execution time to be correct.

Returns:

The slicing result.

__getitem__(self, *slices: Slice, *, out_dims: List[Dim] = List()) -> Self

Shorthand for symbolic slicing with Int ranges.

Args:

  • ​*slices (Slice): The slice values for each dimension respectively. If fewer than rank() slices are provided, the remaining dimensions will be trivially sliced. In other words s[:, :2] is equivalent to s[:, :2, :, :] for a tensor of rank 4. Currently indexing and slicing may not be mixed.
  • ​out_dims (List[Dim]): The expected output dimensions returned by slicing. These will be assert at graph execution time to be correct.

Returns:

The slicing result.

Raises:

An exception if out_dims is empty and can't be calculated at graph build time.

__neg__​

__neg__(self) -> Self

Numerical negative, element-wise.

Returns:

The operation result.

__add__​

__add__(self, rhs: Self) -> Self

Element-wise addition.

Args:

  • ​rhs (Self): The right hand side operand.

Returns:

The operation result.

__add__(self, rhs: Int) -> Self

Element-wise addition by an Int literal.

Args:

  • ​rhs (Int): The right hand side operand.

Returns:

The operation result.

__add__(self, rhs: SIMD[float64, 1]) -> Self

Element-wise addition by a Float64.

Args:

  • ​rhs (SIMD[float64, 1]): The right hand side operand.

Returns:

The operation result.

__sub__​

__sub__(self, rhs: Self) -> Self

Element-wise subtraction.

Args:

  • ​rhs (Self): The right hand side operand.

Returns:

The operation result.

__sub__(self, rhs: Int) -> Self

Element-wise subtraction by an Int literal.

Args:

  • ​rhs (Int): The right hand side operand.

Returns:

The operation result.

__sub__(self, rhs: SIMD[float64, 1]) -> Self

Element-wise subtraction by a Float64.

Args:

  • ​rhs (SIMD[float64, 1]): The right hand side operand.

Returns:

The operation result.

__mul__​

__mul__(self, rhs: Self) -> Self

Element-wise multiplication.

Args:

  • ​rhs (Self): The right hand side operand.

Returns:

The operation result.

__mul__(self, rhs: Int) -> Self

Element-wise multiplication by an Int literal.

Args:

  • ​rhs (Int): The right hand side operand.

Returns:

The operation result.

__mul__(self, rhs: SIMD[float64, 1]) -> Self

Element-wise multiplication by a Float64.

Args:

  • ​rhs (SIMD[float64, 1]): The right hand side operand.

Returns:

The operation result.

__matmul__​

__matmul__(self, rhs: Self) -> Self

Matrix multiplication.

Args:

  • ​rhs (Self): The right hand side operand.

Returns:

The operation result.

__truediv__​

__truediv__(self, rhs: Self) -> Self

Element-wise division.

Args:

  • ​rhs (Self): The right hand side operand.

Returns:

The operation result.

__truediv__(self, rhs: Int) -> Self

Element-wise division by an Int literal.

Args:

  • ​rhs (Int): The right hand side operand.

Returns:

The operation result.

__truediv__(self, rhs: SIMD[float64, 1]) -> Self

Element-wise division by a Float64.

Args:

  • ​rhs (SIMD[float64, 1]): The right hand side operand.

Returns:

The operation result.

__pow__​

__pow__(self, rhs: Self) -> Self

Element-wise raise to power.

Args:

  • ​rhs (Self): The right hand side operand.

Returns:

The operation result.

__pow__(self, rhs: Int) -> Self

Element-wise raise to power by an Int literal.

Args:

  • ​rhs (Int): The right hand side operand.

Returns:

The operation result.

__pow__(self, rhs: SIMD[float64, 1]) -> Self

Element-wise raise to power by a Float64.

Args:

  • ​rhs (SIMD[float64, 1]): The right hand side operand.

Returns:

The operation result.

__radd__​

__radd__(self, rhs: Self) -> Self

Element-wise addition.

Args:

  • ​rhs (Self): The right hand side operand.

Returns:

The operation result.

__radd__(self, rhs: Int) -> Self

Element-wise addition by an Int literal.

Args:

  • ​rhs (Int): The right hand side operand.

Returns:

The operation result.

__radd__(self, rhs: SIMD[float64, 1]) -> Self

Element-wise addition by a Float64.

Args:

  • ​rhs (SIMD[float64, 1]): The right hand side operand.

Returns:

The operation result.

__rsub__​

__rsub__(self, rhs: Self) -> Self

Element-wise subtraction.

Args:

  • ​rhs (Self): The right hand side operand.

Returns:

The operation result.

__rsub__(self, rhs: Int) -> Self

Element-wise subtraction by an Int literal.

Args:

  • ​rhs (Int): The right hand side operand.

Returns:

The operation result.

__rsub__(self, rhs: SIMD[float64, 1]) -> Self

Element-wise subtraction by a Float64.

Args:

  • ​rhs (SIMD[float64, 1]): The right hand side operand.

Returns:

The operation result.

__rmul__​

__rmul__(self, rhs: Self) -> Self

Element-wise multiplication.

Args:

  • ​rhs (Self): The right hand side operand.

Returns:

The operation result.

__rmul__(self, rhs: Int) -> Self

Element-wise multiplication by an Int literal.

Args:

  • ​rhs (Int): The right hand side operand.

Returns:

The operation result.

__rmul__(self, rhs: SIMD[float64, 1]) -> Self

Element-wise multiplication by a Float64.

Args:

  • ​rhs (SIMD[float64, 1]): The right hand side operand.

Returns:

The operation result.

__rtruediv__​

__rtruediv__(self, rhs: Self) -> Self

Element-wise division.

Args:

  • ​rhs (Self): The right hand side operand.

Returns:

The operation result.

__rtruediv__(self, rhs: Int) -> Self

Element-wise division by an Int literal.

Args:

  • ​rhs (Int): The right hand side operand.

Returns:

The operation result.

__rtruediv__(self, rhs: SIMD[float64, 1]) -> Self

Element-wise division by a Float64.

Args:

  • ​rhs (SIMD[float64, 1]): The right hand side operand.

Returns:

The operation result.

__rpow__​

__rpow__(self, rhs: Self) -> Self

Element-wise raise to power.

Args:

  • ​rhs (Self): The right hand side operand.

Returns:

The operation result.

__rpow__(self, rhs: Int) -> Self

Element-wise raise to power by an Int literal.

Args:

  • ​rhs (Int): The right hand side operand.

Returns:

The operation result.

__rpow__(self, rhs: SIMD[float64, 1]) -> Self

Element-wise raise to power by a Float64.

Args:

  • ​rhs (SIMD[float64, 1]): The right hand side operand.

Returns:

The operation result.

graph​

graph(self) -> Graph

Returns the Graph owning this Symbol.

Returns:

The parent Graph.

type​

type(self) -> Type

Returns this Symbol's type.

Returns:

The Symbol's type.

tensor_type​

tensor_type(self) -> TensorType

Returns this Symbol's type, as TensorType.

Implicitly asserts that the type is indeed TensorType, and raises an error otherwise.

Returns:

The tensor type of this Symbol.

shape​

shape(self) -> List[Dim]

Returns this Symbol's tensor shape, as List[Dim].

Implicitly asserts that the type is indeed TensorType, and raises an error otherwise.

Returns:

The tensor shape of this Symbol.

__str__​

__str__(self) -> String

Returns a String representation of this Symbol.

The representation uses an internal MLIR Assembly format, and typically shows the node that outputs this Symbol. Its structure is subject to change without notice, and should not be used for serialization. For debugging purposes only.

Returns:

A textual representation of this Symbol.

write_to​

write_to[W: Writer](self, inout writer: W)

Formats this symbol to the provided Writer.

Parameters:

  • ​W (Writer): A type conforming to the Writable trait.

Args:

  • ​writer (W): The object to write to.

rebind​

rebind(self, *dims: Dim) -> Self

rebind(self, dims: List[Dim]) -> Self

reshape​

reshape(self) -> Self

reshape(self, *dims: Int) -> Self

Reshapes this Symbol.

Uses the mo.reshape op. Requires the symbol to be a TensorType.

Args:

  • ​*dims (Int): The new dimensions.

Returns:

A new Symbol that has the given shape.

reshape(self, *dims: Dim) -> Self

Reshapes this Symbol.

Uses the mo.reshape op. Requires the symbol to be a TensorType.

Args:

  • ​*dims (Dim): The new dimensions.

Returns:

A new Symbol that has the given shape.

reshape(self, *dims: Variant[Symbol, Int]) -> Self

Reshapes this Symbol.

Uses the mo.reshape op. Requires the symbol to be a TensorType.

Args:

  • ​*dims (Variant[Symbol, Int]): The new dimensions.

Returns:

A new Symbol that has the given shape.

swapaxes​

swapaxes(self, axis1: Int, axis2: Int) -> Self

Interchanges two axes of this Symbol.

Uses the mo.transpose op. Negative values are allowed, and represent the axis number counting from the last.

Args:

  • ​axis1 (Int): One of the axes to swap.
  • ​axis2 (Int): The other axis.

Returns:

A new transposed Symbol.

broadcast_to​

broadcast_to(self, *dims: Dim) -> Self

Broadcasts this Symbol to the specified dims.

Uses the mo.broadcast_to op. Requires the symbol to be a TensorType.

Args:

  • ​*dims (Dim): The target dimensions.

Returns:

A new Symbol that is broadcast to the given shape.

broadcast_to(self, shape: List[Dim], location: Optional[_SourceLocation] = Optional(#kgen.none)) -> Self

Broadcasts this Symbol to the specified shape.

Uses the mo.broadcast_to op. Requires the symbol to be a TensorType.

Args:

  • ​shape (List[Dim]): The target shape.
  • ​location (Optional[_SourceLocation]): An optional location for a more specific error message.

Returns:

A new Symbol that is broadcast to the given shape.

print​

print(self, label: String = String("debug_tensor"))

Prints this Symbol's value at runtime.

This uses mo.debug.tensor.unsafe.print to enable printing the runtime value that this Symbol represents, at grpah execution time.

Args:

  • ​label (String): A label to accompany the printout.

insert_transformation​

insert_transformation(self, transform: fn(Symbol) raises -> Symbol)

Inserts nodes in between this Symbol and all its current uses.

This enables inserting ops in between this Symbol and all its uses, for example to modify an existing Graph.

Note: The function is called exactly once, even if self has no uses.

Args:

  • ​transform (fn(Symbol) raises -> Symbol): A function that creates a unary subgraph (single input, single output) and returns the result of the final node. The function will be called with this Symbol, and its return value will replace all of its uses.