Mojo struct
RuntimeTuple
@register_passable(trivial)
struct RuntimeTuple[origin: ImmutableOrigin, //, S: IntTuple[origin] = IntTuple(-1), /, *, element_bitwidth: Int = bitwidthof[AnyTrivialRegType,__mlir_type.!kgen.target](), unsigned: Bool = False]
A struct representing tuple-like data with compile-time and runtime elements.
RuntimeTuple combines static (compile-time) and dynamic (runtime) handling of tuple-like data structures, typically used for tensor shapes, indices, and coordinates in high-performance computing contexts.
This struct is optimized for parallel execution and hardware acceleration, allowing efficient manipulation of multi-dimensional data. It supports both known compile-time values and runtime-determined values.
Parameters
- origin (
ImmutableOrigin): The origin corresponding to theIntTuple. - S (
IntTuple[origin]):IntTuplewith compile-time known values (orUNKNOWN_VALUEfor runtime values). - element_bitwidth (
Int): Bit width for the underlying numeric type (default: bitwidth of Int). - unsigned (
Bool): Whether to use unsigned integer types (default: False).
Aliases
int_type = _get_returned_type[::Int,::Bool](): The numeric data type used for elements in this RuntimeTuple, based on element_bitwidth and unsigned parameters.scalar_length = len[::Sized](flatten[::Origin[::Bool(S)): The total number of scalar elements in this RuntimeTuple after flattening nested tuples.
Fields
- value (
Index[len[::Sized](flatten[::Origin[::Bool(S)), element_bitwidth=element_bitwidth, unsigned=unsigned]): Storage for the actual tuple values, implemented as an IndexList with the appropriate size and element type.
Implemented traits
AnyType,
CollectionElement,
Copyable,
Intable,
Movable,
Sized,
Stringable,
UnknownDestructibility,
Writable
Methods
__init__
__init__() -> Self
Initialize a RuntimeTuple with default values.
For dimensions with known compile-time values in S, uses those values. For unknown dimensions, initializes them to UNKNOWN_VALUE.
@implicit
__init__(*values: Int) -> Self
Initialize a RuntimeTuple with the provided values.
Args:
- *values (
Int): Variadic number of integer values to initialize the tuple with.
@implicit
__init__[l: Int](values: Index[l, element_bitwidth=element_bitwidth, unsigned=unsigned]) -> Self
Initialize a RuntimeTuple from an IndexList.
Parameters:
- l (
Int): Compile-time length of the inputIndexList.
Args:
- values (
Index[l, element_bitwidth=element_bitwidth, unsigned=unsigned]):IndexListto initialize from. Must have same length as theRuntimeTuple. The values will be cast to the appropriate element type if needed.
__getitem__
__getitem__[i: Int](self) -> RuntimeTuple[S.__getitem__(i), element_bitwidth=element_bitwidth, unsigned=unsigned]
Retrieves the element at the specified index in the tuple.
This method provides array-like indexing for RuntimeTuple, allowing access to individual elements or sub-tuples. It handles the internal offset calculation to access the correct elements in the flattened storage array.
Parameters:
- i (
Int): The index of the element to retrieve.
Returns:
A new RuntimeTuple containing the element or sub-tuple at the specified index.
__setitem__
__setitem__[i: Int](mut self, val: SIMD[_get_returned_type[::Int,::Bool](), 1])
Sets the value of the element at the specified index in the tuple.
This method enables array-like assignment for RuntimeTuple elements, handling the internal offset calculation to modify the correct element in the flattened storage array.
Parameters:
- i (
Int): The index of the element to modify.
Args:
- val (
SIMD[_get_returned_type[::Int,::Bool](), 1]): The new value to assign to the element.
offset_until
static offset_until[i: Int]() -> Int
Calculates the offset in the flattened value array for a given tuple index.
This method computes the sum of lengths of all flattened subtuple elements that come before the specified index, which is used for indexing into the internal storage.
Parameters:
- i (
Int): The tuple index to calculate the offset for.
Returns:
The offset in the flattened array where the i-th element begins.
get_int
get_int(self) -> SIMD[_get_returned_type[::Int,::Bool](), 1]
Returns the integer value of this RuntimeTuple.
For tuples with a known compile-time value, returns that value. For tuples with a runtime value, returns the first element of the internal storage array.
Returns:
The integer value of this RuntimeTuple.
__str__
__str__(self) -> String
Converts the RuntimeTuple to its string representation.
This method provides a human-readable string representation of the tuple, which is useful for debugging and logging.
Returns:
A string representation of the RuntimeTuple.
concat
concat[: ImmutableOrigin, //, R: IntTuple[$0]](self, rhs: RuntimeTuple[R, element_bitwidth=element_bitwidth, unsigned=unsigned]) -> RuntimeTuple[concat[::Origin[::Bool(S, R), element_bitwidth=element_bitwidth, unsigned=unsigned]
Concatenates two RuntimeTuples together.
This method combines the current RuntimeTuple with another one, preserving
both compile-time and runtime values. It handles the complexity of merging
the underlying storage arrays while maintaining the proper semantic structure.
Parameters:
- R (
IntTuple[$0]): TheIntTupletype parameter of the right-hand side RuntimeTuple.
Args:
- rhs (
RuntimeTuple[R, element_bitwidth=element_bitwidth, unsigned=unsigned]): TheRuntimeTupleto concatenate to the end of this one.
Returns:
A new RuntimeTuple containing all elements from both tuples in sequence.
flatten
flatten(self) -> RuntimeTuple[flatten[::Origin[::Bool(S), element_bitwidth=element_bitwidth, unsigned=unsigned]
Flattens a potentially nested RuntimeTuple into a single-level tuple.
This method converts a hierarchical structure of tuples into a flat representation, preserving all values but removing the nested structure. This is useful for operations that need to treat all elements uniformly.
Returns:
A new RuntimeTuple containing all elements in a flat (non-nested) structure.
write_to
write_to[W: Writer](self, mut writer: W)
Writes the RuntimeTuple to a Writer object.
This method is used by the string conversion system to generate a string representation of the RuntimeTuple. It handles both scalar values and nested tuple structures, producing a properly formatted output.
Parameters:
- W (
Writer): The Writer type to use for output.
Args:
- writer (
W): The Writer object to write the string representation to.
__len__
__len__(self) -> Int
Returns the length (number of top-level elements) of the RuntimeTuple.
This method provides the standard Python-like len() functionality, giving the number of elements at the top level of the tuple structure. For nested tuples, this returns the number of first-level entries, not the total number of scalar values.
Returns:
The number of top-level elements in the tuple.
cast
cast[type: DType](self) -> RuntimeTuple[S, element_bitwidth=bitwidthof[::DType,__mlir_type.!kgen.target](), unsigned=unsigned]
Casts the RuntimeTuple to use a different numeric type.
This method creates a new RuntimeTuple with the same structure and values but using a different underlying numeric type for storage. This is useful for changing precision or signedness of the data.
Parameters:
- type (
DType): The target DType to cast the elements to.
Returns:
A new RuntimeTuple with elements cast to the specified type.
__int__
__int__(self) -> Int
Converts the RuntimeTuple to an integer value.
This method enables implicit conversion of a RuntimeTuple to an integer, but is constrained to only work on scalar tuples (those that contain a single value).
Returns:
The integer value of the tuple.
Was this page helpful?
Thank you! We'll create more content like this.
Thank you for helping us improve!