# loki.transformations.parametrise module

Parametrise variables.

E.g., parametrise

    subroutine driver(a, b)
        integer, intent(in) :: a
        integer, intent(in) :: b
        call kernel(a, b)
    end subroutine driver

    subroutine kernel(a, b)
        integer, intent(in) :: a
        integer, intent(in) :: b
        real :: array(a)
        ...
    end subroutine kernel

using the transformation

    dic2p = {'a': 10}
    scheduler.process(transformation=ParametriseTransformation(dic2p=dic2p))

to

    subroutine driver(parametrised_a, b)
        integer, parameter :: a = 10
        integer, intent(in) :: parametrised_a
        integer, intent(in) :: b
        IF (parametrised_a /= 10) THEN
            PRINT *, "Variable a parametrised to value 10, but subroutine driver received another value."
            STOP 1
        END IF
        call kernel(b)
    end subroutine driver

    subroutine kernel(b)
        integer, parameter :: a = 10
        integer, intent(in) :: b
        real :: array(a)
        ...
    end subroutine kernel

or

    subroutine driver(parametrised_a, b)
        integer, intent(in) :: parametrised_a
        integer, intent(in) :: b
        IF (parametrised_a /= 10) THEN
            PRINT *, "Variable a parametrised to value 10, but subroutine driver received another value."
            STOP 1
        END IF
        call kernel(b)
    end subroutine driver

    subroutine kernel(b)
        integer, intent(in) :: b
        real :: array(10)
        ...
    end subroutine kernel

using the transformation

    dic2p = {'a': 10}
    scheduler.process(transformation=ParametriseTransformation(dic2p=dic2p, replace_by_value=True))

class ParametriseTransformation(dic2p, replace_by_value=False, entry_points=None, abort_callback=None, key=None)

  Bases: `Transformation`

  Parametrise variables with provided values.

  This transformation checks for each subroutine (defined as driver or entry point) the arguments to be parametrised according to `dic2p` and passes this information down the calltree.

  Note

  A sanity run-time check will be inserted at each entry point to check consistency of the provided value and argument value at this point!

  Warning

  The subroutine/call signature(s) may be altered as arguments are converted to local parameters or int literals. Therefore, consistency must be ensured, meaning all parts of the code calling subroutines that are transformed and all possibly differing names of variables at the entry points must be included, otherwise the resulting code will not compile correctly!

  E.g., use this class like this:

      def error_stop(**kwargs):
          msg = kwargs.get("msg")
          return ir.GenericStmt(text=f'error stop "{msg}"'),

      dic2p = {'a': 12, 'b': 11}

      transformation = ParametriseTransformation(dic2p=dic2p, abort_callback=error_stop,
                              entry_points=("driver1", "driver2"))

      scheduler.process(transformation=transformation)

  Parameters:

    - dic2p (dict) – Dictionary of variable names and corresponding values to be parametrised.

    - replace_by_value (bool) – Replace variables entirely by value (default: False)

    - entry_points (None or tuple) – Subroutine names to be used as entry points for parametrisation. Default None uses driver(s) as entry points.

    - abort_callback –

      Callback routine used for error on sanity check. Available arguments via `kwargs`:

      - `msg` - predefined error message

      - `routine` - the routine executing the sanity check

      - `var` - the variable getting checked

      - `value` - the value the variable should have (according to `dic2p`)

    - key (str) – Access identifier/key for the `item.trafo_data` dictionary. Only necessary to provide if several of these transformations are carried out in succession.

  transform_subroutine(routine, **kwargs)

    Transformation applied to `Subroutine` item.

    Parametrises all variables as defined by `dic2p` either to be a parameter or by replacing the variable with the value itself.

    Parameters:

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

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

declare_fixed_value_scalars_as_constants(routine)

  Mark local scalars that are assigned a fixed value as parameters.

  This is not really sophisticated and will eventually be superseded by a constant propagation transformation.