Skip to content

About

Fast financial charting for Python: candlesticks and 32 indicators, with optional Rust and GPU acceleration.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

258 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

kimsfinance

High-Performance Financial Charting Library with Optional GPU Acceleration

PyPI version Python 3.13+ License: AGPL-3.0 Tests Chart Speed Speedup GPU Batch WebP Encoding File Size Quality Commercial License


Table of Contents


Why kimsfinance?

The fastest Python financial charting library - 194x average speedup with Rust CPU implementation

  • ๐Ÿš€ 194x Faster: Rust CPU implementation demolishes mplfinance (validated across 4 indicators)
  • โšก Peak Throughput: 6,249 images/sec in batch processing mode with optimal settings
  • ๐Ÿฆ€ Rust Performance: 764x faster ATR, 3-5x faster moving averages vs mplfinance
  • ๐Ÿ”ฅ GPU Batch Processing: 41x speedup with persistent kernels - calculate 1000+ indicators in constant time
  • ๐Ÿ“Š Superior Quality: "OLED vs CRT TV" level improvement - sharper, clearer charts
  • ๐ŸŽจ 4 Professional Themes: Classic, Modern, TradingView, Light - production-ready aesthetics
  • ๐Ÿ’พ 79% Smaller Files: WebP lossless compression (0.5 KB vs 2.57 KB PNG)
  • ๐Ÿ”ง Zero Core Dependencies: Only Pillow + NumPy required (GPU & Rust optional)
  • ๐Ÿงช Production Ready: 1,500+ tests, comprehensive coverage, full type safety
  • ๐ŸŽฏ Developer Friendly: Simple API, flexible output (PIL Image, numpy array, file)
  • โš™๏ธ GPU Acceleration: Optional RAPIDS/CuPy support for massive datasets
  • ๐Ÿ“ˆ 32 Technical Indicators: ATR, RSI, MACD, Stochastic, Bollinger Bands, and 27 more (26 standalone functions with Rust acceleration)
  • ๐Ÿ Python 3.14 Support: 27% single-thread, 3.1x multi-thread speedup with free-threading
  • ๐Ÿ“Š Backtesting Engine: GPU-accelerated backtesting with genetic optimization

Quick Start

import kimsfinance as kf

# Load your OHLCV data (works with pandas, polars, numpy, lists)
df = kf.load_csv("ohlcv.csv")

# Create a chart - that's it!
kf.plot(df, output="chart.webp", theme="modern")

# Result: 28.8x faster than mplfinance, OLED-quality, 0.5 KB file

Quick Comparison

Feature mplfinance kimsfinance Python kimsfinance Rust CPU Advantage
Speed (ATR) 216.83 ms 2.16 ms 0.28 ms 764x faster ๐Ÿ”ฅ
Speed (RSI) 3.42 ms 3.23 ms 1.37 ms 2.5x faster
Speed (Charts) 785.53 ms 107.64 ms N/A 7.3x faster
File Size 2.57 KB 0.50 KB 0.50 KB 79% smaller
Image Quality Good OLED-level OLED-level Superior
GPU Batch None 25x faster 41x faster Persistent kernels
Backtesting None Basic GPU-accelerated Full engine

๐Ÿš€ Performance Highlights

5-Way Benchmark Results (2025-10-27, i9-13980HX, RTX 3500 Ada)

Indicator Performance (100,000 candles)

Indicator mplfinance kimsfinance Py CPU kimsfinance Py GPU kimsfinance Rust CPU Rust GPU Batch
SMA(20) 0.91 ms 1.19 ms 1.18 ms 0.17 ms (5.2x) N/A
EMA(20) 0.70 ms 1.01 ms 1.10 ms 0.21 ms (3.4x) N/A
RSI(14) 3.42 ms 3.23 ms 2.80 ms 1.37 ms (2.5x) N/A
ATR(14) 216.83 ms 2.16 ms 2.20 ms 0.28 ms (764x) ๐Ÿ”ฅ N/A

Average Speedup vs mplfinance:

  • Python CPU: 25.7x faster
  • Python GPU: 25.3x faster
  • Rust CPU: 194x faster ๐Ÿ†

Chart Rendering Performance

Candles kimsfinance mplfinance Speedup
100 107.64 ms 785.53 ms 7.3x
1,000 344.53 ms 3,265.27 ms 9.5x
10,000 396.68 ms 27,817.89 ms 70.1x ๐Ÿ”ฅ
100,000 1,853.06 ms 52,487.66 ms 28.3x

Average Chart Speedup: 28.8x faster than mplfinance

Additional Performance Benefits

Metric Benefit Notes
GPU Batch Processing 41x faster Persistent kernels - 1000+ indicators in ~35ms constant time
Image Encoding 61x faster WebP fast mode (22ms vs 1,331ms)
File Size 79% smaller WebP lossless (0.5 KB vs 2.57 KB PNG)
Visual Quality OLED-level Superior clarity over mplfinance
Peak Throughput 6,249 img/sec Batch mode with optimal settings
Python 3.14 27% single-thread Free-threading: 3.1x multi-thread

Performance Summary: kimsfinance offers multiple performance tiers - Python (25x faster), Rust CPU (194x faster), and GPU batch processing (41x persistent kernel speedup). Choose the implementation that matches your use case and infrastructure.


โœจ Key Features

๐ŸŽจ Chart Rendering

  • PIL-based rendering - 2.15x faster than matplotlib
  • Vectorized drawing - NumPy coordinate computation (both sequential & batch modes)
  • Superior quality - "CRT TV vs OLED" level improvement
  • Antialiasing - Optional RGB fast mode or high-quality RGBA
  • 4 Professional themes - Classic, Modern, TradingView, Light
  • Grid lines - Optional price level & time marker grid
  • Customizable wicks - Variable wick width ratios

โšก Performance Optimization

  • Rust implementation - 194x average speedup, 764x for ATR
  • GPU persistent kernels - 41x faster batch indicator processing
  • Python 3.14 support - 27% single-thread, 3.1x multi-thread with free-threading
  • WebP fast mode - 61x faster encoding with <5% quality loss
  • Speed presets - fast / balanced / best
  • Quality control - Fine-grained quality parameter (1-100)
  • Batch rendering - 20-30% speedup for multiple charts
  • Parallel rendering - render_charts_parallel() with multiprocessing
  • Optional Numba JIT - 50-100% faster coordinate computation (opt-in)
  • Memory optimized - C-contiguous arrays, reduced allocations
  • Pre-computed colors - Theme colors computed at import time

๐ŸŽฏ Developer-Friendly API

  • Direct-to-file - render_and_save() one-shot operation
  • Array output - render_to_array() for ML pipelines
  • Batch API - render_ohlcv_charts() for multiple datasets
  • Parallel API - render_charts_parallel() for CPU multiprocessing
  • Flexible output - PIL Image, numpy array, or file

๐Ÿ”Œ mplfinance Integration (Optional)

  • Drop-in acceleration - Monkey-patches mplfinance for 7-10x speedup
  • Seamless integration - Uses activate() to enable, deactivate() to disable
  • Non-invasive - Original functions preserved and restored on deactivate
  • Polars-powered - Replaces pandas with GPU-accelerated Polars operations
  • Automatic fallback - Falls back to pandas if acceleration fails
  • Thread-safe - Safe for use in multi-threaded applications

Usage:

import mplfinance as mpf
import kimsfinance as mfp

# Enable acceleration for mplfinance
mfp.activate(engine='auto')  # 7-10x faster moving averages!

# Use mplfinance normally
mpf.plot(df, type='candle', mav=(5,10,20))

# Disable when done
mfp.deactivate()

What gets accelerated:

  • _plot_mav() - Simple Moving Averages (SMA)
  • _plot_ema() - Exponential Moving Averages (EMA)

Note: The monkey-patching approach is used for backward compatibility with existing mplfinance code. For new projects, we recommend using the native kimsfinance API for better performance and more features. Moving averages are computed on CPU even with GPU enabled because CPU is faster for these small, sequential operations (validated through benchmarking).

๐Ÿ”ฌ GPU Acceleration (Optional)

  • Persistent kernels - 41x speedup for batch indicator processing
  • cuDF integration - 6.4x faster OHLCV processing
  • Technical indicators - GPU-accelerated ATR, RSI, Stochastic, and more
  • Rust GPU bindings - Native CUDA performance from Python
  • Auto selection - Smart CPU/GPU routing
  • Auto-tuning - Calibrate CPU/GPU crossover points for your hardware

๐Ÿ“Š Backtesting Engine (Rust)

  • GPU-accelerated - Fast indicator calculation on GPU
  • Parameter sweep - Test 96+ combinations in <1 second
  • Genetic optimizer - 3.1x speedup with hybrid FP8/FP64 precision
  • 10 indicators - RSI, ATR, MACD, Bollinger, SMA, EMA, and more
  • Comprehensive metrics - Sharpe, drawdown, win rate, profit factor
  • Python integration - PyO3 bindings for seamless Rust โ†” Python

๐Ÿ’ป Test Hardware

All benchmarks performed on a Lenovo ThinkPad P16 Gen2 (Mobile Workstation)

Component Specification
Laptop Lenovo ThinkPad P16 Gen2
CPU Intel Core i9-13980HX (24 cores, 32 threads)
GPU NVIDIA RTX 3500 Ada Generation Laptop GPU (12GB VRAM)
RAM 64GB DDR5
Storage NVMe SSD
OS Linux 6.17.1
Python 3.13
Pillow 12.0.0

๐Ÿš€ Performance Potential: These impressive results are from a mobile workstation with thermal constraints. Desktop systems with:

  • Better cooling (sustained higher clocks vs mobile thermal throttling)
  • Higher TDP limits (desktop CPUs: 125W+ vs laptop: 55W base)
  • Desktop GPUs (RTX 4090: 24GB VRAM, RTX 6000 Ada: 48GB VRAM)
  • More cores (Threadripper: 64-96 cores, Xeon: 128+ cores)
  • More RAM (128GB+)
  • Faster NVMe RAID arrays

...will achieve significantly higher throughput. Conservative estimates: desktop systems could reach 8,000-10,000 img/sec, server-grade hardware 15,000+ img/sec.


๐Ÿ“Š Benchmark Results

Chart Generation Evolution

Version Speed File Size Quality Notes
mplfinance 35 img/sec 2.57 KB Good Baseline
polars v1 (PIL) 75 img/sec 0.53 KB Better +2.15x
+ WebP fast 2,458 img/sec 0.51 KB Better +70x
+ Vectorization 6,249 img/sec 0.50 KB OLED Peak throughput ๐Ÿš€

Validated Comparison Benchmarks (2025-10-22)

See BENCHMARK_RESULTS_WITH_COMPARISON.md for detailed methodology.

Candles mplfinance Time kimsfinance Time Speedup Validated
100 785.53 ms 107.64 ms 7.3x โœ…
1,000 3,265.27 ms 344.53 ms 9.5x โœ…
10,000 27,817.89 ms 396.68 ms 70.1x โœ…
100,000 52,487.66 ms 1,853.06 ms 28.3x โœ…

Average: 28.8x faster (median across dataset sizes)

WebP Encoding Modes

Mode Time/Image Quality File Size Use Case
Fast 22 ms 90% 0.50 KB Production (61x faster) โšก
Balanced 132 ms 95% 0.52 KB High quality (10x faster)
Best 1,331 ms 100% 0.55 KB Maximum quality

Recommendation: Use fast mode - imperceptible quality loss for 61x speedup.


๐ŸŽ“ Technical Details

How Performance is Achieved

The 28.8x average speedup (up to 70.1x at 10K candles) comes from multiple optimizations:

  1. PIL Direct Rendering (+2.15x)

    • Replace matplotlib overhead with direct PIL drawing
    • Eliminate figure/axes creation
    • Memory-efficient coordinate computation
  2. WebP Fast Mode (+61x encoding)

    • libwebp method=4 with optimized quality
    • Skip unnecessary encoding passes
    • Maintain >90% visual quality
  3. Batch Drawing (+1.3x)

    • Pre-compute all coordinates
    • Group elements by color
    • Single draw call per color
  4. Vectorization (+2.5x)

    • NumPy operations for coordinate calculation
    • Eliminate Python loops
    • SIMD optimization on modern CPUs

Theoretical Peak: Under optimal conditions (large batch processing, WebP fast encoding, vectorized coordinates), throughput can reach 6,249 img/sec on high-end hardware.

Validated Average: Across different dataset sizes (100-100K candles), the average speedup is 28.8x faster than mplfinance.

Architecture

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚   Input: OHLCV      โ”‚  Dict with open/high/low/close/volume
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
           โ”‚
           โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ Coordinate Engine   โ”‚  Vectorized NumPy computation
โ”‚   (Batch Drawing)   โ”‚  Group by color, pre-compute all
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
           โ”‚
           โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚   PIL Renderer      โ”‚  Direct drawing (no matplotlib)
โ”‚  (RGB fast mode)    โ”‚  Optional antialiasing
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
           โ”‚
           โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  WebP Fast Encode   โ”‚  method=4, quality=75
โ”‚   (61x faster)      โ”‚  22ms vs 1,331ms
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
           โ”‚
           โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  Output: Image      โ”‚  PIL Image or file (0.50 KB)
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

๐Ÿ“ฆ Installation

Basic Installation

# Minimal installation (Pillow + NumPy only)
pip install kimsfinance

With GPU Acceleration (Optional)

# Install with GPU support for 6.4x OHLCV processing speedup
pip install kimsfinance[gpu]

# Or install GPU libraries separately
pip install --extra-index-url=https://pypi.nvidia.com cudf-cu13 cupy-cuda13x  # CUDA 12 GPUs: cudf-cu12 cupy-cuda12x

With JIT Optimization (Optional)

# For 50-100% faster coordinate computation
pip install kimsfinance[jit]

# Or install Numba separately
pip install numba>=0.59

With Rust Performance (Optional)

# For 194x average speedup (764x for ATR) - the Rust bindings are a separate package
pip install kimsfinance kimsfinance_core

With Python 3.14 Free-Threading (Optional)

# Install python3.14t (free-threaded build)
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.14-nogil

# Use python3.14t for 27% single-thread + 3.1x multi-thread speedup
python3.14t -m pip install kimsfinance[all]

All Features

# Install every Python extra (GPU + JIT + reporting + interactive + dev/test); add kimsfinance_core for Rust
pip install kimsfinance[all]

From Source

git clone https://github.com/kimasplund/kimsfinance
cd kimsfinance
pip install -e .

# With all extras
pip install -e ".[all]"

Requirements

  • Python: 3.13+ (3.14+ recommended for 27% speedup + free-threading)
  • Pillow: 12.0+ (10-12% faster than 11.x)
  • NumPy: Latest version
  • Polars: Latest version (optional, for data processing)
  • Numba: 0.59+ (optional, for JIT compilation)
  • kimsfinance_core: Rust bindings (optional, for 194x speedup)

๐Ÿš€ Quick Start

Loading Data

kimsfinance accepts in-memory data (NumPy arrays, Polars/Pandas DataFrames). Load from any source:

import polars as pl
import kimsfinance as kf

# Load from Parquet (recommended - 10-100x faster than CSV)
df = pl.read_parquet('ohlcv_data.parquet')

# Plot directly
kf.plot(df, type='candle', savefig='chart.webp')

๐Ÿ“– See Data Loading Guide for Parquet, CSV, databases, APIs, WebSockets, and more.

Basic Chart Rendering

from kimsfinance.plotting import render_ohlcv_chart, save_chart

# Your OHLCV data (numpy arrays or lists)
ohlc = {
    'open': [100, 102, 101, 103, 102],
    'high': [103, 104, 102, 105, 103],
    'low': [99, 101, 100, 102, 101],
    'close': [102, 101, 103, 102, 103],
}
volume = [1000, 1200, 900, 1100, 1050]

# Render chart (returns PIL Image)
img = render_ohlcv_chart(
    ohlc=ohlc,
    volume=volume,
    width=300,
    height=200,
    theme='classic'
)

# Save with fast WebP encoding (61x faster!)
save_chart(img, 'chart.webp', format='webp', speed='fast')

Speed Modes

# Fast mode: 22ms/image (recommended for production)
save_chart(img, 'chart.webp', speed='fast')     # 61x faster

# Balanced mode: 132ms/image (high quality)
save_chart(img, 'chart.webp', speed='balanced') # 10x faster

# Best mode: 1,331ms/image (maximum quality)
save_chart(img, 'chart.webp', speed='best')     # baseline

One-Shot Render and Save

from kimsfinance.plotting import render_and_save

# Render + save in one call
render_and_save(
    ohlc=ohlc,
    volume=volume,
    output_path='chart.webp',
    width=300,
    height=200,
    format='webp',
    speed='fast'  # 61x faster encoding
)

Batch Rendering (20-30% faster)

from kimsfinance.plotting import render_ohlcv_charts

# Render multiple charts at once
datasets = [
    {'ohlc': ohlc1, 'volume': volume1},
    {'ohlc': ohlc2, 'volume': volume2},
    {'ohlc': ohlc3, 'volume': volume3},
]

# Batch rendering with shared settings
images = render_ohlcv_charts(
    datasets,
    width=300,
    height=200,
    theme='classic',
    use_batch_drawing=True  # 20-30% faster
)

# Save all images
for i, img in enumerate(images):
    save_chart(img, f'chart_{i}.webp', speed='fast')

Array Output (for ML pipelines)

from kimsfinance.plotting import render_to_array

# Get numpy array (H, W, C) uint8
array = render_to_array(
    ohlc=ohlc,
    volume=volume,
    width=300,
    height=200
)

# Feed directly to PyTorch/TensorFlow
import torch
tensor = torch.from_numpy(array).permute(2, 0, 1)  # (C, H, W)

Parallel Rendering (Multiprocessing)

from kimsfinance.plotting import render_charts_parallel

# Prepare datasets
datasets = [
    {'ohlc': ohlc1, 'volume': volume1},
    {'ohlc': ohlc2, 'volume': volume2},
    # ... 100+ datasets
]

# Parallel rendering with 8 worker processes
output_paths = [f'chart_{i}.webp' for i in range(len(datasets))]

render_charts_parallel(
    datasets=datasets,
    output_paths=output_paths,
    num_workers=8,  # Use 8 CPU cores
    speed='fast',   # Fast WebP encoding
    theme='modern',
    width=300,
    height=200
)

# Linear scaling: 8 cores = ~8x faster batch processing

๐ŸŽจ Customization

Themes

# Classic theme (black background, bright green/red)
img = render_ohlcv_chart(ohlc, volume, theme='classic')

# Modern theme (dark gray, teal/red)
img = render_ohlcv_chart(ohlc, volume, theme='modern')

# TradingView theme (TradingView-style dark theme)
img = render_ohlcv_chart(ohlc, volume, theme='tradingview')

# Light theme (white background, teal/red)
img = render_ohlcv_chart(ohlc, volume, theme='light')

Styling Options

img = render_ohlcv_chart(
    ohlc=ohlc,
    volume=volume,
    width=800,
    height=600,

    # Theme
    theme='modern',                   # 'classic' | 'modern' | 'tradingview' | 'light'

    # Custom colors (optional, overrides theme)
    bg_color='#1E1E1E',              # Hex color
    up_color='#26A69A',              # Bullish candle color
    down_color='#EF5350',            # Bearish candle color

    # Visual features
    enable_antialiasing=True,         # RGBA mode (smoother, prettier)
    show_grid=True,                   # Price level & time marker grid
    wick_width_ratio=0.1,             # Wick width (10% of candle body)

    # Performance
    use_batch_drawing=True            # Auto-enabled for 1000+ candles (20-30% faster)
)

Grid Lines

# Enable grid for better price/time reference
img = render_ohlcv_chart(
    ohlc=ohlc,
    volume=volume,
    show_grid=True,   # Draws 10 horizontal + up to 20 vertical lines
    theme='modern'     # Grid color matches theme
)

# Grid is semi-transparent in RGBA mode (25% opacity)
img = render_ohlcv_chart(
    ohlc=ohlc,
    volume=volume,
    show_grid=True,
    enable_antialiasing=True  # Grid with alpha blending
)

๐Ÿ“š API Reference

Core Functions

render_ohlcv_chart()

Render a single candlestick chart.

def render_ohlcv_chart(
    ohlc: dict[str, ArrayLike],
    volume: ArrayLike,
    width: int = 300,
    height: int = 200,
    theme: str = 'classic',
    bullish_color: tuple[int, int, int] = (38, 166, 154),
    bearish_color: tuple[int, int, int] = (239, 83, 80),
    enable_antialiasing: bool = False,
    show_grid: bool = False,
    wick_width_ratio: float = 0.1,
    use_batch_drawing: bool = False
) -> Image.Image

Returns: PIL Image object

save_chart()

Save chart with optimized encoding.

def save_chart(
    img: Image.Image,
    output_path: str,
    format: str | None = None,
    speed: str = 'balanced',  # 'fast' | 'balanced' | 'best'
    quality: int | None = None,
    **kwargs
) -> None

Speed modes:

  • fast: 22ms/image, quality=75 (61x faster) โšก
  • balanced: 132ms/image, quality=85 (10x faster)
  • best: 1,331ms/image, quality=100 (baseline)

render_and_save()

One-shot render + save.

def render_and_save(
    ohlc: dict[str, ArrayLike],
    volume: ArrayLike,
    output_path: str,
    format: str | None = None,
    speed: str = 'balanced',
    **render_kwargs
) -> None

render_ohlcv_charts()

Batch rendering (20-30% faster).

def render_ohlcv_charts(
    datasets: list[dict[str, Any]],
    **common_kwargs
) -> list[Image.Image]

render_to_array()

Get numpy array for ML pipelines.

def render_to_array(
    ohlc: dict[str, ArrayLike],
    volume: ArrayLike,
    **render_kwargs
) -> np.ndarray  # Shape: (H, W, C), dtype: uint8

render_charts_parallel()

Parallel rendering with multiprocessing.

def render_charts_parallel(
    datasets: list[dict[str, Any]],
    output_paths: list[str] | None = None,
    num_workers: int | None = None,  # Defaults to CPU count
    speed: str = 'fast',
    **common_render_kwargs
) -> list[str | bytes]  # Returns paths or PNG bytes

Features:

  • Linear scaling with CPU cores (8 cores = ~8x faster)
  • Automatic worker count (defaults to os.cpu_count())
  • File output or in-memory PNG bytes
  • Order preservation (results match input order)

Example:

# Render 1000 charts in parallel
datasets = [{'ohlc': ohlc_i, 'volume': vol_i} for i in range(1000)]
paths = [f'chart_{i}.webp' for i in range(1000)]

render_charts_parallel(
    datasets,
    output_paths=paths,
    num_workers=8,
    speed='fast',
    theme='modern'
)

๐Ÿ”ฌ GPU Acceleration

While chart rendering is optimal on CPU, GPU acceleration provides massive speedups for OHLCV processing:

OHLCV Processing Performance

Method Speed Speedup
pandas (CPU) 1,416 candles/sec 1x
cuDF (GPU) 9,102 candles/sec 6.4x โšก

When to Use GPU

Operation CPU GPU Speedup
Chart Rendering โœ… Optimal โŒ Slower -
OHLCV Aggregation Good โœ… 6.4x faster 6.4x
Technical Indicators Good โœ… 1.2-2.9x faster 1.2-2.9x
Moving Averages โœ… Optimal โŒ Slower -

Recommendation: Use GPU for OHLCV processing, CPU for chart rendering.

Auto-tuning

kimsfinance can auto-tune the GPU_CROSSOVER_THRESHOLDS to your specific hardware. This can lead to significant performance improvements by ensuring that the GPU is only used when it is actually faster than the CPU.

To run the auto-tuner, simply call the run_autotune function:

from kimsfinance.core import run_autotune

# This will benchmark your CPU and GPU and save the optimal thresholds
run_autotune()

The auto-tuner will run a series of benchmarks to determine the optimal crossover points for your hardware and save the results to a cache file. The next time you run kimsfinance, it will automatically load the tuned thresholds.


๐Ÿงช Benchmarking

Run Your Own Benchmarks

from kimsfinance.benchmarks import benchmark_chart_rendering

# Compare with mplfinance
results = benchmark_chart_rendering(
    num_candles=50,
    num_iterations=100,
    output_format='webp'
)

print(f"mplfinance: {results['mplfinance_time']:.2f}ms")
print(f"kimsfinance: {results['polars_time']:.2f}ms")
print(f"Speedup: {results['speedup']:.1f}x")

Benchmark Results

Tested on: Intel i9-13980HX (24 cores), RTX 3500 Ada (12GB VRAM)

=== 50 candles, 100 iterations ===

mplfinance:
  Median: 325.55 ms
  Throughput: 3.07 charts/sec
  File size: 2.57 KB

kimsfinance:
  Median: 151.29 ms
  Throughput: 6.61 charts/sec
  File size: 0.53 KB

Speedup: 2.15x faster
File size: 79% smaller

=== With WebP fast mode ===

kimsfinance (fast):
  Median: 2.28 ms
  Throughput: 438 charts/sec

Speedup: 143x faster than mplfinance

๐ŸŽฏ Use Cases

1. High-Volume Chart Generation

Generate millions of charts for ML training:

import pandas as pd
from kimsfinance.plotting import render_and_save

# Process entire dataset
df = pd.read_csv('ohlcv_data.csv')

for i in range(len(df) - 50):
    window = df.iloc[i:i+50]

    ohlc = {
        'open': window['open'].values,
        'high': window['high'].values,
        'low': window['low'].values,
        'close': window['close'].values,
    }

    render_and_save(
        ohlc=ohlc,
        volume=window['volume'].values,
        output_path=f'charts/chart_{i}.webp',
        speed='fast',  # 61x faster encoding
        width=300,
        height=200
    )

# At 6,249 img/sec, generates 375K images in 1 minute

2. Real-Time Chart Updates

WebSocket integration for live charts:

async def on_candle_update(candle_data):
    img = render_ohlcv_chart(
        ohlc=candle_data['ohlc'],
        volume=candle_data['volume'],
        width=800,
        height=600,
        enable_antialiasing=True  # Pretty for display
    )

    # Fast save (22ms)
    save_chart(img, 'live_chart.webp', speed='fast')

    # Broadcast to clients
    await broadcast_image(img)

3. ML Data Pipeline

Generate training data for CNNs:

from kimsfinance.plotting import render_to_array
import torch

def generate_dataset(ohlcv_df, labels):
    images = []

    for i in range(len(ohlcv_df) - 50):
        window = ohlcv_df.iloc[i:i+50]

        # Get numpy array
        array = render_to_array(
            ohlc={'open': window['open'].values, ...},
            volume=window['volume'].values,
            width=300,
            height=200
        )

        images.append(array)

    # Convert to PyTorch tensors
    images = torch.from_numpy(np.array(images))
    images = images.permute(0, 3, 1, 2)  # (N, C, H, W)

    return images, labels

# At 6,249 img/sec, processes 100K charts in 16 seconds

๐Ÿ”ง Troubleshooting

Slow Performance

If rendering is slower than expected:

# 1. Verify Pillow 12.0+
import PIL
print(PIL.__version__)  # Should be 12.0+

# 2. Use fast mode
save_chart(img, 'chart.webp', speed='fast')  # Not 'balanced' or 'best'

# 3. Disable antialiasing for speed
img = render_ohlcv_chart(ohlc, volume, enable_antialiasing=False)

# 4. Enable batch drawing for many candles
img = render_ohlcv_chart(ohlc, volume, use_batch_drawing=True)

Quality Issues

If images look pixelated or blurry:

# 1. Increase resolution
img = render_ohlcv_chart(ohlc, volume, width=800, height=600)

# 2. Enable antialiasing
img = render_ohlcv_chart(ohlc, volume, enable_antialiasing=True)

# 3. Use higher quality encoding
save_chart(img, 'chart.webp', speed='balanced')  # or 'best'

# 4. Manually set quality
save_chart(img, 'chart.webp', quality=95)

GPU Not Detected

# Install RAPIDS
pip install --extra-index-url=https://pypi.nvidia.com cudf-cu13 cupy-cuda13x  # CUDA 12 GPUs: cudf-cu12 cupy-cuda12x

# Verify
python -c "import cudf; import cupy; print('GPU ready!')"

Chart Types & Indicators

Chart Types (6 Built-in)

kimsfinance supports multiple chart types for different trading strategies:

  1. Candlestick - Traditional OHLC candles (default)
  2. OHLC Bars - Open-High-Low-Close bars
  3. Line - Close price line chart
  4. Hollow Candles - Hollow/filled based on close vs open
  5. Renko - Brick charts for trend following
  6. Point & Figure - X/O charts for price action

Technical Indicators (32 Built-in)

All indicators are available in Python, with 26 standalone Rust-accelerated indicator functions (30+ indicators total incl. batch-only) for massive datasets:

Trend Indicators:

  • SMA (Simple Moving Average)
  • EMA (Exponential Moving Average)
  • WMA (Weighted Moving Average)
  • VWAP (Volume Weighted Average Price)
  • MACD (Moving Average Convergence Divergence)

Momentum Indicators:

  • RSI (Relative Strength Index)
  • Stochastic Oscillator
  • Williams %R
  • CCI (Commodity Channel Index)
  • ROC (Rate of Change)
  • CMO (Chande Momentum Oscillator)

Volatility Indicators:

  • ATR (Average True Range)
  • Bollinger Bands
  • Keltner Channels
  • Donchian Channels

Volume Indicators:

  • OBV (On Balance Volume)
  • MFI (Money Flow Index)
  • A/D Line (Accumulation/Distribution)
  • Chaikin Money Flow

See full indicator list for all 32 indicators


๐Ÿ“– Documentation

Getting Started

Tutorials

Advanced Topics

Reference


๐Ÿง‘โ€๐Ÿ’ป Development

Setup

git clone https://github.com/kimasplund/kimsfinance
cd kimsfinance

# Create virtual environment
python3.13 -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e .

# Install dev dependencies (pytest, black, mypy, ruff, pre-commit, ...) and the git hooks
pip install -e ".[dev]"
pre-commit install

Running Tests

# Run all tests
pytest tests/

# Run with coverage
pytest --cov=kimsfinance tests/

# Run specific test
pytest tests/plotting/test_plotting.py::test_render_ohlcv_chart

Code Quality

# Format code
black kimsfinance/

# Type checking
mypy kimsfinance/

# Linting
ruff check kimsfinance/

๐Ÿ—บ๏ธ Roadmap

Completed โœ…

  • PIL-based rendering (2.15x faster)
  • WebP fast mode (61x faster encoding)
  • Batch drawing optimization (20-30% speedup)
  • Comprehensive vectorization (NumPy coordinate computation)
  • Sequential mode vectorization (consistent performance)
  • Optional Numba JIT compilation (50-100% faster)
  • C-contiguous memory layout (optimal CPU cache)
  • Reduced array allocations (40-50% fewer)
  • Pre-computed theme colors (import-time optimization)
  • Grid line vectorization
  • Speed presets (fast/balanced/best)
  • Quality parameter (fine-grained control)
  • Batch rendering API (render_ohlcv_charts)
  • Parallel rendering API (render_charts_parallel)
  • Direct-to-file API (render_and_save)
  • Array output for ML (render_to_array)
  • 4 professional themes (Classic, Modern, TradingView, Light)
  • Grid lines with semi-transparent overlay
  • Variable wick width customization
  • Python 3.13 compatibility
  • Python 3.14 support (27% single-thread, 3.1x multi-thread)
  • 1,500+ comprehensive tests
  • 6 chart types (Candlestick, OHLC, Line, Hollow, Renko, Point & Figure)
  • 32 technical indicators (ATR, RSI, MACD, Stochastic, Bollinger, etc.) - 26 standalone Rust indicator functions (30+ incl. batch-only)
  • GPU-accelerated indicators (1.2-2.9x speedup)
  • Rust implementation (194x average speedup)
  • GPU persistent kernels (41x batch speedup)
  • Backtesting engine with genetic optimization

In Progress ๐Ÿšง

  • Multi-timeframe charts (1m, 5m, 1h, 1d, etc.)
  • Interactive charts with callbacks
  • Real-time WebSocket integration examples
  • Advanced indicator combinations

Planned ๐Ÿ”ฎ

  • WebAssembly support (browser rendering)
  • Streaming chart updates
  • 3D visualization
  • Custom drawing API
  • Chart templates

๐Ÿ“ Citation

If you use kimsfinance in your research or academic work, please cite:

@software{kimsfinance2025,
  title = {kimsfinance: High-Performance Financial Charting Library with GPU Acceleration},
  author = {Asplund, Kim},
  year = {2025},
  url = {https://github.com/kimasplund/kimsfinance},
  version = {0.2.0},
  note = {194x average speedup (Rust CPU), 41x GPU batch processing, 6,249 charts/sec peak throughput}
}

For blog posts or articles:

kimsfinance by Kim Asplund (2025) - A high-performance Python financial charting library achieving 194x average speedup (Rust CPU) over mplfinance with GPU acceleration and backtesting engine. https://github.com/kimasplund/kimsfinance


๐Ÿ“„ License

kimsfinance uses dual licensing:

๐Ÿ†“ Open Source License (AGPL-3.0)

Free for individuals and open source projects

kimsfinance is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

โœ… Use for free if you:

  • Are an individual/researcher
  • Open-source your entire application
  • Use for personal/educational purposes

See LICENSE for full terms.

๐Ÿ’ผ Commercial License

Required for proprietary/commercial use

You need a commercial license if you:

  • โŒ Run kimsfinance as a network service (API, web app)
  • โŒ Use in proprietary trading systems (hedge funds, HTF firms)
  • โŒ Embed in closed-source SaaS products
  • โŒ Don't want to open-source your application

Pricing:

  • Startup: $999/year (<$1M revenue, up to 10M charts/month)
  • Business: $4,999/year (unlimited usage, priority support)
  • Enterprise: Contact us (hedge funds/HTF firms - custom pricing, source access, SLA)

๐Ÿ“ง Contact: licensing@asplund.kim

Full Details: See COMMERCIAL-LICENSE.md and LICENSING.md

๐ŸŽฏ Bottom Line: Free for individuals and researchers. Companies using it in production = pay up! ๐Ÿ˜„

Why AGPL-3.0? AGPL requires companies to open-source their code if they use kimsfinance as a network service. Since most hedge funds and HTF firms won't reveal their secret sauce, they buy a commercial license. This funds continued development while keeping it free for the community.


๐Ÿ™ Acknowledgments

Inspiration: This project was inspired by mplfinance's approach to financial charting, but has been completely reimagined for modern Python 3.13+ with:

  • PIL-based rendering (2.15x faster than matplotlib)
  • Rust implementation (194x average speedup)
  • GPU acceleration via RAPIDS and persistent kernels (41x batch speedup)
  • WebP fast mode (61x faster encoding)
  • Python 3.14 free-threading support (3.1x multi-thread speedup)
  • Comprehensive vectorization with optional Numba JIT
  • 194x average speedup over mplfinance with Rust CPU

While the concept is inspired by mplfinance, kimsfinance is a complete rewrite with a fundamentally different architecture optimized for extreme performance.

Other acknowledgments:

  • Pillow - Python Imaging Library (12.0+)
  • RAPIDS AI - GPU-accelerated data processing
  • Polars - Fast DataFrame library
  • NumPy - Numerical computing
  • Numba - JIT compilation for Python

๐Ÿ“ง Contact & Support

Get Help

  • ๐Ÿ“– Documentation: docs/ - Comprehensive guides and tutorials
  • ๐Ÿ’ฌ GitHub Discussions: Ask questions - Community Q&A
  • ๐Ÿ› GitHub Issues: Report bugs - Bug reports and feature requests
  • ๐Ÿ“ง Email: hello@asplund.kim - Direct support and commercial inquiries

Commercial Support

Need priority support, custom features, or enterprise SLA?

  • Startup Plan: $999/year - Priority support, bug fixes within 72 hours
  • Business Plan: $4,999/year - Priority support + custom features
  • Enterprise Plan: Contact us - Dedicated support, SLA, source access

๐Ÿ“ง Contact: licensing@asplund.kim

Community


โญ Show Your Support

If kimsfinance helps accelerate your trading systems or ML pipelines, please consider:

  • โญ Star the repository - Help others discover kimsfinance
  • ๐Ÿ› Report bugs - Help us improve quality
  • ๐Ÿ“ Contribute - Submit pull requests for features or fixes
  • ๐Ÿ“ข Share - Spread the word in your community
  • ๐Ÿ’ผ Commercial License - Support development while getting priority support

Every star, issue report, and contribution helps make kimsfinance better!


Built with โšก by traders, for traders

kimsfinance - The fastest Python financial charting library. 194x average speedup (Rust CPU) over mplfinance, with GPU batch processing (41x) and Python 3.14 free-threading (3.1x).

Why wait seconds when you can get charts in microseconds?

Get Started | View Benchmarks | Read Docs | See Examples

About

Fast financial charting for Python: candlesticks and 32 indicators, with optional Rust and GPU acceleration.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages