finhjb 0.1.6

This is a Python library for solving Hamilton-Jacobi-Bellman (HJB) equations using JAX. It provides a framework for numerical solutions to dynamic optimization problems in finance and economics.

FinHJB

简体中文 README | Documentation | 中文文档

FinHJB is a Python library for solving one-dimensional Hamilton-Jacobi-Bellman (HJB) equations with JAX.

This repository also ships a Codex skill, finhjb-model-coder, for turning continuous-time finance models, LaTeX notes, and paper excerpts into executable one-dimensional FinHJB code.

Install

uv add finhjb

pip install finhjb

Installation defaults to CPU. If you want GPU support, install the appropriate JAX backend separately.

Choose Your Path

1. Use FinHJB as a Python library

Use this path if you already know the model you want to implement and want to work directly with the package API.

Start here:

• Installation and Environment
• Library Quickstart
• Modeling Guide
• Solver Guide
• API Reference

2. Learn FinHJB through the BCW examples

Use this path if you want to understand the package by reproducing and adapting the repository's four BCW examples.

This BCW path is now formula-first rather than result-first:

• Getting Started tells you how to run the repository examples and what headline magnitudes to expect.
• BCW2011 Case Study gives the common homogeneity reduction and notation map.
• the four walkthroughs are the main derivation-to-code bridge from BCW equations into Parameter / Boundary / PolicyDict / Policy / Model.
• the supported execution contract is repository-root execution, for example uv run python src/example/BCW2011Liquidation.py.

Start here:

• Getting Started
• BCW2011 Case Study
• BCW2011 Liquidation Walkthrough
• BCW2011 Refinancing Walkthrough
• BCW2011 Hedging Walkthrough
• BCW2011 Credit Line Walkthrough
• Adapting BCW to Your Model

3. Use finhjb-model-coder

Use this path if you want Codex to read equations, paper notes, or LaTeX and turn them into FinHJB code.

Before asking for runnable code, confirm that the target Python environment can actually run finhjb.

Start here:

• FinHJB Model Coder
• Model Coder Overview
• Inputs and Readiness
• Output and Validation

The finhjb-model-coder workflow expects Codex to:

• decide whether the model fits the current one-dimensional FinHJB interface
• confirm that the target Python environment can actually run finhjb
• confirm the derivative scheme and boundary-search method before code generation
• stop and confirm baseline calibration values when symbols are defined but usable numbers are not
• split the deliverable into solve, data, and plotting files when the task combines sensitivity analysis with plotting
• stop and confirm the missing derivation steps when the mathematics does not yet map directly into FinHJB code
• generate code, run a post-generation test loop, and repair failures before delivery

Repository Notes

• The published finhjb package is the right choice for downstream projects.
• The BCW example scripts in src/example/ are repository files. They are not included in the published wheel.
• The repository BCW path now includes Case I liquidation, Case II refinancing, Case IV hedging, and Case V credit line examples.
• The BCW scripts are maintained for repository-root execution with imports from src.example....
• The finhjb-model-coder skill also lives in the repository, not in the published wheel.

Install the skill from a repository checkout with:

python scripts/install_skill.py

Useful variants:

python scripts/install_skill.py --dry-run
python scripts/install_skill.py --dest ~/.codex/skills --force
python scripts/install_skill.py --mode link --force

Documentation Map

• Docs Portal
• Installation and Environment
• Getting Started
• FinHJB Model Coder
• BCW2011 Case Study
• Adapting BCW to Your Model