Is your feature request related to a problem? Please describe.
Docstrings o the original Fortran code often include intent (in, out, inout) of fields that are read and/or written in a stencil. When naively ported to NDSL, these end up in stencil docstrings e.g.
def tridiag_solve(
a: FloatField,
b: FloatField,
c: FloatField,
d: FloatField,
x: FloatField,
delta: FloatField,
) -> None:
"""
This stencil solves a square, k x k tridiagonal matrix system
with coefficients a, b, and c, and vectors p and d using the Thomas algorithm:
Args:
a (in): lower-diagonal matrix coefficients
b (in): diagonal matrix coefficients
c (in): upper-diagonal matrix coefficients
d (in): Result vector
x (out): The vector to solve for
delta (out): d post-pivot
"""
...This causes issues with python docstrings because (in) and (out) above are captured as Google-style type annotation, thus overriding the type of a from FloatField to in:
.
Describe the solution you'd like
We'd like to preserve the type as well as the intent of field arguments to stencils. The current idea is to augment the NDSL-type system to include something like In[FloatField], Out[FloatField], InOut[FloatField] when fields get passed to stencils.
The feature would be opt-in initially: users could continue to pass FloatFields. The intent would be striped at the NDSL-level such that no changes are required in gt4py.
Down the line, we could see consistency checks by passing the intended read/write information down to GT4Py.
Describe alternatives you've considered
We've discussed dropping the intent and discarded the idea because stencils can have many arguments and the prospect of being able to check consistency in the future is appealing.
Naming is always something that can be discussed. Other languages, e.g. C / C++, know this concept as const correctness. While python has support for Final variables and class members, Final is explicitly not defined/implemented for function arguments, further reading:
I suggest, we play the DSL card here and go with in/out/inout as "known slang in the domain". in/out/inout is so far away from const/final that - if python typing ever gets to this point - we can probably change to the python solution without breakage within a deprecation period (if we feel it's appropriate to do so).
Additional context
The above example was taken from PR #381, which "fixed" the docstrings at the cost of removing the intent.
Is your feature request related to a problem? Please describe.
Docstrings o the original Fortran code often include intent (in, out, inout) of fields that are read and/or written in a stencil. When naively ported to NDSL, these end up in stencil docstrings e.g.
This causes issues with python docstrings because
(in)and(out)above are captured as Google-style type annotation, thus overriding the type ofafromFloatFieldtoin:.
Describe the solution you'd like
We'd like to preserve the type as well as the intent of field arguments to stencils. The current idea is to augment the NDSL-type system to include something like
In[FloatField],Out[FloatField],InOut[FloatField]when fields get passed to stencils.The feature would be opt-in initially: users could continue to pass
FloatFields. The intent would be striped at the NDSL-level such that no changes are required in gt4py.Down the line, we could see consistency checks by passing the intended read/write information down to GT4Py.
Describe alternatives you've considered
We've discussed dropping the intent and discarded the idea because stencils can have many arguments and the prospect of being able to check consistency in the future is appealing.
Naming is always something that can be discussed. Other languages, e.g.
C/C++, know this concept asconstcorrectness. While python has support forFinalvariables and class members,Finalis explicitly not defined/implemented for function arguments, further reading:Finalin type arguments to avoid shadowing arguments - disallow reassignment of function parameters python/mypy#11076I suggest, we play the DSL card here and go with in/out/inout as "known slang in the domain". in/out/inout is so far away from const/final that - if python typing ever gets to this point - we can probably change to the python solution without breakage within a deprecation period (if we feel it's appropriate to do so).
Additional context
The above example was taken from PR #381, which "fixed" the docstrings at the cost of removing the intent.