Context. Appendix to the documentation proposal. This personal draft describes GT4Py
mainatf3b3ab28; it is not an accepted normative standard.
gt4py.next DSL API reference
This page describes the Python-facing computation API of gt4py.next at
revision f3b3ab28ecfc4de6ef914d6e7bed17a5447fd43f. It is organized as an API
reference, following the category indexes and per-operation entries used by the
Python Array API standard.
The requirements and behavior described here are GT4Py’s own; this page does
not claim Array API conformance.
The companion DSL specification contains the formal language model, repository evidence, and conflict analysis. This reference presents the supported call contracts. Current limitations identify observed restrictions or differences between execution modes; a frontend accepting an expression does not establish support on every backend. Proposed resolutions in the companion’s conflict register are not additional implemented APIs.
Interpretation used notes link affected contracts directly to the relevant issue in Section 8 of the DSL specification and state the interpretation adopted here. Notes in a category introduction apply to every entry in that category.
API index
| Category | Objects and operations |
|---|---|
| Conventions | Namespaces, signatures, type notation, execution contexts |
| Data types and promotion | bool, signed/unsigned integer types, floating types, int, float, IndexType, tuples, named collections |
| Dimensions and domains | Dimension, DimensionKind, Dims, UnitRange, unit_range, Domain, domain, GridType, staggering helpers |
| Field object | Attributes, asnumpy, as_scalar, operators, indexing, remapping |
| Broadcasting | Dimension alignment, domain intersection, scalar expansion |
| Creation functions | empty, zeros, ones, full, as_field, as_connectivity, FieldConstructor |
| Elementwise functions | Arithmetic, trigonometric, hyperbolic, exponential, rounding, and predicate functions |
| Conversion and selection | astype, broadcast, where |
| Connectivity and remapping | Connectivity, CartesianConnectivity, FieldOffset, Cartesian shifts, neighbor access |
| Neighbor reductions | neighbor_sum, max_over, min_over |
| Computation definitions | field_operator, scan_operator, program, permitted statements |
| Invocation and execution | out, domain, offset_provider, output slices, backend selection, compilation methods |
| Experimental functions | as_offset, concat_where |
| Errors and support | Validation, numerical limits, backend restrictions, source references |
Conventions
Namespaces
Public names below are available from gt4py.next unless explicitly qualified.
Host code commonly uses import gt4py.next as gtx. Inside a captured computation,
callable names must be directly bound: import where, for example, outside the
function and call where(...) inside it. A captured call to gtx.where(...)
is currently rejected. Supported qualified references to dimensions, offsets,
and constants have separate resolution rules.
as_offset and concat_where are available from
gt4py.next.ffront.experimental. Python allocation, object construction,
backend selection, and compilation control occur outside captured bodies.
This page does not inventory every package export. The
public exports also include the host utilities
Device, DeviceType, CUPY_DEVICE_TYPE, and is_scalar_type, and the
program_processors submodule; they are outside this reference, see the
core definitions. Constructor device=
parameters take Device values.
Signatures and type notation
/ marks positional-only parameters; * marks keyword-only parameters. The
signatures retain GT4Py parameter names and ordering, rather than substituting
Array API signatures. Some captured call forms impose extra restrictions, noted
on their entries. Displayed generic types are documentation notation:
| Notation | Meaning |
|---|---|
Scalar | A supported scalar value with a concrete dtype |
Field[D, T] | A field with ordered dimensions D and scalar dtype T |
Number | Arithmetic scalar or field; excludes boolean operands |
Floating | Float32/float64 scalar or field |
Boolean | Boolean scalar or field |
TupleValue | A fixed, recursively nested tuple of supported values |
Product | A supported tuple or named collection, recursively containing scalar/field leaves |
DomainLike | A Domain, mapping of dimensions to ranges, or sequence of dimension/range pairs |
Output | Field or nested output collection matching an operator’s field result |
OffsetProvider | Mapping from offset tags to runtime neighbor tables |
<default-backend> | Omission uses the configured default backend, initially None |
<auto> | Omit the argument to request automatic detection; not an exported value |
float64 shown as an allocation default denotes the equivalent dtype default.
Call forms using *args and **kwargs document an entry point accepting the
parameters of the wrapped definition; they do not permit variadic parameter
declarations inside the DSL.
Interpretation used (C12). Declaration signatures use annotated ordinary positional-or-keyword parameters with all values supplied. Other Python declaration forms are not promised to work or to be rejected uniformly; wrapper call signatures do not enlarge this subset.
Common requirements
- Field dimensions identify logical coordinates. Array-axis positions and physical memory strides do not determine dimension identity.
- Arithmetic operands normally have matching dtypes. Dimension broadcasting does not perform implicit dtype conversion.
- Inputs contain every coordinate read, including shifted and dynamically selected coordinates. Callers supply halos and valid connectivity indices.
- Output fields contain every coordinate written. Values outside the selected output domain remain unchanged.
- Unless stated otherwise, elementwise functions preserve input dtype and align dimensions by the broadcasting rules.
- Floating-point accuracy, overflow, exceptional arithmetic, and reduction order have no complete common-backend contract. An entry’s mathematical description specifies the operation; it does not promise bitwise identical output or Array API special-case rules.
Data types and promotion
Scalar types
| Name | Category | Meaning |
|---|---|---|
bool | Boolean | Logical false or true; distinct from arithmetic integers |
int8, int16, int32, int64 | Signed integer | Signed integer dtype of the indicated width |
uint8, uint16, uint32, uint64 | Unsigned integer | Unsigned integer dtype of the indicated width |
float32, float64 | Floating point | Floating dtype of the indicated width |
int | Python alias spelling | Maps to int64 as an annotation/constructor |
float | Python alias spelling | Maps to float64 as an annotation/constructor |
IndexType | Index annotation alias | Alias of int32; constructor alias support is incomplete |
Current limitations. All listed sized types are exported and represented
in the type system. Some conversion and execution paths support only bool,
int32, int64, float32, and float64; smaller/unsigned widths require
backend-specific validation. Complex, object, and general string field
arithmetic are not established DSL operations.
Interpretation used (C13). The exported type universe is documented separately from execution coverage. Small and unsigned widths require evidence for the selected conversion, allocation, and backend paths.
Scalar construction and literals
T(literal) -> scalar of dtype TParameters. T is a supported scalar constructor. literal is a literal
value accepted by that constructor. Typed string literals such as
float64("inf") are supported; general string computation is not implied.
Returns. A scalar with the requested dtype.
Notes. Use astype for a computed value. Constructor aliases do
not establish an unrestricted alternative to literal-only conversion.
A decimal floating literal has dtype float64. An ordinary Python integer value
is classified as int32 when representable, otherwise int64. Source constants
are classified before unary signs: -2147483648 consequently has type int64,
and -9223372036854775808 is rejected because its positive operand exceeds
int64. NumPy scalar constants retain their dtype.
Interpretation used (C13). Integer value inference, the int annotation, and source-literal parsing retain their distinct current rules. An annotation does not contextually convert a literal, and a negative source literal is classified through its positive operand first.
Type promotion rules
For ordinary arithmetic, both scalar dtypes must be equal. Scalars expand over field dimensions; fields combine dimensions according to the broadcasting rules. An arithmetic result has that same dtype. Comparisons instead produce bool. There is no automatic int-to-float or float32-to-float64 conversion.
Thus int32_field + 1 is type-compatible, but int64_field + 1 requires an
explicit int64 literal or conversion. The ** operator has a separate result
rule, described under field operators.
Captured call parameters match annotated dtypes, dimensions, and product structure. An expression’s dimension broadcasting does not make field annotations freely interchangeable. A scalar can match a zero-dimensional field parameter of the same dtype, but field-only operations can behave differently in embedded execution because the scalar is not always wrapped. Supply an actual zero-dimensional field when field behavior matters.
Interpretation used (C3, C5). Dimension promotion does not imply dtype widening, including in where. The tested floating-base/integral-scalar-exponent case for ** remains an exception to ordinary matching-dtype rules; power follows the ordinary rules.
Interpretation used (C7). Scalar/zero-dimensional argument compatibility is retained without promising runtime wrapping. Use an actual zero-dimensional field when field operations are required.
Interpretation used (C21). Host callers must also supply matching types. Direct embedded operator calls do not enforce all runtime dtype, dimension, or nominal-collection checks; accidental acceptance or assignment casts do not establish supported coercion.
Tuples and named collections
tuple[T0, T1, ...] describes a fixed product; the literal (a, b) constructs
one in a computation. Products may be nested. They are tuples of field/scalar
values, rather than fields whose elements are arbitrary Python tuples.
Typed named tuples and supported dataclasses/custom named collections preserve
member names and their original Python type. Use module-resolvable,
data-only declarations. Dataclasses have restrictions including nonempty
members and no default-valued fields, InitVar, or custom initialization as
specified by their validation contract. Locally defined collection classes
have known lowering limitations.
Tuple indexing uses a literal integer, including a negative index. Unpacking
supports one starred target, whose result is a tuple. Named members are accessed
as product projections. where and concat_where support matching named
products. astype supports recursive tuples without equivalent named-product
frontend support. Scan calls have special scalar-to-field product matching.
See static types and collection limitations.
Interpretation used (C17, C19). Products contain scalar values or scalar-valued fields; internal IR tuple representations do not add tuple-valued field elements. Named collections use module-resolvable, data-only declarations satisfying the documented restrictions, and support is stated per builtin. Incomplete validation does not establish broader dataclass support.
Dimensions and domains
Dimension
Dimension(value: str, kind: DimensionKind = DimensionKind.HORIZONTAL) -> DimensionConstructs an immutable dimension label.
Parameters. value is its name; kind identifies horizontal locations,
local neighbor slots, or a vertical axis.
Returns. A dimension whose equality is determined by both value and
kind, independent of Python object identity.
Operations. d(i) forms a named absolute index. d + n and d - n form
Cartesian remappings. Dimension/index comparisons form coordinate regions for
concat_where; they do not construct general numerical index fields.
Interpretation used (C15). Dimension identity is the pair (value, kind), following current equality rather than the historical name-only description.
Interpretation used (C16). Region expressions describe coordinate sets, but the shared concat_where contract is one-dimensional with a contiguous result. Broader typed region algebra does not imply embedded support.
DimensionKind
The enumeration members are HORIZONTAL, LOCAL, and VERTICAL.
Canonical field dimension order is horizontal, local, vertical, then
lexicographic base name within each kind. Field/DSL checks reject noncanonical
order, duplicate dimensions, multiple local dimensions, and a base dimension
together with its staggered counterpart. Host Domain construction has weaker
checks.
Dims
Field[Dims[I, J, K], float64]
Field[Dims[()], float64]Supplies the ordered dimensions of a field annotation. Dims[()] denotes a
zero-dimensional field. The legacy spelling Field[[I, J, K], float64] also
appears in the API. Bounds are runtime properties, not annotation parameters.
Dimensions must be listed in canonical order: with horizontal
I and vertical K, Dims[K, I] raises InvalidAnnotationError at
decoration; it is not reordered.
UnitRange and unit_range
UnitRange(start: integer, stop: integer) -> UnitRange
unit_range(r: RangeLike) -> UnitRangeParameters. start and stop are absolute integer bounds. r can be an
existing range object, a unit-step Python range, a bound pair, or an integer
extent. An extent n denotes [0,n). None denotes an unbounded range;
None in a bound pair denotes the corresponding unbounded endpoint.
Returns. The half-open range [start,stop) with step one. Empty ranges
normalize to [0,0). Semantic unbounded ranges can be represented internally;
material allocation requires finite extents.
Attributes. .start, .stop expose bounds. Python len requires finite
bounds. UnitRange does not describe strided computation domains.
Domain and domain
Domain(*named_ranges, dims=None, ranges=None) -> Domain
domain(domain_like: DomainLike) -> DomainParameters. Construct Domain from named ranges, or provide both dims
and ranges of equal length. Use domain to convert convenient mappings and
sequences; for example domain({I: (0, 8), K: range(2, 5)}).
Returns. An ordered product of named unit ranges. .dims, .ranges,
.shape, and .ndim expose its layout and extents. A domain with no axes has
exactly one coordinate, the empty tuple (), and is not empty; any empty
constituent interval makes a domain empty.
Operations. Domain intersection aligns dimensions and intersects shared ranges. A missing dimension is treated as unbounded. Domains use absolute coordinates; output slices use relative bounds.
Errors. Duplicate dimensions, mismatched dimension/range counts, or invalid
range representations are not valid domains. Do not mix positional named ranges
with dims/ranges construction.
Interpretation used (C15). Domains retain their ordered dimensions. Captured program domain dictionaries must follow output-dimension order; the proposed order-independent map interpretation is not used as current behavior.
GridType
GridType.CARTESIAN selects Cartesian constraints;
GridType.UNSTRUCTURED permits unstructured neighbor relations and
Cartesian-like calculations. Omission on a computation definition requests
grid inference from dimensions, offsets, and referenced operators. Explicit
Cartesian selection rejects an unstructured requirement.
flip_staggered
flip_staggered(dim: Dimension) -> DimensionParameters. dim is a base or staggered dimension.
Returns. Its counterpart, preserving kind. Applying the function twice
recovers an equal dimension. For nonstaggered I, index i on
flip_staggered(I) has position i - 1/2 in base-grid coordinates.
is_staggered
is_staggered(dim: Dimension) -> boolParameters. dim is a dimension.
Returns. Whether it is a staggered dimension. Use this helper rather than depending on the internal name encoding.
as_non_staggered
as_non_staggered(dim: Dimension) -> DimensionParameters. dim is a dimension.
Returns. Its base dimension, or dim itself when already nonstaggered.
Source: common.py.
Field object
Field
Field[Dims[d0, ...], T]A field represents scalar values of dtype T on a domain of named coordinates.
Field is a protocol and annotation, not the storage allocation constructor;
use the creation functions to obtain array-backed fields.
A scalar and a zero-dimensional field remain distinct values.
Interpretation used (C7, C17). A scalar and a zero-dimensional field are distinct, even where argument matching permits substitution. Field elements are scalar; tuple results are products of fields or scalars.
Attributes
| Attribute | Meaning | Availability |
|---|---|---|
field.domain | Logical bounds and dimensions | Host interface |
field.dtype | Dtype descriptor, including its scalar type | Host interface |
field.ndarray | Backing array for array-backed fields | Host interface; not guaranteed for every abstract field/connectivity |
field.codomain | Value type, or a dimension for a connectivity | Host interface |
Host properties and methods do not automatically become captured DSL expressions. Storage layout and device selection are independent of logical dimension labels.
asnumpy
field.asnumpy() -> numpy.ndarrayReturns. The field’s values as a NumPy array on the host. This is an interoperability method, not a captured computation. Do not infer a universal copy/alias guarantee from the return type.
as_scalar
field.as_scalar() -> ScalarReturns. The value of a zero-dimensional field.
Errors. Extraction requires a zero-dimensional field. A nonzero-dimensional
field with a single element is not thereby a scalar. Python truth testing of a
Field raises a truth-value error; use explicit scalar extraction on the host
or where for field selection.
Field operators
The table describes the captured DSL operators. Their scalar/field dimensions follow the broadcasting rules unless noted.
| Expression | Accepted operands | Result |
|---|---|---|
+x, -x | Arithmetic scalar/field | Same type; identity or negation |
x + y, x - y, x * y | Matching arithmetic dtypes | Same dtype, merged dimensions |
x / y, x // y | Matching arithmetic dtypes | Same inferred dtype, merged dimensions; numerical caveats below |
x % y | Matching integral dtypes | Same dtype, merged dimensions |
x ** y | Arithmetic base/exponent | Base type in current frontend; scalar integral exponents of floating bases are tested |
x == y, x != y, x < y, x <= y, x > y, x >= y | Matching arithmetic dtypes | Bool over merged dimensions |
x & y, x | y, x ^ y | Bool operands | Conjunction, disjunction, exclusive-or over merged dimensions |
~x | Actual bool field for consistent field behavior | Logical field negation |
not x | Scalar bool for consistent scalar behavior | Logical scalar negation |
Current limitations. Integer / retains integer static type, while embedded
array true division may produce a floating value. Floor division and negative
modulo have backend exclusions. ** does not consistently account for extra
exponent dimensions. Field not is accidentally accepted on some paths;
Python scalar ~True differs from logical negation. Bool equality is outside
the ordinary arithmetic comparison rule. In-place augmented assignments such
as += are not captured DSL statements.
Interpretation used (C5). ** keeps the current base-type result and the tested floating-base/integral-scalar-exponent case. No general rule for broadcasting extra field-exponent dimensions is promised.
Interpretation used (C6). Use not for scalar bool and ~ for actual bool fields. Accidental acceptance of field not or scalar inversion is not a cross-mode logical-negation contract.
Interpretation used (C14). The table records static result types. Integer division and exceptional arithmetic retain their execution-mode caveats; Python, NumPy, or Array API numerical behavior is not assumed uniformly.
Indexing and writes
| Context | Supported form | Meaning |
|---|---|---|
| Tuple expression | values[q] with literal integer q | Product projection |
| Field-operator expression | field[LocalDim(q)] | Select a local component and remove that dimension |
| Program output | out[slice0, ...], one slice per dimension | Relative restriction of the write domain; slice steps must be omitted |
| Host array-backed field | Relative and named absolute indexing | Field restriction/view according to the concrete implementation |
| Host mutable field | out[index] = value | Storage mutation outside the captured language |
Captured field-operator subscripts are not general NumPy indexing. Captured
program output slices do not accept integer indices, ellipsis, or explicit steps
(including ::1). Tuple dynamic indexing/slicing is not established. The host
restrict/premap methods implement field restriction/remapping; captured
remapping uses field-call syntax.
Captured output slice bounds must be integer literals (including supported
negative literals) or omitted. Runtime names and computed expressions such as
1+1 are unsupported; use an explicit absolute domain for runtime bounds.
Slices may alias storage. Some in-place calls are tested, but arbitrary shifted input/output overlap and overlapping tuple outputs have no uniform snapshot contract. Use independent outputs or explicit temporaries in such cases.
Source: Field protocol, embedded fields, and field operations.
Interpretation used (C18). Selected tested in-place uses remain supported, but arbitrary shifted aliases or overlapping outputs have no promised snapshot semantics. Independent outputs or explicit temporaries avoid relying on the proposed future rule.
Broadcasting
Dimension and domain algorithm
- Validate each operand’s ordered dimensions.
- Form the union of dimension labels in canonical order.
- On a dimension present in multiple fields, intersect their ranges.
- On a dimension absent from an operand, that operand is constant along the dimension. A scalar is constant along all field dimensions.
- Apply the scalar operation at each coordinate, projecting the coordinate onto each operand’s dimensions.
For example, a field on I:[0,4) plus a field on K:[0,3) has dimensions
(I,K) and domain I:[0,4) × K:[0,3). Two fields on I:[0,4) and I:[1,5)
combine on I:[1,4). A length-one range does not invoke NumPy positional
broadcasting on a shared dimension.
Broadcasting preserves dtype; the operation’s dtype constraints still apply. Explicit broadcast adds requested dimensions. Tuple structures are processed only by operations that explicitly support them.
Evaluation domains
Ordinary pointwise expressions require the common domain of their operands.
where does not promise short-circuit branch evaluation and cannot generally
hide an invalid shifted access. concat_where instead chooses contributed
coordinate regions, intersecting orthogonal branch domains first.
The result’s expression domain and the output’s requested write domain are related but distinct. A program must have valid input reads for its requested writes; output-domain selection does not fill, clip, or exchange halo values.
Creation functions
All creation functions are host APIs. dtype accepts a supported dtype-like
object. allocator accepts an array namespace or GT4Py allocator/factory/backend;
device selects the allocation device. With neither supplied, ordinary
allocation uses a CPU default. Input conversion can infer the device from data.
aligned_index is a sequence of named absolute indices used as an alignment
reference by custom allocators. Array-namespace allocation ignores it with a
warning. Allocator/device incompatibilities are errors. A backing array’s
physical layout does not alter the logical domain.
Interpretation used (C13). A dtype being exported does not guarantee that every constructor, conversion helper, or allocator accepts it. Smaller and unsigned widths need validation on the chosen host path and backend.
empty
empty(domain: DomainLike, dtype=float64, *, aligned_index=None,
allocator=None, device=None) -> FieldCreates an uninitialized field.
Parameters. domain gives finite dimensions and bounds; dtype gives the
value type. Allocation keywords follow the common creation rules above.
Returns. A newly allocated field of the specified domain and dtype. Its initial element values are undefined.
zeros
zeros(domain: DomainLike, dtype=float64, *, aligned_index=None,
allocator=None, device=None) -> FieldParameters. domain, dtype, and allocation keywords as for empty.
Returns. A newly allocated field filled with zero of the requested dtype.
ones
ones(domain: DomainLike, dtype=float64, *, aligned_index=None,
allocator=None, device=None) -> FieldParameters. domain, dtype, and allocation keywords as for empty.
Returns. A newly allocated field filled with one of the requested dtype.
full
full(domain: DomainLike, fill_value: Scalar, dtype=None, *, aligned_index=None,
allocator=None, device=None) -> FieldParameters. domain gives the finite domain; fill_value is the value
assigned to every element. Omitted dtype is inferred from the fill value’s
type. Allocation keywords follow empty.
Returns. A newly allocated field of the selected dtype, filled with the converted fill value. Host dtype inference here is not the frontend’s small-integer-literal inference rule.
as_field
as_field(domain: DomainLike | sequence[Dimension], data, dtype=None, *,
origin=None, aligned_index=None, allocator=None, device=None) -> FieldCopies supported array data into field storage.
Parameters. data supplies shape, dtype, and element values. domain may
be a concrete domain or just dimension labels. With labels, each data extent
n supplies [0,n); origin[d]=o changes it to [-o,n-o). With no dtype,
use the input data dtype. Allocation keywords follow the common rules.
Returns. A field with copied storage and the requested logical domain.
There is no copy=False argument.
Errors. Shape and domain extents must agree. The number of dimension labels
must equal data rank. Origin keys must be valid dimensions; a nonempty origin
cannot accompany a concrete domain.
Example.
import numpy as np
import gt4py.next as gtx
I = gtx.Dimension("I")
f = gtx.as_field([I], np.arange(5, dtype=np.float64), origin={I: 1})
assert f.domain == gtx.domain({I: (-1, 4)})as_connectivity
as_connectivity(domain: DomainLike | sequence[Dimension], codomain: Dimension,
data, dtype=None, *, origin=None, aligned_index=None,
allocator=None, device=None, skip_value=<auto>) -> ConnectivityCopies an integer index array and attaches connectivity metadata.
Parameters. domain and conversion/allocation options follow as_field.
codomain is the dimension indexed by stored values. skip_value identifies
missing neighbors. Omission detects -1 when present in data, otherwise uses
None; explicit None disables this detection.
Returns. An integer-valued connectivity. A two-dimensional origin/local
neighbor table can be supplied through offset_provider.
Current limitations. Execution paths require None or -1 skip metadata;
constructing a table with another sentinel can succeed but remapping can fail.
Arbitrary connectivity shapes accepted by construction are broader than the
compiled neighbor-table interface.
Interpretation used (C10). Use -1 for missing neighbors and None when no missing-neighbor sentinel is used. Constructor acceptance of other integral sentinels is not executable-remapping support.
FieldConstructor
FieldConstructor(allocator=None, aligned_index=None, device=None) -> FieldConstructor
constructor.empty(domain, *, dtype=float64) -> Field
constructor.zeros(domain, *, dtype=float64) -> Field
constructor.ones(domain, *, dtype=float64) -> Field
constructor.full(domain, fill_value, *, dtype=None) -> Field
constructor.as_field(domain, data, *, dtype=None, origin=None) -> FieldParameters. Constructor arguments bind allocation policy. Method arguments have the corresponding creation-function meanings; method dtypes are keyword-only.
Returns. Reusable construction configuration, whose methods return fields. This is a host utility, not an allocation operation within the DSL.
Source: constructors.py.
Elementwise functions
Each entry below is available from gt4py.next and callable by a directly
bound name inside a field operator. Parameters shown before / are positional.
Unary functions act on each scalar/field element. Binary functions combine
matching dtypes using dimension promotion and common domains. The mathematical
meaning applies on the function’s valid numerical domain; exceptions, NaNs,
infinities, signed zero, overflow, and accuracy remain subject to the
numerical support notes.
Source for all entries in this category: builtin definitions and frontend typing.
| Group | Functions |
|---|---|
| Arithmetic | abs, neg, minimum, maximum, fmod, power |
| Trigonometric | sin, cos, tan, arcsin, arccos, arctan |
| Hyperbolic | sinh, cosh, tanh, arcsinh, arccosh, arctanh |
| Exponential and special | sqrt, exp, log, gamma, cbrt |
| Rounding | floor, ceil, trunc |
| Predicates | isfinite, isinf, isnan |
Interpretation used (C14). For every entry in this category, the mathematical operation and static dtype are specified separately from numerical edge behavior. Backend-dependent exceptions, exceptional values, and accuracy are not replaced by an assumed Array API contract.
abs
abs(value: Number, /) -> NumberParameters. value is a nonboolean arithmetic scalar or field.
Returns. The absolute value of each element. The static result preserves input dtype, dimensions, and domain; a scalar input gives a scalar result.
arccos
arccos(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The inverse cosine in radians. The real-valued mathematical domain is [-1,1]. The static result preserves input dtype, dimensions, and domain; a scalar
input gives a scalar result.
arccosh
arccosh(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The inverse hyperbolic cosine. The real-valued mathematical domain is [1,+∞). The static result preserves input dtype, dimensions, and domain; a scalar
input gives a scalar result.
arcsin
arcsin(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The inverse sine in radians. The real-valued mathematical domain is [-1,1]. The static result preserves input dtype, dimensions, and domain; a scalar
input gives a scalar result.
arcsinh
arcsinh(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The inverse hyperbolic sine of each element. The static result preserves input dtype, dimensions, and domain; a scalar input gives a scalar result.
arctan
arctan(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The inverse tangent in radians. The static result preserves input dtype, dimensions, and domain; a scalar input gives a scalar result.
arctanh
arctanh(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The inverse hyperbolic tangent. Its finite real-valued mathematical domain is (-1,1). The static result preserves input dtype, dimensions, and domain; a scalar
input gives a scalar result.
cbrt
cbrt(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The real cube root of each element, including negative elements. The static result preserves input dtype, dimensions, and domain; a scalar input gives a scalar result.
ceil
ceil(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The least integer-valued floating value no less than the input. The static result preserves input dtype, dimensions, and domain; a scalar input gives a scalar result.
Notes. The result keeps its floating dtype. Use astype for an integer dtype.
cos
cos(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The cosine of each element; angles are in radians. The static result preserves input dtype, dimensions, and domain; a scalar input gives a scalar result.
cosh
cosh(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The hyperbolic cosine of each element. The static result preserves input dtype, dimensions, and domain; a scalar input gives a scalar result.
exp
exp(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The base-e exponential of each element. The static result preserves input dtype, dimensions, and domain; a scalar input gives a scalar result.
floor
floor(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The greatest integer-valued floating value no greater than the input. The static result preserves input dtype, dimensions, and domain; a scalar input gives a scalar result.
Notes. The result keeps its floating dtype. Use astype for an integer dtype.
fmod
fmod(lhs: Number, rhs: Number, /) -> NumberParameters. lhs and rhs are arithmetic scalars/fields with equal dtypes.
Returns. The remainder with a quotient truncated toward zero: mathematically lhs - trunc(lhs/rhs) * rhs, for nonzero rhs. The result has the common dtype
and merged field dimensions on the common domain; two scalar inputs give a scalar.
Notes. Floating operands are accepted here; the captured % operator has
an integral-operand restriction. Negative operands also distinguish truncation
remainder from floor-based modulo.
Interpretation used (C14). The mathematical remainder above uses a truncated quotient. It does not establish uniform exceptional arithmetic or remove the separate backend restrictions on integral % and floor division.
gamma
gamma(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The gamma function of each element, away from its poles at nonpositive integers. The static result preserves input dtype, dimensions, and domain; a scalar input gives a scalar result.
isfinite
isfinite(value: Floating, /) -> BooleanParameters. value is a floating scalar or field.
Returns. True where an element is finite and false where it is infinite or NaN. The result has bool dtype and the same dimensions/domain as a field input, or is a scalar bool for scalar input.
isinf
isinf(value: Floating, /) -> BooleanParameters. value is a floating scalar or field.
Returns. True where an element is positive or negative infinity. The result has bool dtype and the same dimensions/domain as a field input, or is a scalar bool for scalar input.
isnan
isnan(value: Floating, /) -> BooleanParameters. value is a floating scalar or field.
Returns. True where an element is NaN. The result has bool dtype and the same dimensions/domain as a field input, or is a scalar bool for scalar input.
log
log(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The natural logarithm of each positive element. The static result preserves input dtype, dimensions, and domain; a scalar input gives a scalar result.
maximum
maximum(lhs: Number, rhs: Number, /) -> NumberParameters. lhs and rhs are arithmetic scalars/fields with equal dtypes.
Returns. The larger of the two corresponding values. The result has the common dtype and merged field dimensions on the common domain; two scalar inputs give a scalar.
Current limitations. NaN and signed-zero selection are not specified uniformly across execution modes.
Interpretation used (C14). Ordinary ordered values use the larger-value rule. NaN and signed-zero selection remain unresolved across modes rather than inheriting Array API special cases.
minimum
minimum(lhs: Number, rhs: Number, /) -> NumberParameters. lhs and rhs are arithmetic scalars/fields with equal dtypes.
Returns. The smaller of the two corresponding values. The result has the common dtype and merged field dimensions on the common domain; two scalar inputs give a scalar.
Current limitations. NaN and signed-zero selection are not specified uniformly across execution modes.
Interpretation used (C14). Ordinary ordered values use the smaller-value rule. NaN and signed-zero selection remain unresolved across modes rather than inheriting Array API special cases.
neg
neg(value: Number, /) -> NumberParameters. value is a nonboolean arithmetic scalar or field.
Returns. The additive inverse of each element, -value. The static result preserves input dtype, dimensions, and domain; a scalar
input gives a scalar result.
power
power(lhs: Number, rhs: Number, /) -> NumberParameters. lhs and rhs are arithmetic scalars/fields with equal dtypes.
Returns. The first operand raised to the second operand. The result has the common dtype and merged field dimensions on the common domain; two scalar inputs give a scalar.
Current limitations. With integral operands, frontend type deduction prints a
result-type consistency diagnostic to standard output; it is not a Python warning
and cannot be filtered as one. This function uses ordinary matching-dtype promotion, unlike the
** operator’s special base-type result rule.
Interpretation used (C5). power requires matching dtypes and promotes dimensions normally. The base-type rule and mixed scalar exponent case of ** do not extend to this function.
sin
sin(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The sine of each element; angles are in radians. The static result preserves input dtype, dimensions, and domain; a scalar input gives a scalar result.
sinh
sinh(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The hyperbolic sine of each element. The static result preserves input dtype, dimensions, and domain; a scalar input gives a scalar result.
sqrt
sqrt(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The nonnegative square root of each nonnegative element. The static result preserves input dtype, dimensions, and domain; a scalar input gives a scalar result.
tan
tan(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The tangent of each element; angles are in radians. The static result preserves input dtype, dimensions, and domain; a scalar input gives a scalar result.
tanh
tanh(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The hyperbolic tangent of each element. The static result preserves input dtype, dimensions, and domain; a scalar input gives a scalar result.
trunc
trunc(value: Floating, /) -> FloatingParameters. value is a floating scalar or field.
Returns. The integer-valued floating value obtained by truncation toward zero. The static result preserves input dtype, dimensions, and domain; a scalar input gives a scalar result.
Notes. The result keeps its floating dtype. Use astype for an integer dtype.
Conversion and selection
astype
astype(value: Scalar | Field | TupleValue, type_: type, /) -> Scalar | Field | TupleValueConverts values to an explicit dtype.
Parameters. value is a scalar, field, or recursively nested tuple.
type_ is the destination scalar type.
Returns. A value with every primitive leaf converted to type_. Field
dimensions/domains and tuple structure are preserved. Scalar leaves remain
scalar; field leaves remain field-valued.
Constraints. Named collections lack the corresponding generic frontend acceptance. Conversion does not add dimensions, extend a domain, or repair an invalid input read. Allocation/copy identity is not part of this expression’s contract. Exceptional/narrowing casts have backend-dependent edge behavior.
See also. Scalar construction, type promotion.
Interpretation used (C13, C19). Conversion is specified for scalars, fields, and recursive tuples, subject to dtype/backend coverage. Named-product support in selection functions does not extend to astype.
Interpretation used (C14). Exceptional and narrowing conversions remain backend-dependent; no uniform overflow or cast-edge rule is added here.
broadcast
broadcast(field: Scalar | Field, dims: tuple[Dimension, ...], /) -> FieldAdds coordinate-independent dimensions to a value.
Parameters. field is a scalar or field. dims is the exact ordered target
dimension tuple and contains every input dimension.
Returns. A field with the input dtype and target dimensions. At coordinate
p, the value is the input at the projection of p onto its input dimensions.
Added axes introduce no coordinate dependence. broadcast(value, ()) has a
zero-dimensional field type.
Errors. Dropping an input dimension or supplying invalid dimensions is not an admissible broadcast.
Current limitations. The embedded scalar implementation returns the original scalar as a representation shortcut. Subsequent output assignment may produce the expected values, but field-only behavior of that intermediate result is not uniform. This does not relax the static field result or target-dimension rule.
Interpretation used (C7). The abstract result is a constant field along added dimensions. The embedded scalar shortcut is recorded as a representation limitation, not a guarantee that subsequent field-only operations work uniformly.
where
where(mask: Field[..., bool], true_field: Scalar | Field | Product,
false_field: Scalar | Field | Product, /) -> Field | ProductSelects values elementwise using a boolean field.
Parameters. mask is a boolean field. The two branches have matching
product structure and equal dtypes at corresponding leaves. Named products
also match named type. Scalar branches are permitted; a scalar mask is not the
ordinary frontend mask contract.
Returns. A field at each primitive result leaf, with dimensions promoted
from that branch pair and the mask. Select true_field wherever the mask is
true and false_field elsewhere. Scalar branch leaves become field-valued.
Corresponding branches need equal dtypes, but different leaves of one tuple may
have different dtypes.
Notes. The branch expressions must be valid over their required common domain. There is no guarantee of short-circuit evaluation or protection from invalid shifted reads in an unselected branch. Use concat_where when selecting coordinate regions with differing branch coverage.
Source: builtins, typing, and selection semantics.
Interpretation used (C3). Only dimensions promote. Each true/false leaf pair must have the same dtype; distinct leaf pairs may have different dtypes. Convert explicitly with astype when needed.
Interpretation used (C19). Matching supported named products are accepted here, without implying that other builtins accept the same structures.
Connectivity and remapping
Connectivity
Connectivity[Dims[...], Dimension]An integer-valued coordinate map with a domain and a codomain dimension.
Connectivity is a protocol; use as_connectivity for table data.
Applying a connectivity to a field substitutes its integer values for the
field’s codomain coordinate. Unaffected field dimensions survive.
Neighbor-table providers use an origin/location dimension and a local slot
dimension as their domain, and the neighbor-location dimension as codomain.
skip_value identifies an absent entry; ordinary dereferences require valid
entries. Duplicated neighbor entries retain their multiplicity.
Interpretation used (C4, C10). Runtime providers map tags to neighbor tables, and executable missing-neighbor metadata uses -1 or None. Historical dimension-valued providers and arbitrary accepted sentinel metadata are not treated as the current execution contract.
CartesianConnectivity
CartesianConnectivity(domain_dim: Dimension, offset: int = 0, *,
codomain: Dimension | None = None) -> ConnectivityParameters. domain_dim is the result-coordinate dimension. offset is
the integral displacement applied to its index. codomain is the input-field
dimension, defaulting to domain_dim.
Returns. The map i -> i + offset, optionally relabeling the dimension.
It represents a translation without a material neighbor table. Array-conversion
methods are not supported by this symbolic connectivity. In DSL expressions,
prefer dimension shift notation described below.
FieldOffset
FieldOffset(value: str, source: Dimension,
target: tuple[Dimension] | tuple[Dimension, Dimension]) -> FieldOffsetDeclares a named remapping.
Parameters. value is the offset-provider tag. source is the dimension
read in the input field. target is the replacement dimension tuple in the
result. For a neighbor offset (A,L), L must have kind LOCAL.
Returns. A declaration resolved against the runtime offset provider when used in a computation.
Notes. This source is the table’s codomain, not its origin dimension.
For example, FieldOffset("E2C", source=Cell, target=(Edge,E2CDim)) reads cell
values and produces edge/local-slot values. The provider table maps
(Edge,E2CDim) to Cell. Current Cartesian dimension shifts are self-contained
and do not require dimension-valued provider entries.
Interpretation used (C4). Named neighbor offsets resolve through table-valued provider entries. Cartesian dimension shifts carry their own meaning and need no historical dimension-valued provider entry.
Indexed single-target FieldOffset retains legacy tagged-provider behavior;
frontend acceptance does not make it equivalent to a self-contained Cartesian
shift. Use field(I+n) or field(I-n) for fixed Cartesian shifts. A
single-target declaration used by as_offset is a separate supported form.
Field remapping
field(connectivity, *additional_connectivities) -> Field
field(offset) -> Field
field(offset[q]) -> FieldParameters. The connectivity’s codomain must be a dimension of field.
For neighbor offset O with provider table C[A,L], bare O selects every
neighbor slot; O[q] selects fixed slot q.
Returns. For bare neighbor access, field(O)(a,l,...) = field(C[a,l],...):
replace the input location dimension by (A,L). For a fixed slot, remove L
and return field(C[a,q],...). field[LocalDim(q)] similarly selects a slot
from an already local/sparse field.
Constraints. A dereferenced neighbor must be valid and within input bounds; there is no value assigned to an ordinary skipped-neighbor read. A remap creating a local dimension allows only one remapping argument. Fixed neighbor remaps may compose; general dynamic unstructured slot selection is not an established operation. Single-target Cartesian offset declarations cannot be used as bare all-neighbor offsets. Their indexed form is accepted by parts of the frontend but retains legacy tagged-provider execution limitations.
Interpretation used (C4). Use dimension arithmetic for fixed Cartesian shifts; indexed single-target FieldOffset is not an equivalent portable, self-contained spelling. This does not restrict single-target declarations used by as_offset.
Interpretation used (C10, C18). Missing-neighbor metadata is limited to -1 or None, and ordinary reads still require a valid neighbor. Tested fixed remaps do not establish support for arbitrary dimension-changing remap combinations.
Cartesian shift expressions
field(I + n) -> Field
field(I - n) -> FieldParameters. I is the result dimension and n is a fixed displacement:
an inline literal, or an attribute of a FrozenNamespace or Enum constant
namespace that closure folding replaces with a literal. A plain captured integer
such as SHIFT = 1 is rejected. Integral displacement reads the
same dimension; half-integral displacement reads its staggered counterpart.
A runtime displacement field uses as_offset.
Returns. For an integral shift, result coordinate i reads input i+n,
and the corresponding input interval is translated by -n. For a half-integral
shift h, the input integer index is i + floor(h) + 1 when the result
dimension is nonstaggered, and i + floor(h) when it is staggered. Other
fractional parts are rejected.
Current limitations. Multiple fixed Cartesian shifts preserve dimensions and can appear together. Dimension-changing combinations, including multiple staggered remaps, need additional validation because result typing does not uniformly incorporate every remapping.
Example. A neighboring sum with explicit input coverage:
import numpy as np
import gt4py.next as gtx
I = gtx.Dimension("I")
@gtx.field_operator
def adjacent_sum(a: gtx.Field[gtx.Dims[I], gtx.float64]):
return a + a(I + 1)
a = gtx.as_field([I], np.arange(4, dtype=np.float64))
out = gtx.zeros({I: 3})
adjacent_sum(a, out=out)
np.testing.assert_array_equal(out.asnumpy(), [1.0, 3.0, 5.0])Source: connectivity model, FieldOffset, and remapping specification.
Interpretation used (C18). Multiple dimension-preserving fixed shifts retain their established behavior. Multi-axis staggering and other dimension-changing combinations are not generalized from those cases because result typing can omit later remaps.
Neighbor reductions
These operations reduce one local neighbor axis with a known connectivity
association. Their results remove that axis and retain other dimensions.
Use axis= explicitly in captured code: the Python signature permits a
positional axis, but frontend reduction handling requires the keyword.
Missing neighbors are excluded. Each valid slot contributes once, even if multiple slots reference the same neighbor. These functions do not define arbitrary global reductions over horizontal/vertical axes. The frontend’s axis-presence check is broader than the local-axis execution contract. Standalone external sparse/local fields cannot generally be reduced without shifted-neighborhood evidence for compiled unrolling.
Interpretation used (C8). The following three functions reduce a LOCAL neighborhood axis with known connectivity association, using axis=. Weaker frontend acceptance does not establish global-axis or standalone sparse-only reductions.
neighbor_sum
neighbor_sum(field: Field, /, axis: Dimension) -> FieldParameters. field contains the local axis axis and the neighborhood
association needed by the backend.
Returns. The sum of valid neighbor-slot values at every remaining coordinate. The static dtype is preserved; the selected dimension is removed. Lowering uses a typed zero initial value.
Current limitations. Array-library accumulation may widen integer dtype. Do not infer a general cross-mode accumulator dtype from frontend result typing.
Interpretation used (C9). Sum retains its input static dtype and typed-zero lowering seed. Actual integer accumulation can widen in embedded execution; an explicit uniform accumulator-dtype policy remains a proposal.
max_over
max_over(field: Field, /, axis: Dimension) -> FieldParameters. field and axis satisfy the common reduction requirements.
Returns. The maximum valid neighbor value at every remaining coordinate, with the input static dtype and the local axis removed.
Current limitations. Lowering seeds with the dtype’s finite minimum, whereas embedded skip handling uses a global input extremum. All-skipped neighborhoods and all-negative-infinity neighborhoods need not agree. NaN handling has no uniform contract.
Interpretation used (C9). The maximum rule describes ordinary nonempty finite neighborhoods. All-skipped, all-negative-infinity, and NaN cases retain the observed mode differences; the proposed uniform negative-infinity seed is not current behavior.
min_over
min_over(field: Field, /, axis: Dimension) -> FieldParameters. field and axis satisfy the common reduction requirements.
Returns. The minimum valid neighbor value at every remaining coordinate, with the input static dtype and the local axis removed.
Current limitations. Lowering seeds with the dtype’s finite maximum, whereas embedded skip handling uses a global input extremum. All-skipped neighborhoods and all-positive-infinity neighborhoods need not agree. NaN handling has no uniform contract.
Interpretation used (C9). The minimum rule describes ordinary nonempty finite neighborhoods. All-skipped, all-positive-infinity, and NaN cases retain the observed mode differences; the proposed uniform positive-infinity seed is not current behavior.
Neighbor reduction example
import numpy as np
import gt4py.next as gtx
from gt4py.next import neighbor_sum
Cell = gtx.Dimension("Cell")
Edge = gtx.Dimension("Edge")
E2CDim = gtx.Dimension("E2C", kind=gtx.DimensionKind.LOCAL)
E2C = gtx.FieldOffset("E2C", source=Cell, target=(Edge, E2CDim))
@gtx.field_operator
def sum_adjacent_cells(a: gtx.Field[gtx.Dims[Cell], gtx.float64]):
return neighbor_sum(a(E2C), axis=E2CDim)
table = gtx.as_connectivity([Edge, E2CDim], Cell, np.array([[0, 1], [1, 2]], dtype=np.int32))
a = gtx.as_field([Cell], np.array([2.0, 3.0, 5.0]))
out = gtx.zeros({Edge: 2})
sum_adjacent_cells(a, out=out, offset_provider={"E2C": table})
np.testing.assert_array_equal(out.asnumpy(), [5.0, 8.0])Support notes. Some paths resolve reduction connectivity by local dimension name, while others use the offset tag. Equal tag/local names avoid that specific difference. Sparse output writes and sparse-only reductions have additional backend exclusions. See reduction semantics and the backend matrix.
Computation definitions
All definition functions consume Python functions whose source is retrievable. Annotations, source names, and captured constants are resolved at frontend construction, including when selecting embedded execution. The supported parameter declaration subset is annotated ordinary positional-or-keyword parameters with all argument values supplied. Full Python support for defaults, positional-only, keyword-only, and variadic declarations is not established.
Use immutable captured configuration and explicit parameters for changing data. Recursive closure collection also rejects unequal same-named captures in a parent and referenced child, even if both are immutable. Distinct capture names or explicit parameters avoid that restriction. Some source capture is cached; changing a Python global does not have a uniform cross-mode invalidation rule.
Interpretation used (C1, C12). The definitions below decorate Python functions, using the supported ordinary annotated parameter subset. Historical AST-root entry points and full Python declaration flexibility are not the current contract.
Interpretation used (C11). Captured values are immutable configuration and changing data are explicit arguments. Distinct names or parameters avoid unequal same-named captures across composed definitions. No common snapshot or mutation-invalidation policy is assumed.
field_operator
field_operator(definition=None, *, backend=<default-backend>, grid_type=None,
**compilation_options) -> FieldOperator | decoratorDefines a pure computation on scalar/field values.
Parameters. definition is an annotated Python function, supplied directly
or by decorator syntax. backend is a backend object or explicit None for
embedded execution; omission selects the configured default. grid_type
selects or requests inference of grid constraints. Supported compilation options
are described under with_compilation_options.
Returns. A field-operator object, or a decorator awaiting the definition. Its definition returns a scalar, field, or supported product internally. An optional return annotation must match the inferred type exactly.
Body requirements. Assignments bind local values and may rebind names; they do not mutate field storage. Every reachable path returns a value, with matching return types. Ordinary function/operator definition names cannot shadow reserved DSL builtin names. Source-captured callable references must be lowerable DSL callables; arbitrary Python callbacks are not supported.
Invocation. Inside another operator, an expression call returns its value.
At a host entry point or in a program, provide out= matching field result
leaves. A scalar result is not a general substitute for a Field output; use
broadcast to make a statically field-valued result.
scan_operator
scan_operator(definition=None, *, axis: Dimension, forward: bool = True,
init=0.0, backend=<default-backend>, grid_type=None)
-> FieldOperator | decoratorLifts a scalar recurrence over columns of a vertical dimension.
Parameters. axis has kind VERTICAL. forward=True traverses increasing
indices; False traverses decreasing indices. init is the initial carry.
The definition’s first parameter is the carry; its type, the return type, and
init agree exactly. The default init=0.0 therefore fits only a scalar
float64 carry; integer, differently typed, or product carries need an explicit
compatible init. Carry values may be scalar or supported scalar products.
The remaining parameters receive the per-point input values.
Returns. A scan operator using the field-operator invocation protocol.
At invocation, omit the carry argument; scalar recurrence parameters accept
matching scalar/field leaves. Result scalar leaves are lifted to fields over
the merged invocation dimensions plus axis. The axis is included even when
absent from input fields.
Semantics. For requested interval [l,u) and each orthogonal coordinate:
forward: carry = init
for k in l, ..., u-1:
carry = definition(carry, inputs_at_k...)
result_at_k = carry
backward: carry = init
for k in u-1, ..., l:
carry = definition(carry, inputs_at_k...)
result_at_k = carryThis pseudocode specifies evaluation order, not permitted Python loop syntax
inside the definition. The scan is inclusive and resets init for every
column and invocation, including a subdomain. The output/domain context
supplies the scan interval.
Current limitations. All scans in one lowered program share an axis.
General horizontal/local scans, per-point initial state, arbitrary nested scan
bodies, and multi-axis scans are not portable features. Some scalar-only scans
lack embedded support. The decorator does not accept the compilation-option
keywords of field_operator; configure the resulting object’s methods instead.
Interpretation used (C2). Embedded scans require one shared domain/column interval, including when called from a program. Explicit per-leaf domain tuples can fail; use a shared domain or separate invocations.
Interpretation used (C20). Direct scans support invocation/JIT but cannot be explicitly precompiled through .compile(). Wrap a scan in a program with concrete field annotations and compile that program for ahead-of-time use.
Example.
import numpy as np
import gt4py.next as gtx
K = gtx.Dimension("K", kind=gtx.DimensionKind.VERTICAL)
@gtx.scan_operator(axis=K, forward=True, init=0.0)
def prefix_sum(carry: float, x: float) -> float:
return carry + x
x = gtx.as_field([K], np.array([1.0, 2.0, 3.0]))
out = gtx.zeros({K: 3})
prefix_sum(x, out=out)
np.testing.assert_array_equal(out.asnumpy(), [1.0, 3.0, 6.0])program
program(definition=None, *, backend=<default-backend>, grid_type=None,
**compilation_options) -> Program | decoratorDefines an ordered sequence of output-writing operator calls.
Parameters. definition, backend, grid_type, and compilation options
have the corresponding field_operator meanings.
Returns. A program object, or a decorator awaiting the definition.
Calling a program writes its output arguments and returns None.
Body requirements. A program contains direct field/scan-operator calls with
out=, optionally domain= or restricted output slices. Statements execute in
source order, so later calls observe earlier writes. Programs do not introduce
local assignment, branches, loops, value returns, or calls to other programs.
Full field expressions are placed inside field operators. Restricted scalar
arithmetic and minimum/maximum may occur in program call/domain arguments.
Example.
import numpy as np
import gt4py.next as gtx
I = gtx.Dimension("I")
@gtx.field_operator
def twice(a: gtx.Field[gtx.Dims[I], gtx.float64]):
return a + a
@gtx.program
def apply_twice(
a: gtx.Field[gtx.Dims[I], gtx.float64],
out: gtx.Field[gtx.Dims[I], gtx.float64],
):
twice(a, out=out, domain={I: (1, 3)})
a = gtx.as_field([I], np.array([1.0, 2.0, 3.0, 4.0]))
out = gtx.full({I: 4}, -1.0)
apply_twice(a, out)
np.testing.assert_array_equal(out.asnumpy(), [-1.0, 4.0, 6.0, -1.0])Statements and control flow
| Form | Field/scan operator body | Program body |
|---|---|---|
| Local assignment, tuple unpacking | Supported; value bindings, no field stores | Not supported |
| Local annotated assignment | Partial: names must be DSL builtins or captured values | Not supported |
Chained assignment b = c = a | Not supported; fails at decoration | Not supported |
return expression | Required on all reachable paths; common return type | No value return |
if/elif/else, conditional expression | Scalar bool condition; branches statically checked; matching result types | Not supported |
| Elementwise conditional | where with bool Field mask | Put in a field operator |
for, while, comprehensions, generators | Not supported | Not supported |
and, or, chained comparisons | Not supported; use parenthesized comparisons with boolean &/| | Not general program expressions |
| Augmented assignment, attribute/subscript stores | Not supported | Writes through operator out= only |
| Imports, nested ordinary functions, lambdas, exceptions, context managers, assertions, classes, pattern matching | Not supported in captured bodies | Not supported in captured bodies |
if selects a scalar branch; both branches must still be statically valid.
Zero-dimensional bool fields are fields and cannot control if. Locals after
branches must be valid on the relevant paths according to binding/type analysis.
Docstrings are removed during parsing; pass is a no-op in field-operator bodies.
Local annotations are evaluated only against DSL builtins and captured closure
variables, so Dims, a gtx. prefix, or a dimension used only in the annotation
can raise NameError at decoration; prefer inferred bindings.
The formal grammar describes the
supported subset in more detail.
Source: decorators, field parser, and program parser.
Invocation and execution
Operator calls
operator(*args, out: Output, domain=<omitted>, offset_provider=<omitted>,
enable_jit=None, **kwargs) -> None
operator(*args, **kwargs) -> DSL value # inside an operator bodyThese are supported call forms; the wrapper’s Python implementation uses
**kwargs to receive out, domain, and offset_provider.
Parameters. args and ordinary kwargs bind the definition’s parameters.
out receives field-valued result leaves and matches dtype, dimensions, and
collection structure. domain restricts writes. An omitted offset_provider
becomes an empty mapping; an explicitly supplied operator provider must be a
mapping, so None is not equivalent. enable_jit overrides whether a missing
compiled variant may be created, otherwise following configured options.
Returns. None for output-writing calls. Expression calls inside another
operator return the DSL value and inherit the enclosing execution context.
Host operator calls require out even in embedded mode.
Interpretation used (C1, C4). Host calls require out and permit explicit domain=. An omitted provider means {}; an explicitly supplied provider must be a mapping. The historical mandatory-provider and domain-prohibition descriptions are not used.
Interpretation used (C21). Matching argument and output types are caller obligations. Direct field-level embedded operator calls bypass some runtime type checks and can execute invalid calls or cast on assignment; this is not a supported coercion API.
Interpretation used (C22). Omit domain to infer writes from outputs. Explicit domain=None acts like omission only in field-level embedded execution; compiled operator host calls reject it during domain conversion.
Program calls
program_object(*args, offset_provider=None, enable_jit=None, **kwargs) -> NoneParameters. args/kwargs bind the program’s declared arguments.
Output fields are program parameters used by its body; there is no universal
extra out parameter independent of the definition. Omitted or explicit
None provider becomes {}. A neighbor computation needs all referenced
offset tables. enable_jit has the same override meaning as for operator calls.
Returns. None, after performing the program’s writes.
Interpretation used (C4). Omitted and explicit None providers both mean {} for programs. Referenced neighbor offsets still require tables; the operator-call restriction on explicitly supplied None does not apply here.
Output-domain rules
| Selection | Meaning |
|---|---|
Explicit program domain={d: (start,stop), ...} | Absolute half-open bounds; nonempty dictionary with integral bounds, matching output dimensions in order |
| Output slice | Relative literal bounds on the current output field; steps omitted, one slice per dimension |
| Domain tuple | Recursively corresponding per-leaf output domains; embedded scans require a shared domain instead |
| Omitted domain in lowered execution | Each output leaf supplies its own domain |
| Omitted domain in field-level embedded execution | Intersection of all output-leaf domains |
A program cannot combine sliced outputs with explicit domain=. For output
bounds [a,b), nonnegative slice bound n means a+n; negative n means
b+n. An omitted bound selects the corresponding endpoint. A dictionary in a
nested domain tuple is not a general replacement for a nested tuple of domains.
Host domain conversion forms are broader than captured program dictionary syntax.
An outer single domain dictionary may apply to every matching output leaf.
Slice bounds must be integer literals (including supported negative literals)
or omitted, not runtime names or expressions such as 1+1. For runtime bounds,
use an explicit absolute domain such as domain={I: (0,n)}; account for nonzero
logical origins when replacing a relative slice.
Current limitations. Unequal tuple-output extents with an omitted domain can produce different writes between modes. Use equal domains or, for ordinary field operators, explicit per-leaf domains to avoid that difference. Embedded scans require a single shared domain/column interval and can fail on domain tuples, including when called from a program. Local/sparse output dimensions have lowering/backend restrictions. No domain rule allocates missing halos or specifies arbitrary overlapping output writes.
Interpretation used (C1, C15). Explicit absolute domains and relative output slicing are current alternatives, subject to the combination restriction above. Captured domain dictionaries retain the output-dimension key-order constraint.
Interpretation used (C2). Per-leaf domains are the model for explicit multiple-output selection. The distinct omitted-domain rules of lowered and embedded execution remain documented behavior. Equal domains or explicit per-leaf tuples avoid the default-mode disagreement for ordinary field operators; there is no blanket same-shape requirement. Embedded scans instead need a shared domain or separate invocations.
Interpretation used (C18). Domain selection does not establish snapshot semantics for overlapping inputs or outputs. The aliasing limits under indexing and writes still apply.
Backends
| Selection | Execution |
|---|---|
None | Field-level embedded execution of the original Python definitions over registered field implementations |
gtx.itir_python | Lowering followed by roundtrip execution of iterator IR in Python |
gtx.gtfn_cpu | GridTools native CPU backend |
gtx.gtfn_gpu | GridTools GPU backend |
Other Backend object | The selected backend’s transformation/execution pipeline |
Pass backend objects rather than name strings. A nested operator uses its caller’s execution context; its configured backend applies at its own host entry point. These backends differ in supported features and numerical cases; Python roundtrip is distinct from field-level embedded execution.
Interpretation used (C17). Backend selectors are objects (or None), not historical string names. Internal iterator execution and representation choices do not add Python DSL primitives or tuple-valued field elements.
with_backend
entry.with_backend(backend: Backend | None) -> configured copyParameters. backend is the desired backend object or None.
Returns. A configured copy of the program/operator. It does not submit a compilation by itself.
Interpretation used (C17). Pass a backend object or None; docstring examples using backend-name strings are treated as historical examples rather than an accepted selector interface.
with_grid_type
entry.with_grid_type(grid_type: GridType) -> configured copyParameters. grid_type selects Cartesian or unstructured constraints.
Returns. A program/operator copy configured with that grid type. An incompatible explicit grid selection is an error.
with_compilation_options
entry.with_compilation_options(**compilation_options) -> configured copyParameters. Supported options are:
| Option | Meaning |
|---|---|
enable_jit: bool | Allow compilation of missing variants during a call; initial policy comes from configuration |
static_params: sequence[str] | Names of scalar arguments to specialize |
static_domains: bool | Specialize field bounds; default false |
connectivities: OffsetProvider | Connectivity configuration available to compilation workflows |
Returns. A configured copy. These options affect staging/execution; they do not add DSL syntax or change an expression’s defined mathematical value.
Interpretation used (C20). For explicit compilation, configured connectivities must supply runtime neighbor tables (or {} when none are needed). Nonempty provider-type-only mappings are rejected despite broader annotations.
with_static_params
program_object.with_static_params(*static_params: str | None) -> ProgramParameters. Names of scalar parameters to specialize. No arguments, or a
single None, clears the set; otherwise use parameter names.
Returns. A configured program copy.
with_bound_args
program_object.with_bound_args(**kwargs) -> ProgramWithBoundArgsParameters. Scalar program arguments to bind by name.
Returns. A program with a reduced call interface. Unknown parameter names
and supplying an already bound argument again are errors. Explicit .compile()
on this bound-program wrapper is currently unimplemented.
compile
entry.compile(offset_provider=None, **static_args) -> same entrySubmits variants to the entry point’s compiled-program pool.
Parameters. offset_provider is a runtime neighbor-table mapping, or a list
of such mappings. Supply a mapping (possibly {} when no tables are needed)
unless connectivity configuration supplies it. Each static_args value is a
list of candidate scalar/product values; combinations form specialized variants.
The entry must have a non-None backend.
Returns. The same object, with variants added to its pool; this differs
from the configured-copy behavior of with_* methods.
Errors. Compiling without a backend raises RuntimeError. Missing
connectivity/provider information raises ValueError; non-list static argument
values raise TypeError. If JIT is disabled, subsequent invocation needs a
matching compiled variant.
Interpretation used (C20). Nonempty provider type descriptors are currently rejected with ValueError, despite their accepted annotation. Direct scan operators also cannot be precompiled through this interface, which does not supply their required argument types. For ahead-of-time scan compilation, compile a wrapping program with concrete field annotations; direct scan invocation/JIT remains available.
wait_for_compilation
wait_for_compilation() -> NoneReturns. None after all tracked submitted compilations finish.
This is the namespace-level gtx.wait_for_compilation() function.
Errors. Failed compilation exceptions are surfaced; multiple failures can be grouped. Waiting does not itself execute the resulting programs.
Source: entry points, compilation options, and compiled variants.
Experimental functions
Import these names from gt4py.next.ffront.experimental outside the captured
function, then use directly bound names inside it. Their accepted type forms
are broader than uniformly executable cases.
as_offset
as_offset(offset: FieldOffset, field: Field, /) -> ConnectivityConstructs a coordinate-dependent Cartesian displacement for field remapping.
Parameters. offset is a single-target Cartesian offset with equal source
and target dimension d. field has integral dtype and contains d; its values
are the displacements at each result coordinate.
Returns. A connectivity for which a(as_offset(offset,q))(p) reads
a at the coordinate obtained by replacing p[d] with p[d] + q(p).
All selected input coordinates must exist.
Current limitations. General dynamic unstructured neighbor selection is not established. Extra dimensions on the displacement field are not consistently reflected in static result typing. Check the selected backend’s dynamic-offset support and transitive halo requirements.
Interpretation used (C18). The coordinate-dependent displacement meaning is retained, but extra displacement dimensions are not promised to propagate correctly through remap typing. Complete dimension deduction is a proposed future rule, not an assumption of this entry.
concat_where
concat_where(domain: Domain, true_field: Scalar | Field | Product,
false_field: Scalar | Field | Product, /) -> Field | ProductAssembles values selected by coordinate region.
Parameters. domain is a one-dimensional region for the common embedded
contract. Branches have matching structure and corresponding dtypes, with
dimension broadcasting. They need only cover their selected contributions.
Returns. At coordinates in domain, select the true branch; elsewhere
select the false branch. Let d be the region dimension, T and F the branch
domains, and Q their projected intersection on all dimensions except d:
Q = projection_except_d(T) ∩ projection_except_d(F)
result_domain = Q ∩ ((T ∩ domain) ∪ (F ∩ complement(domain))).Extend Q without restriction along d for the final intersection. Missing
branch dimensions broadcast; products are processed leafwise. Orthogonal
intersection occurs before concatenation, so differently bounded branches do
not create an arbitrary nonrectangular union.
Region expressions. With n of IndexType (int32), d < n, d <= n,
d > n, d >= n, and d == n select their corresponding integer-coordinate
intervals. d != n selects a complement with a gap and is frontend syntax with
backend-specific support: field-level embedded execution raises
NotImplementedError when evaluating the condition, before concat_where runs.
Use concat_where(d < n, t, concat_where(d > n, t, f)) for the same selection.
Chained comparisons are rejected; parenthesized region combinations have
frontend typing but not uniform execution support.
Errors and limitations. Embedded execution requires a one-dimensional
condition and a contiguous resulting domain. Interior gaps raise
NonContiguousDomain. Some disjoint/multidimensional conditions pass frontend
typing but cannot execute embedded. Empty branches, scalar/unbounded broadcasts,
and more elaborate region combinations have feature-specific exclusions.
Example. The result intersects the orthogonal J ranges:
import numpy as np
import gt4py.next as gtx
from gt4py.next.ffront.experimental import concat_where
I = gtx.Dimension("I")
J = gtx.Dimension("J")
t = gtx.as_field({I: (0, 1), J: (0, 3)}, np.ones((1, 3), dtype=np.float64))
f = gtx.as_field({I: (1, 2), J: (1, 4)}, np.zeros((1, 3), dtype=np.float64))
result = concat_where(I < 1, t, f)
assert result.domain == gtx.domain({I: (0, 2), J: (1, 3)})
np.testing.assert_array_equal(result.asnumpy(), [[1.0, 1.0], [0.0, 0.0]])Source: experimental definitions, embedded implementation, and concat limitations.
Interpretation used (C16). The shared execution contract uses a one-dimensional condition and contiguous result. Disjoint or multidimensional expressions accepted by typing remain backend-specific rather than part of that common subset.
Interpretation used (C19). Matching supported named products are selected leafwise here. This structure support does not imply named-product conversion support in astype.
Errors and support
Validation
Invalid syntax, unresolved names, annotation mismatches, incompatible dtypes,
invalid dimensions, and invalid calls are rejected by the DSL frontend with
DSLError or a subclass. The diagnostic includes source information when
available. Host constructors and execution controls may raise ordinary Python
exceptions. Some accepted-but-unimplemented paths fail later with assertions
or NotImplementedError; frontend acceptance alone is not a support test.
See the diagnostic guide and unsupported syntax.
Numerical support
The static dtype rules are specified above. Current implementations do not establish a complete uniform contract for integer division, overflow/narrowing, negative modulo, exceptional scalar arithmetic, NaN/signed-zero selection, extreme/empty reductions, or floating-point reassociation. Some division-by-zero tests permit either IEEE values or exceptions. Do not assume the special cases or accuracy requirements of the Array API standard merely from a shared function name.
Interpretation used (C9, C14). Static types and ordinary mathematical results are retained while unsettled runtime edge cases remain explicit. Uniform reduction identities, accumulator dtypes, and numerical special-case rules are recommendations in the companion, not guarantees added by this API page.
Backend support and related specification
Use feature exclusions together with frontend feature tests for backend support. Iterator-only facilities are outside this API. Allocator, cache, runner, and backend workspace management are host infrastructure.
The companion specification records the evidence and interpretation of current disagreements:
- Dtype, power, boolean, and broadcast rules.
- Output domains and aliasing.
- Closure capture and composition.
- Reduction semantics.
- Experimental region semantics.
- Repository evidence and focused observations.
This page is a reference for the reviewed checkout. It is not a new public API, a backend conformance certification, or an adoption of the companion’s proposed future resolutions.