loki.transformations.array_indexing.promote

Utilities for promoting the rank of array variables.

Functions

promote_nonmatching_variables(routine, ...)

Promote multiple variables with potentially non-matching promotion dimensions or index expressions.

promote_variables(routine, variable_names, pos)

Promote a list of variables by inserting new array dimensions of given size and updating all uses of these variables with a given index expression.

promotion_dimensions_from_loop_nest(...)

Determine promotion dimensions corresponding to the iteration space of a loop nest.
promote_variables(routine, variable_names, pos, index=None, size=None)

Promote a list of variables by inserting new array dimensions of given size and updating all uses of these variables with a given index expression.

When providing only size or index, promotion is restricted to updating only variable declarations or their use, respectively, and the other is left unchanged.

Parameters:

  • routine (Subroutine) – The subroutine in which the variables should be promoted.

  • variable_names (list of str) – The names of variables to be promoted. Matching of variables against names is case-insensitive.

  • pos (int) – The position of the new array dimension using Python indexing convention (i.e., count from 0 and use negative values to count from the end).

  • index (pymbolic.primitives.Expression, optional) – The indexing expression (or a tuple for multi-dimension promotion) to use for the promotion dimension(s), e.g., loop variables. Usage of variables is only updated if index is provided. When the index expression is not live at the variable use, : is used instead.

  • size (pymbolic.Expression, optional) – The size of the dimension (or tuple for multi-dimension promotion) to insert at pos. When this is provided, the declaration of variables is updated accordingly.

promote_nonmatching_variables(routine, promotion_vars_dims, promotion_vars_index)

Promote multiple variables with potentially non-matching promotion dimensions or index expressions.

This is a convenience routine for using promote_variables() that groups variables by indexing expression and promotion dimensions to reduce the number of calls to promote_variables().

Parameters:

  • routine (any:Subroutine) – The subroutine to be modified.

  • promotion_vars_dims (dict) – The mapping of variable names to promotion dimensions. The variables’ shapes are expanded where necessary to have at least these dimensions.

  • promotion_vars_index (dict) – The mapping of variable names to subscript expressions to be used whenever reading/writing the variable.

promotion_dimensions_from_loop_nest(var_names, loops, promotion_vars_dims, promotion_vars_index)

Determine promotion dimensions corresponding to the iteration space of a loop nest.

Parameters:

  • var_names (list of str) – The names of variables to consider for promotion.

  • loops (list of Loop) – The list of nested loops, sorted from outermost to innermost.

  • promotion_vars_dims (dict((str, tuple))) – The mapping of variable names to promotion dimensions. When determining promotion dimensions for the variables in var_names this dict is checked for already existing promotion dimensions and, if not matching, the maximum of both is taken for each dimension.

  • promotion_vars_index (dict((str, tuple))) – The mapping of variable names to subscript expressions. These expressions are later inserted for every variable use. When the indexing expression for the loop nest does not match the existing expression in this dict, a RuntimeError is raised.

Returns:

(:data:`promotion_vars_dims`, :data:`promotion_vars_dims`) – The updated mappings promotion_vars_dims and promotion_vars_index.

Return type:

tuple of dict