diff --git a/docs/source/installation.md b/docs/source/installation.md index c369a7fa5217fa7496197c1d3cc66d4833171c6c..cea0acd2feba1c45f2e73b0d52292a92aaa28d07 100644 --- a/docs/source/installation.md +++ b/docs/source/installation.md @@ -25,6 +25,7 @@ The following feature sets are available: - `interactive` (**recommended**): Install dependencies for using pystencils interactively from within Jupyter notebooks. + Setting this flag will cause pip to install `jupyter`, `matplotlib`, and `graphviz`, among others, alongside pystencils. - `alltrafos` (**recommended**): Install dependencies to enable a wider set of code transformation. These include [islpy](https://pypi.org/project/islpy/) for polyhedral loop transformations, and [py-cpuinfo](https://pypi.org/project/py-cpuinfo/) for detecting the current hardware in order diff --git a/docs/source/reference/api/codegen.rst b/docs/source/reference/api/codegen.rst new file mode 100644 index 0000000000000000000000000000000000000000..6418f32f6fe6d78267a373150fe7a2257c5e0b97 --- /dev/null +++ b/docs/source/reference/api/codegen.rst @@ -0,0 +1,29 @@ +Code Generator and Configuration +================================ + +.. module:: pystencils.kernelcreation + +.. autosummary:: + :toctree: generated + :nosignatures: + + create_kernel + +.. module:: pystencils.config + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: autosummary/entire_class.rst + + CreateKernelConfig + CpuOptimConfig + OpenMpConfig + VectorizationConfig + GpuIndexingConfig + +.. autosummary:: + :toctree: generated + :nosignatures: + + AUTO \ No newline at end of file diff --git a/docs/source/reference/api/index.rst b/docs/source/reference/api/index.rst index 7a824422ef51ce612683c2d25acf04b51d3f779a..b19c6303eb578f4b621febe507519ae3822df20a 100644 --- a/docs/source/reference/api/index.rst +++ b/docs/source/reference/api/index.rst @@ -10,3 +10,4 @@ Modules field sympyextensions + codegen diff --git a/docs/source/reference/kernelcreation.md b/docs/source/reference/kernelcreation.md index a9fa9a8fc40485bfc061093d8eed1f57670ee8d9..fc0b2248e386a7f3f111080e0aa0980306612529 100644 --- a/docs/source/reference/kernelcreation.md +++ b/docs/source/reference/kernelcreation.md @@ -40,13 +40,11 @@ It takes two arguments: - and a configuration object, an instance of {any}`CreateKernelConfig <pystencils.config.CreateKernelConfig>`. ```{eval-rst} -.. module:: pystencils.kernelcreation - .. autosummary:: - :toctree: generated :nosignatures: - create_kernel + pystencils.kernelcreation.create_kernel + pystencils.config.CreateKernelConfig ``` For a simple kernel, an invocation of the code generator might look like this: @@ -106,28 +104,6 @@ The code generation engine can be configured using a wide range of options. This section aims at explaining the majority of these options, their interaction and effects, use cases and caveats. -```{eval-rst} - -.. module:: pystencils.config - -.. autosummary:: - :toctree: generated - :nosignatures: - :template: autosummary/entire_class.rst - - CreateKernelConfig - CpuOptimConfig - OpenMpConfig - VectorizationConfig - GpuIndexingConfig - -.. autosummary:: - :toctree: generated - :nosignatures: - - AUTO -``` - ### Target Specification @@ -291,7 +267,8 @@ of its stencil -- that is, the maximum neighbor offset encountered in any field If, for instance, a neighbor node in $x$-direction with offset $k$ is accessed by the kernel, it cannot legally execute on the outermost $k$ layers of nodes in that direction since it would access memory out-of-bounds. -Therefore, an automatic number of $k$ ghost layers is inferred. +Therefore, an automatic number of $k$ ghost layers at each domain border is inferred. +As we can see in the example below, the number of inferred ghost layers at each domain border will be set to the maximum required in any dimension. ```{code-cell} ipython3 :tags: [remove-cell] @@ -302,13 +279,13 @@ u, v = ps.fields("u, v: [2D]") To illustrate, the following kernel accesses neighbor nodes with a maximum offset of two: ```{code-cell} ipython3 -ranged_update = ps.Assignment(u.center(), v[-2, -2] + v[2, 2]) +ranged_update = ps.Assignment(u.center(), v[-2, -1] + v[2, 1]) cfg = ps.CreateKernelConfig(ghost_layers=ps.config.AUTO) kernel = ps.create_kernel(ranged_update, cfg) ``` -With `ghost_layers=ps.config.AUTO`, its iteration space will look like this (yellow cells are included, purple cells excluded): +With `ghost_layers=ps.config.AUTO`, its iteration space will look like this (yellow cells are included, purple cells excluded). ```{code-cell} ipython3 :tags: [remove-input] @@ -453,7 +430,7 @@ and use a step size of two: $$ start(y)= \begin{cases} - 0 & \quad \text{if } y \% 2 = 0 \\ + 0 & \quad \text{if } y \; \mathrm{rem} \; 2 = 0 \\ 1 & \quad \text{otherwise} \end{cases} $$