Translation Units

loopy.translation_unit.CallableId: TypeAlias = str | loopy.library.reduction.ReductionOpFunction

Represent a PEP 604 union type

E.g. for int | str

class loopy.translation_unit.CallableId

See above.

class loopy.translation_unit.CallablesTable

A type alias for callables tables, mapping from CallableId to InKernelCallable

class loopy.TranslationUnit(callables_table: CallablesTable, target: TargetBase, entrypoints: frozenset[str])

Records the information about all the callables in a loopy program.

An instance of TranslationUnit is the object that gets lowered for a loopy.target.TargetBase.

entrypoints

A frozenset of the names of the kernels which could be called from the host.

default_entrypoint

The LoopKernel representing the main entrypoint of the program, if defined. Currently, this attribute may only be accessed if there is exactly one entrypoint in the translation unit. Will raise an error if the default entrypoint is not a LoopKernel.

callables_table

An instance of constantdict.constantdict mapping the function identifiers in a kernel to their associated instances of InKernelCallable.

target

An instance of loopy.target.TargetBase.

func_id_to_in_knl_callables_mappers

A frozenset of functions of the signature (target: TargetBase, function_identifier: str) that returns an instance of loopy.kernel.function_interface.InKernelCallable or None.

executor(*args, entrypoint: str | None = None, **kwargs) → ExecutorBase

Return an object that hosts caches of compiled code for execution (i.e. a subclass of ExecutorBase, specific to an execution environment (e.g. an OpenCL context) and a given entrypoint.

Parameters:

entrypoint – The name of the entrypoint callable to be called. Defaults to default_entrypoint. An error will result if multiple entrypoints exist and no entrypoint is specified.

The variable arguments to this are target-specific. The PyOpenCLTarget takes a Context or a CommandQueue.

__call__(*args, **kwargs)

Builds and calls the entrypoint kernel, if TranslationUnit.target is an executable target.

Parameters:

entrypoint – The name of the entrypoint callable to be called. Defaults to default_entrypoint.

Warning

While this was the main execution interface for loopy for many years (and reasonably efficient), the caches that made this so kept lots of expensive ‘stuff’ (such as OpenCL contexts) alive for no good reason, leading to major inefficiencies. See executor() for an efficient, cached way to invoke kernels.

copy(**kwargs: Any) → Self

__getitem__(name) → LoopKernel

For the callable named name, return a loopy.LoopKernel. if it’s a CallableKernel otherwise return the callable itself.

with_kernel(kernel: LoopKernel) → Self

If self contains a callable kernel with kernel’s name, replaces its subkernel and returns a copy of self. Else records a new callable kernel with kernel as its subkernel.

Parameters:

kernel – An instance of loopy.LoopKernel.

Returns:

Copy of self with updated callable kernels.

Note

• To create an instance of loopy.TranslationUnit, it is recommended to go through loopy.make_kernel().

• This data structure and its attributes should be considered immutable, any modifications should be done through copy().

class loopy.translation_unit.CallablesInferenceContext(callables: ~constantdict.constantdict[str | ~loopy.library.reduction.ReductionOpFunction, ~loopy.kernel.function_interface.InKernelCallable], clbl_name_gen: ~collections.abc.Callable[[str], str], renames: ~collections.abc.Mapping[str | ~loopy.library.reduction.ReductionOpFunction, frozenset[str]] = <factory>, new_entrypoints: frozenset[str] = frozenset({}))

Helper class for housekeeping a loopy.TranslationUnit.callables_table while traversing through callables of loopy.TranslationUnit.

callables

A mapping from the callable names to instances of loopy.kernel.function_interface.InKernelCallable.

renames

A mapping from old function identifiers to a frozenset of new function identifiers.

new_entrypoints

A frozenset of renamed entrypoint names.

with_callable(old_function_id: str | ReductionOpFunction | Variable, new_clbl: InKernelCallable, is_entrypoint: bool = False) → tuple[Self, Variable | ReductionOpFunction]

Updates the callable referred by function_id’s in self’s namespace to new_clbl.

Parameters:

• old_function_id – An instance of pymbolic.primitives.Variable or loopy.library.reduction.ReductionOpFunction.

• new_clbl – An instance of loopy.kernel.function_interface.InKernelCallable.

Returns:

(new_self, new_function_id) is a copy of self with new_clbl in its namespace. new_clbl can be referred to by new_function_id in new_self’s namespace.

finish_program(t_unit: TranslationUnit) → TranslationUnit

Returns a copy of program with rollback renaming of the callables done whenever possible.

For example: If all the sin function ids diverged as sin_0, sin_1, then all the renaming is done such that one of the flavors of the callable is renamed back to sin.

__getitem__(name: str | ReductionOpFunction) → InKernelCallable

loopy.translation_unit.make_program(kernel: LoopKernel) → TranslationUnit

Returns an instance of loopy.TranslationUnit with kernel as the only callable kernel.

loopy.translation_unit.check_each_kernel(check: Callable[Concatenate[LoopKernel, P], None]) → Callable[Concatenate[TranslationUnit, P], None]

loopy.translation_unit.for_each_kernel(transform: Callable[Concatenate[LoopKernel, P], LoopKernel]) → Callable[Concatenate[TUnitOrKernelT, P], TUnitOrKernelT]

Function wrapper for transformations of the type transform(kernel: LoopKernel, *args, **kwargs) -> LoopKernel. Returns a function that would apply transform to all callable kernels in a loopy.TranslationUnit.

class loopy.translation_unit.TUnitOrKernelT

alias of TypeVar(‘TUnitOrKernelT’, LoopKernel, ~loopy.translation_unit.TranslationUnit)

class loopy.translation_unit.P

A typing.ParamSpec for use in annotating for_each_kernel() and check_each_kernel().