feat: add math/base/special/gelu

[AryanSharma48]

Part of #15575

Description

What is the purpose of this pull request?

This pull request:

• adds @stdlib/math/base/special/gelu to evaluate the Gaussian Error Linear Unit (GELU) activation function.
• implements the numerically stable formulation using @stdlib/math/base/special/erfc to prevent catastrophic cancellation for negative values.
• handles IEEE 754 edge cases including signed zeros, NaN, and ±Infinity.
• includes unit tests with 2 ULPs tolerance assertions, benchmarks, usage examples, TypeScript declarations, and documentation.

Related Issues

Does this pull request have any related issues?

This pull request has the following related issues:

• [RFC]: Add modern scalar ML activation functions (GELU, SiLU) to @stdlib/math/base/special #15575

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

No.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• Read, understood, and followed the contributing guidelines.

AI Assistance

When authoring the changes proposed in this PR, did you use any kind of AI assistance?

• Yes
• No

If you answered "yes" above, how did you use AI assistance?

• Code generation (e.g., when writing an implementation or fixing a bug)
• Test/benchmark generation
• Documentation (including examples)
• Research and understanding

Disclosure

If you answered "yes" to using AI assistance, please provide a short disclosure indicating how you used AI assistance. This helps reviewers determine how much scrutiny to apply when reviewing your contribution. Example disclosures: "This PR was written primarily by Claude Code." or "I consulted ChatGPT to understand the codebase, but the proposed changes were fully authored manually by myself.".

I consulted an AI assistant for research and mathematical understanding of the GELU formulation and repository conventions, while the changes were authored in accordance with canonical @stdlib guidelines.

---

@stdlib-js/reviewers

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
math/base/special/gelu	$\\color{green}180/180$ $\\color{green}+0.00\\%$	$\\color{green}9/9$ $\\color{green}+0.00\\%$	$\\color{green}2/2$ $\\color{green}+0.00\\%$	$\\color{green}180/180$ $\\color{green}+0.00\\%$

The above coverage report was generated for the changes in this PR.

[AryanSharma48]

Following up on the discussion from the 6 Oct 2026 office hours on the API design for GELU. I've written up the ecosystem research and the design I'm proposing, plus a few open questions before I push the updated implementation.

Ecosystem Analysis

Ecosystem	Approach	Default
PyTorch	approximate='none' / 'tanh' string option	Exact
TensorFlow / Keras	approximate=False / True boolean	Exact
JAX	approximate=True / False	tanh approximation
Julia (NNlib)	Separate functions: gelu, gelu_erf	tanh approximation
Rust (Candle)	Separate methods: .gelu(), .gelu_erf()	tanh approximation
Rust (Burn)	Single exact gelu	Exact

Python frameworks favor kwargs because option parsing is negligible next to tensor kernel execution. The 1.702 variant, $x \cdot \sigma(1.702x)$, is not native to PyTorch or Keras. It appears in inference engines such as Mojo MAX (gelu_quick) and Megatron Bridge (quick_gelu).

Proposed API

V8 penalizes polymorphic functions and options-object parsing in hot loops, so I propose explicit methods (as in Julia and Rust) with exact precision as the default (as in PyTorch and TF):

var gelu = require( '@stdlib/math/base/special/gelu' );

gelu( x );        // Exact, x * Phi(x)
gelu.tanh( x );   // Tanh approximation
gelu.quick( x );  // 1.702 approximation

I suggest .quick() over .sigmoid() for the 1.702 variant. NNlib already uses gelu_sigmoid for an algebraically stable rewrite of the tanh formula, so .quick() avoids a naming collision and matches Mojo and Megatron.

Numerical Stability and Testing

• Exact: Writing it as 0.5 * x * (1 + erf(x/√2)) suffers catastrophic cancellation on the negative tail. The PR evaluates $\Phi(x)$ via erfc. JAX does something similar with x/2 * erfc(-x/√2).
• Tanh: The common form 0.5 * x * (1 + tanh(z)) is fine for ML workloads, but it suffers cancellation on the negative tail. Relative error grows rapidly from roughly $x \lesssim -3$ (about 30 eps at $x = -3$ and several thousand eps at $x = -4$), and the result underflows to -0.0 near $x \approx -8$, where the true value is about $10^{-15}$. Since @stdlib tests special functions against high-precision references with ULP-based assertions, I'm evaluating it as $x \cdot \sigma(2z)$ via @stdlib/math/base/special/expit, which is mathematically identical and removes the cancellation. In a preliminary double-precision check, residual far-tail error stayed within a few tens of eps.
• Fixtures: I'll generate them with a Python mpmath script (mp.dps = 80) as the high-precision reference. The tanh and quick fixtures evaluate each approximation's own formula, not exact GELU. Tests will use ULP-based assertions (isAlmostSameValue) with the minimum measured bound per fixture block, and I'll report the measured maxima in the PR.

Open Questions

1. API shape: Are attached methods (gelu.tanh, gelu.quick) acceptable, or do you prefer separate packages for the approximations?
2. Scope: For this first PR, should I keep it to the scalar float64 JS implementation and tests, with the C implementation, native add-on, and geluf as follow-ups?

Unless you object, gelu(-Infinity) will return -0.0, the limiting value.

cc @kgryte

[AryanSharma48]

Following up on our alignment from office hours on 13th Oct 26: I am going to update this PR to strictly focus on the exact GELU implementation (math/base/special/gelu) using the erfc formulation.

I will remove the tanh and quick approximations from this branch and open them as separate, standalone PRs under the math/base/special/fast/ namespace.