XY: A High-Performance, Composable, GPU-Accelerated Plotting Library

XY is a cutting-edge Python library designed for creating interactive, customizable, and incredibly fast charts. Whether you are working in a Jupyter notebook, building a web application, or generating static files, XY provides a unified solution for data visualization.

[!IMPORTANT] Current Status: XY is currently in alpha. Expect frequent updates and enhancements as the library evolves.

🚀 Core Philosophy & Capabilities

XY bridges the gap between simple everyday plotting and the visualization of massive datasets. It allows users to define charts either through a declarative syntax or by following familiar matplotlib conventions.

The Secret Sauce: Rust & GPU Acceleration

To handle immense scale, XY utilizes a Rust-based core. Instead of attempting to render every single data point—which would crash most browsers—the engine calculates only what is necessary for the current screen resolution.

• Dynamic Level of Detail: When viewing large datasets, XY renders a density surface.
• Interactive Drilling: As you pan, zoom, or hover, the engine re-calculates the specific range, allowing you to drill down into the original raw rows.
• Extreme Scale: The library has successfully rendered the entirety of OpenStreetMap, a dataset containing $\approx 10^{10}$ (10 billion) points.

---

🛠️ Getting Started

Installation

You can install XY via pip or the uv package manager:

# Using pip
pip install xy

# Using uv
uv add xy

Quick Start Checklist

• Install the library
• Define your data arrays
• Create a Chart container
• Add marks (like lines or points)
• Render or export the result

Basic Usage Example

A chart in XY consists of a container and the marks placed within it.

import xy

# Create a simple line chart
chart = xy.Chart(
    xy.line([1, 2, 3, 4, 5], [120, 180, 165, 240, 310])
)

# Export options
# chart.to_html("chart.html")
# chart.to_png("chart.png")
# chart.to_svg("chart.svg")

# In a notebook, simply call the object to render
chart

Scaling to 100 Million Points

For massive data, XY uses a density surface to maintain performance.

import numpy as np
import xy

# Generating a massive dataset
rng = np.random.default_rng()
x = rng.standard_normal(100_000_000)
y = rng.standard_normal(100_000_000)

chart = xy.Chart(
    xy.points(
        x, y, 
        color = np.exp(-np.abs(x)/2.2), 
        colormap = "magma_r", 
        density = True, 
        opacity = 0.85,
        size = 2.5, 
        zoom_size_factor = 2.6, 
        zoom_opacity = 0.95,
    ),
    xy.theme(
        background = "#ffffff", 
        plot_background = "#ffffff", 
        grid_color = "#e6e6e1", 
        axis_color = "#c3c2b7", 
        text_color = "#0b0b0b",
    ),
    title = "100 million points",
)
chart

---

🔄 Matplotlib Compatibility

If you are already comfortable with pyplot workflows, transitioning to XY is simple. In many cases, you can just swap the import statement:

import numpy as np
import xy # Instead of import matplotlib.pyplot as plt

x = np.linspace(0, 10, 100)
y = np.sin(x)
xy.plot(x, y)
xy.show()

Note: Please refer to the compatibility guide, as not all matplotlib features are currently implemented.

---

🎨 Deep Customization

XY gives you granular control over every visual layer using Python.

Example of advanced styling:

xy.Chart(
    xy.line(x, y, color = "#7c3aed", width = 3),
    class_name = "rounded-xl bg-white",
    class_names = {
        "tooltip": "rounded-lg bg-zinc-900 text-white"
    },
)

---

📊 Performance Benchmarks

The following tests measure the time from the start of the render until the canvas is stable (10 identical frames) and correct (sentinel points verified).

Rendering Speed (Seconds)

XY maintains a nearly flat performance curve across four orders of magnitude because it switches to density surfaces above 200k rows.

Memory Efficiency

XY also significantly reduces the Python-side resident memory footprint (excluding the $\approx 1\text{ GiB}$ base overhead of headless Chrome).

Memory Advantage (XY vs Others):

• 10k points: $1.8\times$ better
• 1M points: $2.1\times$ better
• 25M points: $2.9\times$ better