diff --git a/docs/api/cpp_std.md b/docs/api/cpp_std.md
new file mode 100644
index 0000000000000000000000000000000000000000..bfd9aaa5fc69984b804b3099ad8b91a46cc841ff
--- /dev/null
+++ b/docs/api/cpp_std.md
@@ -0,0 +1,8 @@
+
+::: pystencilssfg.source_concepts.cpp.std_vector_ref
+
+::: pystencilssfg.source_concepts.cpp.mdspan_ref
+
+::: pystencilssfg.source_concepts.cpp.StdVector
+
+::: pystencilssfg.source_concepts.cpp.StdMdspan
diff --git a/docs/api/generator.md b/docs/api/generator.md
index 07128fdb51a3ea794feb58e99c16af302eca6b06..1b2b77f1ac0fbc1572a67bdd708d644fcfdf7a75 100644
--- a/docs/api/generator.md
+++ b/docs/api/generator.md
@@ -3,3 +3,4 @@
::: pystencilssfg.configuration.SfgConfiguration
+::: pystencilssfg.configuration.DEFAULT_CONFIG
diff --git a/docs/api/index.md b/docs/api/index.md
index 3dd46892d2030f56078025321c5ccdda47413fb1..d3c9905d887aee50dd3c06ba5ec10cfbd0de56cc 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -13,6 +13,11 @@ These pages document the public API of *pystencils-sfg*.
- [Source File Components](source_components.md)
- [Kernel Call Tree](tree.md)
+### High-Level Language Concepts
+
+ - [Base Classes](source_objects.md)
+ - [C++ Standard Library](cpp_std.md)
+
### Code Generation
- [Emission and Printing](emission.md)
\ No newline at end of file
diff --git a/docs/api/source_objects.md b/docs/api/source_objects.md
new file mode 100644
index 0000000000000000000000000000000000000000..2ba6d4ff3bd7c9fe8aa0d3d43e23bb2811680572
--- /dev/null
+++ b/docs/api/source_objects.md
@@ -0,0 +1,6 @@
+
+::: pystencilssfg.source_concepts.SrcObject
+
+::: pystencilssfg.source_concepts.SrcField
+
+::: pystencilssfg.source_concepts.SrcVector
diff --git a/docs/api/tree.md b/docs/api/tree.md
index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..c50e4dee760a7fc861673a89f4779f347e21bca0 100644
--- a/docs/api/tree.md
+++ b/docs/api/tree.md
@@ -0,0 +1,30 @@
+
+## 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
+
+
diff --git a/docs/usage/generator_scripts.md b/docs/usage/generator_scripts.md
index da34bada9b8672a48271064b20ee2acda18a3cac..66b2652d8d5e40496bf61f99c9633bef0a2515c5 100644
--- a/docs/usage/generator_scripts.md
+++ b/docs/usage/generator_scripts.md
@@ -153,10 +153,10 @@ Extract kernel parameters from C++ objects:
[`SrcField`][pystencilssfg.source_concepts.SrcField].
Currently, *pystencils-sfg* provides mappings to
[`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
[`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.
- [`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.
diff --git a/mkdocs.yml b/mkdocs.yml
index e92f5173c8b98ecc5b4e439b9efae31c98cbaefa..66c52d0c048f26c0675cf8b85d6144c5d8ca4e2f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -45,9 +45,15 @@ nav:
- 'CLI and Build System Integration': usage/cli.md
- 'API Documentation':
- 'Overview': api/index.md
- - 'Source File Generator': api/generator.md
- - 'Code Generation Context': api/context.md
- - 'Composer': api/composer.md
- - 'Source File Components': api/source_components.md
- - 'Kernel Call Tree': api/tree.md
- - 'Emission and Printing': api/emission.md
+ - 'Front End':
+ - 'Source File Generator': api/generator.md
+ - 'Code Generation Context': api/context.md
+ - 'Composer': api/composer.md
+ - 'Source File Modelling':
+ - '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
diff --git a/src/pystencilssfg/composer/basic_composer.py b/src/pystencilssfg/composer/basic_composer.py
index 29b8d96a6c55d07849aa7a1883925bf0e054c48c..492847a0554e493c2ca65c3f79b0fe0e2869b220 100644
--- a/src/pystencilssfg/composer/basic_composer.py
+++ b/src/pystencilssfg/composer/basic_composer.py
@@ -193,7 +193,7 @@ class SfgBasicComposer:
Args:
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)
@@ -205,7 +205,12 @@ class SfgBasicComposer:
return SfgStatements(mapping, (lhs,), (rhs,))
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(
*(
rhs.extract_component(dest, coord)
diff --git a/src/pystencilssfg/configuration.py b/src/pystencilssfg/configuration.py
index c6c7422ef07c6d88d33b611def1828a80970bdc6..9a8071eb0d7b7088d15175488f3ad3cdef15c74a 100644
--- a/src/pystencilssfg/configuration.py
+++ b/src/pystencilssfg/configuration.py
@@ -86,6 +86,42 @@ class SfgOutputSpec:
@dataclass
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
header_extension: str | None = None
@@ -147,6 +183,7 @@ DEFAULT_CONFIG = SfgConfiguration(
codestyle=SfgCodeStyle(),
output_directory=".",
)
+"""Default configuration for the [SourceFileGenerator][pystencilssfg.SourceFileGenerator]."""
def run_configurator(configurator_script: str):
diff --git a/src/pystencilssfg/generator.py b/src/pystencilssfg/generator.py
index 99339fff52ad7734b61e25cf471b9a5e1b47bf59..afd79d9ed86dce515326fbc97c3a7ad8c3a2ced2 100644
--- a/src/pystencilssfg/generator.py
+++ b/src/pystencilssfg/generator.py
@@ -15,40 +15,6 @@ from .context import SfgContext
class SourceFileGenerator:
"""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):
diff --git a/src/pystencilssfg/source_concepts/source_objects.py b/src/pystencilssfg/source_concepts/source_objects.py
index f86227e176de88d8c8f538050ea281c270e8b4f3..01e98d558b0ef440dcaed1980b0eb367a7a81843 100644
--- a/src/pystencilssfg/source_concepts/source_objects.py
+++ b/src/pystencilssfg/source_concepts/source_objects.py
@@ -58,6 +58,19 @@ TypedSymbolOrObject: TypeAlias = Union[TypedSymbol, SrcObject]
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):
super().__init__(identifier, src_type)
@@ -90,6 +103,18 @@ class SrcField(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
def extract_component(
self, destination: TypedSymbolOrObject, coordinate: int
diff --git a/src/pystencilssfg/tree/__init__.py b/src/pystencilssfg/tree/__init__.py
index d25a5ebbd9d69f1b13b4c5937cfbf688f9edd9d2..46d42f83c788dfb622c58f77645115523bb0dc7c 100644
--- a/src/pystencilssfg/tree/__init__.py
+++ b/src/pystencilssfg/tree/__init__.py
@@ -1,5 +1,7 @@
from .basic_nodes import (
SfgCallTreeNode,
+ SfgCallTreeLeaf,
+ SfgEmptyNode,
SfgKernelCallNode,
SfgBlock,
SfgSequence,
@@ -11,6 +13,8 @@ from .conditional import SfgBranch, SfgCondition, IntEven, IntOdd
__all__ = [
"SfgCallTreeNode",
+ "SfgCallTreeLeaf",
+ "SfgEmptyNode",
"SfgKernelCallNode",
"SfgSequence",
"SfgBlock",
diff --git a/src/pystencilssfg/tree/basic_nodes.py b/src/pystencilssfg/tree/basic_nodes.py
index 437afc959a94aeb51efe7193e3ae6a4d4e28e1ab..8561759da7c49a94f9c86eaf95dae88bfde821a7 100644
--- a/src/pystencilssfg/tree/basic_nodes.py
+++ b/src/pystencilssfg/tree/basic_nodes.py
@@ -12,7 +12,10 @@ if TYPE_CHECKING:
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):
self._children = list(children)
@@ -50,6 +53,11 @@ class SfgCallTreeNode(ABC):
class SfgCallTreeLeaf(SfgCallTreeNode, ABC):
+ """A leaf node of the call tree.
+
+ Leaf nodes must implement `required_parameters` for automatic parameter collection.
+ """
+
@property
@abstractmethod
def required_parameters(self) -> set[TypedSymbolOrObject]:
@@ -57,6 +65,11 @@ class SfgCallTreeLeaf(SfgCallTreeNode, ABC):
class SfgEmptyNode(SfgCallTreeLeaf):
+ """A leaf node that does not emit any code.
+
+ Empty nodes must still implement `required_parameters`.
+ """
+
def __init__(self):
super().__init__()
@@ -76,9 +89,9 @@ class SfgStatements(SfgCallTreeLeaf):
Args:
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.
- 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__(