# loki.transformations.utilities

Collection of utility routines to deal with general language conversion.

Functions

`check_routine_sequential`(routine) | Check if routine is marked as "sequential".
`convert_to_lower_case`(routine) | Converts all variables and symbols in a subroutine to lower-case.
`eliminate_unused_imports`(module_or_routine, ...) | Eliminate any imported symbols (or imports alltogether) that are not in the set of used symbols.
`find_and_eliminate_unused_imports`(routine) | Find all unused imported symbols and eliminate them from their import statements in the given routine and all contained members.
`find_driver_loops`(section, targets) | Find and return all driver loops in a given section.
`get_integer_variable`(routine, name) | Find a local variable in the routine, or create an integer-typed one.
`get_local_arrays`(routine, section[, unique]) | Collect all local temporary array symbols in a given section.
`get_loop_bounds`(routine, dimension) | Check loop bounds for a particular `Dimension` in a `Subroutine`.
`is_driver_loop`(loop, targets) | Test/check whether a given loop is a driver loop.
`is_pragma_driver_loop`(loop) |
`recursive_expression_map_update`(expr_map[, ...]) | Utility function to apply a substitution map for expressions to itself
`rename_variables`(routine[, symbol_map]) | Rename symbols/variables including (routine) arguments.
`replace_intrinsics`(routine[, function_map, ...]) | Replace known intrinsic functions and symbols.
`replace_selected_kind`(routine) | Find all uses of `selected_real_kind` or `selected_int_kind` and replace them by their `iso_fortran_env` counterparts.
`sanitise_imports`(module_or_routine) | Sanitise imports by removing unused symbols and eliminating imports with empty symbol lists.
`single_variable_declaration`(routine[, ...]) | Modify/extend variable declarations to
`substitute_variables_for_definitions`(...) | Substitute variables for definitions if applicable.
`used_names_from_symbol`(symbol[, modifier]) | Helper routine that yields the symbol names for the different types of symbols we may encounter.

Classes

`IsoFortranEnvMapper`([arch]) | Mapper to convert other Fortran kind specifications to their definitions from `iso_fortran_env`.

convert_to_lower_case(routine)

  Converts all variables and symbols in a subroutine to lower-case.

  Note, this is intended for conversion to case-sensitive languages.

  TODO: Should be extended to Module objects.

replace_intrinsics(routine, function_map=None, symbol_map=None, case_sensitive=False)

  Replace known intrinsic functions and symbols.

  Parameters:

    - routine (`Subroutine`) – The subroutine object in which to replace intrinsic calls

    - function_map (dict[str, str]) – Mapping from function names (`InlineCall` names) to their replacement

    - symbol_map (dict[str, str]) – Mapping from intrinsic symbol names to their replacement

    - case_sensitive (bool) – Match case for name lookups in `function_map` and `symbol_map`

rename_variables(routine, symbol_map=None)

  Rename symbols/variables including (routine) arguments.

  Parameters:

    - routine (`Subroutine`) – The subroutine object in which to rename variables.

    - symbol_map (dict[str, str]) – Mapping from symbol/variable names to their replacement.

sanitise_imports(module_or_routine)

  Sanitise imports by removing unused symbols and eliminating imports with empty symbol lists.

  Note that this is currently limited to imports that are identified to be `Scalar`, `Array`, or `ProcedureSymbol`.

replace_selected_kind(routine)

  Find all uses of `selected_real_kind` or `selected_int_kind` and replace them by their `iso_fortran_env` counterparts.

  This inserts imports for all used constants from `iso_fortran_env`.

single_variable_declaration(routine, variables=None, group_by_shape=False)

  Modify/extend variable declarations to

  - default: only declare one variable each time while preserving the order if `variables=None` and `group_by_shape=False`

  - declare variables specified in `variables``in single/unique declarations if ``variables` is a tuple of variables

  - variable declarations to be grouped according to their shapes if `group_by_shape=True`

  Parameters:

    - routine (`Subroutine`) – The subroutine in which to modify the variable declarations

    - variables (tuple) – Variables to grant unique/single declaration for

    - group_by_shape (bool) – Whether to strictly make unique variable declarations or to only disassemble non-arrays and arrays and among arrays, arrays with differing shapes.

recursive_expression_map_update(expr_map, max_iterations=10, mapper_cls=<class 'loki.expression.mappers.SubstituteExpressionsMapper'>, case_sensitive=None)

  Utility function to apply a substitution map for expressions to itself

  The expression substitution mechanism `SubstituteExpressions` and the underlying mapper `SubstituteExpressionsMapper` replace nodes that are found in the substitution map by their corresponding replacement.

  However, expression nodes can be nested inside other expression nodes, e.g. via the `parent` or `dimensions` properties of variables. In situations, where such expression nodes as well as expression nodes appearing inside such properties are marked for substitution, it may be necessary to apply the substitution map to itself first. This utility routine takes care of that.

  Parameters:

    - expr_map (dict) – The substitution map that should be updated

    - max_iterations (int) – Maximum number of iterations, corresponds to the maximum level of nesting that can be replaced.

    - mapper_cls (`SubstituteExpressionsMapper`) – The underlying mapper to be used (default: `SubstituteExpressionsMapper`).

    - case_sensitive (bool (optional)) – Whether to check w/o case-sensitiviy for early termination opportunities (default: None, use the default/global case-sensitivy setting).

get_integer_variable(routine, name)

  Find a local variable in the routine, or create an integer-typed one.

  Parameters:

    - routine (`Subroutine`) – The subroutine in which to find the variable

    - name (string) – Name of the variable to find the in the routine.

get_loop_bounds(routine, dimension)

  Check loop bounds for a particular `Dimension` in a `Subroutine`.

  Parameters:

    - routine (`Subroutine`) – Subroutine to perform checks on.

    - dimension (`Dimension`) – `Dimension` object describing the variable conventions used to define the data dimension and iteration space.

is_pragma_driver_loop(loop)

find_driver_loops(section, targets)

  Find and return all driver loops in a given section.

  A driver loop is specified either by a call to a routine within targets or by the pragma !$loki driver-loop.

  If there are nested loops, then the highest level pragma-marked driver loop will take precedence and be considered the driver loop. If there is no pragma-marked driver loop, then the highest level loop that does not contain a driver loop will be considered the driver loop.

  Parameters:

    - section (`Section` or tuple) – The subroutine in which to find the driver loops.

    - targets (list or string) – List of subroutines that are to be considered as part of the transformation call tree.

get_local_arrays(routine, section, unique=True)

  Collect all local temporary array symbols in a given section.

  Parameters:

    - routine (`Subroutine`) – The subroutine in which to find local arrays.

    - section (`Section` or tuple of `Node`) – The section or list of nodes to scan for local temporary symbols.

    - unique (bool, optional) – Flag whether to return unique instances of each symbol; default: `False`

check_routine_sequential(routine)

  Check if routine is marked as “sequential”.

  Parameters:

    routine (`Subroutine`) – Subroutine to perform checks on.

substitute_variables_for_definitions(routine, variables)

  Substitute variables for definitions if applicable.

  Parameters:

    - routine (`Subroutine`) – Subroutine to remap the variables.

    - variables (`Expression`, list, tuple) – List of variables to remap.