Skip to main content

​
Installation

This guide walks you through installing QC (Quasi Quantum Computing) and all required dependencies.

​
System Requirements

Python Version

Python 3.8 or higher

Hardware

CPU or NVIDIA GPU (CUDA-compatible)

Memory

Minimum 4GB RAM (8GB+ recommended)

Storage

~1GB for code and checkpoints
QC can run on CPU or GPU. GPU execution is faster but not required. The simulator automatically detects available hardware.

​
Prerequisites

Before installing QC, ensure you have the following:
  • Python 3.8+ with pip
  • Git for cloning the repository
  • (Optional) CUDA toolkit if using GPU acceleration

​
Installation Steps

1

Clone the Repository

Clone the QC source code from your repository:
git clone https://github.com/grisuno/QC
cd QC
2

Create Virtual Environment

Create and activate a Python virtual environment:
python3 -m venv env
source env/bin/activate  # On Linux/macOS
# env\Scripts\activate   # On Windows
Using a virtual environment is strongly recommended to avoid dependency conflicts.
3

Install Dependencies

Install required Python packages:
pip install torch torchvision numpy scipy matplotlib
pip install pyscf openfermion openfermionpyscf
  • PyTorch (torch): Neural network backends and tensor operations
  • NumPy (numpy): Numerical computations and array operations
  • SciPy (scipy): Optimization algorithms (L-BFGS-B for VQE)
  • Matplotlib (matplotlib): Visualization and plotting
  • PySCF (pyscf): Quantum chemistry calculations and molecular data
  • OpenFermion (openfermion): Fermionic operators and Jordan-Wigner transformation
  • OpenFermion-PySCF (openfermionpyscf): Integration between OpenFermion and PySCF
4

Download Neural Network Checkpoints

QC requires pre-trained neural network checkpoint files for the physics backends. Ensure you have:
  • hamiltonian.pth - Hamiltonian backend weights
  • checkpoint_phase3_training_epoch_18921_20260224_154739.pth - Schrödinger backend
  • best_dirac.pth - Dirac backend weights
Place these checkpoint files in the same directory as your Python scripts, or specify their paths when running simulations.
The simulator will fall back to analytical methods if checkpoint files are missing, but neural backend features will be unavailable.
5

Verify Installation

Verify your installation by running a simple test:
python3 quantum_computer.py \
  --hamiltonian-checkpoint hamiltonian.pth \
  --schrodinger-checkpoint checkpoint_phase3_training_epoch_18921_20260224_154739.pth \
  --dirac-checkpoint best_dirac.pth \
  --grid-size 16 \
  --hidden-dim 32 \
  --expansion-dim 64 \
  --device cpu
You should see output showing successful backend loading and test results:
2026-03-01 22:51:18,844 | QuantumComputer | INFO | HamiltonianBackend: loaded hamiltonian.pth
2026-03-01 22:51:18,869 | QuantumComputer | INFO | SchrodingerBackend: loaded checkpoint_phase3_training_epoch_18921_20260224_154739.pth
2026-03-01 22:51:18,891 | QuantumComputer | INFO | DiracBackend: loaded best_dirac.pth

​
Configuration Options

QC supports various configuration parameters that must match the values used during neural network training:
ParameterDefaultDescription
--grid-size16Spatial grid resolution (G×G)
--hidden-dim32Hidden layer dimension in neural networks
--expansion-dim64Expansion dimension for Schrödinger/Dirac backends
--deviceautoComputation device: cpu or cuda
--hamiltonian-checkpointweights/latest.pthPath to Hamiltonian weights
--schrodinger-checkpointweights/schrodinger_crystal_final.pthPath to Schrödinger weights
--dirac-checkpointweights/dirac_phase5_latest.pthPath to Dirac weights
Important: The grid-size, hidden-dim, and expansion-dim parameters must match the values used during checkpoint training. Using mismatched values will cause errors.

​
GPU Acceleration (Optional)

To enable GPU acceleration:
1

Install CUDA Toolkit

Install the appropriate CUDA toolkit for your GPU:
2

Install PyTorch with CUDA

Install PyTorch with CUDA support:
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
Replace cu118 with your CUDA version (e.g., cu121 for CUDA 12.1).
3

Verify CUDA Availability

Check if PyTorch detects your GPU:
import torch
print(torch.cuda.is_available())  # Should print True
print(torch.cuda.get_device_name(0))  # Shows GPU model
4

Run with GPU

Specify --device cuda when running simulations:
python3 quantum_computer.py --device cuda

​
Installation Script

For convenience, use the provided installation script:
install.sh
#!/bin/bash
python3 -m venv env
source env/bin/activate
pip install -r requirements.txt
Run it with: 
chmod +x install.sh
./install.sh

​
Troubleshooting

Solution: Make sure you activated your virtual environment and installed all dependencies:
source env/bin/activate
pip install torch numpy scipy matplotlib pyscf openfermion openfermionpyscf
Solution: Verify checkpoint file paths are correct and files exist:
ls -lh hamiltonian.pth checkpoint_phase3_training_epoch_18921_20260224_154739.pth best_dirac.pth
If missing, download or specify correct paths with --hamiltonian-checkpoint, --schrodinger-checkpoint, and --dirac-checkpoint flags.
Solution: Reduce grid size or switch to CPU:
python3 quantum_computer.py --grid-size 8 --device cpu
Solution: Ensure --grid-size, --hidden-dim, and --expansion-dim match checkpoint training configuration. Default values are:
  • Grid size: 16
  • Hidden dim: 32
  • Expansion dim: 64

​
Verifying Your Installation

Run the molecular simulator test to confirm everything works: 
python3 molecular_sim.py --molecule H2
Expected output: 
2026-03-01 22:51:27,739 | MolecularSimulator | INFO | Loaded H2 from PySCF: HF=-1.11699900, FCI=-1.13730604
...
============================================================
  VQE Result: H2  [openfermion_jw]
============================================================
  VQE energy : -1.13730604 Ha
  FCI energy : -1.13730604 Ha
  |VQE-FCI|  : 1.31e-11 Ha
  Correlation: 100.0%
============================================================
If you see “100.0%” correlation energy captured and |VQE-FCI| < 10⁻¹⁰, your installation is working correctly!

​
Next Steps

Quick Start Tutorial

Run your first quantum simulation

API Reference

Explore the complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us