# loki.transformations.transform_loop

Collection of utility routines that provide loop transformations.

Functions

`do_loop_fission`(routine[, promote, ...]) | Search for `!$loki loop-fission` pragmas in loops and split them.
`do_loop_fusion`(routine) | Search for loops annotated with the loki loop-fusion pragma and attempt to fuse them into a single loop.
`do_loop_interchange`(routine[, project_bounds]) | Search for loops annotated with the loki loop-interchange pragma and attempt to reorder them.
`do_loop_unroll`(routine[, warn_iterations_length]) | Search for `!$loki loop-unroll` pragmas in loops and unroll them.
`eliminate_variable`(polyhedron, index_or_variable) | Eliminate a variable from the polyhedron.
`generate_loop_bounds`(iteration_space, ...) | Generate loop bounds according to a changed iteration order.
`get_loop_components`(loops) | Helper routine to extract loop variables, ranges and bodies of list of loops.
`get_nested_loops`(loop, depth) | Helper routine to extract all loops in a loop nest.
`pragma_ranges_to_loop_ranges`(parameters, scope) | Convert loop ranges given in the pragma parameters from string to a tuple of LoopRange objects.

Classes

`FissionTransformer`(loop_pragmas[, active]) | Bespoke transformer that splits loops or loop nests at `!$loki loop-fission` pragmas.
`LoopUnrollTransformer`([warn_iterations_length]) | Transformer that unrolls loops or loop nests at `!$loki loop-unroll` pragmas.
`TransformLoopsTransformation`([...]) | A `Transformation` that provides a common location for the various loop transformations to be called in a `Scheduler` pipeline.

do_loop_interchange(routine, project_bounds=False)

  Search for loops annotated with the loki loop-interchange pragma and attempt to reorder them.

  Note that this effectively just exchanges variable and bounds for each of the loops, leaving the rest (including bodies, pragmas, etc.) intact.

do_loop_fusion(routine)

  Search for loops annotated with the loki loop-fusion pragma and attempt to fuse them into a single loop.

do_loop_fission(routine, promote=True, warn_loop_carries=True)

  Search for `!$loki loop-fission` pragmas in loops and split them.

  The expected pragma syntax is `!$loki loop-fission [collapse(n)] [promote(var-name, var-name, ...)]` where `collapse(n)` gives the loop nest depth to be split (defaults to n=1) and `promote` optionally specifies a list of variable names to be promoted by the split iteration space dimensions.

  Parameters:

    - routine (`Subroutine`) – The subroutine in which loop fission is to be applied.

    - promote (bool, optional) – Try to automatically detect read-after-write across fission points and promote corresponding variables. Note that this does not affect promotion of variables listed directly in the pragma’s `promote` option.

    - warn_loop_carries (bool, optional) – Try to automatically detect loop-carried dependencies and warn when the fission point sits after the initial read and before the final write.

do_loop_unroll(routine, warn_iterations_length=True)

  Search for `!$loki loop-unroll` pragmas in loops and unroll them.

  The expected pragma syntax is `!$loki loop-unroll [depth(n)]` where `depth(n)` controls the unrolling of nested loops. For instance, `depth(1)` will only unroll the top most loop of a set of nested loops. However, a child nested loop with a more restrictive depth will not be able to override its parent’s depth. If `depth(n)` is not specified, then all loops nested under a parent with this pragma will be unrolled. E.g. The code sample below will only unroll A and B, but not C:

  ! Loop A !$loki loop-unroll depth(1) DO a = 1, 10

  > ! Loop B !$loki loop-unroll DO b = 1, 10

  > > …

  > END DO ! Loop C - will not be unrolled DO c = 1, 10

  > > …

  > END DO

  END DO

  Parameters:

    - routine (`Subroutine`) – The subroutine in which loop unrolling is to be applied.

    - warn_iterations_length ('Boolean', optional) – This specifies if warnings should be generated when unrolling loops with a large number of iterations (32). It’s mainly to disable warnings when loops are being unrolled for internal transformations and analysis.

class TransformLoopsTransformation(loop_interchange=False, loop_fusion=False, loop_fission=False, loop_unroll=False, interchange_project_bounds=False, fission_promote=True, fission_warn_loop_carries=True, unroll_warn_iterations_length=True)

  Bases: `Transformation`

  A `Transformation` that provides a common location for the various loop transformations to be called in a `Scheduler` pipeline.

  The transformation applies the following methods in order:

  - `do_loop_interchange`

  - `do_loop_fusion`

  - `do_loop_fission`

  - `do_loop_unroll`

  Parameters:

    - loop_interchange (bool) – Run the `do_loop_interchange` utility. Default: `False`.

    - loop_fusion (bool) – Run the `do_loop_fusion` utility. Default: `False`.

    - loop_fission (bool) – Run the `do_loop_fission` utility. Default: `False`.

    - loop_unroll (bool) – Run the `do_loop_unroll` utility. Default: `False`.

    - interchange_project_bounds (bool) – Project loop bounds whilst performing loop interchange. Default: `False`.

    - fission_promote (bool) – Try to automatically detect read-after-write across fission points and promote corresponding variables. Note that this does not affect promotion of variables listed directly in the pragma’s `promote` option. Default: `True`.

    - fission_warn_loop_carries (bool) – Try to automatically detect loop-carried dependencies and warn when the fission point sits after the initial read and before the final write. Default: `True`.

    - unroll_warn_iterations_length (bool) – This specifies if warnings should be generated when unrolling loops with a large number of iterations (32). It’s mainly to disable warnings when loops are being unrolled for internal transformations and analysis. Default: `True`.

  transform_subroutine(routine, **kwargs)

    Defines the transformation to apply to `Subroutine` items.

    For transformations that modify `Subroutine` objects, this method should be implemented. It gets called via the dispatch method `apply()`.

    Parameters:

      - routine (`Subroutine`) – The subroutine to be transformed.

      - **kwargs (optional) – Keyword arguments for the transformation.