fixes to docs. start writing user guide on types.

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

docs/source/index.rst

@@ -82,6 +82,7 @@ Topics
   reference/symbolic_language
   reference/kernelcreation
   reference/gpu_kernels
+  reference/WorkingWithTypes
   reference/types
 
 .. toctree::

docs/source/reference/WorkingWithTypes.md

+---
+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

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]")