# MOT Pricing

![CI](https://github.com/AnouarMohamed/JavaFinalJee/actions/workflows/ci.yml/badge.svg)
![Docs](https://github.com/AnouarMohamed/JavaFinalJee/actions/workflows/docs.yml/badge.svg)
![PyPI](https://img.shields.io/pypi/v/mot-pricing)
![Python](https://img.shields.io/pypi/pyversions/mot-pricing)

`mot-pricing` turns the original one-off notebook into a reproducible Python project for robust pricing with martingale optimal transport (MOT).

The reference experiment in this repository studies:

- `S1 ~ Uniform[1, 3]`
- `S2 ~ Uniform[0, 4]`
- payoff `|S1 - S2|`
- exact martingale constraint `E[S2 | S1] = S1`

The codebase includes:

- an exact linear-programming solver for discrete MOT
- a numerically stable entropic regularization solver
- discrete marginal helpers plus convex-order checks
- a built-in payoff library for spread-style payoffs
- a curated gallery runner for multi-example experiment showcases
- corrected unrestricted coupling benchmarks
- a configurable CLI and script for custom uniform interval experiments
- JSON summaries for reproducible experiment outputs
- reusable reporting helpers for figures, diagnostics, and summaries
- tests for the exact and regularized solvers

## Public Outputs

- Docs site: `https://anouarmohamed.github.io/JavaFinalJee/`
- GitHub releases: the tag workflow attaches wheel and source distribution assets
- PyPI package: `https://pypi.org/project/mot-pricing/`
- TestPyPI package: `https://test.pypi.org/project/mot-pricing/`
- Trusted publishing and GitHub Pages are active for this repository

## Why this repo exists

The original notebook had strong ideas but mixed together derivation, experimentation, plotting, and solver logic. It also had a few correctness and presentation issues:

- unrestricted benchmark labels were flipped
- the dual value was compared to the wrong primal quantity in the regularized section
- the `h` update used direct exponentials and produced overflow warnings

This project keeps the same experiment while packaging it into reusable, testable code.

## Quick Start

Install from PyPI:

```bash
pip install mot-pricing
```

Then run the CLI:

```bash
mot-uniform --n 50 --x-interval 1 3 --y-interval 0 4 --payoff abs_spread --eps 1.0 0.3 0.1 0.03 0.01 --output-dir artifacts
```

Generate the curated gallery:

```bash
mot-gallery --output-dir gallery_artifacts
```

For editable local development:

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -e .[dev]
pytest
```

To build the docs locally:

```bash
pip install -e .[docs]
mkdocs serve
```

If you prefer not to install the package in editable mode:

```bash
pip install -r requirements.txt
python scripts/run_uniform_abs_spread.py --output-dir artifacts
```

Custom payoff example:

```bash
mot-uniform --n 60 --x-interval 1 3 --y-interval 0 4 --payoff call_on_spread --strike 0.25 --eps 0.3 0.1
```

## Expected Results

For the default uniform example:

- the exact MOT upper value converges toward `1.0`
- the lower value is about `0.6`
- the unrestricted comonotone coupling is the minimum benchmark
- the unrestricted countermonotone coupling is the maximum benchmark
- the regularized value approaches the exact LP value as `eps -> 0`

For the broader API:

- `DiscreteMarginal` represents weighted discrete laws
- `check_convex_order_discrete(...)` provides a practical feasibility diagnostic
- built-in payoffs include `abs_spread`, `squared_distance`, `call_on_spread`, `put_on_spread`, and `straddle_on_spread`
- `save_experiment_artifacts(...)` writes figures and machine-readable summaries
- `builtin_gallery_specs()` and `save_gallery_assets(...)` generate a mini research gallery

## Repo Layout

- `src/mot_pricing/`: solver library
- `scripts/`: runnable entry script
- `tests/`: regression and numerical checks
- `CHANGELOG.md`: release history
- `CONTRIBUTING.md`: local development and release flow
- `notebooks/`: notebook material preserved from the original exploration
- `docs/`: GitHub Pages documentation source
- `.github/workflows/`: CI for test automation

## Notebook Status

The original notebook is preserved under `notebooks/` as legacy exploratory work. A clean report notebook now imports the library directly, and the library plus CLI are the canonical implementation.
