Kiyosi

Kiyosi is a modern C++23 derivatives-pricing library with Python bindings, offering consistent APIs for vanilla, exotic, and structured products.

Features

• Vanilla, digital, Asian, barrier, accumulator, snowball, and phoenix instruments
• Analytic, tree-based, finite-difference, integral, and Monte Carlo pricing engines with CPU and CUDA backends
• Price-only valuation and on-demand calculation of selected Greeks
• Numerical analytics, implied volatility, and implied coupon solvers
• Trading calendars and observation schedule builders, including SSE holidays
• A native C++ core exposed through a Python-first API

Quick start with Python

Kiyosi requires Python 3.11 or newer:

python -m pip install kiyosi

PyPI provides prebuilt x64 wheels for Windows and Linux, including CUDA acceleration for Monte Carlo engines. CPU remains the default; using CUDA requires a compatible NVIDIA GPU and driver. On other platforms, installation builds from source and requires CMake 3.28 or newer, Ninja, and a C++23 compiler.

Price a European call with the analytic Black-Scholes engine:

from datetime import date

from kiyosi.instruments import EuropeanOption
from kiyosi.market import BlackScholesMertonParameters, PricingContext
from kiyosi.pricing import AnalyticVanillaEngine

valuation = date(2025, 1, 1)
option = EuropeanOption(
    option_type="call",
    strike=100.0,
    effective_date=valuation,
    expiry_date=date(2026, 1, 1),
)
context = PricingContext(
    model_parameters=BlackScholesMertonParameters(
        risk_free_rate=0.05,
        dividend_yield=0.02,
        volatility=0.20,
    ),
    spot_price=100.0,
    valuation_time=valuation,
)

engine = AnalyticVanillaEngine()
print(engine.price(option, context))  # float; no Greeks are calculated

selected = engine.price_with_greeks(option, context, ["delta", "gamma"])
print(selected.price, selected.delta, selected.gamma)

full = engine.price_with_greeks(option, context, all_greeks=True)
print(full.vega, full.theta)

Pass one lowercase Greek name or an iterable of them to request Greeks. all_greeks=True requests Delta, Gamma, Speed, Theta, Charm, Color, Vega, Vanna, Zomma, and Rho. The two request forms are mutually exclusive. Native Greeks are reused; missing feasible measures use numerical price differences. Unrequested or undefined measures are None, including all Greeks at expiry. Shift keyword arguments (spot_shift, volatility_shift, rate_shift, and time_shift_days) control numerical supplementation. Monte Carlo base and bumped valuations share one seed per call without changing the engine settings. calculate_numerical_greeks() remains the forced numerical alternative.

C++ uses the same contract: price() returns Result<double> and price_with_greeks(option, context, {Greek::delta, Greek::vega}) returns Result<PricingResult>, whose price() is always present. Use true as the third argument for all ten Greeks and pass an optional NumericalShiftSettings as the final argument to customize shifts.

The Python API is organized into three modules:

Select the CUDA backend on any Monte Carlo engine:

from kiyosi.pricing import MonteCarloVanillaEngine

engine = MonteCarloVanillaEngine(backend="cuda")
result = engine.price(option, context)

Enum-like Python inputs use lowercase strings such as "call", "cuda", and "crank_nicolson". Properties return the same strings. Public OptionType, MonteCarloBackend, and similar names are typing.Literal aliases for static type checking; KiyosiError.category remains an ErrorCategory Enum.

Pricing coverage

Model scope

The current pricing models use a Black-Scholes-Merton market context with spot and flat risk-free rate, dividend yield, and volatility parameters. Volatility surfaces and rate curves are not part of the current API.

Validation

Kiyosi's pricing tests compare results with reference values generated independently of Kiyosi using QuantLib. QuantLib is used by the reference-generation tooling and SSE calendar maintenance script; it is not a build or runtime dependency of the C++ core.

For performance comparisons against QuantLib C++, see the pricing benchmark matrix.

C++ library

Building the C++ core requires CMake 3.28 or newer, Ninja, and a C++23 compiler. On Linux, configure, build, test, and install with:

cmake --workflow --preset linux-release
cmake --install out/build/linux-release

On Windows, run the commands from a Visual Studio Developer PowerShell and replace linux-release with windows-release.

After installation, consume the exported CMake target:

find_package(kiyosi CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE kiyosi::kiyosi)

Include the umbrella header with #include <kiyosi/kiyosi.hpp>. See examples/all_pricing_engines.cpp for a broader example covering the available instrument and engine families.

License

Kiyosi is available under the MIT License.