{"id":51830955,"url":"https://github.com/iamchorchos/thegreeklab","last_synced_at":"2026-07-22T15:00:59.844Z","repository":{"id":371343879,"uuid":"1298256714","full_name":"iamchorchos/theGreekLab","owner":"iamchorchos","description":"Java quantitative finance library for option pricing, Greeks and volatility estimation.","archived":false,"fork":false,"pushed_at":"2026-07-22T13:29:22.000Z","size":69379,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-22T15:00:23.929Z","etag":null,"topics":["american-options","binomial-tree","black-scholes","derivatives","financial-engineering","fortran","greeks","implied-volatility","java","maven-central","numerical-methods","option-pricing","panama-ffm","quantitative-finance","trinomial-tree"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iamchorchos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-12T12:19:32.000Z","updated_at":"2026-07-22T13:26:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/iamchorchos/theGreekLab","commit_stats":null,"previous_names":["iamchorchos/thegreeklab"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/iamchorchos/theGreekLab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamchorchos%2FtheGreekLab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamchorchos%2FtheGreekLab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamchorchos%2FtheGreekLab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamchorchos%2FtheGreekLab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iamchorchos","download_url":"https://codeload.github.com/iamchorchos/theGreekLab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamchorchos%2FtheGreekLab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35766436,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-22T02:00:06.236Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["american-options","binomial-tree","black-scholes","derivatives","financial-engineering","fortran","greeks","implied-volatility","java","maven-central","numerical-methods","option-pricing","panama-ffm","quantitative-finance","trinomial-tree"],"created_at":"2026-07-22T15:00:38.628Z","updated_at":"2026-07-22T15:00:59.833Z","avatar_url":"https://github.com/iamchorchos.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TheGreekLab\n\n![TheGreekLab banner](docs/banner.png)\n\n[![CI](https://img.shields.io/github/actions/workflow/status/iamchorchos/thegreeklab/ci.yml?branch=main\u0026label=CI\u0026logo=github)](https://github.com/iamchorchos/thegreeklab/actions/workflows/ci.yml)\n![Java](https://img.shields.io/badge/Java-22-blue)\n![Maven](https://img.shields.io/badge/Build-Maven-C71A36)\n![JUnit](https://img.shields.io/badge/Tests-JUnit%205-25A162)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/44b8c5d347b14242968b22e35d706416)](https://app.codacy.com/gh/iamchorchos/theGreekLab/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n[![Codacy Coverage](https://app.codacy.com/project/badge/Coverage/44b8c5d347b14242968b22e35d706416)](https://app.codacy.com/gh/iamchorchos/theGreekLab/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_coverage)\n[![Release](https://img.shields.io/github/v/release/iamchorchos/theGreekLab)](https://github.com/iamchorchos/theGreekLab/releases)\n[![License](https://img.shields.io/badge/combined%20distribution-GPL--3.0--or--later-blue)](LICENSE)\n[![Download ZIP](https://img.shields.io/badge/Download-ZIP-2EA44F)](https://github.com/iamchorchos/thegreeklab/archive/refs/heads/main.zip)\n\n![Project Type](https://img.shields.io/badge/Project-Java%20Library-0F766E)\n![Domain](https://img.shields.io/badge/Domain-Quant%20Finance-1D4ED8)\n![Models](https://img.shields.io/badge/Models-BSM%20%7C%20Black--76%20%7C%20CRR%20%7C%20LR%20%7C%20Trinomial%20%7C%20BS2002-7C3AED)\n![Native](https://img.shields.io/badge/Native-Java%20Panama%20%2B%20Fortran-2563EB)\n![Greeks](https://img.shields.io/badge/Greeks-Analytical%20%2B%20Numerical-B45309)\n![Maven Wrapper](https://img.shields.io/badge/Maven%20Wrapper-Included-2EA44F)\n\nTheGreekLab is a Java quantitative finance library for option pricing, Greeks,\nvolatility estimation and model cross-validation.\n\nThe project focuses on clean domain modeling, explicit input validation and\nnumerical tests for vanilla European and American option models.\n\n## Features\n\n- European option pricing:\n  - Black-Scholes-Merton for equity options\n  - Black-76 for futures options\n  - Garman-Kohlhagen for FX options\n  - deterministic discrete cash-dividend schedules\n  - Simple, Haug-Haug, Bos-Gairat-Shepeleva and Bos-Vandermark\n    discrete-dividend approximations\n- American option pricing:\n  - Cox-Ross-Rubenstein binomial tree\n  - Leisen-Reimer binomial tree\n  - recombining trinomial tree for European and American vanilla options\n  - Bjerksund-Stensland 2002 closed-form approximation\n- Native numerical integration:\n  - bivariate normal CDF through the Java Foreign Function and Memory API\n  - original Fortran `pbivnorm` routine\n- Greeks:\n  - price, delta, gamma, vega, theta and rho across supported pricing models\n  - immutable `StandardGreekValues` snapshots for retrieving them together\n  - numerical standard Greeks for Bjerksund-Stensland 2002\n  - bump-and-revalue standard Greeks for all discrete-dividend approximations\n  - node-based delta, gamma and theta plus bumped vega and rho for the\n    trinomial tree\n  - vanna, volga, charm, speed, lambda\n  - dual delta, dual gamma\n  - vera, zomma, color, ultima\n  - epsilon, veta and parmicharma for supported European models\n- Volatility tools:\n  - historical close-to-close volatility\n  - Parkinson high-low volatility\n  - implied volatility via Brent root finding\n- Market data abstractions:\n  - equity frame\n  - futures frame\n  - FX frame\n- JUnit test suite with numerical cross-validation data\n\n## Requirements\n\n- Java 22+\n- Maven, or the included Maven wrapper\n- Native `pbivnorm` library for the current platform when using\n  Bjerksund-Stensland 2002\n\nThe project includes Maven wrapper scripts, so a global Maven installation is\nnot required.\n\nA Windows x86-64 `pbivnorm.dll` is bundled with the project. GitHub Actions\nbuilds the Linux x86-64 library from `src/main/fortran/pbivnorm.f` before\nrunning Maven. Other platforms can supply an external library through:\n\n```text\n-Dthegreeklab.pbivnorm.path=/absolute/path/to/library\n```\n\nor the `THEGREEKLAB_PBIVNORM_PATH` environment variable. Applications using\nthe native CDF should enable native access for the unnamed module:\n\n```text\n--enable-native-access=ALL-UNNAMED\n```\n\n## Releases\n\nStarting with version 2.0.1, releases are published to Maven Central under\n`io.github.iamchorchos:thegreeklab` and remain available from\n[GitHub Releases](https://github.com/iamchorchos/theGreekLab/releases).\n\nAdd the library to a Maven project with:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.iamchorchos\u003c/groupId\u003e\n    \u003cartifactId\u003ethegreeklab\u003c/artifactId\u003e\n    \u003cversion\u003e2.2.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nNew semantic-version tags such as `v2.0.0` are verified automatically and\npublish:\n\n- signed Maven artifacts to Maven Central,\n- the compiled library JAR on GitHub Releases,\n- source and Javadoc JARs,\n- SHA-256 checksums for every artifact.\n\nMaintainer setup and release instructions are documented in\n[docs/PUBLISHING.md](docs/PUBLISHING.md).\n\n## Running Tests\n\nWindows PowerShell:\n\n```powershell\n.\\mvnw.cmd test\n```\n\nLinux/macOS:\n\n```bash\n./mvnw test\n```\n\nThe full test suite contains large numerical datasets, so it may take longer\nthan a small unit-test-only project.\n\nTo run all verification checks and generate the JaCoCo coverage report:\n\n```bash\n./mvnw verify\n```\n\nThe local HTML report is written to `target/site/jacoco/index.html`. The build\nrequires at least 85% line coverage and 65% branch coverage. CI also archives\nthe complete report and uploads `jacoco.xml` to Codacy.\n\nAfter a release is available from Maven Central, compare the current public and\nprotected API with that explicit baseline using japicmp:\n\nWindows PowerShell:\n\n```powershell\n.\\mvnw.cmd verify -Papi-compatibility \"-Dapi.baseline.version=2.1.0\"\n```\n\nLinux/macOS:\n\n```bash\n./mvnw verify -Papi-compatibility -Dapi.baseline.version=2.1.0\n```\n\nThe compatibility profile fails on binary- or source-incompatible changes and\nwrites its reports to `target/japicmp`. Keeping the baseline version explicit\nmakes local and CI results reproducible. Enable this profile in CI after the\nfirst `2.x` artifact has been published; the intentional `1.x` to `2.x` API\nmigration is the bootstrap boundary.\n\n## Benchmarks\n\nThe JMH suite measures:\n\n- the Bjerksund-Stensland price, each standard Greek and the combined\n  `greeks()` snapshot,\n- complete Bjerksund-Stensland, Cox-Ross-Rubinstein and Leisen-Reimer\n  valuations, including their standard Greeks,\n- an end-to-end call to native `pbivnorm` through the public Panama FFM\n  bridge.\n\nRun the benchmark profile on Windows:\n\n```powershell\n.\\mvnw.cmd -Pbenchmarks test-compile exec:exec\n```\n\nOn Linux/macOS:\n\n```bash\n./mvnw -Pbenchmarks test-compile exec:exec\n```\n\nThe model comparison uses a one-year American put with strike 100, spot 95,\na 5% risk-free rate, 3% dividend yield and 25% volatility. The tree models run\nwith 251 and 1001 steps. Every measured binomial invocation receives a fresh\nmodel so that the benchmark includes tree construction and backward induction\ninstead of reporting a cached price.\nTo run only the American-option benchmark:\n\n```powershell\n.\\mvnw.cmd -Pbenchmarks test-compile exec:exec \"-Dbenchmark.include=.*AmericanOptionBenchmark.*\"\n```\n\nResults are printed to the console and saved as\n`target/jmh-result.json`. Run benchmarks outside a debugger on an otherwise\nidle machine; absolute timings depend on the JDK, native library, CPU and\noperating system.\n\n## Code Quality\n\nThe project is configured with:\n\n- Maven Compiler Plugin with Java 22 release target\n- JUnit 5 test suite\n- JaCoCo XML and HTML coverage reports\n- SpotBugs during `mvn verify`\n- japicmp binary and source API checks against an explicit released baseline\n- Codacy coverage and quality monitoring\n- GitHub Actions CI in `.github/workflows/ci.yml`\n- reproducible release artifacts from `.github/workflows/release.yml`\n\nThe project itself should be treated primarily as a library.\n\n## Quick Start\n\nBlack-Scholes-Merton equity option:\n\n```java\nimport com.thegreeklab.finance.contract.OptionContract;\nimport com.thegreeklab.finance.enums.Option;\nimport com.thegreeklab.finance.enums.OptionType;\nimport com.thegreeklab.finance.frame.EquityFrame;\nimport com.thegreeklab.finance.model.european.BlackScholesMerton;\nimport com.thegreeklab.finance.time.DayCountConvention;\n\nimport java.time.ZoneOffset;\nimport java.time.ZonedDateTime;\n\nZonedDateTime now = ZonedDateTime.now(ZoneOffset.UTC);\nZonedDateTime expiry = now.plusMonths(6);\n\nOptionContract call = new OptionContract(\n        \"AAPL\",\n        OptionType.CALL,\n        Option.EUROPEAN,\n        210.0,\n        expiry,\n        100\n);\n\nEquityFrame frame = new EquityFrame(\n        now,\n        205.35,\n        0.045,\n        0.005\n);\n\nBlackScholesMerton model = new BlackScholesMerton(\n        call,\n        frame,\n        0.22,\n        DayCountConvention.ACT_365F\n);\n\ndouble price = model.price();\ndouble delta = model.delta();\ndouble gamma = model.gamma();\ndouble vega = model.vega();\n```\n\n### Version 2 time model\n\n`OptionContract` stores expiration exactly once as a `ZonedDateTime`. Every\ncontract-based model explicitly selects a `DayCountConvention`, currently\n`ACT_365F` or `ACT_360`; day count has no process-global or environment-based\ndefault.\nThe v1 constructor parameters `expirationNanosEpoch` and\n`secondsInExpirationYear` have been removed, eliminating contradictory\nexpiration metadata.\n\nFull examples for every supported model and volatility utility are available in\n[docs/USAGE.md](docs/USAGE.md).\n\n## Documentation\n\n- [Usage guide](docs/USAGE.md)\n- [Mathematical notes](docs/MATH.md)\n- [Sources and references](docs/REFERENCES.md)\n- [Publishing guide](docs/PUBLISHING.md)\n- [Changelog](CHANGELOG.md)\n- [Contributing guide](CONTRIBUTING.md)\n- [Security policy](SECURITY.md)\n\n## Project Structure\n\n```text\nsrc/main/java/com/thegreeklab\n  finance/contract/           option contract model\n  finance/enums/              option type and exercise style enums\n  finance/exception/          domain-specific exceptions\n  finance/frame/              market-data frames\n  finance/model/american/     American option models\n    approximations/           Bjerksund-Stensland 2002\n    binomial/                 CRR and Leisen-Reimer trees\n    trinomial/                recombining trinomial tree\n  finance/model/european/     European option models\n    discrete/                 cash dividends, schedules and adjustment models\n  finance/model/greeks/       Greeks interface\n  finance/numerical/          numerical utilities\n  math/                       volatility, distributions and numerical helpers\n\nsrc/main/fortran              native pbivnorm source\nsrc/main/resources/native     bundled platform libraries\n\nsrc/test/java                 unit and cross-validation tests\nsrc/test/resources            numerical reference datasets\n```\n\n## Design Notes\n\n- The library separates contract data from market data.\n- European models accept only European contracts.\n- Discrete-dividend models require an `EquityFrame` with zero continuous\n  dividend yield and include only cash dividends strictly between valuation\n  and expiration.\n- `DividendSchedule` is immutable and sorts entries chronologically.\n- Discrete-dividend approximations expose their adjusted spot, strike and\n  volatility, plus immutable bump scenarios and five numerical standard Greeks.\n- American binomial models accept only American contracts.\n- The trinomial tree accepts European and American vanilla contracts and\n  supports immutable scenario repricing through `BumpableOptionModel`.\n- Bjerksund-Stensland accepts American contracts and exposes price plus\n  numerical delta, gamma, vega, theta and rho.\n- Market-data frames encode the model-specific cost of carry:\n  - `EquityFrame`: `b = r - q`\n  - `FuturesFrame`: `b = 0`\n  - `FXFrame`: `b = domesticRate - foreignRate`\n- Invalid inputs fail fast through domain-specific exceptions.\n- Binomial Greeks are finite-difference based and can be sensitive to tree\n  depth, bump size and near-zero option values.\n\n## Validation\n\nThe test suite covers:\n\n- model validation and invalid input handling\n- Black-Scholes invariants\n- expiry behavior\n- historical volatility\n- Parkinson volatility\n- implied volatility\n- ERF and normal CDF accuracy\n- Peizer-Pratt inversion\n- American binomial model behavior\n- trinomial price and standard-Greek convergence against Black-Scholes-Merton\n- trinomial early-exercise behavior and immutable bump operations\n- published Haug-Haug and Bos-Vandermark discrete-dividend reference values\n- discrete-dividend input adjustments, schedule filtering and numerical Greeks\n- all 36 Bjerksund-Stensland 2002 values from Haug table 3-2\n- bivariate normal identities and perfect-correlation limits\n- Bjerksund-Stensland expiry, no-arbitrage bounds and numerical fallback\n- Bjerksund-Stensland Greeks in the European limit and American exercise region\n- CRR model behavior, identities and numerical Greeks\n\nThe publications, table references, fixture provenance and numerical-data\nlimitations are recorded in [Sources and references](docs/REFERENCES.md).\n\n## Licensing\n\nThe combined JAR distribution is provided under\n[GPL-3.0-or-later](LICENSE). TheGreekLab uses component-specific licensing:\n\n- original Java code, tests and documentation: [MIT](LICENSES/MIT.txt),\n- `pbivnorm.f` and native binaries compiled from it:\n  [GPL-2.0-or-later](LICENSES/GPL-2.0.txt),\n- distributions combining the Java and native components:\n  [GPL-3.0-or-later](LICENSES/GPL-3.0.txt).\n\nThe MIT license continues to apply independently to the original Java files.\nThe native provenance and author attribution are recorded in [NOTICE](NOTICE).\nThe complete component-level explanation is in\n[LICENSING.md](LICENSING.md).\nLicense texts and the notice are also included in built JAR files under\n`META-INF`.\n\n## Status\n\nThis is a library-oriented quantitative-finance project with independently\ncross-validated pricing models and an automated verification pipeline.\n\nIt is not financial advice and should not be used for live trading or risk\nmanagement without independent validation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamchorchos%2Fthegreeklab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiamchorchos%2Fthegreeklab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamchorchos%2Fthegreeklab/lists"}