# loki.expression.mappers

Mappers for traversing and transforming the Expression tree.

Classes

`AttachScopesMapper`([fail]) | A Pymbolic expression mapper (i.e., a visitor for the expression tree) that determines the scope of `TypedSymbol` nodes and updates its `scope` pointer accordingly.
`DetachScopesMapper`() | A Pymbolic expression mapper (i.e., a visitor for the expression tree) that rebuilds an expression unchanged but with the scope for every `TypedSymbol` detached.
`ExpressionCallbackMapper`(callback, combine) | A visitor for expressions that returns the combined result of a specified callback function.
`ExpressionDimensionsMapper`() | A visitor for an expression that determines the dimensions of the expression.
`ExpressionRetriever`(query[, recurse_query]) | A mapper for the expression tree that looks for entries specified by a query.
`LokiIdentityMapper`() | A visitor to traverse and transform an expression tree
`LokiStringifyMapper`(*args, **kwargs) | A class derived from the default `StringifyMapper` that adds mappings for nodes of the expression tree that we added ourselves.
`LokiWalkMapper`() | A mapper that traverses the expression tree and calls `visit()` for each visited node.
`SubstituteExpressionsMapper`(expr_map) | A Pymbolic expression mapper (i.e., a visitor for the expression tree) that defines on-the-fly handlers from a given substitution map.

class LokiStringifyMapper(*args, **kwargs)

  Bases: `StringifyMapper`

  A class derived from the default `StringifyMapper` that adds mappings for nodes of the expression tree that we added ourselves.

  This is the default pretty printer for nodes in the expression tree.

  rec_with_force_parens_around(expr, *args, **kwargs)
  map_logic_literal(expr, enclosing_prec, *args, **kwargs)
  map_float_literal(expr, enclosing_prec, *args, **kwargs)
  map_int_literal(expr, enclosing_prec, *args, **kwargs)
  map_string_literal(expr, enclosing_prec, *args, **kwargs)
  map_intrinsic_literal(expr, enclosing_prec, *args, **kwargs)
  map_variable_symbol(expr, enclosing_prec, *args, **kwargs)
  map_deferred_type_symbol(expr, enclosing_prec, *args, **kwargs)
  map_procedure_symbol(expr, enclosing_prec, *args, **kwargs)
  map_derived_type_symbol(expr, enclosing_prec, *args, **kwargs)
  map_meta_symbol(expr, enclosing_prec, *args, **kwargs)
  map_scalar(expr, enclosing_prec, *args, **kwargs)
  map_array(expr, enclosing_prec, *args, **kwargs)
  map_inline_call(expr, enclosing_prec, *args, **kwargs)
  map_cast(expr, enclosing_prec, *args, **kwargs)
  map_range(expr, enclosing_prec, *args, **kwargs)
  map_range_index(expr, enclosing_prec, *args, **kwargs)
  map_loop_range(expr, enclosing_prec, *args, **kwargs)
  map_sum(expr, enclosing_prec, *args, **kwargs)

    Since substraction and unary minus are mapped to multiplication with (-1), we are here looking for such cases and determine the matching operator for the output.

  map_product(expr, enclosing_prec, *args, **kwargs)
  map_quotient(expr, enclosing_prec, *args, **kwargs)
  map_parenthesised_add(expr, enclosing_prec, *args, **kwargs)
  map_parenthesised_mul(expr, enclosing_prec, *args, **kwargs)
  map_parenthesised_div(expr, enclosing_prec, *args, **kwargs)
  map_parenthesised_pow(expr, enclosing_prec, *args, **kwargs)
  map_string_concat(expr, enclosing_prec, *args, **kwargs)
  map_literal_list(expr, enclosing_prec, *args, **kwargs)
  map_inline_do(expr, enclosing_prec, *args, **kwargs)
  map_array_subscript(expr, enclosing_prec, *args, **kwargs)
  map_string_subscript(expr, enclosing_prec, *args, **kwargs)
  map_c_reference(expr, enclosing_prec, *args, **kwargs)
  map_c_dereference(expr, enclosing_prec, *args, **kwargs)

class ExpressionRetriever(query, recurse_query=None, **kwargs)

  Bases: `LokiWalkMapper`

  A mapper for the expression tree that looks for entries specified by a query.

  Parameters:

    - query – Function handle that is given each visited expression node and yields True or False depending on whether that expression should be included into the result.

    - recurse_query (optional) – Optional function handle to which each visited expression node is given and that should return True or False depending on whether that expression node and its children should be visited.

  post_visit(expr, *args, **kwargs)
  reset()
  retrieve(expr, *args, **kwargs)

class ExpressionDimensionsMapper

  Bases: `Mapper`

  A visitor for an expression that determines the dimensions of the expression.

  map_algebraic_leaf(expr, *args, **kwargs)
  map_logic_literal(expr, *args, **kwargs)
  map_float_literal(expr, *args, **kwargs)
  map_int_literal(expr, *args, **kwargs)
  map_string_literal(expr, *args, **kwargs)
  map_intrinsic_literal(expr, *args, **kwargs)
  map_variable_symbol(expr, *args, **kwargs)
  map_scalar(expr, *args, **kwargs)
  map_deferred_type_symbol(expr, *args, **kwargs)
  map_array(expr, *args, **kwargs)
  map_array_subscript(expr, *args, **kwargs)
  map_string_subscript(expr, *args, **kwargs)
  map_range_index(expr, *args, **kwargs)
  map_sum(expr, *args, **kwargs)
  map_product(expr, *args, **kwargs)
  map_inline_do(expr, *args, **kwargs)

class ExpressionCallbackMapper(callback, combine)

  Bases: `CombineMapper`

  A visitor for expressions that returns the combined result of a specified callback function.

  retrieve(expr, *args, **kwargs)
  map_constant(expr, *args, **kwargs)
  map_logic_literal(expr, *args, **kwargs)
  map_string_literal(expr, *args, **kwargs)
  map_intrinsic_literal(expr, *args, **kwargs)
  map_int_literal(expr, *args, **kwargs)
  map_float_literal(expr, *args, **kwargs)
  map_variable_symbol(expr, *args, **kwargs)
  map_deferred_type_symbol(expr, *args, **kwargs)
  map_meta_symbol(expr, *args, **kwargs)
  map_scalar(expr, *args, **kwargs)
  map_array(expr, *args, **kwargs)
  map_array_subscript(expr, *args, **kwargs)
  map_string_subscript(expr, *args, **kwargs)
  map_inline_call(expr, *args, **kwargs)
  map_cast(expr, *args, **kwargs)
  map_range(expr, *args, **kwargs)
  map_range_index(expr, *args, **kwargs)
  map_loop_range(expr, *args, **kwargs)
  map_parenthesised_add(expr, *args, **kwargs)
  map_parenthesised_mul(expr, *args, **kwargs)
  map_parenthesised_div(expr, *args, **kwargs)
  map_parenthesised_pow(expr, *args, **kwargs)
  map_string_concat(expr, *args, **kwargs)
  map_literal_list(expr, *args, **kwargs)
  map_inline_do(expr, *args, **kwargs)
  map_procedure_symbol(expr, *args, **kwargs)

class SubstituteExpressionsMapper(expr_map)

  Bases: `LokiIdentityMapper`

  A Pymbolic expression mapper (i.e., a visitor for the expression tree) that defines on-the-fly handlers from a given substitution map.

  It returns a copy of the expression tree with expressions substituted according to the given `expr_map`. If an expression node is encountered that is found in `expr_map`, it is replaced with the corresponding expression from the map. For any other nodes, traversal is performed via `LokiIdentityMapper`.

  Note

  No recursion is performed on substituted expression nodes, they are taken as-is from the map. Otherwise substitutions that involve the original node would result in infinite recursion - for example a replacement that wraps a variable in an inline call: `my_var -> wrapped_in_call(my_var)`.

  When there is a need to recursively apply the mapping, the mapping needs to be applied to itself first. A potential use-case is renaming of variables, which may appear as the name of an array subscript as well as in the `dimensions` attribute of the same expression: `SOME_ARR(SOME_ARR > SOME_VAL)`. The mapping can be applied to itself using the utility function `recursive_expression_map_update`.

  Parameters:

    expr_map (dict) – Expression mapping to apply to the expression tree.

  map_from_expr_map(expr, *args, **kwargs)

    Replace an expr with its substitution, if found in the `expr_map`, otherwise continue tree traversal

class LokiIdentityMapper

  Bases: `IdentityMapper`

  A visitor to traverse and transform an expression tree

  This can serve as basis for any transformation mappers that apply changes to the expression tree. Expression nodes that are unchanged are returned as is.

  rec(expr, *args, **kwargs)

    Dispatch expr to its corresponding mapper method. Pass on `*args` and `**kwargs` unmodified.

    This method is intended as the top-level dispatch entry point and may be overridden by subclasses to present a different/more convenient interface. `rec()` on the other hand is intended as the recursive dispatch method to be used to recurse within mapper method implementations.

  map_algebraic_leaf(expr, *args, **kwargs)
  map_logic_literal(expr, *args, **kwargs)
  map_string_literal(expr, *args, **kwargs)
  map_intrinsic_literal(expr, *args, **kwargs)
  map_int_literal(expr, *args, **kwargs)
  map_float_literal(expr, *args, **kwargs)
  map_variable_symbol(expr, *args, **kwargs)
  map_deferred_type_symbol(expr, *args, **kwargs)
  map_procedure_symbol(expr, *args, **kwargs)
  map_derived_type_symbol(expr, *args, **kwargs)
  map_meta_symbol(expr, *args, **kwargs)
  map_scalar(expr, *args, **kwargs)
  map_array(expr, *args, **kwargs)
  map_array_subscript(expr, *args, **kwargs)
  map_string_subscript(expr, *args, **kwargs)
  map_inline_call(expr, *args, **kwargs)
  map_cast(expr, *args, **kwargs)
  map_sum(expr, *args, **kwargs)
  map_quotient(expr, *args, **kwargs)
  map_parenthesised_add(expr, *args, **kwargs)
  map_product(expr, *args, **kwargs)
  map_parenthesised_mul(expr, *args, **kwargs)
  map_parenthesised_div(expr, *args, **kwargs)
  map_parenthesised_pow(expr, *args, **kwargs)
  map_string_concat(expr, *args, **kwargs)
  map_range(expr, *args, **kwargs)
  map_range_index(expr, *args, **kwargs)
  map_loop_range(expr, *args, **kwargs)
  map_literal_list(expr, *args, **kwargs)
  map_inline_do(expr, *args, **kwargs)
  map_c_reference(expr, *args, **kwargs)
  map_c_dereference(expr, *args, **kwargs)

class AttachScopesMapper(fail=False)

  Bases: `LokiIdentityMapper`

  A Pymbolic expression mapper (i.e., a visitor for the expression tree) that determines the scope of `TypedSymbol` nodes and updates its `scope` pointer accordingly.

  Parameters:

    fail (bool, optional) – If True, the mapper raises `RuntimeError` if the scope for a symbol can not be found.

  map_variable_symbol(expr, *args, **kwargs)

    Handler for `VariableSymbol`

    This updates the symbol’s scope via `_update_symbol_scope()` and then calls the parent class handler routine

    Note: this may be a different handler as attaching the scope and therefore type may change a symbol’s type, e.g. from `DeferredTypeSymbol` to `Scalar`

  map_deferred_type_symbol(expr, *args, **kwargs)

    Handler for `VariableSymbol`

    This updates the symbol’s scope via `_update_symbol_scope()` and then calls the parent class handler routine

    Note: this may be a different handler as attaching the scope and therefore type may change a symbol’s type, e.g. from `DeferredTypeSymbol` to `Scalar`

  map_procedure_symbol(expr, *args, **kwargs)

class DetachScopesMapper

  Bases: `LokiIdentityMapper`

  A Pymbolic expression mapper (i.e., a visitor for the expression tree) that rebuilds an expression unchanged but with the scope for every `TypedSymbol` detached.

  This will ensure that type information is stored locally on the object itself, which is useful when storing information for inter-procedural analysis passes.

  map_variable_symbol(expr, *args, **kwargs)
  map_deferred_type_symbol(expr, *args, **kwargs)
  map_procedure_symbol(expr, *args, **kwargs)