quaco.js/README.md

A lightweight modular Quantum Computing Simulator in JavaScript. Supports qubits, quantum gates, entanglement, circuits, algorithms, and visualization.

# QuaCo.js

QuaCo.js is a modern, modular, and lightweight Quantum Computing Simulator built entirely in JavaScript.

It allows developers, students, and researchers to easily simulate qubits, quantum gates, entanglement, quantum circuits, and famous quantum algorithms like Deutsch-Jozsa and Grover's Search — right from the browser or Node.js environment.

Whether you're learning quantum mechanics, teaching quantum principles, or prototyping quantum programs, QuaCo.js provides a clean, simple, and extensible playground to explore the fascinating world of quantum computing — without needing expensive quantum hardware.

---


## Features
- **Qubits** simulation with complex amplitudes
- **Quantum Gates**: X, Y, Z, H, CNOT, and more
- **Quantum Registers** for multi-qubit systems
- **Quantum Circuits**: Build and run full programs
- **Quantum Algorithms**:
  - Deutsch-Jozsa Algorithm
  - Grover’s Search Algorithm
- **Measurement simulation** (probabilistic collapse)
- **Histogram Visualizer** for output
- **Node.js** + **Browser** compatible
- **Pure ES6 modules**, no heavy dependencies

---


## Installation

```bash
npm install quaco.js
```

*(or clone the repository for local development.)*

---


## Usage

### 1. Superposition Example

```javascript
import { Simulator } from 'quaco.js';
import { QuantumGate } from 'quaco.js';
import { Visualizer } from 'quaco.js';

const sim = new Simulator(1);
sim.addGate(QuantumGate.hadamard(), 0);

const results = sim.run(1000);
Visualizer.showHistogram(results);
```

---


### 2. Entanglement (Bell State) Example

```javascript
import { Simulator } from 'quaco.js';
import { QuantumGate } from 'quaco.js';
import { Visualizer } from 'quaco.js';

const sim = new Simulator(2);
sim.addGate(QuantumGate.hadamard(), 0);
sim.addCNOT(0, 1);

const results = sim.run(1000);
Visualizer.showHistogram(results);
```

---


### 3. Deutsch-Jozsa Algorithm Example

```javascript
import { DeutschJozsa } from 'quaco.js';

const result = DeutschJozsa.run(3, 'balanced');
console.log("Result:", result); // 'balanced' or 'constant'
```

---


### 4. Grover's Search Algorithm Example

```javascript
import { Grover } from 'quaco.js';

const found = Grover.run(3, 5);
console.log("Found marked item:", found);
```

---


## Run Examples

```bash
npm run example:superposition
npm run example:entanglement
npm run example:deutschjozsa
npm run example:grover
```

---


## Documentation

- **src/Qubit.js** — Single qubit state and operations
- **src/QuantumRegister.js** — Multi-qubit register
- **src/QuantumGate.js** — Common quantum gates
- **src/Circuit.js** — Circuit builder
- **src/Simulator.js** — High-level controller
- **src/Algorithms/DeutschJozsa.js** — Algorithm 1
- **src/Algorithms/Grover.js** — Algorithm 2
- **src/Visualizer/Visualizer.js** — Console-based histogram

Full detailed documentation coming soon!

---


## Why QuaCo.js?

- Learn and teach **quantum computing concepts** easily
- No expensive hardware required
- Run in **Node.js**, **browsers**, or embedded systems
- Clean, modular architecture (extend easily)
- Great for educational platforms, experiments, and research

---


## License

MIT License  
*(Free for personal, educational, commercial use.)*

---


## Contribution

Want to contribute?  
Feel free to submit:
- New algorithms (QFT, Shor’s, Teleportation, etc.)
- Visualization upgrades
- Web GUI integration

**Pull Requests are welcome!**

---


## Connect

Built with passion for quantum computing and open education.

[GitHub Repository](https://github.com/VSPaone/quaco.js)

---