gt4py.cartesian package

Subpackages

Submodules

gt4py.cartesian.caching module

Caching strategies for stencil generation.

class gt4py.cartesian.caching.CachingStrategy(builder: StencilBuilder)[source]

Bases: abc.ABC

abstract property backend_root_path: pathlib.Path

Calculate and if necessary create the caching base path for the backend being used.

Avoid trying to create the root_path automatically.

abstract property cache_info: Dict[str, Any]

Read currently stored cache info from file into a dictionary.

Empty if file is not found or not readable or no caching is intended.

abstract property cache_info_path: Optional[pathlib.Path]: Calculate the file path where caching info for the current process should be stored.

capture_externals() → Dict[str, Any][source]: Extract externals from the annotated stencil definition for fingerprinting. Freezes the references.

property class_name: str: Calculate the name for the stencil class, default is to read from build options.

abstract generate_cache_info() → Dict[str, Any][source]

Generate the cache info dict.

Backend specific additions can be added via a hook propery on the backend instance. Override gt4py.backend.base.Backend.extra_cache_info() to store extra info.

abstract is_cache_info_available_and_consistent(*, validate_hash: bool) → bool[source]

Check if the cache can be read and is consistent.

If the cache info file can be read, try to validate it against the current info as returned by py:meth:generate_cache_info.

Parameters: validate_hash – Should the stencil fingerprint and source code hash be validated or not

property module_postfix: str

Generate the postfix for stencil modules, can depend on the fingerprint.

Backends use this property when generating the module filename.

The example code would cause the generated module and class names to depend on the fingerprint of the stencil. That would ensure that after changing and regenerating a stencil it’s module can be loaded without unloading the previous version first. The default is empty and is suitable for when no caching is used.

Can also be re-used elsewhere for similar purposes.

property module_prefix: str

Generate the prefix for stencil modules.

Backends use this property to determine the stencil module filename. This may help distinguish python modules from other files.

The default is an empty string and is suitable for situations where no caching is required and the generated module is intended to be imported manually.

name: str

abstract property root_path: pathlib.Path: Calculate and if necessary create the root path for stencil generation operations.

abstract property stencil_id: gt4py.cartesian.definitions.StencilID: Calculate the stencil ID used for naming and cache consistency checks.

abstract update_cache_info() → None[source]

Regenerate cache info and update the cache info file.

Parameters: extra_cache_info – Additional info to be written

class gt4py.cartesian.caching.JITCachingStrategy(builder: StencilBuilder, *, root_path: Optional[str] = None, dir_name: Optional[str] = None)[source]

Bases: gt4py.cartesian.caching.CachingStrategy

Caching strategy for JIT stencil generation.

Assign a fingerprint to the stencil being generated based on the definition function and some of the build options. During generation, store this fingerprint along with other information in a cache info file.

In order to decide whether the stencil can be loaded from cache, check if a cache info file exists in the location corresponding to the current stencil. If it exists, compare it to the additional caching information for the current stencil. If the cache is consistent, a rebuild can be avoided.

_extract_api_annotations() → List[str][source]: Extract API annotations from the annotated stencil definition for fingerprinting.

property backend_root_path: pathlib.Path

Calculate and if necessary create the caching base path for the backend being used.

Avoid trying to create the root_path automatically.

property cache_info: Dict[str, Any]

Read currently stored cache info from file into a dictionary.

Empty if file is not found or not readable or no caching is intended.

property cache_info_path: Optional[pathlib.Path]: Get the cache info file path from the stencil module path.

capture_externals() → Dict[str, Any][source]: Extract externals from the annotated stencil definition for fingerprinting.

property class_name: str: Calculate the name for the stencil class, default is to read from build options.

generate_cache_info() → Dict[str, Any][source]

Generate the cache info dict.

Backend specific additions can be added via a hook propery on the backend instance. Override gt4py.backend.base.Backend.extra_cache_info() to store extra info.

is_cache_info_available_and_consistent(*, validate_hash: bool, catch_exceptions: bool = True) → bool[source]

Check if the cache can be read and is consistent.

If the cache info file can be read, try to validate it against the current info as returned by py:meth:generate_cache_info.

Parameters: validate_hash – Should the stencil fingerprint and source code hash be validated or not

property module_postfix: str

Generate the postfix for stencil modules, can depend on the fingerprint.

Backends use this property when generating the module filename.

The example code would cause the generated module and class names to depend on the fingerprint of the stencil. That would ensure that after changing and regenerating a stencil it’s module can be loaded without unloading the previous version first. The default is empty and is suitable for when no caching is used.

Can also be re-used elsewhere for similar purposes.

property module_prefix: str

Generate the prefix for stencil modules.

Backends use this property to determine the stencil module filename. This may help distinguish python modules from other files.

The default is an empty string and is suitable for situations where no caching is required and the generated module is intended to be imported manually.

name: str = 'jit'

property options_id: str

property root_path: pathlib.Path: Calculate and if necessary create the root path for stencil generation operations.

property stencil_id: gt4py.cartesian.definitions.StencilID: Calculate the stencil ID used for naming and cache consistency checks.

update_cache_info() → None[source]

Regenerate cache info and update the cache info file.

Parameters: extra_cache_info – Additional info to be written

class gt4py.cartesian.caching.NoCachingStrategy(builder: StencilBuilder, *, output_path: pathlib.Path = PosixPath('.'))[source]

Bases: gt4py.cartesian.caching.CachingStrategy

Apply no caching, useful for CLI.

Instead of calculating paths and names based on a stencil fingerprint, use user input or by default the current working dir to output source and build files.

This caching strategy is incapable of avoiding rebuilds and after rebuilding at runtime the old stencil and it’s module has to be unloaded by the user before reloading for any changes to take effect.

All methods related to generating or checking the cache info are noops and cache validation always fails.

Parameters

builder – A stencil builder instance
output_path – The path to where all source code should be written

property backend_root_path: pathlib.Path: Simply pass through the user chosen output path.

property cache_info: Dict[str, Any]

Read currently stored cache info from file into a dictionary.

Empty if file is not found or not readable or no caching is intended.

property cache_info_path: Optional[pathlib.Path]: Calculate the file path where caching info for the current process should be stored.

generate_cache_info() → Dict[str, Any][source]

Generate the cache info dict.

Backend specific additions can be added via a hook propery on the backend instance. Override gt4py.backend.base.Backend.extra_cache_info() to store extra info.

is_cache_info_available_and_consistent(*, validate_hash: bool) → bool[source]

Check if the cache can be read and is consistent.

If the cache info file can be read, try to validate it against the current info as returned by py:meth:generate_cache_info.

Parameters: validate_hash – Should the stencil fingerprint and source code hash be validated or not

name: str = 'nocaching'

property root_path: pathlib.Path: Get stencil code output path set during initialization.

property stencil_id: gt4py.cartesian.definitions.StencilID: Get a fingerprint-less stencil id.

update_cache_info() → None[source]

Regenerate cache info and update the cache info file.

Parameters: extra_cache_info – Additional info to be written

gt4py.cartesian.caching.strategy_factory(name: str, builder: StencilBuilder, *args: Any, **kwargs: Any) → gt4py.cartesian.caching.CachingStrategy[source]

gt4py.cartesian.cli module

Command line interface.

class gt4py.cartesian.cli.BackendChoice(choices: Sequence[str], case_sensitive: bool = True)[source]

Bases: click.types.Choice

Backend commandline option type.

Converts from name to backend class.

Example

gets converted to gt4pyc.backend.GTCNumpyBackend.

classmethod backend_table() → str[source]: Build a string with a table of backend compatibilities.

convert(value: str, param: Optional[click.core.Parameter], ctx: Optional[click.core.Context]) → Type[gt4py.cartesian.backend.base.CLIBackendMixin][source]: Convert a CLI option argument to a backend.

static enabled_backend_cls_from_name(backend_name: str) → Optional[Type[gt4py.cartesian.backend.base.CLIBackendMixin]][source]: Check if a given backend is enabled for CLI.

static get_backend_names() → KeysView[source]

name: str = 'backend': the descriptive name of this type

class gt4py.cartesian.cli.BackendOption[source]

Bases: click.types.ParamType

Backend specific build options for commandline usage.

convert from "key=value" strings to (key, value) tuples, where value is converted to the type declared for the chosen backend (looked up in the context).

_try_split(value: str) → Tuple[str, str][source]: Be helpful in case of formatting error.

convert(value: str, param: Optional[click.core.Parameter], ctx: Optional[click.core.Context]) → Tuple[str, Any][source]

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters

value – The value to convert.
param – The parameter that is using this type to convert its value. May be None.
ctx – The current context that arrived at this value. May be None.

converter_map = {<class 'bool'>: BOOL, <class 'int'>: INT, <class 'float'>: FLOAT, <class 'str'>: STRING}

name: str = 'option': the descriptive name of this type

class gt4py.cartesian.cli.GTScriptBuilder(input_path: Union[str, pathlib.Path], *, output_path: Union[str, pathlib.Path], backend: Type[gt4py.cartesian.backend.base.CLIBackendMixin], silent: bool = False)[source]

Bases: object

Generate stencil source code from a GTScript module.

Parameters

input_path – path (string or Pathlike) to the GTScript module.
output_path – path (string or Pathlike) to where the generated source files should be written.
backend – class of the backend that should be used.
silent – silence all reporting to stdout if True

generate_stencils(build_options: Optional[Dict[str, Any]] = None) → None[source]

import_input_module(input_path: pathlib.Path) → module[source]

iterate_stencils() → Generator[gt4py.cartesian.lazy_stencil.LazyStencil, None, None][source]

report_stencil_names() → None[source]

write_computation_src(root_path: pathlib.Path, computation_src: Dict[str, Union[str, Dict]]) → None[source]

class gt4py.cartesian.cli.Reporter(silent: bool = False)[source]

Bases: object

Wrapper around click echo functions or noops depending on the silent constructor param.

gt4py.cartesian.cli.get_param_by_name(ctx: click.core.Context, name: str) → click.core.Parameter[source]

gt4py.cartesian.config module

gt4py.cartesian.definitions module

class gt4py.cartesian.definitions.AccessKind(value)[source]

Bases: enum.IntFlag

An enumeration.

NONE = 0

READ = 1

READ_WRITE = 3

WRITE = 2

class gt4py.cartesian.definitions.BuildOptions(*, name: str, module: str, format_source: bool = True, backend_opts: Dict[str, Any] = NOTHING, build_info: Optional[dict] = None, rebuild: bool = False, raise_if_not_cached: bool = False, cache_settings: Dict[str, Any] = NOTHING, impl_opts: Dict[str, Any] = NOTHING)[source]

Bases: gt4py.cartesian.utils.attrib.AttributeClassLike

Build options.

as_dict(): Generate a dict with this instance’s data attributes.

property attributes: Generate a list with this class’ attribute names.

property qualified_name

property shashed_id

validate(): Validate this instance’s data attributes.

class gt4py.cartesian.definitions.DomainInfo(parallel_axes: Tuple[str, ...], sequential_axis: str, min_sequential_axis_size: int, ndim: int)[source]

Bases: object

min_sequential_axis_size: int

ndim: int

parallel_axes: Tuple[str, ...]

sequential_axis: str

class gt4py.cartesian.definitions.FieldInfo(access: gt4py.cartesian.definitions.AccessKind, boundary: gt4py.cartesian.gtc.definitions.Boundary, axes: Tuple[str, ...], data_dims: Tuple[int, ...], dtype: numpy.dtype)[source]

Bases: object

access: gt4py.cartesian.definitions.AccessKind

axes: Tuple[str, ...]

boundary: gt4py.cartesian.gtc.definitions.Boundary

data_dims: Tuple[int, ...]

property domain_mask

property domain_ndim

dtype: numpy.dtype

property mask

property ndim

exception gt4py.cartesian.definitions.GTError[source]: Bases: Exception

exception gt4py.cartesian.definitions.GTSemanticError(message)[source]: Bases: gt4py.cartesian.definitions.GTError

exception gt4py.cartesian.definitions.GTSpecificationError(message)[source]: Bases: gt4py.cartesian.definitions.GTError

exception gt4py.cartesian.definitions.GTSyntaxError(message, *, frontend)[source]: Bases: gt4py.cartesian.definitions.GTError

class gt4py.cartesian.definitions.ParameterInfo(access: Union[Literal[<AccessKind.NONE: 0>], Literal[<AccessKind.READ: 1>]], dtype: numpy.dtype)[source]

Bases: object

access: Union[Literal[<AccessKind.NONE: 0>], Literal[<AccessKind.READ: 1>]]

dtype: numpy.dtype

class gt4py.cartesian.definitions.StencilID(qualified_name: str, version: str)[source]

Bases: gt4py.cartesian.utils.attrib.AttributeClassLike

as_dict(): Generate a dict with this instance’s data attributes.

property attributes: Generate a list with this class’ attribute names.

validate(): Validate this instance’s data attributes.

gt4py.cartesian.gt_cache_manager module

Utils for cleaning and querying the internal GT4Py cache for generated code.

gt4py.cartesian.gt_cache_manager.clean_caches(caches: Sequence[pathlib.Path], *, verbose: bool = False) → None[source]

gt4py.cartesian.gt_cache_manager.find_caches(root: Optional[str] = None, cache_name: Optional[str] = None) → List[pathlib.Path][source]

gt4py.cartesian.gtscript module

Implementation of GTScript: an embedded DSL in Python for stencil computations.

Interface functions to define and compile GTScript definitions and empty symbol definitions for the keywords of the DSL.

gt4py.cartesian.gtscript.BACKWARD = -1: Backward iteration order.

gt4py.cartesian.gtscript.FORWARD = 1: Forward iteration order.

gt4py.cartesian.gtscript.Field = <gt4py.cartesian.gtscript._FieldDescriptorMaker object>: Field descriptor.

gt4py.cartesian.gtscript.I = Axis(name=I): I axes (parallel).

gt4py.cartesian.gtscript.IJ = (Axis(name=I), Axis(name=J)): Tuple of axes I, J.

gt4py.cartesian.gtscript.IJK = (Axis(name=I), Axis(name=J), Axis(name=K)): Tuple of axes I, J, K.

gt4py.cartesian.gtscript.IK = (Axis(name=I), Axis(name=K)): Tuple of axes I, K.

gt4py.cartesian.gtscript.J = Axis(name=J): J axes (parallel).

gt4py.cartesian.gtscript.JK = (Axis(name=J), Axis(name=K)): Tuple of axes J, K.

gt4py.cartesian.gtscript.K = Axis(name=K): K axes (sequential).

gt4py.cartesian.gtscript.PARALLEL = 0: Parallel iteration order.

gt4py.cartesian.gtscript.Sequence = <gt4py.cartesian.gtscript._SequenceDescriptorMaker object>: Sequence descriptor.

gt4py.cartesian.gtscript.__INLINED(compile_if_expression)[source]: Evaluate condition at compile time and inline statements from selected branch.

gt4py.cartesian.gtscript.abs(x)[source]: Return the absolute value of the argument

gt4py.cartesian.gtscript.acos(x)[source]: Return the arc cosine of x, in radians.

gt4py.cartesian.gtscript.acosh(x)[source]: Return the inverse hyperbolic cosine of x, in radians.

gt4py.cartesian.gtscript.asin(x)[source]: return the arc sine of x, in radians.

gt4py.cartesian.gtscript.asinh(x)[source]: return the inverse hyperbolic sine of x, in radians.

gt4py.cartesian.gtscript.atan(x)[source]: Return the arc tangent of x, in radians.

gt4py.cartesian.gtscript.atanh(x)[source]: Return the inverse hyperbolic tangent of x, in radians.

gt4py.cartesian.gtscript.cbrt(x)[source]: Return the cubic root of x.

gt4py.cartesian.gtscript.ceil(x)[source]: Return the ceiling of x, the smallest integer greater than or equal to x.

gt4py.cartesian.gtscript.compile_assert(expr)[source]: Assert that expr evaluates to True at compile-time.

gt4py.cartesian.gtscript.computation(order)[source]: Define the computation.

gt4py.cartesian.gtscript.cos(x)[source]: Return the cosine of x radians.

gt4py.cartesian.gtscript.cosh(x)[source]: Return the hyperbolic cosine of x radians.

gt4py.cartesian.gtscript.exp(x)[source]: Return e raised to the power x, where e is the base of natural logarithms.

gt4py.cartesian.gtscript.externals(*args)[source]: Inlined values of the externals definitions.

gt4py.cartesian.gtscript.floor(x)[source]: Return the floor of x, the largest integer less than or equal to x.

gt4py.cartesian.gtscript.function(func)[source]: Mark a GTScript function.

gt4py.cartesian.gtscript.gamma(x)[source]: Return the gamma function of x.

gt4py.cartesian.gtscript.horizontal(*args)[source]: Define a block of code that is restricted to a set of regions in the parallel axes.

gt4py.cartesian.gtscript.interval(*args)[source]: Define the interval of computation in the ‘K’ sequential axis.

gt4py.cartesian.gtscript.isfinite(x)[source]: Return True if x is neither an infinity nor a NaN, and False otherwise. (Note that 0.0 is considered finite.)

gt4py.cartesian.gtscript.isinf(x)[source]: Return True if x is a positive or negative infinity, and False otherwise.

gt4py.cartesian.gtscript.isnan(x)[source]: Return True if x is a NaN (not a number), and False otherwise.

gt4py.cartesian.gtscript.lazy_stencil(backend=None, definition=None, *, build_info=None, dtypes=None, externals=None, format_source=True, name=None, rebuild=False, raise_if_not_cached=False, eager=False, check_syntax=True, **kwargs)[source]

Create a stencil object with deferred building and optional up-front syntax checking.

Parameters

backend (str) – Name of the implementation backend.
definition (None when used as a decorator, otherwise a function or a :class:`gt4py.StencilObject) – Function object defining the stencil.
build_info (dict, optional) – Dictionary used to store information about the stencil generation. (None by default).
dtypes (dict`[`str, dtype_definition], optional) – Specify dtypes for string keys in the argument annotations.
externals (dict, optional) – Specify values for otherwise unbound symbols.
format_source (bool, optional) – Format generated sources when possible (True by default).
name (str, optional) – The fully qualified name of the generated StencilObject. If None, it will be set to the qualified name of the definition function. (None by default).
rebuild (bool, optional) – Force rebuild of the gt4py.StencilObject even if it is found in the cache. (False by default).
raise_if_not_cached (bool, optional) – If this is True, the call will raise an exception if the stencil does not exist in the cache, or if the cache is inconsistent. (False by default).
eager (bool, optional) – If true do not defer stencil building and instead return the fully built raw implementation object.
check_syntax (bool, default=True, optional) – If true, build and cache the IR build stage already, which checks stencil definition syntax.
**kwargs (dict, optional) – Extra backend-specific options. Check the specific backend documentation for further information.

Returns

Wrapper around an instance of the dynamically-generated subclass of gt4py.StencilObject. Defers the generation step until the last moment and allows syntax checking independently. Also gives access to a more fine grained generate / build process.

Return type

gridtools.build.LazyStencil

gt4py.cartesian.gtscript.log(x)[source]: Return the natural logarithm of x (to base e).

gt4py.cartesian.gtscript.max(x, y)[source]: Return the largest of two or more arguments.

gt4py.cartesian.gtscript.min(x, y)[source]: Return the smallest of two or more arguments.

gt4py.cartesian.gtscript.mod(x, y)[source]: returns the first argument modulo the second one

gt4py.cartesian.gtscript.sin(x)[source]: Return the sine of x radians

gt4py.cartesian.gtscript.sinh(x)[source]: Return the hyperbolic sine of x radians

gt4py.cartesian.gtscript.sqrt(x)[source]: Return the square root of x.

gt4py.cartesian.gtscript.stencil(backend, definition=None, *, build_info=None, dtypes=None, externals=None, format_source=True, name=None, rebuild=False, cache_settings=None, raise_if_not_cached=False, **kwargs)[source]

Generate an implementation of the stencil definition with the specified backend.

It can be used as a parametrized function decorator or as a regular function.

Parameters

backend (str) – Name of the implementation backend.
definition (None when used as a decorator, otherwise a function or a :class:`gt4py.StencilObject) – Function object defining the stencil.
build_info (dict, optional) – Dictionary used to store information about the stencil generation. (None by default). Possible key-value pairs include: - ‘symbol_info’: (Dict[str, SymbolInfo]) Dictionary of SymbolInfo objects - ‘parse_time’: (float) Frontend run time, e.g., parsing GTScript in seconds - ‘module_time’: (float) Python module generation time in seconds - ‘codegen_time’” (float) Backend-specific code generation time in seconds - ‘build_time’: (float) Compilation time, i.e., for non-Python backends in seconds - ‘load_time’: (float) Module load time for cached stencils in seconds
dtypes (dict`[`str, dtype_definition], optional) – Specify dtypes for string keys in the argument annotations.
externals (dict, optional) – Specify values for otherwise unbound symbols.
format_source (bool, optional) – Format generated sources when possible (True by default).
name (str, optional) – The fully qualified name of the generated StencilObject. If None, it will be set to the qualified name of the definition function. (None by default).
rebuild (bool, optional) – Force rebuild of the gt4py.StencilObject even if it is found in the cache. (False by default).
raise_if_not_cached (bool, optional) – If this is True, the call will raise an exception if the stencil does not exist in the cache, or if the cache is inconsistent. (False by default).
cache_settings (dict, optional) – Dictionary to configure cache (directory) settings (see gt4py.cartesian.config.cache_settings). Possible key-value pairs: - root_path: (str) - dir_name: (str)
**kwargs (dict, optional) – Extra backend-specific options. Check the specific backend documentation for further information.

Returns

Properly initialized instance of a dynamically-generated subclass of gt4py.StencilObject.

Return type

gridtools.StencilObject

Raises

ValueError – If inconsistent arguments are specified.

Examples

TODO

gt4py.cartesian.gtscript.tan(x)[source]: Return the tangent of x radians.

gt4py.cartesian.gtscript.tanh(x)[source]: Return the hyperbolic tangent of x radians.

gt4py.cartesian.gtscript.trunc(x)[source]: Return the Real value x truncated to an Integral (usually an integer)

gt4py.cartesian.gtscript_imports module

GTScript import machinery.

Usage Example

from gt4py.cartesian import gtscript_imports

# simple usage
gtscript_imports.enable()  # for allowing .gt.py everywhere in sys.path

# advanced usage
gtscript_imports.enable(
    search_path=[<path1>, <path2>, ...],  # for allowing only in search_path
    generate_path=<mybuildpath>,  # for generating python modules in a specific dir
    in_source=False,  # set True to generate python modules next to gtscfipt files
)

# scoped usage
with gtscript_imports.enabled():
    import ...

class gt4py.cartesian.gtscript_imports.GtsFinder(search_path: Optional[List[Union[str, pathlib.Path]]] = None, generate_path: Optional[Union[str, pathlib.Path]] = None, in_source: bool = False)[source]

Bases: importlib.abc.MetaPathFinder

Implements the importlib.abc.PathFinder protocol.

This finder is responsible for finding GTScript files within a set of search paths.

Parameters

search_path – Search path for gtscript sources, defaults to sys.path
generate_path – Path to generate py modules in. use a temp dir by default
in_source – If True, py modules are built next to the gtscript files (generate_path is ignored).

find_spec(fullname: str, path=None, target=None) → Optional[_frozen_importlib.ModuleSpec][source]: Create a module spec for the first matching source file path.

get_generate_path(src_file_path: pathlib.Path) → pathlib.Path[source]: Find the out-of-source or in-source generate directory.

install() → None[source]

iter_search_candidates(fullname: str, path: Optional[List[pathlib.Path]]) → Generator[pathlib.Path, None, None][source]: Iterate possible source file paths.

load_module(fullname: str, path=None, target=None) → module[source]

class gt4py.cartesian.gtscript_imports.GtsLoader(fullname: str, path: pathlib.Path, generate_at: pathlib.Path)[source]

Bases: _frozen_importlib_external.SourceFileLoader

Extend importlib.machinery.SourceFileLoader for GTScript files.

Generate a python module for a GTScript file and use the super class to load that instead.

create_module(spec: _frozen_importlib.ModuleSpec) → module[source]: Use default semantics for module creation.

get_filename(fullname: Optional[str] = None) → str[source]

Generate a py module if an up to date one doesn’t exist yet.

Create the generation directory if necessary. Use file stats to check if the module needs to be updated.

Parameters: fullname (str, optional) – Dotted name corresponding to the gtscript module.
Return type: The file path of the generated py module as a string

get_source_code(fullname: str) → str[source]

property plpath: pathlib.Path

gt4py.cartesian.gtscript_imports._add_extension(path: pathlib.Path, extension: str) → pathlib.Path[source]: Add an extension to the filename of a path.

gt4py.cartesian.gtscript_imports.enable(*, search_path: Optional[List[Union[str, pathlib.Path]]] = None, generate_path: Optional[Union[str, pathlib.Path]] = None, in_source: bool = False) → gt4py.cartesian.gtscript_imports.GtsFinder[source]

Install GTScript import extensions.

Parameters are passed through to the constructor of GtsFinder.

gt4py.cartesian.gtscript_imports.enabled(**kwargs: Any) → Iterator[source]

Create a context within which GTScript extensions can be imported.

Example

gt4py.cartesian.lazy_stencil module

Stencil Object that allows for deferred building.

class gt4py.cartesian.lazy_stencil.LazyStencil(builder: StencilBuilder)[source]

Bases: object

A stencil object which defers compilation until it is needed.

Usually obtained using the gt4py.gtscript.lazy_stencil() decorator, not directly instanciated. This is done by keeping a reference to a gt4py.stencil_builder.StencilBuilder instance.

Compilation happens implicitly on first access to the implementation property. Low-level build utilities are accessible through the public builder attribute.

__call__(*args: Any, **kwargs: Any) → None[source]: Execute the stencil, building the stencil if necessary.

property backend: Backend: Do not trigger a build.

check_syntax() → None[source]: Create the gtscript IR for the stencil, failing on syntax errors.

property field_info: Dict[str, Any]

Access the compiled stencil object’s field_info attribute.

Triggers a build if necessary.

implementation

Expose the compiled backend-specific python callable which executes the stencil.

Compilation happens at first access, the result is cached and should consecutively be accessible without overhead (not rigorously tested / benchmarked).

run(*args: Any, **kwargs: Any) → None[source]: Pass through to the implementation.run.

gt4py.cartesian.loader module

Implementation of stencil functions defined with symbolic Python functions.

This module contains functions to generate callable objects implementing a high-level stencil function definition using a specific code generating backend.

gt4py.cartesian.loader.gtscript_loader(definition_func: gt4py.cartesian.type_hints.StencilFunc, backend: str, build_options: BuildOptions, externals: Dict[str, Any]) → StencilObject[source]

gt4py.cartesian.loader.load_stencil(frontend_name: str, backend_name: str, definition_func: gt4py.cartesian.type_hints.StencilFunc, externals: Dict[str, Any], build_options: BuildOptions) → Type[StencilObject][source]: Generate a new class object implementing the provided definition.

gt4py.cartesian.stencil_builder module

class gt4py.cartesian.stencil_builder.StencilBuilder(definition_func: Union[gt4py.cartesian.type_hints.StencilFunc, gt4py.cartesian.type_hints.AnnotatedStencilFunc], *, backend: Optional[Union[str, Type[BackendType]]] = None, options: Optional[gt4py.cartesian.definitions.BuildOptions] = None, frontend: Optional[Type[FrontendType]] = None)[source]

Bases: object

Orchestrates code generation and compilation.

Parameters

definition_func – Stencil definition function, before or after annotation.
backend – Backend class to be instantiated for this build
options – Build options, defaults to name and module of the definition_func
frontend – Frontend class to be used

Notes

Backends can use the with_backend_data() method the backend_data() property to set and retrieve backend specific information for use in later steps.

property backend_data: Dict[str, Any]

build() → Type[StencilObject][source]: Generate, compile and/or load everything necessary to provide a usable stencil class.

property class_name: str

property cli_backend: CLIBackendMixin

classmethod default_options_dict(definition_func: Union[gt4py.cartesian.type_hints.StencilFunc, gt4py.cartesian.type_hints.AnnotatedStencilFunc]) → Dict[str, Any][source]

property definition: gt4py.cartesian.type_hints.AnnotatedStencilFunc

property externals: Dict[str, Any]

generate_bindings(targe_language: str) → Dict[str, Union[str, Dict]][source]: Generate target_language bindings source, fail if backend does not support CLI.

generate_computation() → Dict[str, Union[str, Dict]][source]: Generate the stencil source code, fail if backend does not support CLI.

property gtir: gt4py.cartesian.gtc.gtir.Stencil

property gtir_pipeline: gt4py.cartesian.gtc.passes.gtir_pipeline.GtirPipeline

property is_build_data_empty: bool

property module_name: str

property module_path: pathlib.Path

property module_qualname: str

classmethod name_to_options_args(name: Optional[str]) → Dict[str, str][source]: Check for qualified name, extract also module option in that case.

classmethod nest_impl_options(options_dict: Dict[str, Any]) → Dict[str, Any][source]

property pkg_name: str

property pkg_path: pathlib.Path

property pkg_qualname: str

property root_pkg_name: str

property stencil_id: gt4py.cartesian.definitions.StencilID

property stencil_source: str

Read the stencil source from the written module file.

Raises: FileNotFoundError – if the file has not been written yet

with_backend(backend_name: str) → gt4py.cartesian.stencil_builder.StencilBuilder[source]

Fluidly set the backend type from backend name.

Parameters: backend_name – Name of the backend type.

Notes

Resets all cached build data.

with_backend_data(data: Dict[str, Any]) → gt4py.cartesian.stencil_builder.StencilBuilder[source]

with_caching(caching_strategy_name: str, *args: Any, **kwargs: Any) → gt4py.cartesian.stencil_builder.StencilBuilder[source]

Fluidly set the caching strategy from the name.

Parameters

caching_strategy_name – Name of the caching strategy to be passed to the factory.
args – Passed through to the caching strategy factory
kwargs – Passed through to the caching strategy factory

Notes

Resets all cached build data.

with_changed_options(**kwargs: Dict[str, Any]) → gt4py.cartesian.stencil_builder.StencilBuilder[source]

with_externals(externals: Dict[str, Any]) → gt4py.cartesian.stencil_builder.StencilBuilder[source]

Fluidly set externals for this build.

Resets all cached build data.

with_options(*, name: str, module: str, **kwargs: Any) → gt4py.cartesian.stencil_builder.StencilBuilder[source]

Fluidly set the build options.

Parameters

name – Name of the stencil
module – qualified module name of the stencil’s module
kwargs – passed through to the options instance

with_root_pkg_name(name: str) → gt4py.cartesian.stencil_builder.StencilBuilder[source]

gt4py.cartesian.stencil_object module

class gt4py.cartesian.stencil_object.ArgsInfo(device: str, array: Union[ForwardRef('cp.ndarray'), numpy.ndarray], original_object: Optional[Any] = None, origin: Optional[Tuple[int, ...]] = None, dimensions: Optional[Tuple[str, ...]] = None)[source]

Bases: object

array: Union[cp.ndarray, numpy.ndarray]

device: str

dimensions: Optional[Tuple[str, ...]] = None

origin: Optional[Tuple[int, ...]] = None

original_object: Optional[Any] = None

class gt4py.cartesian.stencil_object.FrozenStencil(stencil_object: gt4py.cartesian.stencil_object.StencilObject, origin: Dict[str, Tuple[int, ...]], domain: Tuple[int, ...])[source]

Bases: object

Stencil with pre-computed domain and origin for each field argument.

__call__(**kwargs) → None[source]: Call self as a function.

domain: Tuple[int, ...]

origin: Dict[str, Tuple[int, ...]]

stencil_object: gt4py.cartesian.stencil_object.StencilObject

class gt4py.cartesian.stencil_object.StencilObject(*args, **kwargs)[source]

Bases: abc.ABC

Generic singleton implementation of a stencil callable.

This class is used as base class for specific subclass generated at run-time for any stencil definition and a unique set of external symbols. Instances of this class do not contain state and thus it is implemented as a singleton: only one instance per subclass is actually allocated (and it is immutable).

The callable interface is the same of the stencil definition function, with some extra keyword arguments.

Keyword Arguments

domain (Sequence of int, optional) – Shape of the computation domain. If None, it will be used the largest feasible domain according to the provided input fields and origin values (None by default).
origin ([int * ndims] or {‘field_name’: [int * ndims]}, optional) – If a single offset is passed, it will be used for all fields. If a dict is passed, there could be an entry for each field. A special key ‘_all_’ will represent the value to be used for all the fields not explicitly defined. If None is passed or it is not possible to assign a value to some field according to the previous rule, the value will be inferred from the boundary attribute of the field_info dict. Note that the function checks if the origin values are at least equal to the boundary attribute of that field, so a 0-based origin will only be acceptable for fields with a 0-area support region.
exec_info (dict, optional) – Dictionary used to store information about the stencil execution. (None by default). If the dictionary contains the magic key ‘__aggregate_data’ and it evaluates to True, the dictionary is populated with a nested dictionary per class containing different performance statistics. These include the stencil calls count, the cumulative time spent in all stencil calls, and the actual time spent in carrying out the computations.

abstract __call__(*args, **kwargs) → None[source]: Call self as a function.

_call_run(field_args: Dict[str, Union[cp.ndarray, numpy.ndarray]], parameter_args: Dict[str, Any], domain: Optional[Tuple[int, ...]], origin: Optional[Union[Tuple[int, int, int], Dict[str, Tuple[int, ...]]]], *, validate_args: bool = True, exec_info: Optional[Dict[str, Any]] = None) → None[source]

Check and preprocess the provided arguments (called by StencilObject subclasses).

Note that this function will always try to expand simple parameter values to complete data structures by repeating the same value as many times as needed.

Parameters

field_args (dict) – Mapping from field names to actually passed data arrays. This parameter encapsulates *args in the actual stencil subclass by doing: {input_name[i]: arg for i, arg in enumerate(args)}
parameter_args (dict) – Mapping from parameter names to actually passed parameter values. This parameter encapsulates **kwargs in the actual stencil subclass by doing: {name: value for name, value in kwargs.items()}

Check StencilObject for a full specification of the domain, origin and exec_info keyword arguments.

Return type: None
Raises: ValueError – If invalid data or inconsistent options are specified.

static _get_max_domain(array_infos: Dict[str, Optional[gt4py.cartesian.stencil_object.ArgsInfo]], domain_infos: gt4py.cartesian.definitions.DomainInfo, field_infos: Dict[str, gt4py.cartesian.definitions.FieldInfo], origin: Dict[str, Tuple[int, ...]], *, squeeze: bool = True) → gt4py.cartesian.gtc.definitions.Shape[source]

Return the maximum domain size possible.

Parameters

field_args – Mapping from field names to actually passed data arrays.
origin – The origin for each field.
squeeze – Convert non-used domain dimensions to singleton dimensions.

Returns

`Shape`

Return type

the maximum domain size.

_validate_args(arg_infos: Dict[str, Optional[gt4py.cartesian.stencil_object.ArgsInfo]], param_args: Dict[str, Any], domain: Tuple[int, ...], origin: Dict[str, Tuple[int, ...]]) → None[source]

Validate input arguments to _call_run.

Raises

ValueError – If invalid data or inconsistent options are specified.
TypeError – If an incorrect field or parameter data type is passed.

abstract property backend: str

clean_call_args_cache() → None[source]

Clean the argument cache.

Return type: None

abstract property constants: Dict[str, Any]

definition_func: Callable[[...], Any]

abstract property domain_info: gt4py.cartesian.definitions.DomainInfo

abstract property field_info: Dict[str, gt4py.cartesian.definitions.FieldInfo]

freeze(*, origin: Dict[str, Tuple[int, ...]], domain: Tuple[int, ...]) → gt4py.cartesian.stencil_object.FrozenStencil[source]

Return a StencilObject wrapper with a fixed domain and origin for each argument.

Parameters

origin (dict) – The origin for each Field argument.
domain (Sequence of int) – The compute domain shape for the frozen stencil.

Notes

Both origin and domain arguments should be compatible with the domain and origin specification defined in StencilObject.

Returns: The stencil wrapper. This should be called with the regular stencil arguments, but the field origins and domain cannot be changed. Note, no checking of origin or domain occurs at call time so it is the users responsibility to ensure correct usage.
Return type: FrozenStencil

abstract property options: Dict[str, Any]

abstract property parameter_info: Dict[str, gt4py.cartesian.definitions.ParameterInfo]

abstract run(*args, **kwargs) → None[source]

abstract property source: str

gt4py.cartesian.type_hints module

class gt4py.cartesian.type_hints.AnnotatedStencilFunc(*args, **kwargs)[source]: Bases: gt4py.cartesian.type_hints.StencilFunc, Protocol

class gt4py.cartesian.type_hints.StencilFunc(*args, **kwargs)[source]

Bases: Protocol

__call__(*args: Any, **kwargs: Dict[str, Any]) → None[source]: Call self as a function.

Module contents

Python API to develop performance portable applications for weather and climate.