Skip to content

docs[next]: new user documentation for gt4py.next - #3024

Open
egparedes wants to merge 10 commits into
mainfrom
docs-next-user-guide
Open

egparedes wants to merge 10 commits into
mainfrom
docs-next-user-guide

Conversation

@egparedes

@egparedes egparedes commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Description

Follows #3023 (documentation site infrastructure, already merged). Replaces the placeholder page of the gt4py.next subsite 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:

Section Pages
Getting started Landing page, quickstart
Data structures Grids and fields (dimensions, domains, allocation, unstructured meshes)
GT4Py DSL Field operators, premap and neighbors (Cartesian, unstructured, concat_where, staggered dimensions), scan operators, programs
Execution Running operators and programs: embedded execution, gtfn_cpu, build cache, compiling in advance, static parameters, short GPU note
Examples Horizontal diffusion, vertical diffusion (tridiagonal solver with scans), operators on an unstructured mesh. All checked against NumPy and also run as compiled programs

Other changes

  • test_examples nox session: runs every executable page of the gt4py.next subsite, in any of its folders, including the landing page.
  • The toolchain guides (HackTheToolchain.md, WorkflowPatterns.md) move from docs/user/next/advanced/ to docs/development/next/toolchain/, since they are developer documentation. They are still run by test_examples.
  • The figures of the small unstructured mesh are generated by a script, docs/user/next/images/mesh_figures.py, from the same tables used in the pages.
  • The gt4py.cartesian site is now titled "GT4Py Cartesian" instead of "GT4Py (cartesian)".
  • Documentation workflow: the site can also be deployed manually from main (workflow dispatch with the deploy input), not only from a release tag.
  • Welcome page card and docs/development/tools/documentation.md updated to describe the new content.

Notes

Requirements

  • All fixes and/or new features come with corresponding tests: the pages are executed in the docs build and by the test_examples session.
  • Important design decisions have been documented in the appropriate ADR inside the docs/development/ADRs/ folder: not applicable.

@egparedes
egparedes added this pull request to stack #3025 November 20, 2026 11:47
@egparedes
egparedes force-pushed the docs-next-user-guide branch 5 times, most recently from c3c3431 to db408a6 Compare November 20, 2026 12:59

@egparedes egparedes left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have some comments. Also, if possible, I would like to see nicer images for the meshes.

Comment thread docs/user/next/quickstart.md Outdated
Comment on lines +118 to +124
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)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Make sure the color map scales for the two images show the same range

Comment thread docs/user/next/quickstart.md Outdated
---
laplacian_cpu = laplacian.with_backend(gtx.gtfn_cpu)

lap_phi_cpu = gtx.zeros(grid)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
```

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a subsection mentioning how to allocate for embedded execution selecting the device or the actual ndarray library (e.g. cupy or jax)

Comment on lines +173 to +174
```{figure} ../images/connectivity_numbered_grid.svg
---

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we generate nicer looking images for meshes in general?

```

### Connectivities and offsets

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add also a note mentioning that support for other kind of static pytrees will be probably added in the future

Comment thread docs/user/next/dsl/scan-operators.md Outdated

## States with several values

When several quantities are carried from level to level, the state is a tuple,

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Base automatically changed from docs-site-infrastructure to main November 20, 2026 14:42
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.
@egparedes
egparedes force-pushed the docs-next-user-guide branch from 5bbef0e to ed7488e Compare November 20, 2026 14:57
@egparedes
egparedes marked this pull request as ready for review November 20, 2026 15:42
immutable collection of named values:

```{code-cell} ipython3
from gt4py.eve.utils import FrozenNamespace

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/user/next/index.md Outdated
Comment on lines +13 to +38
```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)})
```

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in e296320: the landing page is now an executed notebook, so the snippet runs in the docs build and in test_examples.

@github-actions

Copy link
Copy Markdown

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪
✅ Merge recommendation: Needs review
🔎 Failure modes

What: The small-mesh connectivity tables and cell values are duplicated between `mesh_figures.py` and the Markdown pages (`dsl/shifts.md`, `python/grids-and-fields.md`). If one copy is edited without the other, the committed SVG figures no longer depict the mesh the pages' code computes, and nothing compares the two sources.
Where: docs/user/next/images/mesh_figures.py
Trigger: A contributor updates a table (e.g. `EDGE_TO_CELL`) or `CELL_VALUES` in one place only and regenerates (or skips regenerating) the figures.
Detected by: nothing; only a manual visual comparison of the figures against the printed notebook outputs.
Covered in this PR: No

What: `test_examples` discovers executable pages only in the hard-coded folders (`.`, `dsl`, `python`, `examples`). An executable page added to any other folder under `docs/user/next/` is silently never run by the test session.
Where: noxfile.py:test_examples
Trigger: A new documentation subfolder containing a `format_name: myst` page, added without extending the folder tuple in `noxfile.py`.
Detected by: The Sphinx/MyST-NB site build still executes such pages, so a failing cell would fail the docs build but not this session; the session itself gives no signal.
Covered in this PR: No

🏅 Score: 88
🧪 PR contains tests
🔒 No security concerns identified
🔀 Multiple PR themes

Sub-PR theme: Move the toolchain guides from the next user docs to the development docs

Relevant files:

  • docs/development/next/toolchain/HackTheToolchain.md
  • docs/development/next/toolchain/WorkflowPatterns.md
  • docs/user/next/conf.py
  • noxfile.py

Sub-PR theme: New gt4py.next user guide written as executable MyST notebooks

Relevant files:

  • docs/user/next/index.md
  • docs/user/next/quickstart.md
  • docs/user/next/dsl/field-operators.md
  • docs/user/next/dsl/shifts.md
  • docs/user/next/dsl/scan-operators.md
  • docs/user/next/dsl/programs.md
  • docs/user/next/python/grids-and-fields.md
  • docs/user/next/python/running.md
  • docs/user/next/examples/index.md
  • docs/user/next/examples/horizontal-diffusion.md
  • docs/user/next/examples/vertical-diffusion.md
  • docs/user/next/examples/unstructured-operators.md
  • docs/user/next/images/mesh_figures.py
  • docs/development/tools/documentation.md
  • docs/user/index.md
  • noxfile.py

Sub-PR theme: Title the gt4py.cartesian documentation site GT4Py Cartesian

Relevant files:

  • docs/user/cartesian/conf.py


⚙️ Agent run details
  • Model: openai/zai-org/GLM-5.3-Flash
  • Tokens: 41,007 in / 46,786 out / 87,793 total
  • Time cost: 545.9s
  • AI calls: 1

@havogt havogt left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed until shifts and neighbors. Now too tired to continue.

Comment thread docs/user/next/quickstart.md Outdated

```{code-cell} ipython3
nx, ny = 64, 48
grid = gtx.domain({I: nx, J: ny})

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
grid = gtx.domain({I: nx, J: ny})
domain = gtx.domain({I: nx, J: ny})

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in e296320. I renamed the variable in the other pages too, so that the examples are consistent.

Comment thread docs/user/next/quickstart.md Outdated
Comment on lines +73 to +77
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
```

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed in e296320. ndarray is no longer mentioned anywhere in the guide.

Comment on lines +114 to +117
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:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied in e296320.

Comment thread docs/user/next/quickstart.md Outdated
```

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied in e296320.

Comment thread docs/user/next/quickstart.md Outdated

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Link added in e296320.


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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/user/next/dsl/shifts.md Outdated

### Selecting one neighbor

Read `E2C` as "for every edge, its cells": shifting a field with it gives a

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/user/next/dsl/shifts.md Outdated
Comment on lines +258 to +276
### 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())
```

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### 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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/user/next/dsl/shifts.md Outdated
Comment on lines +284 to +286
- **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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm... That doesn't play nicely with my comment above.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "Missing neighbors" section is removed in e296320, see the reply in the thread below.

Comment thread docs/user/next/dsl/shifts.md Outdated
Comment on lines +288 to +308
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.
```

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@havogt havogt left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

scan operator review

Comment thread docs/user/next/dsl/scan-operators.md Outdated
Comment on lines +118 to +123
```{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.
```

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
```{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.
```

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed in c30067f.

Comment thread docs/user/next/dsl/scan-operators.md Outdated
Comment on lines +124 to +129
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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!

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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))."

Comment thread docs/user/next/dsl/scan-operators.md Outdated
Comment on lines +132 to +134
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:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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:

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied in c30067f.

Comment thread docs/user/next/dsl/scan-operators.md Outdated
Comment on lines +173 to +178

```{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.
```

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
```{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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed in c30067f.


# Programs

In the previous pages, operators were called directly from Python with `out=`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

This branch was successfully deployed

1 active (outdated) deployment
pr-agent — ed7488e2 Deployed Nov 20, 2026 by egparedes via pr-agent / pr-agent #159
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants