Skip to content

[JAX] Add sqrtsoftplus router score function - #3448

Open
jberchtold-nvidia wants to merge 2 commits into
NVIDIA:mainfrom
jberchtold-nvidia:jberchtold/jax-sqrtsoftplus-router
Open

[JAX] Add sqrtsoftplus router score function#3448
jberchtold-nvidia wants to merge 2 commits into
NVIDIA:mainfrom
jberchtold-nvidia:jberchtold/jax-sqrtsoftplus-router

Conversation

@jberchtold-nvidia

Copy link
Copy Markdown
Collaborator

Description

Expose sqrtsoftplus routing to TE/JAX

Type of change

  • Documentation change (change only to the documentation, either a fix or a new content)
  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Infra/Build change
  • Code refactoring

Changes

  • Expose sqrtsoftplus router enum and add corresponding tests

Checklist:

  • I have read and followed the contributing guidelines
  • The functionality is complete
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes

Signed-off-by: Jeremy Berchtold <jberchtold@nvidia.com>
@jberchtold-nvidia
jberchtold-nvidia marked this pull request as draft August 31, 2026 18:20
@jberchtold-nvidia

Copy link
Copy Markdown
Collaborator Author

/te-ci jax

@greptile-apps

greptile-apps Bot commented Aug 31, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

The PR exposes the native sqrtsoftplus router score function through the JAX and Flax MoE APIs.

  • Adds matching C++, pybind, and Python enum values.
  • Allows sqrtsoftplus routing with expert bias and auxiliary scores.
  • Extends single-device and distributed forward/backward tests.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename Overview
transformer_engine/jax/router.py Exposes sqrtsoftplus in the public fused-router API and permits its supported expert-bias pairing.
transformer_engine/jax/cpp_extensions/router.py Mirrors the native sqrtsoftplus score-function enum in the JAX primitive layer.
transformer_engine/jax/csrc/extensions/misc.h Adds the native-facing JAX enum value aligned with the shared router contract.
transformer_engine/jax/moe.py Documents sqrtsoftplus support in the functional expert-parallel MoE path.
transformer_engine/jax/flax/moe.py Documents sqrtsoftplus as a supported Flax MoE routing configuration.
tests/jax/test_fused_router.py Adds reference, enum, forward, backward, bias, grouped-routing, and auxiliary-score coverage for sqrtsoftplus.
tests/jax/test_distributed_router.py Extends distributed forward and backward router comparisons to sqrtsoftplus.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[JAX or Flax MoE caller] --> B[Validate sqrtsoftplus score function]
  B --> C[JAX FFI router primitive]
  C --> D[Native sqrtsoftplus scoring]
  D --> E[Top-k routing and weights]
  E --> F[Expert dispatch]
  D -. dense scores .-> G[Optional auxiliary loss]
Loading

Reviews (2): Last reviewed commit: "Merge branch 'main' into jberchtold/jax-..." | Re-trigger Greptile

@jberchtold-nvidia
jberchtold-nvidia marked this pull request as ready for review September 1, 2026 22:23
Comment on lines +163 to +171
grad_weights = jnp.linspace(0.5, 1.5, num_experts, dtype=jnp.float32)[None, :]

def target_loss(x):
p, _ = fused_topk_with_score_function(
x,
topk=topk,
score_function=score_function,
)
return jnp.sum(p)
return jnp.sum(p * grad_weights)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

not sure why we are adding this?

score_function=score_function,
)
return jnp.sum(p)
return jnp.sum(p * grad_weights)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

same here

@pytest_parametrize_wrapper("group_topk", GROUP_TOPK_OPTIONS)
@pytest_parametrize_wrapper("scaling_factor", SCALING_FACTOR_OPTIONS)
@pytest_parametrize_wrapper("enable_bias", ENABLE_BIAS_OPTIONS)
@pytest.mark.triton

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

This is not just in your PR but I saw a lot of mark.triton on this file and it actually does not use triton here (fused router is a CUDA kernel not triton kernel so I can make anoother PR to remove all the wrong marks)

Comment on lines +447 to +465
def test_sqrtsoftplus_score_function_enum():
from transformer_engine.jax.router import ScoreFunction

logits = make_logits(128, 32, "sqrtsoftplus")
string_fn = jax.jit(
partial(fused_topk_with_score_function, topk=4, score_function="sqrtsoftplus")
)
enum_fn = jax.jit(
partial(
fused_topk_with_score_function,
topk=4,
score_function=ScoreFunction.SQRTSOFTPLUS,
)
)

string_probs, string_routing_map = string_fn(logits)
enum_probs, enum_routing_map = enum_fn(logits)
assert jnp.array_equal(string_probs, enum_probs)
assert jnp.array_equal(string_routing_map, enum_routing_map)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

This does not seem to be needed to test between enum and string to be passed into score_function

num_groups=num_groups,
group_topk=group_topk,
scaling_factor=scaling_factor,
score_function="sqrtsoftplus",

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

we can also just pytest parameterize the score_function, what do you think?

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