Metadata-Version: 2.4
Name: specular-differentiation
Version: 1.2.2
Summary: Specular differentiation in normed vector spaces and its applications
Author-email: Kiyuob Jung <kyjung@msu.edu>
License: MIT License
Project-URL: Documentation, https://kyjung2357.github.io/specular-differentiation
Project-URL: Repository, https://github.com/kyjung2357/specular-differentiation
Project-URL: Issues, https://github.com/kyjung2357/specular-differentiation/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.4
Provides-Extra: jax
Requires-Dist: jax>=0.10; extra == "jax"
Requires-Dist: jaxlib>=0.10; extra == "jax"
Provides-Extra: numba
Requires-Dist: numba>=0.65; extra == "numba"
Provides-Extra: torch
Requires-Dist: torch>=2.12; extra == "torch"
Provides-Extra: ode
Requires-Dist: matplotlib>=3.10; extra == "ode"
Requires-Dist: pandas>=3.0; extra == "ode"
Requires-Dist: tqdm>=4.67; extra == "ode"
Provides-Extra: optimization
Requires-Dist: matplotlib>=3.10; extra == "optimization"
Requires-Dist: tqdm>=4.67; extra == "optimization"
Provides-Extra: dev
Requires-Dist: specular-differentiation[ode]; extra == "dev"
Requires-Dist: specular-differentiation[optimization]; extra == "dev"
Requires-Dist: specular-differentiation[numba]; extra == "dev"
Requires-Dist: specular-differentiation[jax]; extra == "dev"
Requires-Dist: pytest>=9.0; extra == "dev"
Requires-Dist: scipy>=1.17; extra == "dev"
Requires-Dist: torch>=2.12; extra == "dev"
Requires-Dist: ipython>=9.13; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Requires-Dist: mkdocs-callouts; extra == "docs"
Requires-Dist: mkdocs-include-markdown-plugin; extra == "docs"
Dynamic: license-file

# Specular Differentiation

[![PyPI version](https://badge.fury.io/py/specular-differentiation.svg)](https://badge.fury.io/py/specular-differentiation)
![Python 3.14](https://img.shields.io/badge/python-3.14-3776AB.svg?style=flat&logo=python&logoColor=white)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18246734.svg)](https://doi.org/10.5281/zenodo.18246734)
[![License](https://img.shields.io/pypi/l/specular-differentiation.svg)](https://pypi.org/project/specular-differentiation/)
[![CodeFactor](https://www.codefactor.io/repository/github/kyjung2357/specular-differentiation/badge)](https://www.codefactor.io/repository/github/kyjung2357/specular-differentiation)
[![CodeQL Advanced](https://github.com/kyjung2357/specular-differentiation/actions/workflows/codeql.yml/badge.svg)](https://github.com/kyjung2357/specular-differentiation/actions/workflows/codeql.yml)
[![Docs](https://img.shields.io/github/deployments/kyjung2357/specular-differentiation/github-pages?label=docs&logo=github)](https://kyjung2357.github.io/specular-differentiation)

The Python package `specular` implements *specular differentiation* which generalizes classical differentiation.
This implementation strictly follows the definitions, notations, and results in [[1]](#references) and [[2]](#references).

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.

![specular-derivative-animation](https://raw.githubusercontent.com/kyjung2357/specular-differentiation/main/docs/figures/specular-derivative-animation.gif)

## Table of Contents
* [Introduction](#installation)
* [Applications](#applications)
* [Documentation](#documentation)
* [LaTeX macros](#latex-macros)
* [Citing specular-differentiation](#citing-specular-differentiation)
* [References](#references)

## Installation

### Requirements

`specular-differentiation` requires:

* **Python** >= 3.14
* `numpy` >= 2.4

Additional features are available through optional dependencies:

* `ode`: `matplotlib`, `pandas`, `tqdm`
* `optimization`: `matplotlib`, `tqdm`
* `numba`: `numba`
* `jax`: `jax`, `jaxlib`
* `torch`: `torch`

### User installation

**Standard Installation**

```bash
pip install specular-differentiation
```

This installs the core specular differentiation API, including `A`, `derivative`, `directional_derivative`, `partial_derivative`, `gradient`, and `jacobian`.

**Optional features**

```bash
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**

```bash
pip install -e ".[dev]"
```

### [Backend support](https://kyjung2357.github.io/specular-differentiation/api/backend/)

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](https://en.wikipedia.org/wiki/Rectified_linear_unit) $f(x) = max(0, x)$ at the origin.

```python
import specular

ReLU = lambda x: max(x, 0)
print(specular.derivative(ReLU, x=0))
```

```text
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](https://kyjung2357.github.io/specular-differentiation/api/ode/)

* **Directory**: `examples/ode/`
* **References**: [[1]](#references), [[3]](#references)

In [[1]](#references), 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.

![ODE-example-1](https://raw.githubusercontent.com/kyjung2357/specular-differentiation/main/docs/figures/ODE-example-1.png)

![ODE-example-2](https://raw.githubusercontent.com/kyjung2357/specular-differentiation/main/docs/figures/ODE-example-2.png)

### [Optimization](https://kyjung2357.github.io/specular-differentiation/api/optimization/)

* **Directory**: `examples/optimization/`
* **References**: [[3]](#references)

In [[3]](#references), 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](https://en.wikipedia.org/wiki/Gradient_descent) (GD), [Adaptive Moment Estimation](https://arxiv.org/abs/1412.6980) (Adam), and [Broyden-Fletcher-Goldfarb-Shanno](https://en.wikipedia.org/wiki/Broyden%E2%80%93Fletcher%E2%80%93Goldfarb%E2%80%93Shanno_algorithm) (BFGS).

![optimization-example](https://raw.githubusercontent.com/kyjung2357/specular-differentiation/main/docs/figures/optimization-example.png)

## [Documentation](https://kyjung2357.github.io/specular-differentiation/)

### [Getting Started](https://kyjung2357.github.io/specular-differentiation/started/)
### [API Reference](https://kyjung2357.github.io/specular-differentiation/api/)
### [Examples](https://kyjung2357.github.io/specular-differentiation/examples/)

## [LaTeX Macro](https://kyjung2357.github.io/specular-differentiation/started/latex-macro/)

To use the specular differentiation symbol in your LaTeX document, add the following code to your preamble (before `\begin{document}`):

```latex
% 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:

```bibtex
@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*](https://arxiv.org/abs/2601.09900). arXiv preprint arXiv:2601.09900, 2026.

[2] K. Jung. [*Specular differentiation in normed vector spaces: Quasi-Mean Value and Quasi-Fermat Theorems*](https://arxiv.org/abs/2601.10950). arXiv preprint arXiv:2601.10950, 2026. 

[3] K. Jung. [*Specular gradient methods for nonsmooth convex optimization in Euclidean spaces: a subgradient selection strategy*](https://arxiv.org/abs/2605.25490). arXiv preprint 	arXiv:2605.25490, 2026.
