RFC: Rename FusionDefinition.execute/manual_execute for clarity and add documentation on usage

[IvanYashchuk]

Summary

The current method names in the Python API for nvFuser (FusionDefinition.execute and FusionDefinition.manual_execute) are unclear and could be misleading for users unfamiliar with the internal differences between FusionExecutorCache and KernelExecutor. This RFC proposes renaming these methods to better reflect their behavior and improve the documentation to clarify when and why each method should be used.

Background

• FusionDefinition.execute uses FusionExecutorCache, which provides automatic shape specialization, scheduling, segmentation (multi-kernel), and kernel caching. It is the recommended high-level entry point for most users.
• FusionDefinition.manual_execute uses KernelExecutor, which is intended for manual, one-shot, static execution, typically in benchmarking or testing scenarios. It does not manage segmentation, shape specialization, or kernel caching.

Problems with Current Naming

• The name execute does not communicate automatic scheduling, segmentation, or caching.
• The name manual_execute is ambiguous: it could mean manual scheduling, manual cache bypass, or simply manual running of the kernel.
• The documentation does not make the distinction clear, leading to misuse and confusion, especially for new users and contributors.

Proposed Changes

1. Rename Methods for Semantic Clarity

• Rename execute to one of the following:
  • run(): short and Pythonic, means “do the smart thing”
  • execute_cached() or run_cached(): reflects kernel caching
  • auto_execute() or auto_run(): indicates auto shape/scheduling support
• Rename manual_execute to one of the following:
  • run_kernel(): explicit that it executes a single kernel
  • execute_raw() or run_raw(): highlights low-level/manual dispatch
  • manual_run() or manual_execute(): explicit, but less informative
• Optionally, consider run_dynamic()/run_static() if shape specialization is the main difference.

2. Documentation Improvements

• Clearly document the distinction:
  • When to use each method
  • What features are enabled/disabled (segmentation, cache, scheduling)
  • Performance tradeoffs and typical use-cases (production vs. benchmarking)
• Provide example use-cases for each path (including distributed tensor support if relevant)
• Reference the underlying execution engine (FusionExecutorCache vs KernelExecutor) in the docstrings

3. Migration Plan

• Deprecate old names with clear warning messages in docstrings and runtime (for a transition period)
• Update all examples and guides to use the new method names

Motivation

• Make it easier for new users and contributors to understand which API to use and why
• Encourage best practices: run() (previously execute) should be the default path for almost everyone
• Reduce maintenance and support burden due to confusion/discovery issues

Alternatives Considered

• Leave naming as-is and only improve documentation
  • Less effective, could still lead to accidental misuse
• Overload a single method with optional parameters
  • Might reduce confusion, but could clutter the interface and lose explicitness

Call for Discussion

• Which pair of names do people find most intuitive for the high-level (cached, segmented, scheduled, dynamic) and low-level (manual, single kernel, static, no cache) entry points?
• Should we prioritize Pythonic simplicity, technical explicitness, or symmetry?
• Any migration/breakage concerns for downstream usages?
• Are there strong reasons to retain the current names?

---

CC: @kevinstephano, @rdspring1