Metadata-Version: 2.5
Name: the-hawkes-package
Version: 0.3.0
Summary: Simulation of temporal and spatio-temporal Hawkes processes via Ogata thinning.
Project-URL: Homepage, https://github.com/jeMATHfischer/TheHawkesPackage
Project-URL: Documentation, https://jeMATHfischer.github.io/TheHawkesPackage/
Project-URL: Repository, https://github.com/jeMATHfischer/TheHawkesPackage
Project-URL: Issues, https://github.com/jeMATHfischer/TheHawkesPackage/issues
Project-URL: Changelog, https://github.com/jeMATHfischer/TheHawkesPackage/blob/master/CHANGELOG.md
Author-email: Jens Fischer <jefischer@posteo.de>
Maintainer-email: Jens Fischer <jefischer@posteo.de>
License-Expression: MIT
License-File: LICENSE
Keywords: hawkes-process,mcmc,metropolis-hastings,ogata-thinning,point-process,self-exciting,spatio-temporal,stochastic-simulation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.8
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: furo>=2024.5.6; extra == 'dev'
Requires-Dist: ipykernel>=6.29; extra == 'dev'
Requires-Dist: matplotlib>=3.7; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: myst-nb>=1.1; extra == 'dev'
Requires-Dist: nbstripout>=0.7; extra == 'dev'
Requires-Dist: numpydoc>=1.7; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest-randomly>=3.15; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: sphinx-copybutton>=0.5; extra == 'dev'
Requires-Dist: sphinx-design>=0.6; extra == 'dev'
Requires-Dist: sphinx>=7.3; extra == 'dev'
Requires-Dist: twine>=6.1; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2024.5.6; extra == 'docs'
Requires-Dist: ipykernel>=6.29; extra == 'docs'
Requires-Dist: matplotlib>=3.7; extra == 'docs'
Requires-Dist: myst-nb>=1.1; extra == 'docs'
Requires-Dist: numpydoc>=1.7; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
Requires-Dist: sphinx-design>=0.6; extra == 'docs'
Requires-Dist: sphinx>=7.3; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.1; extra == 'test'
Requires-Dist: pytest-randomly>=3.15; extra == 'test'
Requires-Dist: pytest>=7.4; extra == 'test'
Description-Content-Type: text/markdown

# the-hawkes-package

[![CI](https://github.com/jeMATHfischer/TheHawkesPackage/actions/workflows/ci.yml/badge.svg)](https://github.com/jeMATHfischer/TheHawkesPackage/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/the-hawkes-package.svg)](https://pypi.org/project/the-hawkes-package/)
[![Python](https://img.shields.io/badge/python-3.10%20%E2%80%93%203.14-blue)](https://pypi.org/project/the-hawkes-package/)
[![Docs](https://img.shields.io/badge/docs-latest-blue)](https://jeMATHfischer.github.io/TheHawkesPackage/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/jeMATHfischer/TheHawkesPackage/blob/master/LICENSE)

Simulation of temporal and spatio-temporal Hawkes processes via Ogata's thinning algorithm.

A Hawkes process is a self-exciting point process: every event raises the probability of further
events for a while afterwards. This package simulates them for a range of kernel shapes — including
non-monotone ("bell-shaped") kernels and nonlinear intensities, where the naive thinning bound is
wrong — and extends the construction to a spatial domain with periodic boundaries.

```
λ(t | H_t) = φ( μ + Σ_{t_i < t} κ(t − t_i) )
```

## Installation

```bash
pip install the-hawkes-package
```

Requires Python 3.10+, NumPy and SciPy.

## Quickstart

```python
import numpy as np
import hawkes_package as hp

# Linear Hawkes with an exponential kernel: param = [mu, alpha, beta]
process = hp.ExponentialHawkes(np.array([2.0, 0.5, 1.0]), rng=42)
process.simulate(100)

times, intensity = process.intensity_over_interval(np.linspace(0, process.Events[-1], 1000))
```

The constructor enforces the stationarity condition `alpha / beta < 1` and raises `ValueError`
otherwise — an unstable process would not terminate.

### Available processes

| Class | Use when |
|---|---|
| `ExponentialHawkes` | Linear intensity, exponential kernel. The classic case. |
| `MonotoneKernelHawkes` | Any monotone-decreasing kernel, with a monotone-increasing nonlinearity `φ`. |
| `BellShapeHawkes` | Kernels with a single interior maximum, where the excitation ramps up before decaying. |
| `SpatioTemporalHawkesProcess` | Events carry a location on a `Circle`, `Torus2D` or `FundamentalDomain`. |

### Spatial domains

```python
import hawkes_package as hp

process = hp.SpatioTemporalHawkesProcess(
    base=lambda x: 0.5,
    spatial=lambda d: max(0.0, 1 - d / np.pi),
    temporal=lambda dt: 0.9 * np.exp(-5 * dt),
    domain=hp.Circle(),
    monotone_temporal_kernel=True,
    rng=42,
)
process.simulate(50)
```

The background may vary in space — `base=lambda x: 0.5 + 0.2*np.cos(x[0])` — and generalises
unchanged to two dimensions, since a callable always receives a shape-`(ndim,)` point.

`SpatialDomain` is an ABC — implement `distance`, `wrap`, `sample_uniform`, `volume` and `bounds`
to simulate on your own geometry. A domain need not fill its bounding box: override the optional
`contains` and `volume_element` hooks, and `volume` must then equal the integral of
`volume_element` over the part of `bounds` that `contains` admits. For a domain that does fill its
box — the default — that reduces to `volume == prod(bounds widths)`.

`Circle` and `Torus2D` are written out by hand. `FundamentalDomain` is the general construction
they are instances of, a convex polygon plus the side-pairing isometries that identify its
boundary, and reaches quotients no rectangle expresses — the hexagonal torus first among them:

```python
domain = hp.FundamentalDomain.hexagon(1.0)
```

`make_periodic` wraps an isotropic kernel so it sums correctly over the domain's image points, and
can be passed straight in as `spatial=`:

```python
kernel = hp.make_periodic(lambda d: np.exp(-(d**2)), hp.Circle())
process = hp.SpatioTemporalHawkesProcess(base, kernel, temporal, domain=hp.Circle())
```

## Reproducibility

Every process takes `rng=`, accepting `None`, an `int` seed, or an existing `numpy.random.Generator`:

```python
hp.ExponentialHawkes(param, rng=42)  # reproducible
hp.ExponentialHawkes(param, rng=my_generator)  # share one stream
```

`np.random.seed(...)` does **not** control simulations. See [CHANGELOG.md](https://github.com/jeMATHfischer/TheHawkesPackage/blob/master/CHANGELOG.md).

## Migrating from `TheHawkesPackage`

The import name changed to `hawkes_package`. `import TheHawkesPackage` still works but emits a
`DeprecationWarning`; the shim is removed in 0.4.0. `simulate(k)` is now the method on every
process class — `propagate_by_amount`, `propagate_by_k_events` and the `propogate_by_amount` typo
remain as deprecated aliases.

## Documentation

<https://jeMATHfischer.github.io/TheHawkesPackage/>

## License

MIT — see [LICENSE](https://github.com/jeMATHfischer/TheHawkesPackage/blob/master/LICENSE).
