Skip to content

refactor[next]: rename Backend to Toolchain and align field names - #2741

Open
egparedes wants to merge 1 commit into
otf-split-1-stages-artifactsfrom
otf-split-2-toolchain-naming
Open

refactor[next]: rename Backend to Toolchain and align field names#2741
egparedes wants to merge 1 commit into
otf-split-1-stages-artifactsfrom
otf-split-2-toolchain-naming

Conversation

@egparedes

@egparedes egparedes commented Jul 30, 2026

Copy link
Copy Markdown
Contributor

Description

Third PR of the otf-toolchain-split stack (on top of #2737). Pure renaming — no behavior change.

ADR 0017 already defines toolchain as "all the code components that work together to go from DSL code to an optimized, runnable python callable". The root object implementing exactly that is currently called Backend, with its frontend half named transforms and its backend half named executor — so "backend" means both the whole thing and one of its halves. This PR adopts the ADR's vocabulary, resolving the standing TODO(tehrengruber) in backend.py that asks for this rename.

Old New
next.backend.Backend next.backend.Toolchain
Toolchain.transforms Toolchain.frontend
Toolchain.executor Toolchain.backend
otf.workflow.ConcreteArtifact otf.workflow.ProgramWithArgs
ProgramWithArgs.data ProgramWithArgs.definition
otf.stages.CompilableProgramDef otf.stages.CompilableProgram

Deliberately not renamed here: OTFCompileWorkflowCompilePipeline (comes with the explicit __call__ later in this stack), CompilationTask.executor (different vocabulary — the process-pool runner of ADR 0024), and stages.ConcreteProgramDef.

No compatibility aliases

These are hard renames: the old names stop resolving in this release rather than lingering behind a deprecation layer, so downstream migrates once at a known point instead of drifting on a half-working shim. An alias layer would have been partial anyway — constructing with the old keyword names (Toolchain(executor=…), ProgramWithArgs(data=…), GTFNBackendFactory(executor=…)) cannot be aliased on a dataclass without hand-writing __init__.

Removed with no replacement alias: backend.Backend, Toolchain.transforms, Toolchain.executor, otf.workflow.ConcreteArtifact, ProgramWithArgs.data, otf.stages.CompilableProgramDef, and the public gtx.typing.Backend (now gtx.typing.Toolchain) — the one documented public export affected.

Other things worth a reviewer's eye

  • Class-body shadowing in the factories. With the field now named backend, a factory-boy class body declaring backend = factory.LazyAttribute(...) would shadow the gt4py.next.backend module for any later lookup in that same class body. runners/gtfn.py and runners/dace/workflow/backend.py therefore now import it as backend as next_backend.
  • ItirShim.definitionItirShim.operator_def (ffront/foast_to_past.py): without this, the .data.definition rename would have produced self.definition.definition. No alias — it is an internal lowering detail.
  • EmbeddedDummyBackend.executor.backend in tests/next_tests/definitions.py, keeping the test double on the new vocabulary rather than relying on the deprecation property.
  • One error-message text change: iterator/runtime.py now names 'gt4py.next.backend.Toolchain'.
  • Left deliberately out of scope: iterator/ARCHITECTURE.md still has ### roundtrip.executor / ### double_roundtrip.executor headings. That document is already substantially stale (it cites a backend_executor.py and a fencil_processors/ that no longer exist), so refreshing it belongs in its own change rather than being half-done here.

Cache keys

fingerprinting.py embeds fully-qualified class names and dataclass field names, so renaming ConcreteArtifact/data rotates the keys of the two persistent translation caches (gtfn and dace). CachedStep already mixes BUILD_CACHE_VERSION_ID (= gt4py.__version__, commit-bearing) into every key, so those keys rotate on every release anyway: the effect is one extra cache miss on upgrade, with no risk of stale hits.

ADR

Adds ADR 0027 — Toolchain Naming and Pipeline Simplification, which partially supersedes ADR 0011 (its workflow-combinator framework and otf.step_types naming) and refines ADR 0017 (whose term toolchain becomes the name of the root object). The ADR also records the pipeline and observability decisions implemented by the following PRs in this stack, and one-line back-pointers were added to 0011 and 0017.

Requirements

  • All fixes and/or new features come with corresponding tests. (Rename-only; existing suites plus an added alias smoke check cover it.)
  • Important design decisions have been documented in the appropriate ADR inside the docs/development/ADRs/ folder.

https://claude.ai/code/session_01R8zRtFMhdJ8c96XJYCXkRk

@egparedes
egparedes marked this pull request as ready for review July 30, 2026 17:58
@egparedes
egparedes force-pushed the otf-split-2-toolchain-naming branch from 40c134b to 63713c3 Compare July 30, 2026 17:58
Adopt the vocabulary ADR 0017 already defines: the root object that carries a
program from DSL source to a runnable callable is the *toolchain*, not the
*backend* (which is one of its two halves). Renamed:

- `next.backend.Backend` -> `next.backend.Toolchain`
- `Toolchain.transforms` -> `Toolchain.frontend`
- `Toolchain.executor` -> `Toolchain.backend`
- `otf.workflow.ConcreteArtifact` -> `otf.workflow.ProgramWithArgs`
- `ProgramWithArgs.data` -> `ProgramWithArgs.definition`
- `otf.stages.CompilableProgramDef` -> `otf.stages.CompilableProgram`
- `gtx.typing.Backend` -> `gtx.typing.Toolchain`

These are hard renames: no deprecation aliases are kept, so downstream has to
move in this release rather than drift on a compatibility layer. An alias would
have been partial anyway -- constructing with the old keyword names cannot be
aliased on a dataclass without hand-writing `__init__` -- and a half-working
compatibility layer is harder to act on than one loud break.

Also resolves the `TODO(tehrengruber)` in `backend.py` asking for exactly this
rename, and records the decision in a new ADR 0027, which partially supersedes
ADR 0011 and refines ADR 0017.

No behavior change. Fingerprints embed qualified class and field names, so the
`ProgramWithArgs` rename rotates the two persistent translation-cache keys
(gtfn, dace) once; `BUILD_CACHE_VERSION_ID` already rotates them on every
release, so this only means one extra cache miss on upgrade.

Claude-Session: https://claude.ai/code/session_01R8zRtFMhdJ8c96XJYCXkRk
@egparedes
egparedes force-pushed the otf-split-2-toolchain-naming branch from 63713c3 to 5dfb78f Compare July 31, 2026 16:15
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.

1 participant