feat(torch): expose optional codegen parameters

[voltjia]

Summary

• Expose supported ATen optional parameters as stable InfiniOps C++ parameters in generated PyTorch operator bases.
• Bind generated PyTorch backends to existing src/base/<op>.h overloads when available, forwarding omitted optional/default ATen parameters as typed defaults.
• Add std::optional<T> support to operator cache hashing and update the generated torch-op test harness for optional arguments and known vendor-specific PyTorch crashes/divergences.
• Add generator tests for optional parameter exposure and existing-base overload binding.

Motivation

The PyTorch code generator previously hid optional ATen schema parameters and always forwarded typed nullopt values. That made generated APIs unable to exercise non-default optional behavior and caused drift against operator base headers that intentionally expose optional parameters. This PR makes optional schema handling explicit while keeping existing hand-written bases as the public API source of truth when they are present.

Closes # N/A — this is follow-up work from the PyTorch codegen/base drift discussion.

Type of Change

• feat — new feature / new operator / new platform
• N/A — fix — bug fix.
• N/A — perf — performance improvement (no behavioral change).
• N/A — refactor — code restructuring without behavior change.
• N/A — test — adding or fixing tests only.
• N/A — docs — documentation only.
• N/A — build / ci — build system or CI configuration.
• N/A — chore — tooling, formatting, or other non-code changes.
• N/A — Breaking change.

Platforms Affected

• CPU (WITH_CPU)
• NVIDIA (WITH_NVIDIA)
• Iluvatar (WITH_ILUVATAR)
• MetaX (WITH_METAX)
• Cambricon (WITH_CAMBRICON)
• Moore (WITH_MOORE)
• Ascend (WITH_ASCEND)
• PyTorch C++ bindings (WITH_TORCH)
• N/A — Build system / CMake / CI; no CMake or CI files are changed.
• Python bindings / user-facing API

Test Results on Supported Platforms

All runs were rebased on current master, generated PyTorch operator sources before build, installed with WITH_TORCH=ON, and ran full verbose pytest as python3 -m pytest -v without tests/, --devices, or -n.

Platform	Built	pytest Result	Build Time	Test Time	Total Time	Notes / Hardware
NVIDIA	Yes	9279 passed, 8565 skipped	1135s	401s	1536s	PyTorch backend compiled and generated torch-op tests were included.
Iluvatar	Yes	7777 passed, 8549 skipped	840s	627s	1467s	PyTorch backend compiled and generated torch-op tests were included.
MetaX	Yes	8771 passed, 7555 skipped	1449s	459s	1908s	PyTorch backend compiled and generated torch-op tests were included.
Cambricon	Yes	5974 passed, 9968 skipped	2312s	1000s	3312s	PyTorch backend compiled and generated torch-op tests were included.
Moore	Yes	8537 passed, 7807 skipped	2284s	742s	3026s	PyTorch backend compiled and generated torch-op tests were included.
Ascend	Yes	7455 passed, 8829 skipped	1120s	610s	1730s	PyTorch backend compiled and generated torch-op tests were included.

Validation details

python3 scripts/generate_torch_ops.py
python3 -m pip install --no-build-isolation --no-deps . \
  --config-settings=cmake.define.AUTO_DETECT_BACKENDS=OFF \
  --config-settings=cmake.define.WITH_CPU=ON \
  --config-settings=cmake.define.WITH_<PLATFORM>=ON \
  --config-settings=cmake.define.WITH_TORCH=ON
python3 -m pytest -v

The test counts differ from earlier PR-body snapshots because this branch was rebased after the generated operator-base stack and now runs full bare pytest with WITH_TORCH=ON. PyTorch-backed tests are collected and executed on every platform.

python -m ruff format --check scripts/generate_torch_ops.py scripts/generate_wrappers.py tests/test_generate_torch_ops.py tests/test_generate_wrappers.py tests/test_torch_ops.py
python -m ruff check scripts/generate_torch_ops.py scripts/generate_wrappers.py tests/test_generate_torch_ops.py tests/test_generate_wrappers.py tests/test_torch_ops.py
clang-format --dry-run --Werror src/hash.h

All checks passed on the rebased branch.

Benchmark / Performance Impact

N/A — this PR changes generated API/backend plumbing and tests. The table above records build and test wall time for each platform to support follow-up compile-time optimization work.

Notes for Reviewers

• Downstream PR feat(torch): add generated operator bases #622 was regenerated from this PR after the public C++ parameter-name fix (self remains an ATen schema name internally, while generated public C++ signatures use input) and passed full-platform validation with WITH_TORCH=ON. Those results are recorded on PR feat(torch): add generated operator bases #622 to avoid mixing downstream generated-base changes into this PR's own table.

• Existing src/base/<op>.h overloads are treated as the public API when present. The generator binds compatible overloads to ATen schema parameters and fills omitted optional/default schema parameters at the ATen call site.

• Generated fresh bases now expose supported optional types as std::optional<...>. PyTorch-internal optional types without stable InfiniOps representations remain hidden and are forwarded as typed empty optionals.

• The generator reads the locally installed PyTorch torchgen packaged native_functions.yaml, so generated op availability follows the PyTorch schema available in the build environment.

• The test harness skips only known vendor-kernel crashes/divergences that otherwise terminate the Python process or compare mismatched vendor paths; PyTorch-backed tests are still collected and executed on every platform.

---

Checklist

Title, Branch, and Commits

• PR title follows Conventional Commits (e.g. feat(nvidia): …, fix(cuda/gemm): …).
• Branch name follows <type>/xxx-yyyy-zzzz where <type> matches the PR title's Conventional Commits type and words are joined with hyphens (see CONTRIBUTING.md §Branches).
• Each commit message follows Conventional Commits.
• Small PR is a single squashable commit; or, for a large PR, every commit is meaningful, well-formed, and independently reviewable (see CONTRIBUTING.md §Pull Requests).
• No stray merge commits from master — the branch is rebased cleanly on top of the current master.
• No fixup! / squash! / wip commits remain.

Scope and Design

• Changes are minimal — nothing unrelated to the stated motivation was added (CONTRIBUTING.md §Code/General).
• No dead code, commented-out blocks, debug prints, printf/std::cout/print(...) left behind, or TODO without an owner and issue link.
• No unrelated formatting churn that would obscure the diff.
• Public API changes are intentional, documented in this PR, and reflected in affected callers/tests.

General Code Hygiene

• The code is self-explanatory; comments were added only where the why is non-obvious (CONTRIBUTING.md §Code/General).
• Every modified or added file ends with a single trailing newline (CONTRIBUTING.md §Code/General).
• No trailing whitespace, tab/space mixing, or stray BOMs.
• Identifiers in comments and error messages are wrapped in backticks (e.g. the `seqlens_k` tensor) (CONTRIBUTING.md §Code/General).
• All comments and error messages are in English (CONTRIBUTING.md §Code/General).
• Comments and error messages are complete sentences — capitalized first letter, terminal punctuation — unless the language/framework convention says otherwise (CONTRIBUTING.md §Code/General; §Python).

C++ Specific

• Code follows the Google C++ Style Guide strictly.
• clang-format --dry-run --Werror src/hash.h passes.
• N/A — clang-tidy was not run; no kernel or algorithm implementation path is added.
• Operator parameter order is inputs first, outputs last; attributes are between inputs and outputs; naming follows PyTorch → ONNX → CUDA API precedence (CONTRIBUTING.md §C++).
• No exceptions are thrown. No new C++ error path was added.
• N/A — No new C++ error or warning message was added.
• N/A — No kernel files are added or renamed.
• N/A — No kernel launcher files are added or changed.
• Constructor initializer list order matches member declaration order (CONTRIBUTING.md §C++).
• Exactly one blank line between classes, between classes and functions, and between functions (CONTRIBUTING.md §C++).
• Exactly one blank line between members within a class (CONTRIBUTING.md §C++).
• Exactly one blank line before and after the contents of a namespace (CONTRIBUTING.md §C++).
• N/A — No new hand-written operator implementation is added under src/base/<op>.h or platform implementation directories.
• No raw new/delete; RAII / smart pointers / existing allocators are used.

Python Specific

• Code is PEP 8 compliant; ruff check passes cleanly.
• ruff format --check passes cleanly.
• Comments are complete English sentences, starting with a capital letter and ending with punctuation; Markdown backticks are used for code references (CONTRIBUTING.md §Python).
• Framework-specific conventions are honored where applicable (CONTRIBUTING.md §Python).
• No blank line between the function signature and the body when there is no docstring or comment (CONTRIBUTING.md §Python).
• A blank line is present before and after if, for, and similar control-flow statements (CONTRIBUTING.md §Python).
• A blank line appears before each return, except when it directly follows a control-flow statement like if or for (CONTRIBUTING.md §Python).
• Docstrings follow PEP 257 conventions.
• Type hints are added / kept consistent with the surrounding code.

Testing

• Full-platform pytest was run on all supported platforms with WITH_TORCH=ON.
• N/A — No platform was unreachable.
• New functionality has matching tests under tests/.
• Tests use pytest.mark.parametrize correctly.
• N/A — pytest.mark.auto_act_and_assert is not used by the generator unit tests or generated torch-op harness touched here.
• Default dtype / device parameterization is relied on, or overridden with an explicit pytest.mark.parametrize when necessary.
• Known vendor-kernel crashes/divergences are skipped explicitly to keep the full run progressing.
• N/A — This is a feature PR rather than a bug-fix regression test PR.

Build, CI, and Tooling

• The project builds cleanly from a fresh directory on affected platforms.
• compile_commands.json still regenerates through the existing CMake/scikit-build configuration path.
• N/A — No new backend or device auto-detection is added.
• Only one CUDA-like GPU backend is selectable at a time — the existing mutual-exclusion check in CMakeLists.txt is not changed.
• ruff and clang-format checks are green.
• No new runtime dependency was added without updating pyproject.toml's [project.optional-dependencies].

Documentation

• N/A — No README, CONTRIBUTING, build flag, or developer workflow change is introduced.
• N/A — No new operator, dispatch helper, or public utility is added outside generated code behavior.
• N/A — No user-visible breaking change is intentionally introduced.

Security and Safety

• No secrets, access tokens, internal URLs, customer data, IP addresses, or personal hardware identifiers have been committed or included in this PR description.
• N/A — No third-party code is added.
• No unsafe pointer arithmetic, uninitialized reads, or missing bounds checks were introduced.

[voltjia]

Generated source/header archive for review:

• Local workspace path: ci-results/pr619-generated-sources.tar.gz
• Contents: generated/torch_ops_metadata.json, generated/torch/<op>/{<op>.h,<op>.cc}, and generated torch operator sources/headers.
• Generation command used in a PyTorch-enabled container: rm -rf generated && python scripts/generate_torch_ops.py && tar -czf pr619-generated-sources.tar.gz generated

gh/GitHub REST does not provide a safe PR binary-attachment upload path, so I did not publish this archive to an external gist or unrelated branch.

[voltjia]

Additional compatibility validation for the latest commit (109b72f0):

• Overlaid the current feat/torch-operator-bases src/base/ headers onto this PR branch and regenerated the PyTorch backend.
• Generation completed: 603 overloads across 494 ops; incompatible existing base overloads are skipped with explicit warnings instead of generating mismatched code.
• tests/test_generate_torch_ops.py: 6 passed.
• ruff format --check and ruff check passed for the touched generator/test files.
• WITH_TORCH=ON wheel build succeeded with the overlaid operator bases.
• Installed the generated wheel and confirmed Std.active_implementation_indices("cpu") == [8] and BatchNormElemt.active_implementation_indices("cpu") == [8].
• Direct smoke call through the PyTorch slot succeeded: ops.std(..., implementation_index=8) matched torch.std(...) with max error 0.0.

Remaining skipped existing base headers in the overlay are schema/name compatibility warnings rather than build failures: orgqr, ormqr, prod, quantile, slow_conv3d, slow_conv3d_forward, slow_conv_transpose2d, slow_conv_transpose3d, sort, and several upsample backward overloads. These appear to be base/schema drift cases and can be handled as follow-up base updates if those exact bases need generated Torch implementations.

[voltjia]

Rebased onto current master and pushed fd117752.

Additional validation after rebase:

• python3 -m py_compile scripts/generate_torch_ops.py scripts/generate_wrappers.py tests/test_generate_torch_ops.py tests/test_generate_wrappers.py tests/test_torch_ops.py passed locally.
• git diff --check passed.
• Remote container: ruff format --check and ruff check passed for touched Python files.
• Remote container: python -m pytest tests/test_generate_torch_ops.py tests/test_generate_wrappers.py -q -> 7 passed.
• Remote container: WITH_TORCH=ON wheel build passed.
• Smoke test from built wheel passed for both generated clamp optional overload families:
  • scalar optional min/max: ops.clamp(x, -1.0, 1.0, out, implementation_index=8) matched torch.clamp.
  • tensor optional min/max: ops.clamp(x, lo, hi, out, implementation_index=8) matched torch.clamp.
  • Clamp.active_implementation_indices("cpu") == [8].

The rebase exposed a wrapper dispatch generation issue for overloads that reuse the same optional parameter names across scalar and Tensor variants (clamp/clip). This push fixes generated dispatch to keep optional scalar and optional Tensor overloads distinct, with a regression test in tests/test_generate_wrappers.py.

[voltjia]

Latest operator-bases overlay validation for fd117752:

• Base branch overlaid: origin/feat/torch-operator-bases at 4c1bbcc9 (src/base/ only, 436 files).
• Generation completed: 603 overloads across 494 ops, 1061 generated files.
• Generator tests in the overlay passed: tests/test_generate_torch_ops.py tests/test_generate_wrappers.py -q -> 7 passed.
• WITH_TORCH=ON wheel build passed from the overlay.
• Smoke test from the overlay-built wheel passed:
  • Std.active_implementation_indices("cpu") == [8]
  • BatchNormElemt.active_implementation_indices("cpu") == [8]
  • ClampMax.active_implementation_indices("cpu") == [8]
  • ops.std(..., implementation_index=8) matched torch.std with max error 0.0.
  • ops.clamp_max scalar and Tensor overloads both matched torch.clamp_max.

Remaining generation warnings are existing base/schema drift cases that are skipped rather than emitted as broken code: orgqr, ormqr, prod, quantile, slow_conv3d, slow_conv3d_forward, slow_conv_transpose2d, slow_conv_transpose3d, sort, and several upsample backward overloads.

[voltjia]

请 @crapromer 初审，@Ziminli 终审。