dandelion_chart/README.md

A library for visualizing quantum state probabilities and amplitudes in a geometrical and interactive way.

# Dandelion chart

> A library for visualizing quantum state probabilities and amplitudes in a geometrical and interactive way.



![Dandelion Chart](https://raw.githubusercontent.com/shaolunruan/QuantumEyes-copy/refs/heads/main/public/image.png)


[![npm version](https://badgen.net/npm/v/dandelion_chart)](https://www.npmjs.com/package/dandelion_chart) [![Downloads](https://badgen.net/npm/dt/dandelion_chart)](https://www.npmjs.com/package/dandelion_chart)

---

## Info

- **Purpose**: The Dandelion Chart library is designed to help users visualize quantum state amplitudes and probabilities through an intuitive and geometrical representation.
- **Built On**: The library leverages the power of D3.js for robust rendering and interactivity.
- **Use Case**: Ideal for quantum computing researchers, educators, and developers to explore and explain quantum states visually. Here is the online demo with the integration of dandelion chart: [Dandelion Chart Demo](https://quantumeyes.github.io/)

---

## Highlights

- **Intuitive Visualization**: Maps quantum state amplitudes (real and imaginary parts) to a 2D geometrical representation.
- **Interactive Scaling**: Dynamically adjust circle sizes to reduce visual clutter.
- **Multi-Qubit Support**: Effortlessly visualize quantum systems with multiple qubits.
- **Customizable**: Define your own color schemes for better clarity and personalization.
- **Lightweight**: Easy to integrate into existing projects.

---




## Install
```cmd
npm install dandelion_chart -S
```


## Import

```js
import {dandelion_chart} from 'src/function/package_folder/dandelion_chart'
```

---

[//]: # (## Tutorial)

[//]: # ()
[//]: # (#### We developed dandelion package to bridge the gap of quantum state visualization. Specifically, dandelion chart has three superior features which can be benificial for quantum computing users:)

[//]: # ()
[//]: # (1. **Visualize the probability of each basic states, and visually reflect how amplitudes affect the corresponding probability.**)

[//]: # (2. **Support the multi-qubit visualization, which is way better useful than Block Sphere.**)

[//]: # (3. **Address the scalability issue introduced by a great number of basic states.**)

[//]: # ()
[//]: # ()


## Usage

### Parameters required:
* `state_vectors` *Array* : the state vector array to be visualized
* `[bundle_g, size_arr, position_arr, point_radius=8]` *Array* : placement parameters
  * `bundle_g` *d3_selection* : the container for the dandelion chart
  * `size_arr` *Array* : the size of the dandelion chart
  * `position_arr` *Array* : positio of the dandelion chart
  * `point_radius` *Number* : the radius of the points in the chart, default is 8
* `[theta, theta_point]` *Array* : optional parameters for scaling
  * `theta` *Number* : the parameters to decrease the area of circles, reducing the visual clutter when there are numerous basic states
  * `theta_point` *Number* : the parameters to decrease the radius of points, reducing the visual clutter when there are numerous basic states



### Basic Example

```javascript
import * as d3 from 'd3';
import {dandelion_chart} from 'dandelion_chart'

// Define data for quantum states
let state_vector = [
  [0.13, 0.428],
  [0.07, -0.495],
  [0.1, 0.2],
  [0.4, 0.3]
]

// Create a D3 container
const bundle_g = d3.select('body')
        .append('svg')
        .attr('width', 500)
        .attr('height', 500)
        .append('g')
        .attr('class', 'dandelion-chart-group');


// Initialize the Dandelion Chart
dandelion_chart(state_vector, [bundle_g, [300, 300], [0, 0]], [0.8, 1]);
```