Repository navigation
Conversation
c3c3431 to
db408a6
Compare
egparedes
left a comment
There was a problem hiding this comment.
I have some comments. Also, if possible, I would like to see nicer images for the meshes.
| import matplotlib.pyplot as plt | ||
|
|
||
| fig, axes = plt.subplots(1, 2, figsize=(9, 3.2), constrained_layout=True) | ||
| for ax, field, title in zip(axes, (phi, lap_phi), ("phi", "laplacian(phi)")): | ||
| image = ax.imshow(field.asnumpy().T, origin="lower", cmap="RdBu_r") | ||
| ax.set(title=title, xlabel="I", ylabel="J") | ||
| fig.colorbar(image, ax=ax) |
There was a problem hiding this comment.
Make sure the color map scales for the two images show the same range
| --- | ||
| laplacian_cpu = laplacian.with_backend(gtx.gtfn_cpu) | ||
|
|
||
| lap_phi_cpu = gtx.zeros(grid) |
There was a problem hiding this comment.
For performance, the backend should be passed as allocator here, so we make sure the allocation is made with the correct memory layout for this backend
| Allocate the fields with the backend which is going to run the operators. For | ||
| GPU backends it is required, since the fields must be on the device. | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Add a subsection mentioning how to allocate for embedded execution selecting the device or the actual ndarray library (e.g. cupy or jax)
| ```{figure} ../images/connectivity_numbered_grid.svg | ||
| --- |
There was a problem hiding this comment.
Can we generate nicer looking images for meshes in general?
| ``` | ||
|
|
||
| ### Connectivities and offsets | ||
|
|
There was a problem hiding this comment.
Add an important note here mentioning that we are currently working on a new iteration of the connectivities and offsets concepts explained here to make simpler and more user-friendly, so this part may change soon.
| Operators can refer to objects defined outside them: dimensions, other | ||
| operators and scalar constants. | ||
|
|
||
| ```{code-cell} ipython3 |
There was a problem hiding this comment.
Double check if this is really true. Don't we need to add a Final decoration or use a tuple or FrozenNamespace? In any case, emphasize that this inlines the value of the constant at compilation time for compiled backends.
| after the operator has been compiled may have no effect. | ||
| ``` | ||
|
|
||
| ## Named collections |
There was a problem hiding this comment.
Add also an example with a dataclass
| - The class must be defined at module level, not inside a function. | ||
| - Dataclasses are accepted when all their members are set by the constructor and | ||
| none of them has a default value. | ||
|
|
There was a problem hiding this comment.
Add also a note mentioning that support for other kind of static pytrees will be probably added in the future
|
|
||
| ## States with several values | ||
|
|
||
| When several quantities are carried from level to level, the state is a tuple, |
There was a problem hiding this comment.
Make an example using a named collection class for the state with several states, since it looks much nicer and it is the recommended pattern to follow in this cases
There was a problem hiding this comment.
Make sure it is clear that programs are at the interface of the DSL so programs store the results of the field operators calls by writing in place on its program arguments. This is done mostly for supporting interoperability with frameworks which need to own their buffers memory instead of relying on gt4py allocation
Replace the placeholder page of the `next` subsite with documentation written from scratch as executed MyST notebooks: - Landing page and quickstart. - Grids and fields: dimensions, domains, allocation, unstructured meshes. - The DSL: field operators, shifts and neighbors, scan operators, programs. - Running operators and programs: embedded execution, compiled backends, compilation in advance and static parameters. - Three worked examples checked against NumPy. The `test_examples` nox session runs all the executable pages.
- Quickstart: same color scale in both plots, fields allocated for the backend. - Grids and fields: allocation for embedded execution (array library, device), note on the upcoming rework of connectivities and offsets. - Field operators: constants in a FrozenNamespace (plain globals are rejected by compiled backends), tuple arguments, dataclass collections, notes. - Scan operators: named collection as state. - Programs: role as the interface of the DSL, writing in place. - Mesh figures regenerated with a script.
5bbef0e to
ed7488e
Compare
| immutable collection of named values: | ||
|
|
||
| ```{code-cell} ipython3 | ||
| from gt4py.eve.utils import FrozenNamespace |
There was a problem hiding this comment.
Internal import
The page teaches users to define constants with
from gt4py.eve.utils import FrozenNamespace, but gt4py.eve is the
internal IR-framework subpackage, not the public gt4py.next API. Code
written by readers following this documentation will depend on an internal
module that can be reorganized without a deprecation cycle and break their
code. If this is currently the only supported mechanism, consider
re-exporting FrozenNamespace from gt4py.next or stating its status in
the page; otherwise point readers to a public path.
There was a problem hiding this comment.
The page now says that FrozenNamespace is not exported by gt4py.next for now and has to be imported from gt4py.eve.utils (e296320). Re-exporting it from gt4py.next is an API change outside the scope of this PR.
| ```python | ||
| import gt4py.next as gtx | ||
|
|
||
| I = gtx.Dimension("I") | ||
| J = gtx.Dimension("J") | ||
|
|
||
| IJField = gtx.Field[gtx.Dims[I, J], gtx.float64] | ||
|
|
||
|
|
||
| @gtx.field_operator | ||
| def laplacian(phi: IJField) -> IJField: | ||
| return phi(I + 1) + phi(I - 1) + phi(J + 1) + phi(J - 1) - 4.0 * phi | ||
|
|
||
|
|
||
| if __name__ == "__main__": | ||
| grid = gtx.domain({I: 64, J: 48}) | ||
| phi = gtx.ones(grid) | ||
| result = gtx.zeros(grid) | ||
|
|
||
| # Run it in Python, on NumPy arrays ... | ||
| laplacian(phi, out=result, domain={I: (1, 63), J: (1, 47)}) | ||
|
|
||
| # ... or compile it to C++ | ||
| laplacian_cpu = laplacian.with_backend(gtx.gtfn_cpu) | ||
| laplacian_cpu(phi, out=result, domain={I: (1, 63), J: (1, 47)}) | ||
| ``` |
There was a problem hiding this comment.
Unexecuted example
The "This is what it looks like" snippet is a plain code block without a
jupytext header, so unlike every other page added here it is never executed
by the site build or by test_examples. As the most prominent example of
the site it can silently go out of date when the API evolves — exactly the
problem the executable-notebook setup prevents elsewhere. Consider making
the page executable, or trimming the snippet and linking to the executed
quickstart.
There was a problem hiding this comment.
Done in e296320: the landing page is now an executed notebook, so the snippet runs in the docs build and in test_examples.
PR Reviewer Guide 🔍Here are some key observations to aid the review process:
⚙️ Agent run details
|
havogt
left a comment
There was a problem hiding this comment.
Reviewed until shifts and neighbors. Now too tired to continue.
|
|
||
| ```{code-cell} ipython3 | ||
| nx, ny = 64, 48 | ||
| grid = gtx.domain({I: nx, J: ny}) |
There was a problem hiding this comment.
| grid = gtx.domain({I: nx, J: ny}) | |
| domain = gtx.domain({I: nx, J: ny}) |
There was a problem hiding this comment.
Done in e296320. I renamed the variable in the other pages too, so that the examples are consistent.
| The values are stored in a regular array, which here is a NumPy one: | ||
|
|
||
| ```{code-cell} ipython3 | ||
| type(phi.ndarray), phi.ndarray.shape, phi.ndarray.dtype | ||
| ``` |
There was a problem hiding this comment.
| The values are stored in a regular array, which here is a NumPy one: | |
| ```{code-cell} ipython3 | |
| type(phi.ndarray), phi.ndarray.shape, phi.ndarray.dtype | |
| ``` |
I don't think we want to tell people about ndarray. Maybe it should actually be _ndarray?
There was a problem hiding this comment.
Removed in e296320. ndarray is no longer mentioned anywhere in the guide.
| The points of `lap_phi` outside `interior` have not been touched. `asnumpy()` | ||
| returns the data as a NumPy array, for example to plot it. Both images use the | ||
| same color scale: | ||
|
|
There was a problem hiding this comment.
| The points of `lap_phi` outside `interior` have not been touched. `asnumpy()` | |
| returns the data as a NumPy array, for example to plot it. Both images use the | |
| same color scale: | |
| The points of `lap_phi` outside `interior` have not been touched. `asnumpy()` | |
| returns the data as a NumPy array, for example to plot it. | |
| ``` | ||
|
|
||
| No backend was selected, so this call was executed directly in Python, with the | ||
| operations on fields evaluated by NumPy. This is called **embedded** execution. |
There was a problem hiding this comment.
| operations on fields evaluated by NumPy. This is called **embedded** execution. | |
| operations on fields evaluated by NumPy. We call this **embedded** execution. |
maybe? It's kind of a definition.
|
|
||
| The same field operator can be compiled to optimized code by a **backend**. | ||
| `with_backend` returns a new version of the operator bound to that backend, here | ||
| `gtx.gtfn_cpu`, which generates C++ code using the GridTools library. The |
|
|
||
| Restricting the domain leaves the boundary points untouched. When they need a | ||
| value of their own, as in boundary conditions, use `concat_where`. It is similar | ||
| to `where`, but its condition is a **region of the grid**, written as a |
There was a problem hiding this comment.
Do we explain where? It's important to make the point that where's branches need to be defined on the common domain, while concat_where selects only from the domain (or it's inverse).
There was a problem hiding this comment.
Added in e296320 an explicit comparison: where(mask, a, b) is an operation between three fields, defined only where the mask and both branches are defined; concat_where takes each branch only in its own part of the domain and concatenates the pieces. where itself is introduced in the "Field operators" page, which is now linked from here.
|
|
||
| ### Selecting one neighbor | ||
|
|
||
| Read `E2C` as "for every edge, its cells": shifting a field with it gives a |
There was a problem hiding this comment.
Let's emphasize that you can only use this mode when the slot doesn't have skip_values. The typical example would be an edge which has always exactly 2 neighbors.
There was a problem hiding this comment.
Added in e296320 an "important" box in this section: select a neighbor by index only when every location has it (no missing entries in that column of the table), as with the two vertices of an edge; otherwise use the reductions.
| ### Composing shifts | ||
|
|
||
| The result of a shift is a regular field, which can be passed to other operators | ||
| or shifted again. This operator goes from the cells to the edges and back to the | ||
| cells: | ||
|
|
||
| ```{code-cell} ipython3 | ||
| @gtx.field_operator | ||
| def sum_over_edges(cells: CellField) -> CellField: | ||
| edge_sums = sum_of_adjacent_cells(cells) | ||
| return neighbor_sum(edge_sums(C2E), axis=C2EDim) | ||
|
|
||
|
|
||
| cell_result = gtx.zeros({Cell: 6}) | ||
|
|
||
| sum_over_edges(cell_values, out=cell_result, offset_provider=offset_provider) | ||
| print(cell_result.asnumpy()) | ||
| ``` | ||
|
|
There was a problem hiding this comment.
| ### Composing shifts | |
| The result of a shift is a regular field, which can be passed to other operators | |
| or shifted again. This operator goes from the cells to the edges and back to the | |
| cells: | |
| ```{code-cell} ipython3 | |
| @gtx.field_operator | |
| def sum_over_edges(cells: CellField) -> CellField: | |
| edge_sums = sum_of_adjacent_cells(cells) | |
| return neighbor_sum(edge_sums(C2E), axis=C2EDim) | |
| cell_result = gtx.zeros({Cell: 6}) | |
| sum_over_edges(cell_values, out=cell_result, offset_provider=offset_provider) | |
| print(cell_result.asnumpy()) | |
| ``` |
I don't see why we need to talk about that... It's not a special case. The only thing we might want to mention, but we can also omit, because it doesn't add a lot of value field(E2C)(C2E) is not supported, i.e. Field with 2 local dimensions.
There was a problem hiding this comment.
Section removed in e296320. The reductions section has one sentence saying that a field can only have one local dimension, so cells(E2C)(C2E) is not supported.
| - **A selected neighbor is only defined where it exists.** `cells(E2C[1])` has | ||
| no value at the boundary edges, so an operator using it can only be computed | ||
| on the interior ones. |
There was a problem hiding this comment.
Hmm... That doesn't play nicely with my comment above.
There was a problem hiding this comment.
The "Missing neighbors" section is removed in e296320, see the reply in the thread below.
| In this mesh the interior edges are numbered last, from 6 to 11, so they can be | ||
| selected with a domain: | ||
|
|
||
| ```{code-cell} ipython3 | ||
| @gtx.field_operator | ||
| def jump_across_edge(cells: CellField) -> EdgeField: | ||
| return cells(E2C[1]) - cells(E2C[0]) | ||
|
|
||
|
|
||
| edge_values = gtx.zeros({Edge: 12}) | ||
|
|
||
| jump_across_edge( | ||
| cell_values, out=edge_values, domain={Edge: (6, 12)}, offset_provider=offset_provider | ||
| ) | ||
| print(edge_values.asnumpy()) | ||
| ``` | ||
|
|
||
| ```{tip} | ||
| Number the locations of a mesh so that the ones needing a special treatment, | ||
| like the boundary, are contiguous. Domains can then select them without masks. | ||
| ``` |
There was a problem hiding this comment.
This example is a very corner case thing and not obvious that it is good to do it like this. We should explain: if a location has fewer neighbors than the maximum: use neigbhbor reductions; if you know exactly how many neighbors there are, you can address them directly, e.g. in edges to cells (avoiding the boundary discussion).
There was a problem hiding this comment.
Done in e296320. The "Missing neighbors" section, the domain trick and the numbering tip are gone. The page now says exactly this: reductions ignore missing neighbors and are the way to work when some locations have fewer neighbors than others, and a neighbor is selected by index only when all the locations have it.
- Quickstart: `domain` instead of `grid`, no `ndarray`, link to GridTools. - Grids and fields: reading the data only (no writing through the buffer), missing neighbors explained. - Shifts: precise wording on domains, `where` versus `concat_where`, a neighbor is selected by index only when all locations have it, reductions otherwise; the composing-shifts and missing-neighbors sections are removed. - The landing page is an executed notebook; `test_examples` finds executable pages in any folder of the subsite.
| ```{tip} | ||
| Call scan operators from a field operator or a program. Direct calls from Python | ||
| work, but with a compiled backend they give a warning saying that such calls are | ||
| not optimized. | ||
| ``` | ||
|
|
There was a problem hiding this comment.
| ```{tip} | |
| Call scan operators from a field operator or a program. Direct calls from Python | |
| work, but with a compiled backend they give a warning saying that such calls are | |
| not optimized. | |
| ``` |
| A scan operator only sees the values of its arguments at the current level. To | ||
| use the value of a field at another level, apply the offset in the field | ||
| operator and pass the result as one more argument, for example | ||
| `my_scan(values, values(K - 1))`. The computation must then be restricted to the | ||
| levels where that argument is defined. | ||
|
|
There was a problem hiding this comment.
| A scan operator only sees the values of its arguments at the current level. To | |
| use the value of a field at another level, apply the offset in the field | |
| operator and pass the result as one more argument, for example | |
| `my_scan(values, values(K - 1))`. The computation must then be restricted to the | |
| levels where that argument is defined. | |
| A scan operator is a scalar function, not a field. If you need access to a neighboring value <etc...> |
but don't use K shifts as the example, because they should be avoided!
There was a problem hiding this comment.
Reworded in c30067f along these lines, with a horizontal neighbor as the example instead of a K offset: "A scan operator is a function of scalars, not of fields, so it cannot access the neighbors of a point. If the value of a neighbor is needed, compute it in the field operator and pass it as one more argument, for example my_scan(values, values(I + 1))."
| When several quantities are carried from level to level, the state is a | ||
| [named collection](field-operators.md#named-collections) of scalars, and so are | ||
| `init` and the result: |
There was a problem hiding this comment.
| When several quantities are carried from level to level, the state is a | |
| [named collection](field-operators.md#named-collections) of scalars, and so are | |
| `init` and the result: | |
| When several quantities are carried from level to level, the state needs to be a tuple or better a | |
| [named collection](field-operators.md#named-collections) of scalars, and so are | |
| `init` and the result: |
|
|
||
| ```{tip} | ||
| A plain tuple also works as state, with `init=(0.0, 0.0)` and the annotation | ||
| `tuple[float, float]`. Prefer a named collection: the names of its members make | ||
| the scan operator and the code using its result much easier to read. | ||
| ``` |
There was a problem hiding this comment.
| ```{tip} | |
| A plain tuple also works as state, with `init=(0.0, 0.0)` and the annotation | |
| `tuple[float, float]`. Prefer a named collection: the names of its members make | |
| the scan operator and the code using its result much easier to read. | |
| ``` |
I'd remove this and use my suggestion above.
|
|
||
| # Programs | ||
|
|
||
| In the previous pages, operators were called directly from Python with `out=`. |
There was a problem hiding this comment.
Let's add a leading sentence, along the line: "If you don't need programs, use field_operators only."
And somewhere we should add a note: "field_operator called from the program or called directly are the scope of optimization in compiled backends. To expose as much as possible to the optimization, make the field_operator call span as much as possible" (don't take it literally, make it correct).
There was a problem hiding this comment.
Done in c30067f. The page now starts with "Field operators are enough for most computations: if you do not need a program, use only field operators", and the sentence recommending programs when several operators run together is gone. There is also an "important" box after the first program: in compiled backends the scope of the optimizations is a single field operator call (from a program or directly from Python) with everything it uses, separate calls in a program are not optimized together, so every call should span as much of the computation as possible. Please check that the wording is correct.
Description
Follows #3023 (documentation site infrastructure, already merged). Replaces the placeholder page of the
gt4py.nextsubsite with new user documentation, written from scratch as executed MyST notebooks: every code cell runs when the site is built, so the outputs shown are the real ones and a failing example fails the build.The goal is a short and clear guide, not a complete reference:
concat_where, staggered dimensions), scan operators, programsgtfn_cpu, build cache, compiling in advance, static parameters, short GPU noteOther changes
test_examplesnox session: runs every executable page of thegt4py.nextsubsite, in any of its folders, including the landing page.HackTheToolchain.md,WorkflowPatterns.md) move fromdocs/user/next/advanced/todocs/development/next/toolchain/, since they are developer documentation. They are still run bytest_examples.docs/user/next/images/mesh_figures.py, from the same tables used in the pages.gt4py.cartesiansite is now titled "GT4Py Cartesian" instead of "GT4Py (cartesian)".Documentationworkflow: the site can also be deployed manually frommain(workflow dispatch with thedeployinput), not only from a release tag.docs/development/tools/documentation.mdupdated to describe the new content.Notes
gt4py.next: the docstrings of the public API are not ready to be published yet.concat_whereand staggered dimensions are documented and marked as experimental.remove-stderrtag). fix[next]: quiet warnings and worker noise in default usage #3022 removes those warnings in the library; the tags can be dropped once it is merged.Requirements
test_examplessession.