Skip to content
Snippets Groups Projects
Commit f36a80dd authored by Frederik Hennig's avatar Frederik Hennig
Browse files

source concepts documentation

parent b0ee2247
No related branches found
No related tags found
No related merge requests found
Pipeline #58414 passed
::: pystencilssfg.source_concepts.cpp.std_vector_ref
::: pystencilssfg.source_concepts.cpp.mdspan_ref
::: pystencilssfg.source_concepts.cpp.StdVector
::: pystencilssfg.source_concepts.cpp.StdMdspan
...@@ -3,3 +3,4 @@ ...@@ -3,3 +3,4 @@
::: pystencilssfg.configuration.SfgConfiguration ::: pystencilssfg.configuration.SfgConfiguration
::: pystencilssfg.configuration.DEFAULT_CONFIG
...@@ -13,6 +13,11 @@ These pages document the public API of *pystencils-sfg*. ...@@ -13,6 +13,11 @@ These pages document the public API of *pystencils-sfg*.
- [Source File Components](source_components.md) - [Source File Components](source_components.md)
- [Kernel Call Tree](tree.md) - [Kernel Call Tree](tree.md)
### High-Level Language Concepts
- [Base Classes](source_objects.md)
- [C++ Standard Library](cpp_std.md)
### Code Generation ### Code Generation
- [Emission and Printing](emission.md) - [Emission and Printing](emission.md)
\ No newline at end of file
::: pystencilssfg.source_concepts.SrcObject
::: pystencilssfg.source_concepts.SrcField
::: pystencilssfg.source_concepts.SrcVector
## Base Classes
::: pystencilssfg.tree.SfgCallTreeNode
::: pystencilssfg.tree.SfgCallTreeLeaf
::: pystencilssfg.tree.SfgEmptyNode
## Utility Nodes
::: pystencilssfg.tree.SfgFunctionParams
::: pystencilssfg.tree.SfgRequireIncludes
## Sequences of Statements
::: pystencilssfg.tree.SfgSequence
::: pystencilssfg.tree.SfgStatements
## Structural and Conditional Constructs
::: pystencilssfg.tree.SfgBlock
## Kernel Calls
::: pystencilssfg.tree.SfgKernelCallNode
...@@ -153,10 +153,10 @@ Extract kernel parameters from C++ objects: ...@@ -153,10 +153,10 @@ Extract kernel parameters from C++ objects:
[`SrcField`][pystencilssfg.source_concepts.SrcField]. [`SrcField`][pystencilssfg.source_concepts.SrcField].
Currently, *pystencils-sfg* provides mappings to Currently, *pystencils-sfg* provides mappings to
[`std::vector`](https://en.cppreference.com/w/cpp/container/vector) [`std::vector`](https://en.cppreference.com/w/cpp/container/vector)
(via [`std_vector_ref`][pystencilssfg.source_components.cpp.std_vector_ref]) (via [`std_vector_ref`][pystencilssfg.source_concepts.cpp.std_vector_ref])
and and
[`std::mdspan`](https://en.cppreference.com/w/cpp/container/mdspan) [`std::mdspan`](https://en.cppreference.com/w/cpp/container/mdspan)
(via [`mdspan_ref`][pystencilssfg.source_components.cpp.mdspan_ref]) (via [`mdspan_ref`][pystencilssfg.source_concepts.cpp.mdspan_ref])
from the C++ standard library. from the C++ standard library.
- [`map_vector`][pystencilssfg.SfgComposer.map_vector] maps a sequence of scalar numerical values - [`map_vector`][pystencilssfg.SfgComposer.map_vector] maps a sequence of scalar numerical values
(given as `pystencils.TypedSymbol`s) to a vector data type. Currently, only `std::vector` is provided. (given as `pystencils.TypedSymbol`s) to a vector data type. Currently, only `std::vector` is provided.
......
...@@ -45,9 +45,15 @@ nav: ...@@ -45,9 +45,15 @@ nav:
- 'CLI and Build System Integration': usage/cli.md - 'CLI and Build System Integration': usage/cli.md
- 'API Documentation': - 'API Documentation':
- 'Overview': api/index.md - 'Overview': api/index.md
- 'Source File Generator': api/generator.md - 'Front End':
- 'Code Generation Context': api/context.md - 'Source File Generator': api/generator.md
- 'Composer': api/composer.md - 'Code Generation Context': api/context.md
- 'Source File Components': api/source_components.md - 'Composer': api/composer.md
- 'Kernel Call Tree': api/tree.md - 'Source File Modelling':
- 'Emission and Printing': api/emission.md - 'Source File Components': api/source_components.md
- 'Kernel Call Tree': api/tree.md
- 'High-Level Language Concepts':
- 'Base Classes': 'api/source_objects.md'
- 'C++ Standard Library': 'api/cpp_std.md'
- 'Code Generation':
- 'Emission and Printing': api/emission.md
...@@ -193,7 +193,7 @@ class SfgBasicComposer: ...@@ -193,7 +193,7 @@ class SfgBasicComposer:
Args: Args:
field: The pystencils field to be mapped field: The pystencils field to be mapped
src_object: A `SrcField` object representing a field data structure. src_object: A [SrcField][pystencilssfg.source_concepts.SrcField] object representing a field data structure.
""" """
return SfgDeferredFieldMapping(field, src_object) return SfgDeferredFieldMapping(field, src_object)
...@@ -205,7 +205,12 @@ class SfgBasicComposer: ...@@ -205,7 +205,12 @@ class SfgBasicComposer:
return SfgStatements(mapping, (lhs,), (rhs,)) return SfgStatements(mapping, (lhs,), (rhs,))
def map_vector(self, lhs_components: Sequence[TypedSymbolOrObject], rhs: SrcVector): def map_vector(self, lhs_components: Sequence[TypedSymbolOrObject], rhs: SrcVector):
"""Extracts scalar numerical values from a vector data type.""" """Extracts scalar numerical values from a vector data type.
Args:
lhs_components: Vector components as a list of symbols.
rhs: A [SrcVector][pystencilssfg.source_concepts.SrcVector] object representing a vector data structure.
"""
return make_sequence( return make_sequence(
*( *(
rhs.extract_component(dest, coord) rhs.extract_component(dest, coord)
......
...@@ -86,6 +86,42 @@ class SfgOutputSpec: ...@@ -86,6 +86,42 @@ class SfgOutputSpec:
@dataclass @dataclass
class SfgConfiguration: class SfgConfiguration:
"""
Configuration for the [SfgSourceFileGenerator][pystencilssfg.SourceFileGenerator].
The source file generator draws configuration from a total of four sources:
- The [default configuration][pystencilssfg.configuration.DEFAULT_CONFIG];
- The project configuration;
- Command-line arguments;
- The user configuration passed to the constructor of `SourceFileGenerator`.
They take precedence in the following way:
- Project configuration overrides the default configuration
- Command line arguments override the project configuration
- User configuration overrides default and project configuration,
and must not conflict with command-line arguments; otherwise, an error is thrown.
### Project Configuration via Configurator Script
Currently, the only way to define the project configuration is via a configuration module.
A configurator module is a Python file defining the following function at the top-level:
```Python
from pystencilssfg import SfgConfiguration
def sfg_config() -> SfgConfiguration:
# ...
return SfgConfiguration(
# ...
)
```
The configuration module is passed to the code generation script via the command-line argument
`--sfg-config-module`.
"""
config_source: InitVar[SfgConfigSource | None] = None config_source: InitVar[SfgConfigSource | None] = None
header_extension: str | None = None header_extension: str | None = None
...@@ -147,6 +183,7 @@ DEFAULT_CONFIG = SfgConfiguration( ...@@ -147,6 +183,7 @@ DEFAULT_CONFIG = SfgConfiguration(
codestyle=SfgCodeStyle(), codestyle=SfgCodeStyle(),
output_directory=".", output_directory=".",
) )
"""Default configuration for the [SourceFileGenerator][pystencilssfg.SourceFileGenerator]."""
def run_configurator(configurator_script: str): def run_configurator(configurator_script: str):
......
...@@ -15,40 +15,6 @@ from .context import SfgContext ...@@ -15,40 +15,6 @@ from .context import SfgContext
class SourceFileGenerator: class SourceFileGenerator:
"""Context manager that controls the code generation process in generator scripts. """Context manager that controls the code generation process in generator scripts.
## Configuration
The [source file generator][pystencilssfg.SourceFileGenerator] draws configuration from a total of four sources:
- The [default configuration][pystencilssfg.configuration.DEFAULT_CONFIG];
- The project configuration;
- Command-line arguments;
- The user configuration passed to the constructor of `SourceFileGenerator`.
They take precedence in the following way:
- Project configuration overrides the default configuration
- Command line arguments override the project configuration
- User configuration overrides default and project configuration,
and must not conflict with command-line arguments; otherwise, an error is thrown.
### Project Configuration via Configurator Script
Currently, the only way to define the project configuration is via a configuration module.
A configurator module is a Python file defining the following function at the top-level:
```Python
from pystencilssfg import SfgConfiguration
def sfg_config() -> SfgConfiguration:
# ...
return SfgConfiguration(
# ...
)
```
The configuration module is passed to the code generation script via the command-line argument
`--sfg-config-module`.
""" """
def __init__(self, sfg_config: SfgConfiguration | None = None): def __init__(self, sfg_config: SfgConfiguration | None = None):
......
...@@ -58,6 +58,19 @@ TypedSymbolOrObject: TypeAlias = Union[TypedSymbol, SrcObject] ...@@ -58,6 +58,19 @@ TypedSymbolOrObject: TypeAlias = Union[TypedSymbol, SrcObject]
class SrcField(SrcObject, ABC): class SrcField(SrcObject, ABC):
"""Represents a C++ data structure that can be mapped to a *pystencils* field.
Subclasses of `SrcField` are meant to be used in [SfgComposer.map_field][pystencilssfg.SfgComposer.map_field]
to produce the necessary mapping code from a high-level C++ field data structure to a pystencils field.
Subclasses of `SrcField` must implement `extract_ptr`, `extract_size` and `extract_stride`
to emit code extracting field pointers and indexing information from the high-level concept.
Currently, *pystencils-sfg* provides an implementation for the C++ `std::vector` and `std::mdspan` classes via
[StdVector][pystencilssfg.source_concepts.cpp.StdVector] and
[StdMdspan][pystencilssfg.source_concepts.cpp.StdMdspan].
"""
def __init__(self, identifier: str, src_type: SrcType): def __init__(self, identifier: str, src_type: SrcType):
super().__init__(identifier, src_type) super().__init__(identifier, src_type)
...@@ -90,6 +103,18 @@ class SrcField(SrcObject, ABC): ...@@ -90,6 +103,18 @@ class SrcField(SrcObject, ABC):
class SrcVector(SrcObject, ABC): class SrcVector(SrcObject, ABC):
"""Represents a C++ abstraction of a mathematical vector that can be mapped to a vector of symbols.
Subclasses of `SrcVector` are meant to be used in [SfgComposer.map_vector][pystencilssfg.SfgComposer.map_vector]
to produce the necessary mapping code from a high-level C++ vector data structure to a vector of symbols.
Subclasses of `SrcVector` must implement `extract_component` to emit code extracting scalar values
from the high-level vector.
Currently, *pystencils-sfg* provides an implementation for the C++ `std::vector` via
[StdVector][pystencilssfg.source_concepts.cpp.StdVector].
"""
@abstractmethod @abstractmethod
def extract_component( def extract_component(
self, destination: TypedSymbolOrObject, coordinate: int self, destination: TypedSymbolOrObject, coordinate: int
......
from .basic_nodes import ( from .basic_nodes import (
SfgCallTreeNode, SfgCallTreeNode,
SfgCallTreeLeaf,
SfgEmptyNode,
SfgKernelCallNode, SfgKernelCallNode,
SfgBlock, SfgBlock,
SfgSequence, SfgSequence,
...@@ -11,6 +13,8 @@ from .conditional import SfgBranch, SfgCondition, IntEven, IntOdd ...@@ -11,6 +13,8 @@ from .conditional import SfgBranch, SfgCondition, IntEven, IntOdd
__all__ = [ __all__ = [
"SfgCallTreeNode", "SfgCallTreeNode",
"SfgCallTreeLeaf",
"SfgEmptyNode",
"SfgKernelCallNode", "SfgKernelCallNode",
"SfgSequence", "SfgSequence",
"SfgBlock", "SfgBlock",
......
...@@ -12,7 +12,10 @@ if TYPE_CHECKING: ...@@ -12,7 +12,10 @@ if TYPE_CHECKING:
class SfgCallTreeNode(ABC): class SfgCallTreeNode(ABC):
"""Base class for all nodes comprising SFG call trees.""" """Base class for all nodes comprising SFG call trees.
Any instantiable call tree node must implement `get_code`.
"""
def __init__(self, *children: SfgCallTreeNode): def __init__(self, *children: SfgCallTreeNode):
self._children = list(children) self._children = list(children)
...@@ -50,6 +53,11 @@ class SfgCallTreeNode(ABC): ...@@ -50,6 +53,11 @@ class SfgCallTreeNode(ABC):
class SfgCallTreeLeaf(SfgCallTreeNode, ABC): class SfgCallTreeLeaf(SfgCallTreeNode, ABC):
"""A leaf node of the call tree.
Leaf nodes must implement `required_parameters` for automatic parameter collection.
"""
@property @property
@abstractmethod @abstractmethod
def required_parameters(self) -> set[TypedSymbolOrObject]: def required_parameters(self) -> set[TypedSymbolOrObject]:
...@@ -57,6 +65,11 @@ class SfgCallTreeLeaf(SfgCallTreeNode, ABC): ...@@ -57,6 +65,11 @@ class SfgCallTreeLeaf(SfgCallTreeNode, ABC):
class SfgEmptyNode(SfgCallTreeLeaf): class SfgEmptyNode(SfgCallTreeLeaf):
"""A leaf node that does not emit any code.
Empty nodes must still implement `required_parameters`.
"""
def __init__(self): def __init__(self):
super().__init__() super().__init__()
...@@ -76,9 +89,9 @@ class SfgStatements(SfgCallTreeLeaf): ...@@ -76,9 +89,9 @@ class SfgStatements(SfgCallTreeLeaf):
Args: Args:
code_string: Code to be printed out. code_string: Code to be printed out.
defined_objects: Objects (as `SrcObject` or `TypedSymbol`) that will be newly defined and visible to defined_params: Objects (as `SrcObject` or `TypedSymbol`) that will be newly defined and visible to
code in sequence after these statements. code in sequence after these statements.
required_objects: Objects (as `SrcObject` or `TypedSymbol`) that are required as input to these statements. required_params: Objects (as `SrcObject` or `TypedSymbol`) that are required as input to these statements.
""" """
def __init__( def __init__(
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment