diff --git a/doc/conf.py b/doc/conf.py index 9b8cf81e11dbbaee53110c36b1e601a80ae0104b..4c6d28c9dc7ee57c35d4c5a8d52c7af15dc6d092 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -116,6 +116,7 @@ intersphinx_mapping = { "https://documen.tician.de/cgen": None, "https://documen.tician.de/pymbolic": None, "https://documen.tician.de/pytools": None, + "https://pyrsistent.readthedocs.io/en/latest/": None, } autoclass_content = "class" diff --git a/doc/index.rst b/doc/index.rst index 8ab62928dcdddd72902994d72f1796c9bd47b3b5..d3cb6f38cc0f231058f6a27e41bb05a94da629ea 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -42,6 +42,7 @@ Please check :ref:`installation` to get started. tutorial ref_creation ref_kernel + ref_program ref_transform ref_call ref_other diff --git a/doc/ref_call.rst b/doc/ref_call.rst index 23d358c6e644215f415c90717b38f6d4c469d922..4ba3246a2cd1dcf75bb89ce084d290d97852593c 100644 --- a/doc/ref_call.rst +++ b/doc/ref_call.rst @@ -1,3 +1,8 @@ +.. currentmodule:: loopy + + +.. _func-interface: + Function Interface ================== @@ -5,38 +10,38 @@ Function Interface Resolving and specialization ---------------------------- -In :mod:`loopy`, a :class:`loopy.program.Program` is a collection of callables +In :mod:`loopy`, a :class:`loopy.Program` is a collection of callables and entrypoints. Callable are of type :class`:loopy.kernel.function_interface.InKernelCallable`. Any expression node which has a callable corresponding to it appears as :class:`~loopy.symbolic.ResolvedFunction`. The process of realizing a function as -a :class:`~loopy.kernel.function_interface.InKernelCallable` is referred to as -resolving. +a :class:`~loopy.kernel.function_interface.InKernelCallable` is referred to as resolving. -During code-generation process for a :class:`~loopy.program.Program`, a callable +During code-generation process for a :class:`~loopy.Program`, a callable is *specialized* depending on the types and shapes of the arguments passed at a call site. For example, a call to ``sin(x)`` in :mod:`loopy` is type-generic to begin with, but it later specialized to either ``sinf``, ``sin`` or ``sinl`` depending on the type of its argument ``x``. A callable's behavior during type or shape specialization is encoded via -:meth:`loopy.kernel.function_interface.InKernelCallable.with_dtypes` and -:meth:`loopy.kernel.function_interface.InKernelCallable.with_descrs`. +:meth:`~loopy.kernel.function_interface.InKernelCallable.with_types` and +:meth:`~loopy.kernel.function_interface.InKernelCallable.with_descrs`. Registering callables --------------------- -A user can *register* callables within a :class:`~loopy.program.Program` to +A user can *register* callables within a :class:`~loopy.Program` to allow loopy to resolve calls not pre-defined in :mod:`loopy`. In :mod:`loopy`, we typically aim to expose all the standard math functions defined for -a :class:`~loopy.target.Target`. Other foreign functions could be invoked by +a :class:`~loopy.target.TargetBase`. Other foreign functions could be invoked by *registering* them. An example demonstrating registering a CBlasGemv as a loopy callable: -.. literalinclude:: ../examples/python/external-call.py +.. literalinclude:: ../examples/python/call-external.py +Reference +--------- -A :class:`loopy.kernel.LoopKernel` can be registered via -:func:`loopy.transform.callable.register_callable_kernel`. +.. automodule:: loopy.kernel.function_interface diff --git a/doc/ref_program.rst b/doc/ref_program.rst new file mode 100644 index 0000000000000000000000000000000000000000..2e4d5b9bc64aa8f442203dfa4f41109c9e765743 --- /dev/null +++ b/doc/ref_program.rst @@ -0,0 +1,6 @@ +.. currentmodule:: loopy + +Program +======= + +.. autoclass:: Program diff --git a/doc/tutorial.rst b/doc/tutorial.rst index d93be3e58aaeafbe9298dae0c4856873a866651a..7732aacbe6b25f51c35e3fcd72e558b2bea503b7 100644 --- a/doc/tutorial.rst +++ b/doc/tutorial.rst @@ -1607,7 +1607,7 @@ One way to evaluate these polynomials is with :meth:`islpy.PwQPolynomial.eval_wi grouping, and evaluating subsets of the counts. Suppose we want to know the total number of 32-bit operations of any kind. We can easily count these using functions :func:`loopy.ToCountMap.filter_by` and -:func:`loopy.ToCountMap.eval_and_sum`: +:func:`loopy.ToCountPolynomialMap.eval_and_sum`: .. doctest:: diff --git a/loopy/kernel/function_interface.py b/loopy/kernel/function_interface.py index 6779a1bc75e50a56d2efa2f4a5dbaeb2e9b59e21..81ae58343d4984584ece52ac2c089f675acf8503 100644 --- a/loopy/kernel/function_interface.py +++ b/loopy/kernel/function_interface.py @@ -30,15 +30,17 @@ from loopy.kernel.data import ValueArg, ArrayArg from loopy.symbolic import DependencyMapper, WalkMapper __doc__ = """ - -.. currentmodule:: loopy +.. currentmodule:: loopy.kernel.function_interface .. autoclass:: ValueArgDescriptor + .. autoclass:: ArrayArgDescriptor + .. autoclass:: InKernelCallable + .. autoclass:: CallableKernel -.. autoclass:: ScalarCallable +.. autoclass:: ScalarCallable """ @@ -60,7 +62,7 @@ class ArrayArgDescriptor(ImmutableRecord): """ Records information about an array argument to an in-kernel callable. To be passed to and returned from - :meth:`loopy.kernel.function_interface.InKernelCallable.with_descrs`, used for + :meth:`InKernelCallable.with_descrs`, used for matching shape and address space of caller and callee kernels. ..attribute:: shape @@ -69,7 +71,7 @@ class ArrayArgDescriptor(ImmutableRecord): .. attribute:: address_space - An attribute of :class:`loopy.kernel.data.AddressSpace`. + An attribute of :class:`loopy.AddressSpace`. .. attribute:: dim_tags @@ -332,14 +334,6 @@ class InKernelCallable(ImmutableRecord): A mapping which gives indicates the argument shape and ``dim_tags`` it would be responsible for generating code. - .. note:: - - "``arg_id`` can either be an instance of :class:`int` integer - corresponding to the position of the argument or an instance of - :class:`str` corresponding to the name of keyword argument accepted - by the function. - - - Negative "arg_id" values ``-i`` in the mapping attributes indicate - return value with (0-based) index *i*. .. automethod:: __init__ .. automethod:: with_types @@ -350,6 +344,17 @@ class InKernelCallable(ImmutableRecord): .. automethod:: emit_call .. automethod:: emit_call_insn .. automethod:: is_ready_for_codegen + + .. note:: + + * "``arg_id`` can either be an instance of :class:`int` integer + corresponding to the position of the argument or an instance of + :class:`str` corresponding to the name of keyword argument accepted + by the function. + + * Negative "arg_id" values ``-i`` in the mapping attributes indicate + return value with (0-based) index *i*. + """ fields = {"arg_id_to_dtype", "arg_id_to_descr"} @@ -390,7 +395,7 @@ class InKernelCallable(ImmutableRecord): """ :arg arg_id_to_descr: a mapping from argument identifiers (integers for positional arguments, names for keyword arguments) to - :class:`loopy.ArrayArgDescriptor` instances. Unspecified/unknown + :class:`ArrayArgDescriptor` instances. Unspecified/unknown descriptors are not represented in *arg_id_to_descr*. All the expressions in arg_id_to_descr must have variables that belong @@ -411,8 +416,7 @@ class InKernelCallable(ImmutableRecord): def with_target(self, target): """ Returns a copy of *self* with all the ``dtypes`` in - ``in_knl_callable.arg_id_to_dtype`` associated with the *target*. Refer - :meth:`loopy.types.LoopyType.with_target`. + ``in_knl_callable.arg_id_to_dtype`` associated with the *target*. :arg target: An instance of :class:`loopy.target.TargetBase`. """ @@ -499,6 +503,10 @@ class ScalarCallable(InKernelCallable): """ An abstract interface the to a scalar callable encountered in a kernel. + .. automethod:: with_types + + .. automethod:: with_descrs + .. note:: The :meth:`ScalarCallable.with_types` is intended to assist with type @@ -654,21 +662,25 @@ class CallableKernel(InKernelCallable): """ Records informations about a callee kernel. Also provides interface through member methods to make the callee kernel compatible to be called from a - caller kernel. The :meth:`loopy.register_callable_kernel` should be called - in order to initiate association between a function in caller kernel and - the callee kernel. + caller kernel. :meth:`CallableKernel.with_types` should be called in order to match the ``dtypes`` of the arguments that are shared between the caller and the callee kernel. :meth:`CallableKernel.with_descrs` should be called in order to match - :attr:`ArrayArgDescriptor.dim_tags`, :attr:`ArrayArgDescriptor.shape`, - :attr:`ArrayArgDescriptor.address_space`` of the arguments shared between the - caller and the callee kernel. + the arguments' shapes/strides across the caller and the callee kernel. + + :meth:`CallableKernel.with_hw_axes_sizes` should be called to set the grid + sizes for the :attr:`CallableKernel.subkernel` of the callable. + + .. attribute:: subkernel + + :class:`~loopy.LoopKernel` which is being called. - :meth:`CallableKernel.with_hw_axes` should be called to set the grid - sizes for the :attr:`subkernel` of the callable. + .. automethod:: with_descrs + .. automethod:: with_types + .. automethod:: with_hw_axes_sizes """ fields = {"subkernel", "arg_id_to_dtype", "arg_id_to_descr"} diff --git a/loopy/library/reduction.py b/loopy/library/reduction.py index 468aaff26d583ee5211069355d9a56f504f56e25..6f97e1667b3a523d824c25315a848bbf05545c05 100644 --- a/loopy/library/reduction.py +++ b/loopy/library/reduction.py @@ -45,6 +45,8 @@ __doc__ = """ .. autoclass:: MaxReductionOperation .. autoclass:: MinReductionOperation + +.. autoclass:: ReductionOpFunction """ diff --git a/loopy/program.py b/loopy/program.py index 792abe59aa5f2b3660453d9f54d7c3d3dec94500..2b7c61e2ce13da2980e1d050acd0db2df1111762 100644 --- a/loopy/program.py +++ b/loopy/program.py @@ -49,6 +49,7 @@ __doc__ = """ .. autoclass:: Program .. autofunction:: make_program + .. autofunction:: iterate_over_kernels_if_given_program """ @@ -162,7 +163,7 @@ class Program(ImmutableRecord): An instance of :class:`pyrsistent.PMap` mapping the function identifiers in a kernel to their associated instances of - :class:`loopy.kernel.function_interface.InKernelCallable`. + :class:`~loopy.kernel.function_interface.InKernelCallable`. .. attribute:: target @@ -174,17 +175,16 @@ class Program(ImmutableRecord): TargetBase, function_indentifier: str)`` that would return an instance of :class:`loopy.kernel.function_interface.InKernelCallable` or *None*. + .. automethod:: copy + .. automethod:: __getitem__ + .. note:: - To create an instance of :class:`loopy.Program`, it is recommended to - go through :method:`loopy.make_kernel`. + go through :func:`loopy.make_kernel`. - This data structure and its attributes should be considered - immutable, any modifications should be done through :method:`copy`. + immutable, any modifications should be done through :meth:`~Program.copy`. - .. automethod:: __init__ - .. method:: __getitem__ - - Look up the resolved callable with identifier *name*. """ def __init__(self, entrypoints=frozenset(), @@ -291,6 +291,9 @@ class Program(ImmutableRecord): return self.copy(callables_table=new_callables) def __getitem__(self, name): + """ + Look up the resolved callable with identifier *name*. + """ result = self.callables_table[name] if isinstance(result, CallableKernel): return result.subkernel diff --git a/loopy/statistics.py b/loopy/statistics.py index a20f6fe4872157f27a50c7753863a118866f9858..96d96e3a425dd543b85f77d424976eca373c61b5 100755 --- a/loopy/statistics.py +++ b/loopy/statistics.py @@ -185,7 +185,6 @@ class ToCountMap: .. automethod:: group_by .. automethod:: to_bytes .. automethod:: sum - .. automethod:: eval_and_sum """ @@ -463,7 +462,9 @@ class ToCountMap: class ToCountPolynomialMap(ToCountMap): """Maps any type of key to a :class:`islpy.PwQPolynomial` or a - :class:`GuardedPwQPolynomial`. + :class:`~loopy.statistics.GuardedPwQPolynomial`. + + .. automethod:: eval_and_sum """ def __init__(self, space, count_map=None): diff --git a/loopy/symbolic.py b/loopy/symbolic.py index 82f7525dcc43bdd089042a2f72f511d054ab0101..c6f1fdd8ca17b97a4e135a5eb398ca8e9d125b99 100644 --- a/loopy/symbolic.py +++ b/loopy/symbolic.py @@ -89,6 +89,8 @@ __doc__ = """ .. autoclass:: ExpansionState .. autoclass:: RuleAwareIdentityMapper + +.. autoclass:: ResolvedFunction """ @@ -800,19 +802,13 @@ class RuleArgument(LoopyExpressionBase): class ResolvedFunction(LoopyExpressionBase): """ - A function invocation whose definition is known in a :mod:`loopy` kernel. - Each instance of :class:`loopy.symbolic.ResolvedFunction` in an expression - points to an instance of - :class:`loopy.kernel.function_interface.InKernelCallable` through the - mapping :attr:`loopy.kernel.LoopKernel.scoped_functions`. Refer - :ref:`ref_scoped_function` for a slightly detailed explanation on scoped - functions. + A function invocation whose definition is known in a :mod:`loopy` program. + Refer ref:`func-interface`. .. attribute:: function An instance of :class:`pymbolic.primitives.Variable`, - :class:`loopy.library.reduction.ArgExtOp` or - :class:`loopy.library.reduction.SegmentedOp`. + an instance of :class:`loopy.library.reduction.ReductionOpFunction` """ init_arg_names = ("function", )