Rateslib is a state-of-the-art fixed income library designed for Python. Its purpose is to provide advanced, flexible and efficient fixed income analysis with a high level, well documented API.

The techniques and object interaction within rateslib were inspired by the requirements of multi-disciplined fixed income teams working, both cooperatively and independently, within global investment banks.

This library is released under a Creative Commons Attribution, Non-Commercial, No-Derivatives 4.0 International Licence.

Read the documentation at rateslib.com/py

For detailed documentation, see:

• API Documentation: rateslib.com/py
• Architecture Overview: docs/VISUAL_ARCHITECTURE.md - System diagrams and component interactions
• Mathematical Reference: docs/MATHEMATICAL_FOUNDATIONS.md - Formulas and theory
• Class Reference: docs/COMPLETE_CLASS_REFERENCE.md - Complete API reference
• Example Scripts: docs/SCRIPT_DOCUMENTATION.md - Guide to all example scripts
• Running Examples: docs/RUNNING_EXAMPLES.md - How to run example scripts

This section provides instructions for setting up a local development environment from source.

• Python 3.10 or higher (Python 3.12 recommended)
• Rust toolchain (for building the performance-critical Rust extensions)
• Conda or another Python environment manager

1. Clone the repository

   git clone https://github.com/attack68/rateslib.git
   cd rateslib

2. Create and activate a conda environment

   conda create -n rateslib-dev python=3.12 -y
   conda activate rateslib-dev

3. Install Rust (if not already installed)

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
   source "$HOME/.cargo/env"

4. Install Python dependencies and build tools

   pip install maturin numpy matplotlib pandas
   pip install pytest coverage ruff mypy pandas-stubs  # For development

5. Build the Rust extensions

   maturin develop --release

6. Verify the installation

   cd python
   python -c "import rateslib; print(rateslib.__version__)"

Before running tests, ensure you have:

1. Completed the development setup above
2. Built the Rust extensions with maturin develop --release
3. Activated your conda environment: conda activate rateslib-dev

IMPORTANT: All test commands must be run from the python/ directory using python -m pytest:

# Navigate to the python directory (REQUIRED)
cd python

# Run all tests
python -m pytest tests/

# Run with different output levels
python -m pytest tests/ -q        # Quiet mode (dots only)
python -m pytest tests/ -v        # Verbose (show test names)
python -m pytest tests/ --tb=no   # No traceback on failures

# Run specific tests
python -m pytest tests/test_curves.py                           # Single file
python -m pytest tests/test_curves.py::TestCurve               # Single class
python -m pytest tests/test_curves.py::TestCurve::test_method  # Single method
python -m pytest tests/ -k "test_fx"                           # Pattern matching
python -m pytest tests/scheduling/                             # Specific directory

# Count tests without running
python -m pytest tests/ --collect-only -q | tail -1

Generate code coverage reports to see how well the tests cover the codebase:

# Run tests with coverage measurement
cd python
python -m coverage run -m pytest tests/ -q

# View coverage report in terminal
python -m coverage report

# Generate detailed HTML report
python -m coverage html
# Open htmlcov/index.html in your browser

# Show only files with missing coverage
python -m coverage report --skip-covered --skip-empty

Test Suite:

• Total tests: 3,758
• Passing: 3,684 ✅
• Skipped: 74
• Execution time: ~27 seconds (43s with coverage)

Code Coverage: 97%

• Total lines: 20,990
• Covered: 20,340
• Missing: 650

Coverage by Module:

The project uses ruff for linting and code formatting:

# Check code style issues
cd python
ruff check rateslib/

# Auto-fix issues where possible
ruff check rateslib/ --fix

# Format code
ruff format rateslib/

Use mypy for static type checking:

cd python
mypy rateslib/ --exclude tests

When developing locally without installing the package:

1. Always work from the python/ directory to ensure imports work correctly
2. After Rust changes, rebuild with maturin develop --release from project root
3. Run tests from the python/ directory using python -m pytest
4. Check code quality with ruff and mypy before committing
5. Verify coverage remains high (>95%) for new code

rateslib/
├── python/           # Python source code
│   ├── rateslib/    # Main Python package
│   └── tests/       # Test suite
├── rust/            # Rust source code for performance-critical components
├── notebooks/       # Jupyter notebooks with examples
├── scripts/         # Utility scripts and converted examples
├── docs/            # Architecture and design documentation
├── Cargo.toml       # Rust dependencies and configuration
├── pyproject.toml   # Python project configuration
└── CLAUDE.md        # Developer guidance for AI assistants

Rateslib uses a sophisticated hybrid Python/Rust architecture with several key design patterns:

1. Curves - Interest rate curve construction with multiple interpolation methods

   • Base curves with caching and state management
   • Composite curves for multi-curve environments
   • Automatic differentiation support via dual numbers

2. Instruments - Financial instrument modeling

   • Hierarchical structure: Instruments → Legs → Periods → Cashflows
   • Support for bonds, swaps, FRAs, cross-currency swaps, and more
   • Built-in NPV, rate, and sensitivity calculations

3. FX System - Foreign exchange handling

   • Spot and forward FX rates
   • Interest rate parity calculations
   • Multi-currency instrument support

4. Dual Numbers - Automatic differentiation

   • First and second-order derivatives
   • Seamless integration throughout the codebase
   • Enables efficient risk calculations

5. Solver - Curve calibration

   • Newton-Raphson optimization
   • Multi-curve simultaneous calibration
   • Full sensitivity support

• Mixin Architecture: Composable functionality via _WithCache, _WithState, _WithOperations
• Wrapper Pattern: Curve transformations (shift, roll, translate) via lightweight wrappers
• Automatic Differentiation: Pervasive use of dual numbers for sensitivity calculations
• Rust Acceleration: Performance-critical paths implemented in Rust via PyO3

For detailed architecture diagrams and component analysis, see docs/ARCHITECTURE.md.