diff --git a/docs/source/api/sympyextensions.rst b/docs/source/api/sympyextensions.rst index d377f998ea5d52189007b7c45f6de2f0d92e1258..6bd8fc6ee2118dbff4f4cc7ffa8df05a6cbf357b 100644 --- a/docs/source/api/sympyextensions.rst +++ b/docs/source/api/sympyextensions.rst @@ -71,7 +71,7 @@ Typed Expressions .. autoclass:: pystencils.DynamicType :members: -.. autoclass:: pystencils.sympyextensions.CastFunc +.. autoclass:: pystencils.sympyextensions.tcast Integer Operations diff --git a/docs/source/index.rst b/docs/source/index.rst index 5ddec09f2bb89619cfbc2b6c05c8dcc2bb3108a4..a6bcf5654bf2e6d4c4860ece8ad46342a5ae9d09 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -82,6 +82,7 @@ Topics reference/symbolic_language reference/kernelcreation reference/gpu_kernels + reference/WorkingWithTypes reference/types .. toctree:: diff --git a/docs/source/reference/WorkingWithTypes.md b/docs/source/reference/WorkingWithTypes.md new file mode 100644 index 0000000000000000000000000000000000000000..707553296e8db03e3ae2b98b3dbe8daf4edf636b --- /dev/null +++ b/docs/source/reference/WorkingWithTypes.md @@ -0,0 +1,66 @@ +--- +file_format: mystnb +kernelspec: + name: python3 +--- + +# Working with Data Types + +This guide will demonstrate the various options that exist to customize the data types +in generated kernels. +Data types can be modified on different levels of granularity: +Individual fields and symbols, +single subexpressions, +or the entire kernel. + +```{code-cell} +:tags: [remove-cell] +import pystencils as ps +``` + +## Understanding the pystencils Type Inference Algorithm + +To correctly apply varying data types to pystencils kernels, it is important to understand +how pystencils computes and propagates the data types of expressions. +These are the rules by which untyped symbols learn their data type: + + - All *free symbols* (that is, symbols not defined by an assignment in the kernel) receive the + *default data type* from the code generator configuration. + - All symbols defined using a *constant expression* also receive the default data type. + - All other symbols receive the data type computed for the right-hand side expression of their + defining assignment. + +To determine the type of right hand-side expressions, pystencils looks for any subexpressions +nested inside them which already have a known type. +These might be symbols whose type was already determined, +or expressions with a fixed type, such as field accesses (which get the element type of their field), +explicitly typed symbols, or type casts (see [](explicit_expression_types)). + +:::{attention} +Expressions must always have a unique and unambiguous data type, +and pystencils will not introduce any implicit casts. +If pystencils finds subexpressions with conflicting types inside one expression, +type inference will fail and `create_kernel` will raise an error. +::: + +Through these rules, there are multiple ways to modify the data types used inside a kernel. +These are highlighted in the following sections. + +## Changing the Default Data Type + +The *default data type* is the fallback type assigned by pystencils to all free symbols and symbols with constant +definitions. +It can be modified by setting the {any}`default_dtype <CreateKernelConfig.default_dtype>` option +of the code generator configuration: + +```{code-cell} ipython3 +cfg = ps.CreateKernelConfig() +cfg.default_dtype = "float32" +``` + +:::{admonition} Developers To Do +Fields should use DynamicType by default! +::: + +(explicit_expression_types)= +## Setting Explicit Types for Expressions diff --git a/docs/source/reference/kernelcreation.md b/docs/source/reference/kernelcreation.md index 248855fc1c755d9fee4c62c7db07d469d3ac84ed..93bfda43571c399d6bd9f26f0afd64b8d5e5b918 100644 --- a/docs/source/reference/kernelcreation.md +++ b/docs/source/reference/kernelcreation.md @@ -138,7 +138,7 @@ This happens roughly according to the following rules: We can observe this behavior by setting up a kernel including several fields with different data types: ```{code-cell} ipython3 -from pystencils.sympyextensions import CastFunc +from pystencils.sympyextensions import tcast f = ps.fields("f: float32[2D]") g = ps.fields("g: float16[2D]")