Quantum FPGA Compiler (QFC)

A revolutionary framework that compiles VHDL (hardware description language for FPGAs) to Quantum Assembly (QASM) and executes it on quantum simulators or real quantum hardware.

🚀 Quick Start

# 1. Install dependencies
pip install -r requirements.txt

# 2. Verify installation
python verify_install.py

# 3. Run interactive demo
python demo.py

# 4. Compile and run your first circuit
python qfc.py compile examples/and_gate.vhdl
python qfc.py run examples/and_gate.qasm

New to QFC? Start with GET_STARTED.md for a comprehensive guide!

✨ Features

• VHDL-to-QASM Compiler: Translates classical VHDL designs to quantum circuits
• RISC-V Quantum Emulator: Run RISC-V assembly on quantum circuits
• Linux Boot Support: Boot real Linux kernels (vmlinux/vmlinuz) with initrd
• QASM Input Injection: Inject input values into quantum circuits
• Multi-File Compilation: Compile multiple VHDL files into a single circuit
• QASM File Combiner: Merge multiple QASM circuits
• QASM Runner: Execute QASM files like running Node.js scripts
• Multiple Backends:
  • Qiskit Aer (local simulation)
  • IBM Quantum (real quantum hardware - all commands support IBM backend)
• Input Handling: Support for JSON, text, binary files, stdin, and scripts
• Batch Processing: Compile and run multiple files automatically
• TensorFlow Integration: Hybrid quantum-classical ML models and circuit optimization
• Cross-Platform Executables: Compile to standalone binaries for Windows and Linux
• Circuit Visualization: View quantum circuit diagrams
• Comprehensive Testing: Full test suite included

🎯 Architecture Support

• ✅ Basic logic gates (AND, OR, NOT, XOR, NAND, NOR, XNOR)
• ✅ Combinational circuits (half adder, full adder)
• 🔄 RISC-V IP cores (planned)
• 🔄 ARM IP cores (planned)
• 🔄 Custom VHDL designs (expanding)

📦 Installation

pip install -r requirements.txt
python verify_install.py

See INSTALL.md for detailed installation instructions.

Usage

Compile VHDL to QASM

python qfc.py compile input.vhdl -o output.qasm

Run QASM file

python qfc.py run circuit.qasm --backend aer
python qfc.py run circuit.qasm --backend ibm --token YOUR_IBM_TOKEN

Build Executables

# Windows (without TensorFlow - recommended)
.\build.bat

# Or with options
python build.py --platform windows --clean --exclude-tensorflow

# Linux
./build.sh

# Note: TensorFlow is excluded from executables due to size.
# For ML features, use: python qfc.py

Project Structure

windsurf-project/
├── qfc.py                 # Main CLI entry point
├── compiler/              # VHDL-to-QASM compiler
│   ├── parser.py         # VHDL parser
│   ├── ir.py             # Intermediate representation
│   ├── translator.py     # IR to QASM translator
│   └── optimizer.py      # Quantum circuit optimizer
├── runner/                # QASM execution engine
│   ├── executor.py       # Main executor
│   ├── backends.py       # Backend implementations
│   └── visualizer.py     # Circuit visualization
├── examples/              # Example VHDL files
├── tests/                 # Test suite
└── build/                 # Build scripts and outputs

📚 Examples

See the examples/ directory for sample VHDL designs including:

• ✅ Basic logic gates (AND, OR, NOT, XOR)
• ✅ Half adder and full adder
• ✅ RISC-V RV32I CPU (32-bit ALU, decoder, core)
• ✅ RISC-V RV64I CPU (64-bit ALU, decoder, core)
• 🔄 State machines (planned)
• 🔄 ARM CPU implementations (planned)

Run all examples:

python test_qfc.py

📖 Documentation

• GET_STARTED.md - Comprehensive getting started guide
• QUICKSTART.md - 5-minute quick start
• USAGE.md - Detailed command reference
• ARCHITECTURE.md - Technical architecture
• FAQ.md - Frequently asked questions
• INDEX.md - Complete documentation index

🔧 Tools Included

• qfc.py - Main CLI interface
• test_qfc.py - Comprehensive test suite
• demo.py - Interactive demonstration
• verify_install.py - Installation verification
• build.py - Executable builder
• tools/combine_qasm.py - QASM file combiner
• tools/boot_linux.py - Boot Linux on quantum computers
• emulator/riscv_emulator.py - RISC-V quantum emulator
• emulator/bootrom.py - Bootrom with kernel/initrd loading
• emulator/qasm_input.py - QASM input injection

🎓 Learning Path

1. Beginner: Read GET_STARTED.md and run python demo.py
2. Intermediate: Try examples and read USAGE.md
3. Advanced: Read ARCHITECTURE.md and explore source code

🚀 Project Status

• Version: 0.1.0
• Status: Alpha - Fully Functional
• Platform: Windows (primary), Linux (supported)

See STATUS.md for detailed status and roadmap.

📝 License

MIT License - See LICENSE file for details.

🤝 Contributing

Contributions welcome! This is an experimental project pushing the boundaries of quantum computing.

Areas for contribution:

• Extended VHDL parsing
• Additional quantum gates
• Optimization algorithms
• Documentation improvements
• Example circuits

🌟 Acknowledgments

Built with:

• Qiskit - IBM's quantum computing framework
• Click - Python CLI framework
• PyInstaller - Python to executable converter

---

Ready to start? Run python verify_install.py and then check out GET_STARTED.md!

Questions? See FAQ.md or INDEX.md for all documentation.