quantplus 0.0.4__tar.gz → 0.0.5__tar.gz

{quantplus-0.0.4 → quantplus-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantplus
-Version: 0.0.4
+Version: 0.0.5
 Summary: Cox-Ross-Rubinstein binomial option pricer (C++ core, Cython bindings)
 Author-email: Your Name <you@example.com>
 License: MIT

quantplus-0.0.5/docs/source/api.rst

@@ -0,0 +1,45 @@
+===
+API
+===
+
+This page summarizes the public API exposed by the package.
+
+Top-level functions
+-------------------
+
+The package exports the following functions at the top level:
+
+.. autofunction:: quantplus.crr_price
+
+.. autofunction:: quantplus.black_scholes_price
+
+.. autofunction:: quantplus.crr_tree
+
+Module overview
+---------------
+
+The public package is intentionally lightweight and exposes only the functions
+that users are expected to call directly. The numerical implementation itself is
+kept in the compiled extension and C++ source files.
+
+You can inspect the runtime package directly in Python:
+
+.. code-block:: python
+
+    import quantplus as qp
+
+    print(qp.__all__)
+    print(qp.__version__)
+
+This helps developers confirm which functions are part of the supported public
+surface.
+
+Other useful considerations
+---------------------------
+
+- ``crr_price`` is the main pricing function for binomial-tree valuation.
+- ``black_scholes_price`` is the analytic benchmark for comparison.
+- ``crr_tree`` is useful when you want the tree terminal nodes or payoffs.
+
+The package may evolve over time, but the public interface remains intentionally
+stable and easy to inspect.

quantplus-0.0.5/docs/source/architecture.rst

@@ -0,0 +1,103 @@
+============
+Architecture
+============
+
+``quantplus`` is intentionally small and modular. The project separates the
+public Python API from the performance-critical numerical implementation so that
+users interact with a clean interface while the expensive work runs in compiled
+code.
+
+High-level layout
+-----------------
+
+.. code-block:: text
+
+    quantplus/
+    ├── __init__.py              # public exports
+    ├── _crr_pricer.pyx          # Cython bridge to native C++
+    ├── csrc/
+    │   ├── crr_core.cpp         # CRR and Black-Scholes math
+    │   └── crr_core.h           # C interface declarations
+    └── tests/
+        └── test_quantplus.py    # regression and validation tests
+
+Public Python API
+------------------
+
+The package user interface lives in ``quantplus/__init__.py``. This file imports
+and re-exports the functions that are intended for normal use:
+
+- ``crr_price``
+- ``black_scholes_price``
+- ``crr_tree``
+
+This makes the API easy to discover and keeps the import path simple:
+
+.. code-block:: python
+
+    import quantplus as qp
+
+    price = qp.crr_price(...)
+
+Cython bridge layer
+-------------------
+
+The ``_crr_pricer.pyx`` file is a thin wrapper around the compiled C++ core. It
+is written in Cython so that Python can call native functions while preserving a
+Pythonic API.
+
+This is where the package handles several concerns:
+
+- argument validation
+- conversion from Python values to native types
+- calling the C++ implementation
+- packaging the result back into native Python objects
+
+The bridge is deliberately lightweight. It does not duplicate the numerical logic;
+it mostly delegates to the native implementation and enforces sensible input
+checks.
+
+Native C++ implementation
+-------------------------
+
+The actual model logic is implemented in ``quantplus/csrc/crr_core.cpp``.
+It exposes plain C-linkage functions through ``crr_core.h``. The functions are:
+
+- ``crr_price``
+- ``black_scholes_price``
+- ``crr_price_with_terminal_nodes``
+
+These functions are defined using a simple C ABI so Cython can call them without
+relying on C++ name mangling or class-based object models.
+
+This design matters because it keeps the compiled part:
+
+- fast
+- easy to call from Cython
+- independent of Python object management
+
+Build pipeline
+--------------
+
+The package is built through ``setup.py`` and the metadata in ``pyproject.toml``.
+The build process does the following:
+
+1. Cython compiles ``_crr_pricer.pyx`` into a Python extension.
+2. The native C++ source is compiled and linked into the same extension module.
+3. Python imports the resulting ``quantplus._crr_pricer`` extension at runtime.
+
+This hybrid approach is common in numerical libraries: Python handles the public
+interface and automation, while the inner loop runs in compiled code.
+
+Why this architecture works well
+--------------------------------
+
+The package stays easy to understand because each layer has a clear responsibility:
+
+- Python: user-facing API and validation
+- Cython: interop glue and conversion
+- C++: performance-critical option-pricing logic
+- tests: numerical correctness and regression protection
+
+This separation keeps the code readable while still giving the package the speed of
+native execution for repeated computations and lattice evaluations.

quantplus-0.0.5/docs/source/development.rst

@@ -0,0 +1,93 @@
+===========
+Development
+===========
+
+This project is small enough that development remains lightweight, but it still
+benefits from a clear workflow for building, testing, and documenting the package.
+
+Recommended environment
+------------------------
+
+Use a virtual environment for local development:
+
+.. code-block:: bash
+
+    python -m venv .venv
+    source .venv/bin/activate
+    python -m pip install -U pip
+    python -m pip install -r requirements-dev.txt
+
+Then install the project itself in editable mode:
+
+.. code-block:: bash
+
+    python -m pip install -e .
+
+This allows changes to the Python files and compiled extension to be picked up
+without reinstalling the package repeatedly.
+
+Running tests
+-------------
+
+The project uses ``pytest`` for regression and validation testing. Run the suite
+with:
+
+.. code-block:: bash
+
+    pytest
+
+This checks the pricing functions against known values and ensures that numerical
+behavior stays consistent after changes.
+
+Building the extension
+----------------------
+
+The package compiles the native C++ and Cython extension as part of installation.
+If you want to trigger a fresh build manually, use:
+
+.. code-block:: bash
+
+    python setup.py build_ext --inplace
+
+This builds the extension in place so it can be imported directly from the source
+checkout during testing and debugging.
+
+Building the docs
+-----------------
+
+The documentation is built with Sphinx. From the project root, run:
+
+.. code-block:: bash
+
+    python -m sphinx -b html docs/source docs/build/html
+
+This creates a local HTML build that can be reviewed in the browser.
+
+Project conventions
+-------------------
+
+A few conventions help keep the package maintainable:
+
+- keep the public API small and deliberate
+- prefer simple, explicit function signatures
+- validate common inputs early
+- add regression tests when changing pricing math
+- document numerical assumptions and edge cases clearly
+
+When the pricing logic is modified, it is important to validate the change against
+known examples and the existing test suite.
+
+Contribution workflow
+---------------------
+
+A typical contribution flow looks like this:
+
+1. create a feature branch
+2. make a focused change
+3. add or update tests
+4. run the relevant test subset
+5. update documentation if behavior or usage changes
+6. submit a pull request with a clear summary
+
+This keeps the project coherent and makes it easier to review numerical changes
+that may affect pricing outcomes.

quantplus-0.0.5/docs/source/examples.rst

@@ -0,0 +1,168 @@
+========
+Examples
+========
+
+This page shows a few representative ways to use ``quantplus`` in practice.
+
+European call valuation
+-----------------------
+
+.. code-block:: python
+
+    import quantplus as qp
+
+    price = qp.crr_price(
+        S0=100.0,
+        K=100.0,
+        r=0.05,
+        sigma=0.20,
+        T=1.0,
+        N=200,
+        q=0.01,
+        is_call=True,
+        american=False,
+    )
+
+    print(f"European call price: {price:.6f}")
+
+European put valuation
+----------------------
+
+.. code-block:: python
+
+    import quantplus as qp
+
+    put_price = qp.crr_price(
+        S0=95.0,
+        K=100.0,
+        r=0.04,
+        sigma=0.25,
+        T=2.0,
+        N=500,
+        q=0.02,
+        is_call=False,
+        american=False,
+    )
+
+    print(f"European put price: {put_price:.6f}")
+
+American option valuation
+-------------------------
+
+.. code-block:: python
+
+    import quantplus as qp
+
+    american_put = qp.crr_price(
+        S0=90.0,
+        K=100.0,
+        r=0.03,
+        sigma=0.30,
+        T=1.5,
+        N=300,
+        q=0.0,
+        is_call=False,
+        american=True,
+    )
+
+    print(f"American put price: {american_put:.6f}")
+
+Comparing CRR and Black-Scholes
+-------------------------------
+
+.. code-block:: python
+
+    import quantplus as qp
+
+    s0, k, r, sigma, t, q = 100.0, 100.0, 0.05, 0.20, 1.0, 0.01
+
+    crr_value = qp.crr_price(
+        S0=s0,
+        K=k,
+        r=r,
+        sigma=sigma,
+        T=t,
+        N=500,
+        q=q,
+        is_call=True,
+        american=False,
+    )
+
+    bs_value = qp.black_scholes_price(
+        S0=s0,
+        K=k,
+        r=r,
+        sigma=sigma,
+        T=t,
+        q=q,
+        is_call=True,
+    )
+
+    print(f"CRR price: {crr_value:.6f}")
+    print(f"Black-Scholes price: {bs_value:.6f}")
+
+Inspecting the terminal tree
+----------------------------
+
+The ``crr_tree`` function is useful when you want to inspect the terminal node
+values or build custom visualizations.
+
+.. code-block:: python
+
+    import quantplus as qp
+
+    root, stock_prices, payoffs = qp.crr_tree(
+        S0=100.0,
+        K=100.0,
+        r=0.05,
+        sigma=0.20,
+        T=1.0,
+        N=5,
+        q=0.01,
+        is_call=True,
+    )
+
+    print(root)
+    print(stock_prices)
+    print(payoffs)
+
+This pattern is especially useful when you are debugging the model or comparing
+values across a lattice.
+
+.. plot::
+    :caption: Terminal call and put payoffs at the stock-price nodes returned by ``crr_tree``.
+
+    import matplotlib.pyplot as plt
+    import quantplus as qp
+
+    parameters = dict(S0=100.0, K=100.0, r=0.05, sigma=0.20, T=1.0, N=8, q=0.01)
+    _, call_stocks, call_payoffs = qp.crr_tree(**parameters, is_call=True)
+    _, put_stocks, put_payoffs = qp.crr_tree(**parameters, is_call=False)
+
+    fig, ax = plt.subplots(figsize=(8, 4.5))
+    ax.scatter(call_stocks, call_payoffs, color="#147d78", s=42, label="Call")
+    ax.scatter(put_stocks, put_payoffs, color="#c05a36", s=42, label="Put")
+    ax.axvline(parameters["K"], color="#667780", linestyle="--", linewidth=1,
+                  label="Strike")
+    ax.set_xlabel("Stock price at expiry")
+    ax.set_ylabel("Option payoff at expiry")
+    ax.set_title("Terminal payoffs on the CRR lattice")
+    ax.grid(alpha=0.25)
+    ax.legend(frameon=False)
+    fig.tight_layout()
+
+Running a small sensitivity check
+---------------------------------
+
+.. code-block:: python
+
+    import quantplus as qp
+
+    params = dict(S0=100.0, K=100.0, r=0.05, T=1.0, N=200, q=0.01)
+
+    for sigma in [0.10, 0.20, 0.30, 0.40]:
+        price = qp.crr_price(sigma=sigma, is_call=True, **params)
+        print(f"sigma={sigma:.2f}, price={price:.6f}")
+
+As volatility increases, option prices generally increase for standard long
+positions, which is consistent with the intuition behind the model.

quantplus-0.0.5/docs/source/finance.rst

@@ -0,0 +1,249 @@
+==========================================
+Finance and CRR(Cox-Ross-Rubinstein) model
+==========================================
+
+This page explains the pricing model used by ``quantplus`` and the assumptions
+behind it. The package implements the Cox-Ross-Rubinstein (CRR) binomial tree
+model for option pricing, along with the closed-form Black-Scholes benchmark.
+
+Option pricing problem
+----------------------
+
+An option is a derivative whose value depends on the future behavior of an
+underlying asset. At a high level, the task is to estimate the present value of
+a future payoff under a model for the underlying price process.
+
+For a European option, the value at maturity is known from the payoff function:
+
+- call payoff: max(S_T - K, 0)
+- put payoff: max(K - S_T, 0)
+
+where:
+
+- ``S_T`` is the underlying price at maturity
+- ``K`` is the strike price
+
+The CRR model provides a discrete-time approximation to the risky asset dynamics.
+
+CRR binomial tree model
+-----------------------
+
+The Cox-Ross-Rubinstein framework assumes that the underlying price moves through
+a recombining binomial tree over discrete time steps. At each step, the price can
+move up or down by multiplicative factors:
+
+- ``u``: up factor
+- ``d``: down factor
+
+For a standard CRR construction:
+
+- ``u = exp(sigma * sqrt(dt))``
+- ``d = 1 / u``
+
+where ``dt = T / N`` and ``N`` is the number of time steps.
+
+The risk-neutral up probability is:
+
+.. math::
+
+    p = \frac{e^{(r-q)dt} - d}{u - d}
+
+where:
+
+- ``r`` is the risk-free rate
+- ``q`` is the dividend yield or carry adjustment
+- ``sigma`` is the volatility
+
+This probability is chosen so that the expected discounted stock return matches
+the risk-free rate under the risk-neutral measure.
+
+.. plot::
+   :caption: A four-step CRR stock-price lattice. Different paths recombine at shared nodes.
+
+   from math import exp, sqrt
+
+   import matplotlib.pyplot as plt
+
+   initial_price = 100.0
+   volatility = 0.25
+   expiry = 1.0
+   steps = 4
+   up = exp(volatility * sqrt(expiry / steps))
+   down = 1.0 / up
+
+   fig, ax = plt.subplots(figsize=(9, 4.5))
+   for level in range(steps):
+       for up_moves in range(level + 1):
+           x = level
+           y = 2 * up_moves - level
+           for next_up_moves in (up_moves, up_moves + 1):
+               next_x = level + 1
+               next_y = 2 * next_up_moves - next_x
+               ax.plot([x, next_x], [y, next_y], color="#91a4ad", linewidth=1.2, zorder=1)
+
+   for level in range(steps + 1):
+       for up_moves in range(level + 1):
+           y = 2 * up_moves - level
+           stock_price = initial_price * up**up_moves * down ** (level - up_moves)
+           ax.scatter(level, y, s=90, color="#147d78", edgecolor="white", zorder=2)
+           ax.annotate(f"{stock_price:.0f}", (level, y), xytext=(0, 10),
+                       textcoords="offset points", ha="center", fontsize=8)
+
+   ax.set_xticks(range(steps + 1), [f"Step {step}" for step in range(steps + 1)])
+   ax.set_ylabel("Up/down state")
+   ax.set_title("Recombining CRR stock-price lattice")
+   ax.set_ylim(-steps - 0.8, steps + 0.8)
+   ax.grid(axis="x", alpha=0.2)
+   ax.spines[["top", "right", "left"]].set_visible(False)
+   ax.tick_params(axis="y", left=False, labelleft=False)
+   fig.tight_layout()
+
+Backward induction
+------------------
+
+The option value is computed recursively from maturity back to the present. At the
+terminal nodes, the value is the payoff:
+
+- call: ``max(S - K, 0)``
+- put: ``max(K - S, 0)``
+
+Then at each earlier node, the continuation value is computed as the discounted
+expected value under the risk-neutral probabilities:
+
+.. math::
+
+    V_{i,j} = e^{-r dt} \left( p V_{i+1,j+1} + (1-p) V_{i+1,j} \right)
+
+For American options, the holder may exercise early, so the value is compared
+against the immediate exercise payoff and the larger of the two is chosen:
+
+.. math::
+
+    V_{i,j} = \max\left(V_{i,j}^{continuation}, V_{i,j}^{exercise}\right)
+
+This is exactly the logic implemented in the C++ core of the package.
+
+Assumptions of the CRR model
+----------------------------
+
+The CRR model is based on a set of simplifying assumptions:
+
+- the underlying follows a discrete binomial process over time
+- time is divided into a finite number of steps
+- volatility is constant over the option life
+- the risk-free rate is constant
+- the dividend yield or carry rate is constant
+- there are no arbitrage opportunities in the risk-neutral pricing setup
+- the tree is recombining, so the number of states remains manageable
+
+These assumptions are standard in introductory option-pricing models and are
+well suited for educational and benchmark applications.
+
+European vs American options
+----------------------------
+
+The package distinguishes between:
+
+- European options: exercise only at maturity
+- American options: exercise at any earlier node
+
+In the pricing function, this is controlled by the ``american`` flag:
+
+.. code-block:: python
+
+    price = qp.crr_price(
+        S0=100.0,
+        K=100.0,
+        r=0.05,
+        sigma=0.20,
+        T=1.0,
+        N=200,
+        q=0.01,
+        is_call=True,
+        american=False,
+    )
+
+For a European option, the code follows the standard backward-induction valuation
+without early exercise checks. For an American option, it compares continuation
+value against exercise value at each time step.
+
+Black-Scholes benchmark
+-----------------------
+
+The package also exposes ``black_scholes_price``, which gives the closed-form
+solution to the same problem under the continuous-time geometric Brownian motion
+model. This is valuable for two reasons:
+
+- it provides a familiar benchmark
+- it shows how the binomial model approaches continuous-time pricing as ``N`` grows
+
+The CRR tree becomes more accurate as the number of steps increases because the
+lattice approximates the continuous diffusion more finely.
+
+.. plot::
+   :caption: European call prices from the CRR tree approach the Black-Scholes benchmark as the number of steps increases.
+
+   import matplotlib.pyplot as plt
+   import quantplus as qp
+
+   spot = 100.0
+   strike = 100.0
+   rate = 0.05
+   volatility = 0.20
+   expiry = 1.0
+   dividend_yield = 0.01
+   step_counts = [5, 10, 20, 40, 80, 160, 320]
+   crr_prices = [
+       qp.crr_price(spot, strike, rate, volatility, expiry, count,
+                    q=dividend_yield, is_call=True)
+       for count in step_counts
+   ]
+   benchmark = qp.black_scholes_price(
+       spot, strike, rate, volatility, expiry, q=dividend_yield, is_call=True
+   )
+
+   fig, ax = plt.subplots(figsize=(8, 4.5))
+   ax.plot(step_counts, crr_prices, marker="o", color="#147d78", label="CRR")
+   ax.axhline(benchmark, color="#c05a36", linestyle="--", label="Black-Scholes")
+   ax.set_xscale("log", base=2)
+   ax.set_xticks(step_counts, [str(count) for count in step_counts])
+   ax.set_xlabel("Number of CRR steps")
+   ax.set_ylabel("European call price")
+   ax.set_title("CRR convergence to Black-Scholes")
+   ax.grid(alpha=0.25)
+   ax.legend(frameon=False)
+   fig.tight_layout()
+
+How the code implements this
+----------------------------
+
+In the C++ core, the process is implemented as a nested loop over time steps and
+stock states. The numerical sequence is:
+
+1. compute the terminal payoffs
+2. iterate backwards through time
+3. compute continuation values using risk-neutral probabilities
+4. compare with early exercise when required
+5. return the root node value
+
+In the Python layer, the function only validates user input and then calls the
+compiled native implementation. This keeps the public interface simple while
+preserving efficient numerical execution.
+
+This means the model logic is not hidden in Python loops; the expensive
+calculation runs inside the compiled C++ implementation, while user code remains
+clean and readable.
+
+Practical interpretation
+------------------------
+
+The CRR model is especially useful for:
+
+- teaching option-pricing mechanics
+- benchmarking numerical methods
+- approximating option values when closed-form formulas are not available
+- exploring early-exercise behavior for American options
+
+It is not a complete market model for all exotic derivatives, but it is a clean,
+transparent framework for vanilla options and for understanding how discrete-time
+pricing works in practice.