Skip to content

Revise and clearly define the treatment of field size/stride symbols

Background

Traditionally, the factory function Field.create_generic created each field with its own set of shape and stride symbols, and each of these symbols was exclusive to that field. Many parts of the code, the runtime environment, and integrations, built on top of this assumption being always valid. However, the pystencils frontend allows the creation of fields with arbitray shape and stride symbols, which do not even have to be annotated as such (see !408 (merged), where the specially-annotated frontend symbols were removed for exactly this reason).

At the moment, the backend still implicitly requires that each field has its own exclusive set of indexing symbols (otherwise KernelCreationContext.add_field fails). However, the Field class exposes new_field_with_different_name, which duplicates a field while changing its name, but not its indexing symbols. So now two fields exist with the same set of indexing symbols, which the backend can't handle.

Many problems therefore arise from the fact that indexing symbols enjoy special treatment in pystencils.

Requirements

Allow any symbol of appropriate integer type as an indexing symbol of a field. Only the following restrictions apply:

  • All indexing symbols of a field must have the same type.

The backend must not handle the indexing symbols in any special way, except for checking the above restrictions. The backend must however annotate these symbols with information about their role as array extents and strides. This is a) to have additional information available to check the validity of transformations, and b) to provide that information in the interface of the final product KernelFunction, as the runtime system needs to know how to extract these symbols from the input arrays.

Document the treatment and restrictions on field indexing symbols in the documentation pages.

Ideas

Remove the backend classes below PsFieldAssocSymbol, such that there is only PsSymbol. Instead, implement a system of properties that can be attached to PsSymbols, such that any symbol may carry arbitrary additional information relevant to code generation. Create property objects for field shape and strides, and attach them to any symbols fulfilling such a role.

Refactor the KernelParameter classes: Remove FieldShapeParam, FieldStrideParam but keep FieldParameter; allow one FieldParameter to be associated to multiple fields. Attach the shape and stride annotations from the symbol properties to the parameters in an appropriate way.

Refactor the legacy_cpu and gpu_cupy JIT compilers to comply to the changes and introduce any required sanity checks if parameters fulfill multiple roles.

Also refactor the code generator bridge of waLBerla and the extraction code in pystencils-sfg to comply to the changes.

Edited by Frederik Hennig