pure_greeks 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 918296785f22c79dac0dbf36cc96ba5cab3e31364678b2000346dc118e7a2d35
+  data.tar.gz: 536611801714363ee38eb8ea07eab8c041237138bb78566aaa9340b52d9ec9b0
+SHA512:
+  metadata.gz: 34dafaf69f927d47690e6606c34bf75bd45a37e71ff349f282e7651a6fee71498d50e3b0a81c086365a9bbf28ac5b1ba446f54776bfcdcd2d12265aef18b2ad4
+  data.tar.gz: 2c49149f21e39c69332b11abdecdacce14f4f8623e2cd7dd59f4f3f1653903632218a92552d02ee1c9597ea8b7ec00cf338acc4f85936de3660cd138eea47a35

data/.ruby-version

@@ -0,0 +1 @@
+3.2

data/BENCHMARKS.md

@@ -0,0 +1,50 @@
+# Benchmarks — pure_greeks v0.1.0
+
+Measured on Apple Silicon (arm64-darwin22), Ruby 3.2.0, MRI. Hardware-dependent — your numbers will differ. Re-run on your machine before relying on them.
+
+## Single-option microbenchmark
+
+`bundle exec ruby bench/single_option.rb`
+
+```
+American CRR (200 steps)        83.4 i/s   (12.0 ms per call)
+European Black-Scholes      147,500   i/s   ( 6.8 µs per call)
+```
+
+The American number is dominated by the CRR backward-induction tree (200 steps × up to 200 nodes per step = ~40k node operations per call, plus two more full tree solves for vega and rho via finite difference). The European number is essentially the cost of the Black-Scholes closed form plus three extra `Distribution::Normal.cdf` calls.
+
+## Batch benchmark
+
+`bundle exec ruby bench/batch.rb` (American, mixed calls/puts, IVs in [0.20, 0.65]):
+
+| batch size | wall time | throughput |
+|-----------:|----------:|-----------:|
+|        100 |     1.2 s |  84 ops/s  |
+|      1,000 |    11.9 s |  84 ops/s  |
+|     10,000 |   122.1 s |  82 ops/s  |
+
+Throughput is flat across batch sizes — no GC pressure or hot-path memoization wins, just the per-tree cost compounding linearly. This is the expected shape for pure-Ruby CRR.
+
+## v0.1 ship decision
+
+Tenor's QuantLib pipeline (`GreeksCalculationBatchJob`) processes ~5,000–15,000 options per batch in ~30–60 s, i.e. ~250 ops/s. Our 83 ops/s on the same workload is **~33% of QuantLib's throughput** — acceptable for interactive use and most batch jobs, but slow for large nightly Greeks computations.
+
+The plan's pure-Ruby ship threshold was 50 ops/s; we're comfortably above that. Ship pure Ruby for v0.1; queue performance work for v0.2.
+
+## Performance backlog (v0.2 candidates)
+
+Roughly ordered by expected impact:
+
+1. **Reuse the baseline CRR tree across the σ and r bumps.** Today, vega and rho rebuild the entire tree with a perturbed parameter (3× cost). With careful state separation we can reuse the leaf payoffs and replay only the affected step. Expected: ~3× speedup on American Greeks. Risk: easy to introduce subtle numerical drift if the bumped tree's `dt`, `u`, `d`, `p`, `disc` aren't fully recomputed.
+2. **Drop default `steps` from 200 to 100.** O(N²) tree work, so this is a 4× speedup. Risk: extreme-IV or near-expiry rows lose accuracy — verify against the regression suite before adopting.
+3. **C extension for backward induction** (`rice` or a direct Ruby C extension). Estimated 10–50× speedup on the inner loop. Risk: native code re-introduces the install-friction problem this gem exists to solve. Worth doing only if v0.1 throughput becomes a real bottleneck.
+
+## How to re-run
+
+```bash
+bundle install
+bundle exec ruby bench/single_option.rb     # microbenchmark with benchmark/ips
+bundle exec ruby bench/batch.rb              # batch sweep at 100 / 1k / 10k
+```
+
+`benchmark-ips` is in the gemspec as a `development_dependency`, so `bundle install` pulls it in for the gem checkout but it isn't required for end users.

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-26
+
+Initial release.
+
+### Added
+
+- Object-oriented `PureGreeks::Option` API for vanilla American and European options.
+- Three engines selected automatically by `PureGreeks::Engines::FallbackChain`:
+  - **CRR Binomial American** (200 steps) — for American exercise.
+  - **Black-Scholes European** (closed form) — for European or as fallback.
+  - **Intrinsic** — for `implied_volatility <= 0`.
+- All five Greeks per option: delta, gamma, theta (per calendar day), vega (per 1% vol move), rho (per 1% rate move).
+- Implied volatility solver via Brent's method (`PureGreeks::ImpliedVolatility::BrentSolver`), invoked by passing `market_price:` instead of `implied_volatility:`.
+- `Option#calculation_model` accessor exposes which engine produced the result.
+- Custom error hierarchy (`PureGreeks::Error`, `InvalidInputError`, `ExpiredContractError`, `CalculationError`, `IVConvergenceError`).
+- Regression suite against ~500 historical option snapshots from production data; methodology and observed drift documented in `REGRESSION_REPORT.md`.
+- Performance baselines documented in `BENCHMARKS.md`: ~83 ops/s for American (CRR 200 steps), ~150k ops/s for European (closed form).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jay Ravaliya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.