spxa 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. spxa-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md +34 -0
  2. spxa-1.0.0/.github/ISSUE_TEMPLATE/process_proposal.md +49 -0
  3. spxa-1.0.0/.github/ISSUE_TEMPLATE/rfc.md +41 -0
  4. spxa-1.0.0/.github/workflows/benchmarks.yml +63 -0
  5. spxa-1.0.0/.github/workflows/ci.yml +72 -0
  6. spxa-1.0.0/.github/workflows/docs.yml +51 -0
  7. spxa-1.0.0/.github/workflows/release.yml +58 -0
  8. spxa-1.0.0/.gitignore +15 -0
  9. spxa-1.0.0/.pre-commit-config.yaml +18 -0
  10. spxa-1.0.0/CHANGELOG.md +14 -0
  11. spxa-1.0.0/CONTRIBUTING.md +791 -0
  12. spxa-1.0.0/PKG-INFO +124 -0
  13. spxa-1.0.0/PROCESS_REGISTRY.md +41 -0
  14. spxa-1.0.0/README.md +87 -0
  15. spxa-1.0.0/benchmarks/__init__.py +0 -0
  16. spxa-1.0.0/benchmarks/results/.gitkeep +0 -0
  17. spxa-1.0.0/docs/api.md +1493 -0
  18. spxa-1.0.0/docs/index.md +23 -0
  19. spxa-1.0.0/docs/theory/beyond_levy.md +103 -0
  20. spxa-1.0.0/docs/theory/levy_khintchine.md +81 -0
  21. spxa-1.0.0/docs/theory/triplet_arithmetic.md +97 -0
  22. spxa-1.0.0/docs/tutorials/01_first_composition.ipynb +143 -0
  23. spxa-1.0.0/docs/tutorials/02_finance_models.ipynb +258 -0
  24. spxa-1.0.0/docs/tutorials/03_physics_applications.ipynb +328 -0
  25. spxa-1.0.0/docs/tutorials/fbm_paths.png +0 -0
  26. spxa-1.0.0/docs/tutorials/first_passage.png +0 -0
  27. spxa-1.0.0/docs/tutorials/hawkes.png +0 -0
  28. spxa-1.0.0/docs/tutorials/iv_smile.png +0 -0
  29. spxa-1.0.0/docs/tutorials/levy_paths.png +0 -0
  30. spxa-1.0.0/docs/tutorials/msd.png +0 -0
  31. spxa-1.0.0/docs/tutorials/ou_levy.png +0 -0
  32. spxa-1.0.0/docs/tutorials/stable_paths.png +0 -0
  33. spxa-1.0.0/docs/tutorials/subordination_hist.png +0 -0
  34. spxa-1.0.0/docs/tutorials/vg_paths.png +0 -0
  35. spxa-1.0.0/examples/demo.py +100 -0
  36. spxa-1.0.0/examples/full_showcase.py +557 -0
  37. spxa-1.0.0/mkdocs.yml +71 -0
  38. spxa-1.0.0/pyproject.toml +85 -0
  39. spxa-1.0.0/scripts/build_tutorials.py +104 -0
  40. spxa-1.0.0/scripts/check_benchmark_regression.py +56 -0
  41. spxa-1.0.0/scripts/check_exactness_markers.py +59 -0
  42. spxa-1.0.0/scripts/extract_changelog.py +25 -0
  43. spxa-1.0.0/setup.cfg +4 -0
  44. spxa-1.0.0/spxa/__init__.py +68 -0
  45. spxa-1.0.0/spxa/_internals/__init__.py +0 -0
  46. spxa-1.0.0/spxa/analytics/__init__.py +27 -0
  47. spxa-1.0.0/spxa/analytics/cumulants.py +81 -0
  48. spxa-1.0.0/spxa/analytics/divergence.py +272 -0
  49. spxa-1.0.0/spxa/analytics/fourier.py +183 -0
  50. spxa-1.0.0/spxa/core/__init__.py +27 -0
  51. spxa-1.0.0/spxa/core/exactness.py +47 -0
  52. spxa-1.0.0/spxa/core/exceptions.py +47 -0
  53. spxa-1.0.0/spxa/core/levy_measure.py +221 -0
  54. spxa-1.0.0/spxa/core/process.py +479 -0
  55. spxa-1.0.0/spxa/core/properties.py +209 -0
  56. spxa-1.0.0/spxa/core/triplet.py +202 -0
  57. spxa-1.0.0/spxa/ops/__init__.py +38 -0
  58. spxa-1.0.0/spxa/ops/addition.py +144 -0
  59. spxa-1.0.0/spxa/ops/integral.py +298 -0
  60. spxa-1.0.0/spxa/ops/product.py +247 -0
  61. spxa-1.0.0/spxa/ops/scaling.py +134 -0
  62. spxa-1.0.0/spxa/ops/subordination.py +228 -0
  63. spxa-1.0.0/spxa/sim/__init__.py +47 -0
  64. spxa-1.0.0/spxa/sim/bridge.py +355 -0
  65. spxa-1.0.0/spxa/sim/euler.py +269 -0
  66. spxa-1.0.0/spxa/sim/exact.py +358 -0
  67. spxa-1.0.0/spxa/story/__init__.py +17 -0
  68. spxa-1.0.0/spxa/story/narrator.py +248 -0
  69. spxa-1.0.0/spxa/zoo/__init__.py +45 -0
  70. spxa-1.0.0/spxa/zoo/beyond/__init__.py +11 -0
  71. spxa-1.0.0/spxa/zoo/beyond/fbm.py +217 -0
  72. spxa-1.0.0/spxa/zoo/beyond/hawkes.py +247 -0
  73. spxa-1.0.0/spxa/zoo/beyond/ou_levy.py +230 -0
  74. spxa-1.0.0/spxa/zoo/levy/__init__.py +27 -0
  75. spxa-1.0.0/spxa/zoo/levy/brownian.py +154 -0
  76. spxa-1.0.0/spxa/zoo/levy/cgmy.py +327 -0
  77. spxa-1.0.0/spxa/zoo/levy/gamma.py +224 -0
  78. spxa-1.0.0/spxa/zoo/levy/inverse_gaussian.py +247 -0
  79. spxa-1.0.0/spxa/zoo/levy/meixner.py +324 -0
  80. spxa-1.0.0/spxa/zoo/levy/negative_binomial.py +293 -0
  81. spxa-1.0.0/spxa/zoo/levy/nig.py +259 -0
  82. spxa-1.0.0/spxa/zoo/levy/poisson.py +163 -0
  83. spxa-1.0.0/spxa/zoo/levy/stable.py +286 -0
  84. spxa-1.0.0/spxa/zoo/levy/tempered_stable.py +322 -0
  85. spxa-1.0.0/spxa/zoo/levy/vg.py +286 -0
  86. spxa-1.0.0/spxa/zoo/multivariate.py +448 -0
  87. spxa-1.0.0/spxa.egg-info/PKG-INFO +124 -0
  88. spxa-1.0.0/spxa.egg-info/SOURCES.txt +107 -0
  89. spxa-1.0.0/spxa.egg-info/dependency_links.txt +1 -0
  90. spxa-1.0.0/spxa.egg-info/requires.txt +16 -0
  91. spxa-1.0.0/spxa.egg-info/top_level.txt +1 -0
  92. spxa-1.0.0/tests/__init__.py +0 -0
  93. spxa-1.0.0/tests/exactness/__init__.py +0 -0
  94. spxa-1.0.0/tests/exactness/test_beyond.py +229 -0
  95. spxa-1.0.0/tests/exactness/test_brownian.py +159 -0
  96. spxa-1.0.0/tests/exactness/test_cgmy.py +129 -0
  97. spxa-1.0.0/tests/exactness/test_gamma.py +139 -0
  98. spxa-1.0.0/tests/exactness/test_ig_meixner.py +204 -0
  99. spxa-1.0.0/tests/exactness/test_nig.py +114 -0
  100. spxa-1.0.0/tests/exactness/test_stable.py +146 -0
  101. spxa-1.0.0/tests/exactness/test_ts_nb.py +293 -0
  102. spxa-1.0.0/tests/exactness/test_vg.py +138 -0
  103. spxa-1.0.0/tests/integration/__init__.py +0 -0
  104. spxa-1.0.0/tests/integration/test_composition.py +154 -0
  105. spxa-1.0.0/tests/unit/__init__.py +0 -0
  106. spxa-1.0.0/tests/unit/test_core.py +197 -0
  107. spxa-1.0.0/tests/unit/test_multivariate.py +145 -0
  108. spxa-1.0.0/tests/unit/test_ops.py +284 -0
  109. spxa-1.0.0/tests/unit/test_sim.py +262 -0
@@ -0,0 +1,34 @@
1
+ ---
2
+ name: Bug report
3
+ about: Incorrect result, wrong exactness level, or crash
4
+ labels: bug
5
+ ---
6
+
7
+ ## Description
8
+
9
+ <!-- What went wrong? -->
10
+
11
+ ## Minimal reproducer
12
+
13
+ ```python
14
+ import spxa
15
+ # minimal code that demonstrates the bug
16
+ ```
17
+
18
+ ## Expected behaviour
19
+
20
+ <!-- What should happen? If this is a mathematical correctness issue, cite the theorem or formula. -->
21
+
22
+ ## Actual behaviour
23
+
24
+ <!-- What actually happens? Include the full traceback if there is one. -->
25
+
26
+ ## Is this an exactness violation?
27
+
28
+ If spxa returned a wrong closed-form result (e.g. wrong cumulant, wrong characteristic function value), this is an **exactness violation** — the highest priority bug. Please add the label `exactness-violation` and cite the published formula that contradicts the result.
29
+
30
+ ## Environment
31
+
32
+ - spxa version:
33
+ - Python version:
34
+ - OS:
@@ -0,0 +1,49 @@
1
+ ---
2
+ name: Process proposal
3
+ about: Propose a new stochastic process for the zoo
4
+ labels: process-proposal
5
+ ---
6
+
7
+ ## Process name and class name
8
+
9
+ <!-- e.g. Normal Inverse Gaussian, class NIG -->
10
+
11
+ ## Lévy–Khintchine triplet
12
+
13
+ Provide the triplet $(b, \sigma^2, \nu)$ in closed form, or explain why it does not exist.
14
+
15
+ **Drift $b$:**
16
+
17
+ **Diffusion coefficient $\sigma^2$:**
18
+
19
+ **Lévy measure $\nu(dx)$:**
20
+
21
+ If no triplet exists, state which Lévy property is violated (stationary increments / independent increments) and what the proposed exactness level is.
22
+
23
+ ## Cumulant formulas
24
+
25
+ At minimum, mean and variance. Cite the source for each formula.
26
+
27
+ **Mean $\kappa_1$:**
28
+
29
+ **Variance $\kappa_2$:**
30
+
31
+ **Higher cumulants (if known):**
32
+
33
+ ## Proposed exactness level
34
+
35
+ - [ ] `EXACT` — triplet known in closed form
36
+ - [ ] `MOMENT_PROPAGATION` — moments trackable, no full triplet
37
+ - [ ] `SIMULATION_ONLY`
38
+
39
+ ## Simulation algorithm
40
+
41
+ Which algorithm will be used to simulate sample paths? State complexity per step.
42
+
43
+ ## Primary reference
44
+
45
+ Full citation (authors, year, journal, DOI). Textbook entries are not sufficient — provide the original paper.
46
+
47
+ ## Domain motivation
48
+
49
+ Where is this process used? (finance, physics, biology, etc.) Why does it belong in spxa's zoo?
@@ -0,0 +1,41 @@
1
+ ---
2
+ name: RFC (core change)
3
+ about: Request for comment on a change to spxa/core/ or spxa/ops/
4
+ labels: rfc
5
+ ---
6
+
7
+ ## Summary
8
+
9
+ One paragraph describing the proposed change.
10
+
11
+ ## Motivation
12
+
13
+ Why is this change needed? What problem does it solve?
14
+
15
+ ## Mathematical justification
16
+
17
+ If this change affects arithmetic or property propagation, provide the mathematical basis. Cite theorems.
18
+
19
+ ## Proposed API change
20
+
21
+ Show the before and after, with code examples.
22
+
23
+ **Before:**
24
+ ```python
25
+ ```
26
+
27
+ **After:**
28
+ ```python
29
+ ```
30
+
31
+ ## Backward compatibility
32
+
33
+ Is this a breaking change? If so, what is the deprecation plan?
34
+
35
+ ## Alternatives considered
36
+
37
+ What other approaches were considered and why were they rejected?
38
+
39
+ ## Open questions
40
+
41
+ What still needs to be resolved before implementation begins?
@@ -0,0 +1,63 @@
1
+ name: Benchmarks
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ workflow_dispatch:
7
+
8
+ concurrency:
9
+ group: benchmarks-${{ github.ref }}
10
+ cancel-in-progress: true
11
+
12
+ jobs:
13
+ run:
14
+ name: Run benchmarks
15
+ runs-on: ubuntu-latest
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+ with:
19
+ fetch-depth: 0
20
+ - uses: actions/setup-python@v5
21
+ with:
22
+ python-version: "3.11"
23
+ - name: Install
24
+ run: pip install -e ".[dev]" pytest-benchmark
25
+ - name: Run benchmarks
26
+ run: |
27
+ pytest benchmarks/ \
28
+ --benchmark-json=benchmarks/results/$(git rev-parse --short HEAD).json \
29
+ --benchmark-min-rounds=5 \
30
+ --benchmark-disable-gc
31
+ - name: Commit results
32
+ if: github.event_name == 'push'
33
+ run: |
34
+ git config user.name "github-actions[bot]"
35
+ git config user.email "github-actions[bot]@users.noreply.github.com"
36
+ git add benchmarks/results/
37
+ git diff --cached --quiet || git commit -m "chore: benchmark results $(git rev-parse --short HEAD)"
38
+ git push
39
+ - name: Upload artifact
40
+ uses: actions/upload-artifact@v4
41
+ with:
42
+ name: benchmark-results
43
+ path: benchmarks/results/
44
+
45
+ regression-check:
46
+ name: Regression check
47
+ runs-on: ubuntu-latest
48
+ needs: run
49
+ steps:
50
+ - uses: actions/checkout@v4
51
+ with:
52
+ fetch-depth: 0
53
+ - uses: actions/setup-python@v5
54
+ with:
55
+ python-version: "3.11"
56
+ - run: pip install -e ".[dev]" pytest-benchmark
57
+ - name: Download current results
58
+ uses: actions/download-artifact@v4
59
+ with:
60
+ name: benchmark-results
61
+ path: benchmarks/results/
62
+ - name: Check for regressions
63
+ run: python scripts/check_benchmark_regression.py --threshold 0.20
@@ -0,0 +1,72 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main, dev]
6
+ pull_request:
7
+ branches: [main, dev]
8
+
9
+ concurrency:
10
+ group: ci-${{ github.ref }}
11
+ cancel-in-progress: true
12
+
13
+ jobs:
14
+ lint:
15
+ name: Lint
16
+ runs-on: ubuntu-latest
17
+ steps:
18
+ - uses: actions/checkout@v4
19
+ - uses: actions/setup-python@v5
20
+ with:
21
+ python-version: "3.11"
22
+ - run: pip install ruff mypy
23
+ - run: ruff check spxa tests
24
+ - run: ruff format --check spxa tests
25
+ - run: mypy spxa --ignore-missing-imports
26
+
27
+ test:
28
+ name: Test (Python ${{ matrix.python-version }})
29
+ runs-on: ubuntu-latest
30
+ strategy:
31
+ fail-fast: false
32
+ matrix:
33
+ python-version: ["3.10", "3.11", "3.12"]
34
+ steps:
35
+ - uses: actions/checkout@v4
36
+ - uses: actions/setup-python@v5
37
+ with:
38
+ python-version: ${{ matrix.python-version }}
39
+ - name: Install
40
+ run: |
41
+ pip install -e ".[dev]"
42
+ - name: Run unit tests
43
+ run: pytest tests/unit -v --tb=short
44
+ - name: Run integration tests
45
+ run: pytest tests/integration -v --tb=short
46
+ - name: Run exactness tests
47
+ run: pytest tests/exactness -v --tb=short -p no:xfail
48
+ - name: Coverage
49
+ if: matrix.python-version == '3.11'
50
+ run: |
51
+ pip install pytest-cov
52
+ pytest tests/ --cov=spxa --cov-report=xml --cov-fail-under=80
53
+ - name: Upload coverage
54
+ if: matrix.python-version == '3.11'
55
+ uses: codecov/codecov-action@v4
56
+ with:
57
+ file: coverage.xml
58
+ fail_ci_if_error: false
59
+
60
+ exactness-gate:
61
+ name: Exactness gate (no xfail allowed)
62
+ runs-on: ubuntu-latest
63
+ steps:
64
+ - uses: actions/checkout@v4
65
+ - uses: actions/setup-python@v5
66
+ with:
67
+ python-version: "3.11"
68
+ - run: pip install -e ".[dev]"
69
+ - name: Verify no exactness test is skipped or xfailed
70
+ run: |
71
+ pytest tests/exactness -v --tb=short -p no:xfail --strict-markers
72
+ python scripts/check_exactness_markers.py
@@ -0,0 +1,51 @@
1
+ name: Docs
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ concurrency:
10
+ group: docs-${{ github.ref }}
11
+ cancel-in-progress: true
12
+
13
+ jobs:
14
+ build:
15
+ name: Build docs
16
+ runs-on: ubuntu-latest
17
+ steps:
18
+ - uses: actions/checkout@v4
19
+ - uses: actions/setup-python@v5
20
+ with:
21
+ python-version: "3.11"
22
+ - name: Install
23
+ run: |
24
+ pip install -e ".[docs]"
25
+ pip install mkdocs mkdocs-material mkdocstrings[python] mkdocs-jupyter
26
+ - name: Build
27
+ run: mkdocs build --strict
28
+ - name: Upload artifact
29
+ uses: actions/upload-artifact@v4
30
+ with:
31
+ name: docs-site
32
+ path: site/
33
+
34
+ deploy:
35
+ name: Deploy to GitHub Pages
36
+ runs-on: ubuntu-latest
37
+ needs: build
38
+ if: github.ref == 'refs/heads/main' && github.event_name == 'push'
39
+ permissions:
40
+ contents: write
41
+ steps:
42
+ - uses: actions/checkout@v4
43
+ - uses: actions/setup-python@v5
44
+ with:
45
+ python-version: "3.11"
46
+ - name: Install
47
+ run: |
48
+ pip install -e ".[docs]"
49
+ pip install mkdocs mkdocs-material mkdocstrings[python] mkdocs-jupyter
50
+ - name: Deploy
51
+ run: mkdocs gh-deploy --force
@@ -0,0 +1,58 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - "v*.*.*"
7
+
8
+ jobs:
9
+ validate:
10
+ name: Validate tag matches pyproject version
11
+ runs-on: ubuntu-latest
12
+ steps:
13
+ - uses: actions/checkout@v4
14
+ - uses: actions/setup-python@v5
15
+ with:
16
+ python-version: "3.11"
17
+ - name: Check version consistency
18
+ run: |
19
+ TAG=${GITHUB_REF#refs/tags/v}
20
+ PKG=$(python -c "import tomllib; f=open('pyproject.toml','rb'); d=tomllib.load(f); print(d['project']['version'])")
21
+ if [ "$TAG" != "$PKG" ]; then
22
+ echo "Tag $TAG does not match pyproject.toml version $PKG"
23
+ exit 1
24
+ fi
25
+
26
+ publish:
27
+ name: Publish to PyPI
28
+ runs-on: ubuntu-latest
29
+ needs: validate
30
+ environment: pypi
31
+ permissions:
32
+ id-token: write
33
+ steps:
34
+ - uses: actions/checkout@v4
35
+ - uses: actions/setup-python@v5
36
+ with:
37
+ python-version: "3.11"
38
+ - run: pip install build
39
+ - run: python -m build
40
+ - uses: pypa/gh-action-pypi-publish@release/v1
41
+
42
+ github-release:
43
+ name: Create GitHub release
44
+ runs-on: ubuntu-latest
45
+ needs: publish
46
+ permissions:
47
+ contents: write
48
+ steps:
49
+ - uses: actions/checkout@v4
50
+ - name: Extract changelog entry
51
+ id: changelog
52
+ run: |
53
+ python scripts/extract_changelog.py ${GITHUB_REF#refs/tags/v} > release_notes.md
54
+ - uses: softprops/action-gh-release@v2
55
+ with:
56
+ body_path: release_notes.md
57
+ draft: false
58
+ prerelease: ${{ contains(github.ref, 'alpha') || contains(github.ref, 'beta') || contains(github.ref, 'rc') }}
spxa-1.0.0/.gitignore ADDED
@@ -0,0 +1,15 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ .eggs/
5
+ dist/
6
+ build/
7
+ *.egg
8
+ .pytest_cache/
9
+ .mypy_cache/
10
+ .ruff_cache/
11
+ site/
12
+ .coverage
13
+ coverage.xml
14
+ *.so
15
+ benchmarks/results/*.json
@@ -0,0 +1,18 @@
1
+ repos:
2
+ - repo: https://github.com/astral-sh/ruff-pre-commit
3
+ rev: v0.4.4
4
+ hooks:
5
+ - id: ruff
6
+ args: [--fix]
7
+ - id: ruff-format
8
+
9
+ - repo: https://github.com/pre-commit/pre-commit-hooks
10
+ rev: v4.6.0
11
+ hooks:
12
+ - id: trailing-whitespace
13
+ - id: end-of-file-fixer
14
+ - id: check-yaml
15
+ - id: check-toml
16
+ - id: check-merge-conflict
17
+ - id: no-commit-to-branch
18
+ args: [--branch, main]
@@ -0,0 +1,14 @@
1
+ # Changelog
2
+
3
+ All notable changes to spxa are documented here. Follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and [Semantic Versioning](https://semver.org/).
4
+
5
+ ## Unreleased
6
+
7
+ ### Added
8
+ - `TemperedStable` — pure-jump subordinator with Lévy density C·x^{-1-α}·exp(-λx); exact Bernstein function, cumulants, char_func, CDF inversion simulation (Rosiński 2007)
9
+ - `NegativeBinomialProcess` — finite-activity discrete subordinator; exact characteristic function, cumulants to order 4, NegBin simulation (Quenouille 1949)
10
+ - 34 exactness tests for both new processes
11
+
12
+ ## 0.1.0 — TBD
13
+
14
+ Initial release. Core algebraic engine, Lévy zoo, and analytics module.