Pulsar

Discover Hidden Structure in Your Data

Pulsar is a topological data analysis tool that finds the real shape of high-dimensional data. Instead of forcing your data into spheres (like K-means), Pulsar reveals manifolds, clusters, and intricate structure using Ball Mapper — a proven algorithm for topological discovery.

With an AI assistant (Claude, Gemini, Cursor), you don’t even need code.

Get Started

Try in 5 Minutes

See Pulsar in action with real data: penguins, MMLU, clinical trajectories, and more.

Demos
Use with Claude AI

No code required. Let Claude handle the analysis with Pulsar MCP tools.

MCP Server
Python API

Write your own analysis with Pulsar’s clean Python interface.

Quickstart

Why Pulsar?

You discover structure that traditional clustering misses.

K-means forces your data into spheres. DBSCAN gets confused by varying density. Pulsar finds the true topology — manifolds, voids, intricate networks.

Here’s what you’ll discover:

  • Penguins: Topology recovers species perfectly without looking at species labels. And reveals that island and sex are structurally as important as species.

  • MMLU: The standard LLM benchmark hides 12 distinct clusters within 57 subjects. Reveals leaderboard blind spots.

  • Clinical Data: Patients with identical vital signs can have opposite trajectories. Topology-aware clustering catches this.

  • Infrastructure: Coal plants cluster by operational region and capacity, revealing hidden grid structure.

See all demos: Demos

What is Pulsar?

Pulsar is a Rust-accelerated Python library for topological data analysis:

  • Input: CSV, Parquet, or Pandas DataFrame

  • Process: Grid sweeps over PCA dimensions and epsilon values (Ball Mapper)

  • Output: Weighted network graph (networkx.Graph) showing cluster structure

The workflow:

        graph LR
   A["Data<br/>(CSV)"] --> B["Preprocess"]
   B --> C["PCA Grid"]
   C --> D["Ball Mapper"]
   D --> E["Cosmic Graph"]
   E --> F["Clusters &<br/>Insights"]

   style A fill:#f0f0f0,stroke:#999
   style B fill:#D9EDF7,stroke:#31708F,stroke-width:2px
   style C fill:#D9EDF7,stroke:#31708F,stroke-width:2px
   style D fill:#D9EDF7,stroke:#31708F,stroke-width:2px
   style E fill:#DFF0D8,stroke:#3C763D,stroke-width:2px
   style F fill:#DFF0D8,stroke:#3C763D,stroke-width:2px

Driven by AI (recommended for exploration)

Use Pulsar with Claude AI or Gemini. Point it at your CSV and ask for insights. No code.

See: MCP Server

Programmatic (for reproducibility and automation)

Configure YAML or Python, fit the model, extract the cosmic graph.

from pulsar import ThemaRS

model = ThemaRS("params.yaml")
model.fit()
cosmic = model.cosmic_graph  # networkx.Graph

Key Capabilities

Topological Discovery

Ball Mapper + grid sweeps reveal manifold structure, not just spherical clusters.

Rust Performance

Core algorithms in Rust via PyO3. 10-100x speedups over pure Python implementations.

Grid-Based Exploration

Sweep over PCA dimensions, epsilon values, and random seeds to find robust structure.

Temporal Data

TemporalCosmicGraph for 3D tensors (patient × feature × time). Discover trajectory patterns.

AI-Assisted Analysis

Use with Claude Desktop or Gemini. The AI orchestrates parameter tuning and generates statistical dossiers.

YAML Configuration

Declarative, reproducible pipelines. Easy to version control and share.

Python API

Clean interface: ThemaRS.fit() → networkx.Graph. Integrate into any pipeline.

Installation

pip install pulsar

For development (requires Rust toolchain):

git clone https://github.com/Krv-Labs/pulsar.git
cd pulsar
uv sync
uv run maturin develop --release

Supports Python 3.10, 3.11, 3.12.

Next Steps

  1. See it in action: Demos — five real projects you can run in minutes

  2. Understand why: Why Pulsar? — when to use topological analysis and when to use something else

  3. Use with AI: MCP Server — let Claude or Gemini handle the analysis

  4. Go deeper: User Guide — installation, configuration, and tuning

  5. API docs: API Reference — full class and function reference

References