Installation and a first result

Install

Install the released package from PyPI:

python -m pip install vanilla-option-pricers

For a source checkout, install the package and the build-only documentation tools separately:

python -m pip install -e ".[docs]"

The package’s runtime dependencies remain NumPy and Numba. Sphinx, MyST Parser, and Furo belong only to the optional docs extra.

Run the authoritative offline example

The repository’s pricing and IV script is the single source for first success. It uses only the installed package, NumPy, Numba, and deterministic generated inputs; it requires no network, credentials, pandas, or SciPy and creates no files.

From a source checkout with the package installed, run:

python examples/getting_started/pricing_and_iv.py

The wheel intentionally excludes repository examples. After installing from PyPI, download or copy the linked script and run it from any directory.

For a zero-local-setup trial, the Colab notebook installs the latest released distribution from the official PyPI index, prints its distribution version and import path, and runs the exact same workflow below. The committed notebook contains no execution output.

"""Offline first-success workflow for vanilla-option-pricers."""

from enum import Enum
from importlib.metadata import version
from pathlib import Path
from time import perf_counter

import numpy as np
from numba.typed import List

import vanilla_option_pricers as vop

forward = 100.0
discfactor = 0.98
ttm = 0.50
strikes = np.array([90.0, 100.0, 100.0, 110.0])
option_types = np.array(["P", "P", "C", "C"])
solve_types = List(option_types.tolist())
lognormal_vols = np.full(strikes.shape, 0.20)


class Locals(Enum):
    """Available local pricing and implied-volatility workflows."""

    PRICING_AND_IV = 1


def run_bsm_workflow() -> tuple[np.ndarray, np.ndarray]:
    """Price one aligned BSM slice and recover its implied volatilities."""
    prices = vop.compute_bsm_vanilla_slice_prices(
        ttm,
        forward,
        strikes,
        lognormal_vols,
        option_types,
        discfactor,
    )
    implied_vols = vop.infer_bsm_ivols_from_slice_prices(
        ttm,
        forward,
        discfactor,
        strikes,
        solve_types,
        prices,
    )
    return prices, implied_vols


def run_local(local: Locals) -> None:
    """Run the selected pricing and implied-volatility workflow."""
    if local != Locals.PRICING_AND_IV:
        raise ValueError(f"Unsupported local case: {local}")

    cold_started = perf_counter()
    prices, implied_vols = run_bsm_workflow()
    cold_seconds = perf_counter() - cold_started

    warm_repetitions = 10
    warm_started = perf_counter()
    for _ in range(warm_repetitions):
        warm_prices, warm_implied_vols = run_bsm_workflow()
    warm_mean_seconds = (perf_counter() - warm_started) / warm_repetitions

    max_iv_error = float(np.max(np.abs(implied_vols - lognormal_vols)))
    parity_error = float(prices[2] - prices[1] - discfactor * (forward - strikes[1]))

    absolute_normal_vol = 5.0
    normal_strike = 102.0
    normal_price = vop.compute_normal_price(
        forward,
        normal_strike,
        ttm,
        absolute_normal_vol,
        discfactor,
        "C",
    )
    normal_implied_vol = vop.infer_normal_implied_vol(
        forward,
        ttm,
        normal_strike,
        normal_price,
        discfactor,
        "C",
    )

    if max_iv_error > 1e-7:
        raise RuntimeError(f"BSM implied-volatility round trip failed: {max_iv_error}")
    if abs(parity_error) > 1e-10:
        raise RuntimeError(f"BSM put-call parity failed: {parity_error}")
    if abs(normal_implied_vol - absolute_normal_vol) > 1e-7:
        raise RuntimeError("Bachelier implied-volatility round trip failed")
    if not (
        np.array_equal(prices, warm_prices)
        and np.array_equal(implied_vols, warm_implied_vols)
    ):
        raise RuntimeError("Warm BSM workflow changed the deterministic result")

    print(f"distribution_version={version('vanilla-option-pricers')}")
    print(f"import_path={Path(vop.__file__).resolve()}")
    print(
        "array_shapes="
        f"strikes{strikes.shape} option_types{option_types.shape} "
        f"prices{prices.shape} implied_vols{implied_vols.shape}"
    )
    print("option_types=" + str(option_types.tolist()))
    print("prices=" + np.array2string(prices, precision=8))
    print(f"max_iv_error={max_iv_error:.3e} parity_error={parity_error:.3e}")
    print(
        f"cold_first_call_seconds={cold_seconds:.6f} "
        f"warm_mean_seconds={warm_mean_seconds:.6f} "
        f"warm_repetitions={warm_repetitions}"
    )
    print(
        f"bachelier_absolute_vol={absolute_normal_vol:.6f} "
        f"price={normal_price:.8f} iv_error="
        f"{normal_implied_vol - absolute_normal_vol:.3e}"
    )
    print("bsm_convention=forward, discount factor, years, annualised lognormal volatility")
    print("bachelier_convention=annualised absolute normal volatility in forward units")
    print(
        "change_first=forward, discfactor, ttm, strikes, option_types, model_convention"
    )


if __name__ == "__main__":
    run_local(local=Locals.PRICING_AND_IV)

The script prices one aligned BSM slice, recovers all four input volatilities, and checks the same-strike call/put pair against forward put-call parity. It also prices and inverts one Bachelier call with annualised absolute normal volatility in the same units as the forward and strike.

Successful output reports package version and import path; input/output shapes; option codes and prices; maximum IV and parity errors; one cold first-call duration; the mean of ten warm repeats; and the Bachelier result. Timing values are machine-dependent and are not a benchmark. The verified numerical errors are required to remain below the explicit thresholds in the script.

Start adaptation with the final change_first line: forward, discfactor, ttm, strikes, option_types, and model_convention. Preserve the stated units and alignment contracts when substituting market inputs.

Next steps and boundaries

Use the package-root functions for stable user examples. Array helpers have distinct scalar, aligned-array, grid, and per-expiry contracts; arbitrary broadcasting is not promised. The first call to a Numba-compiled signature includes compilation time.

Continue with pricing and Greeks, implied volatility, Bachelier units, and array/Numba behavior. Use the issue tracker for support.