Version: 2.0

Python Library

Introduction

BQPhy is a specialized Python library for quantum-inspired evolutionary optimization algorithm for solving non-linear, non-convex, real-world optimization problems.

This comprehensive guide will walk you through the complete setup process, from installing the required Python environment to successfully installing and using the BQPhy library. At present, only Windows and Linux Operating Systems are supported, with support to iOS arriving soon.

The library is distributed as a pre-compiled wheel package optimized for Python 3.12 on Linux systems. This guide covers:

Prerequisites
Installing Python 3.12 on Linux systems
Creating isolated virtual environments for clean package management
Installing the BQPhy wheel package
Verifying your installation
Examples of utilization

Prerequisites

Before installing BQPhy, ensure your system meets the following requirements:

Python 3.12 (required for compatibility with the pre-compiled wheel)
x86_64 architecture
Linux or Windows operating system
Basic terminal/command line knowledge
Administrative privileges for system-wide Python installation (if needed)
At least 100MB of free disk space for the virtual environment and library

Installing on Linux

Acquiring Python 3.12

The BQphy python library requires Python version 3.12 to run effectively.

Method 1: Through Package Manager

The standard approach to acquiring packages in Linux environments is through the package manager. In Ubuntu/Debian family, the apt acts as a package repository, adn the appropriate installation commands are as follows,

# Update package list
sudo apt update

# Install Python 3.12
sudo apt install python3.12 python3.12-venv python3.12-dev

In the RedHat/CentOS/Fedora family, the package can be installed through,

# For Fedora (using dnf)
sudo dnf install python3.12 python3.12-devel python3.12-pip

# For RHEL/CentOS 8+ (using dnf)
sudo dnf install python3.12 python3.12-devel python3.12-pip

# For older RHEL/CentOS 7 (using yum)
sudo yum install python3.12 python3.12-devel python3.12-pip

Method 2: Using Deadsnakes PPA (if not available in default repos)

Sometimes, when dealing with older versions of the Linux OS, the package repository may not contain the required python 3.12 files. In this case, it becomes necessary to install it from the dead snakes repository.

sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-dev

Installing on Windows

Method 1: Official Python Installer (Recommended)

Download Python 3.12:
- Visit python.org/downloads/windows
- Download the latest Python 3.12.x installer for Windows
- Choose the appropriate version:
  - 64-bit: python-3.12.x-amd64.exe (recommended for most systems)
  - 32-bit: python-3.12.x.exe (for older systems)
Run the installer:
- Important: Check "Add Python to PATH" during installation
- Check "Install pip" (usually enabled by default)
- Choose "Install Now" or "Customize installation" for advanced options
Verify installation:
```
python --version
pip --version
```

Method 2: Microsoft Store

Install from Microsoft Store:
- Open Microsoft Store
- Search for "Python 3.12"
- Click "Install" on the official Python Software Foundation version
Verify installation:
```
python3.12 --version
```

Method 3: Package Managers

Using Chocolatey

# Install Chocolatey first if not installed
# Then install Python 3.12
choco install python312

Using Winget

winget install Python.Python.3.12

Method 4: Anaconda/Miniconda

# Download and install Miniconda, then:
conda install python=3.12

Creating a Virtual Environment

Why Use Virtual Environments?

Virtual environments are crucial when installing wheel packages like BQPhy. Here's why:

Dependency Isolation

Prevents conflicts between different Python projects and their dependencies
Each project gets its own isolated environment with specific package versions
Avoids "dependency hell" where packages require conflicting versions of the same library

System Protection

Keeps your system Python installation clean and stable
Prevents accidental modification of system-wide packages that other applications might depend on
Reduces risk of breaking system tools that rely on specific Python package versions

Reproducible Environments

Ensures consistent behavior across different machines and deployments
Makes it easier to share project requirements with teammates
Simplifies troubleshooting by eliminating environment-related variables

Easy Cleanup

Simple to remove entire project environment if no longer needed
No leftover packages cluttering your system
Easy to start fresh if something goes wrong

Setting Up the Virtual Environment on Linux

Navigate to your project directory before creating the environment.

Create the virtual environment:
```
python3.12 -m venv .BQP_Env
```
Activate the virtual environment:
```
source .BQP_Env/bin/activate
```
Your terminal prompt should now show (.BQP_Env) at the beginning.
Verify activation (optional):
```
pip list
```
This will show only the basic packages installed in your new environment.

Setting Up the Virtual Environment on Windows

Open Command Prompt or PowerShell:
- Press Win + R, type cmd or powershell, and press Enter
- Or search for "Command Prompt" or "PowerShell" in the Start menu
Navigate to your project directory:
```
cd C:\path\to\your\project
```
Create the virtual environment:
```
python -m venv .BQP_Env
```
Note: Use python3.12 if you have multiple Python versions installed
Activate the virtual environment:

For Command Prompt (cmd):
```
.BQP_Env\Scripts\activate.bat
```
For PowerShell:
```
.BQP_Env\Scripts\Activate.ps1
```
If you get an execution policy error in PowerShell, run:
```
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
Verify the environment (optional):
```
pip list
```
Your prompt should change to show the virtual environment:
```
(.BQP_Env) C:\path\to\your\project>
```

Installing the BQPhy Library to virtual environment

Install the wheel package:

pip install bqphy-0.0.4-cp312-cp312-linux_x86_64.whl

Verify the installation:
```
pip list
```
You should see bqphy listed among the installed packages.

Process

Define the model script in which the input is a list of potential solutions and the output is a list of their fitness values.
In the main function, define the configuration for the BQPhy Python library. As example of this is given below.

    # Problem configuration
    config = {
        "numPopulation": 100,
        "maxGeneration": 200,
        "deltaTheta": .05,
        "designVariables": len(ITEMS),
        "typeOfOptimisation":"BINARY"
    }

Create an object of the BQPhy Optimizer library

    optimizer = qea.BQPhy_OPTIMISER()

Initialize the Optimizer with the configuration dictionary

    optimizer.initialize(config)

Provide the model function as an argument to the BQPhy optimizer object

    optimizer.model(model_function)

Run Optimizer.

    optimizer.runOptimization()     

The optimizer supports CPU and GPU implementation. This is toggled by typing within the runOptimization paranthesis

"cpu" for serial execution
"openmp" for parallel execution
"gpu" for GPU execution

Get the best solution back from the BQPhy Optimizer object

    best_solution, best_fitness = optimizer.getBestDesign()

Deactivating the Virtual Environment

When you're done working with the library:

deactivate

Troubleshooting

Common Issues

Python 3.12 not found: Make sure Python 3.12 is installed and accessible in your PATH
Permission errors: Use sudo for system-wide installations or ensure you have write permissions
Virtual environment activation fails: Check that you're in the correct directory and the environment was created successfully

Getting Help

If you encounter issues not covered here, please check:

Python version compatibility
System architecture (x86_64 required for this wheel)
Virtual environment activation status

Introduction​

Prerequisites​

Installing on Linux​

Acquiring Python 3.12​

Method 1: Through Package Manager​

Method 2: Using Deadsnakes PPA (if not available in default repos)​

Installing on Windows​

Method 1: Official Python Installer (Recommended)​

Method 2: Microsoft Store​

Method 3: Package Managers​

Using Chocolatey​

Using Winget​

Method 4: Anaconda/Miniconda​

Creating a Virtual Environment​

Why Use Virtual Environments?​

Dependency Isolation​

System Protection​

Reproducible Environments​

Easy Cleanup​

Setting Up the Virtual Environment on Linux​

Setting Up the Virtual Environment on Windows​

Installing the BQPhy Library to virtual environment​

Process​

Deactivating the Virtual Environment​

Troubleshooting​

Common Issues​

Getting Help​