Specular Differentiation
The Python package specular implements specular differentiation which generalizes classical differentiation.
This implementation strictly follows the definitions, notations, and results in [1] and [2].
A specular derivative (the red line) can be understood as the average of the inclination angles of the right and left derivatives. In contrast, a symmetric derivative (the purple line) is the average of the right and left derivatives. Their difference is illustrated as in the following figure.
Table of Contents
Installation
Requirements
specular-differentiation requires:
- Python >= 3.14
numpy>= 2.4
Additional features are available through optional dependencies:
ode:matplotlib,pandas,tqdmoptimization:matplotlib,tqdmnumba:numbajax:jax,jaxlibtorch:torch
User installation
Standard Installation
pip install specular-differentiation
This installs the core specular differentiation API, including A, derivative, directional_derivative, partial_derivative, gradient, and jacobian.
Optional features
pip install "specular-differentiation[ode]" # ODE solvers
pip install "specular-differentiation[optimization]" # optimization routines
pip install "specular-differentiation[numba]" # Numba backend
pip install "specular-differentiation[jax]" # JAX backend
pip install "specular-differentiation[torch]" # PyTorch backend
Developer installation
pip install -e ".[dev]"
Backend support
The package is organized around a backend system. NumPy is the default backend, while accelerated backends are optional and may require extra dependencies.
| Backend | Calculation | ODE | Optimization |
|---|---|---|---|
| NumPy | supported | supported | supported (recommended) |
| Numba | supported | supported (recommended) | not supported |
| JAX | supported | supported | experimental |
| PyTorch | experimental | experimental | not supported |
Quick start
The following simple example calculates the specular derivative of the ReLU function $f(x) = max(0, x)$ at the origin.
import specular
ReLU = lambda x: max(x, 0)
print(specular.derivative(ReLU, x=0))
0.41421356237309515
Applications
Specular differentiation is defined in normed vector spaces, allowing for applications in higher-dimensional Euclidean spaces.
The specular package includes the following applications.
Ordinary differential equation
In [1], seven schemes are proposed for solving ODEs numerically:
- the specular Euler scheme of Type 1~6
- the specular trigonometric scheme
- the specular ellipse scheme
- the specular Huen scheme
The following example shows that the specular Euler schemes of Type 5 and 6 yield more accurate numerical solutions than classical schemes: the explicit and implicit Euler schemes and the Crank-Nicolson scheme.
Optimization
- Directory:
examples/optimization/ - References: [3]
In [3], three methods are proposed for optimizing nonsmooth convex objective functions:
- the specular gradient (SPEG) method
- the stochastic specular gradient (S-SPEG) method
- the hybrid specular gradient (H-SPEG) method
The following example compares the three proposed methods with the classical methods: gradient descent (GD), Adaptive Moment Estimation (Adam), and Broyden-Fletcher-Goldfarb-Shanno (BFGS).
Documentation
Getting Started
API Reference
Examples
LaTeX Macro
To use the specular differentiation symbol in your LaTeX document, add the following code to your preamble (before \begin{document}):
% Required packages
\usepackage{graphicx}
\usepackage{bm}
\usepackage{amssymb}
% specular derivative symbol
\newcommand\sd[1][.5]{\mathbin{\vcenter{\hbox{\scalebox{#1}{\,$\bm{\wedge}$}}}}}
% specular Gateaux derivative symbol
\newcommand{\sGd}{\widehat{\mkern-2mu d}\mkern1mu}
% specular gradient symbol
\newcommand{\sg}{\mathord{\raisebox{-0.05ex}{\rule{0pt}{1.3ex}\smash{\scalebox{1.37}[1.22]{\ensuremath{\blacktriangledown}}}}\mkern-1.2mu}}
Citing specular-differentiation
To cite this repository:
@software{Jung_specular-differentiation_2026,
author = {Jung, Kiyuob},
doi = {10.5281/zenodo.18246734},
license = {MIT},
month = aug,
title = {{specular-differentiation}},
url = {https://github.com/kyjung2357/specular-differentiation},
version = {1.2.2},
year = {2026},
}
References
[1] K. Jung. Nonlinear numerical schemes using specular differentiation for initial value problems of first-order ordinary differential equations. arXiv preprint arXiv:2601.09900, 2026.
[2] K. Jung. Specular differentiation in normed vector spaces: Quasi-Mean Value and Quasi-Fermat Theorems. arXiv preprint arXiv:2601.10950, 2026.
[3] K. Jung. Specular gradient methods for nonsmooth convex optimization in Euclidean spaces: a subgradient selection strategy. arXiv preprint arXiv:2605.25490, 2026.
1 maintainer
Metadata
1 maintainer
Release files for specular-differentiation 1.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| specular_differentiation-1.2.2.tar.gz | 33.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| specular_differentiation-1.2.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 71.6 kB
Release files / specular_differentiation-1.2.2.tar.gz
| Download URL | specular_differentiation-1.2.2.tar.gz |
|---|---|
| Size | 33.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
de3e42d061604a7ae213b56528be509126a57d0eaf13d675d70b2df8fc2f941c
|
|
BLAKE2b-256 checksum How to use checksums |
5a433ebbceceab11ddfe6ae4aad1f4ae3db8fb9d29acd849ae48bbc06b629d70
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.5
|
Release files / specular_differentiation-1.2.2-py3-none-any.whl
| Download URL | specular_differentiation-1.2.2-py3-none-any.whl |
|---|---|
| Size | 37.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b6bfebd407d4dbd167c90c075e2fdcf0c0ac0948c74be7d577f8c4d724291506
|
|
BLAKE2b-256 checksum How to use checksums |
5d2aeef8175fc20e9696a0564b46de92d34de99e5ece12419e1d85623a273c7b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.5
|
