{"record":{"id":"17e2ed4e59219ad5","repo":"jax-ml/jax","slug":"the-diff-n-argument-to-jax-scipy-special-sph-har","errorCode":null,"errorMessage":"The 'diff_n' argument to jax.scipy.special.sph_harm_y is not supported.","messagePattern":"The 'diff_n' argument to jax\\.scipy\\.special\\.sph_harm_y is not supported\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"jax/_src/scipy/special.py","lineNumber":2347,"sourceCode":"    n: The degree of the harmonic; must have `n >= 0`. The standard notation for\n      degree in descriptions of spherical harmonics is `l (lower case L)`. We\n      use `n` here to be consistent with `scipy.special.sph_harm_y`. Return\n      values for `n < 0` are undefined.\n    m: The order of the harmonic; must have `|m| <= n`. Return values for\n      `|m| > n` are undefined.\n    theta: The polar (colatitudinal) coordinate; must be in [0, pi].\n    phi: The azimuthal (longitudinal) coordinate; must be in [0, 2*pi].\n    diff_n: Unsupported by JAX.\n    n_max: The maximum degree `max(n)`. If the supplied `n_max` is not the true\n      maximum value of `n`, the results are clipped to `n_max`. For example,\n      `sph_harm_y(n=jnp.array([10]), m=jnp.array([2]), theta=theta, phi=phi, n_max=6)`\n      actually returns\n      `sph_harm_y(n=jnp.array([6]), m=jnp.array([2]), theta=theta, phi=phi, n_max=6)`.\n  Returns:\n    A 1D array containing the spherical harmonics at (n, m, theta, phi).\n  \"\"\"\n  if diff_n is not None:\n    raise NotImplementedError(\n        \"The 'diff_n' argument to jax.scipy.special.sph_harm_y is not supported.\")\n\n  if jnp.isscalar(theta):\n    theta = jnp.array([theta])\n\n  if n_max is None:\n    n_max = np.max(n)\n  n_max = core.concrete_or_error(\n      int, n_max, 'The `n_max` argument of `jax.scipy.special.sph_harm_y` must '\n      'be statically specified to use `sph_harm_y` within JAX transformations.')\n\n  return _sph_harm(n, m, theta, phi, n_max)\n\n\n# exponential integrals\n# these algorithms are ported over from the files ei.c and expn.c in the Cephes mathematical library.\n# https://fossies.org/dox/cephes-math-28/ei_8c_source.html\n# https://fossies.org/dox/cephes-math-28/expn_8c_source.html","sourceCodeStart":2329,"sourceCodeEnd":2365,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/scipy/special.py#L2329-L2365","documentation":"jax.scipy.special.sph_harm_y added a diff_n keyword (for derivative output) in SciPy 1.15, but JAX's implementation only computes the harmonics themselves. Passing any non-None value for diff_n raises NotImplementedError immediately.","triggerScenarios":"Calling sph_harm_y(n, m, theta, phi, n_max=..., diff_n=1) or any non-None diff_n, typically code copied from new SciPy docs.","commonSituations":"Upgrading SciPy-facing code to SciPy >= 1.15 where diff_n is part of the signature, then running the same call under jax.scipy.special; using diff_n for gradient computations of spherical harmonics.","solutions":["Drop the diff_n argument and take gradients with jax.grad/jacfwd instead.","Compute derivative arrays with scipy.special.sph_harm_y (which supports diff_n) outside JAX.","Pin/branch your code on library: use scipy directly when diff_n is required."],"exampleFix":"# before\ny = jax.scipy.special.sph_harm_y(n, m, theta, phi, n_max=6, diff_n=1)\n\n# after\ny = jax.scipy.special.sph_harm_y(n, m, theta, phi, n_max=6)\ndy = jax.jacfwd(lambda t: jax.scipy.special.sph_harm_y(n, m, t, phi, n_max=6))(theta)","handlingStrategy":"fallback","validationCode":"# no pre-call validation possible besides not passing diff_n\nkwargs = {}  # never include diff_n when calling jax.scipy.special.sph_harm_y","typeGuard":null,"tryCatchPattern":"try:\n    y = jax.scipy.special.sph_harm_y(n, m, theta, phi, n_max=n_max)\nexcept NotImplementedError:\n    y = jax.pure_callback(\n        lambda a: scipy.special.sph_harm_y(*a, diff_n=1), ...,\n        (n, m, theta, phi))","preventionTips":["Feature-detect: only pass diff_n when calling SciPy, never jax.","Use autodiff (jacfwd/grad) for derivatives instead of diff_n.","Pin SciPy usage in a thin adapter layer so the JAX path stays clean."],"tags":["jax","scipy","spherical-harmonics","not-implemented","version-mismatch"],"backgroundTag":"unsupported-argument-value","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}