This project requires Python 3.10 or higher and has been tested with Python versions 3.10, 3.11, and 3.12.

Note: Python 3.10+ is required for compatibility with the latest Qiskit ecosystem (qiskit-ibm-runtime 0.44.0+).

Installation#

QBioCode can be installed via PyPI or from source.

Quick Install from PyPI (Recommended)#

Install the latest stable version:

pip install qbiocode

Install with apps support (QProfiler, QSage):

pip install qbiocode[apps]

Install with all optional dependencies:

pip install qbiocode[all]

Install from Source#

Option 1: Setting up a Python Virtual Environment (venv)#

This is the standard way to create an isolated Python enviroment.

Steps:

Install pip (if you don’t have it):

 python -m ensurepip --default-pip

or on some systems:

 sudo apt update
 sudo apt install python3-pip

Create a virtual enviroment:

   python -m venv venv

This command creatas a new directory named venv (you can choose a different name if you prefer) containing a copy of the Python interpreter and necessary supporting files.

Activate the virtual enviroment:

On macOS and Linux:

  source venv/bin/activate

On Windows (command promt):

  venv\Scripts\activate

On Windows (PowerShell):

  .\venv\Scripts\Activate.ps1

Once the activated, you’ll see (venv) at the beginning of your terminal promt.

Install QBioCode:

Once the virtual environment is activated, install QBioCode:

# Clone the repository first
git clone https://github.com/IBM/QBioCode.git
cd QBioCode

# Install in editable mode
pip install -e .

# Or install with apps support
pip install -e ".[apps]"

macOS Users: Install OpenMP for XGBoost (Required)

On macOS, XGBoost requires the OpenMP library. Install it using Homebrew:
```
brew install libomp
```
If you don’t have Homebrew installed, visit https://brew.sh/ for installation instructions.

After installing OpenMP, you may need to reinstall XGBoost:
```
pip install --force-reinstall xgboost
```
Deactivate the virtual enviroment (when you are done):
```
 deactivate
```
This will return you to your base Python enviroment.

Option 2: Setting up a Conda Enviroment#

Create the environment from the requirements.txt file. This can be done using anaconda, miniconda, miniforge, or any other environment manager.

conda create -n qbc python==3.12

Note: if you receive the error bash: conda: command not found..., you need to install some form of anaconda to your development environment.

Activate the new environment:

conda activate qbc
pip install .

macOS Users: Install OpenMP for XGBoost (Required)

On macOS, XGBoost requires the OpenMP library. Install it using Homebrew:
```
brew install libomp
```
If you don’t have Homebrew installed, visit https://brew.sh/ for installation instructions.

After installing OpenMP, you may need to reinstall XGBoost:
```
pip install --force-reinstall xgboost
```
Verify that the new environment and packages were installed correctly:

conda env list
pip list

Option 3: Using Galaxy (Cloud-Based, No Local Installation)#

If you prefer not to install QBioCode on your local or personal machine, you can use Galaxy, a free, web-based platform for data-intensive biomedical research.

Why Galaxy?

No installation required: Run everything in your browser
Free computational resources: Access to cloud computing
Jupyter notebook support: Run QBioCode tutorials directly
Persistent workspace: Your work is saved in the cloud

Step 1: Register for a Galaxy Account#

Go to https://usegalaxy.org/
Click “Login or Register” in the top menu
Select “Register” and fill in:
- Email address
- Password
- Public name (username)
Click “Create” to complete registration
Verify your email address (check your inbox for confirmation link)

Step 2: Launch a Qiskit Jupyter Notebook (Recommended - Pre-installed QBioCode)#

Log in to your Galaxy account at https://usegalaxy.org/
From the left menu, select “Interactive Tools”
Search for “Qiskit Jupyter notebook”
Click on the Qiskit Jupyter tool to launch it
Configure the notebook environment:
- Allocate resources: Default settings are usually sufficient
- Click “Execute” or “Run Tool”
Wait for the notebook server to start (this may take 1-2 minutes)
Once ready, click the link to open your Jupyter environment in a new tab

Pre-installed QBioCode

The Qiskit Jupyter notebook in Galaxy comes with QBioCode pre-installed! You can start using it immediately without any installation steps. However, note that this may not be the latest version of the code.

Step 3: Using QBioCode (Pre-installed Version)#

Once your Qiskit Jupyter notebook server is running:

Verify QBioCode is available:

Open a new notebook or terminal and run:

import qbiocode as qbc
print(f"QBioCode version: {qbc.__version__}")

Access the tutorials:

The tutorials should be available in the file browser. Navigate to the QBioCode tutorial directory and open any notebook:
- Artificial_data_generation/example_data_generation.ipynb
- QProfiler/example_qprofiler.ipynb
- QSage/qsage.ipynb
- Quantum_Projection_Learning/QPL_example.ipynb

Step 3b: Install Latest Version (Optional)#

If you need the latest version of QBioCode with the most recent features and bug fixes:

Open a new terminal in Jupyter:
- Click “File” → “New” → “Terminal” (in JupyterLab)
- Or use the “New” → “Terminal” button (in classic Jupyter)

Install the latest QBioCode from GitHub:

# Clone the repository
git clone https://github.com/IBM/QBioCode.git
cd QBioCode

# Install QBioCode (this will upgrade the pre-installed version)
pip install --upgrade .

Verify the updated installation:

python -c "import qbiocode; print(f'QBioCode version: {qbiocode.__version__}')"

Note

After upgrading, you may need to restart your Jupyter kernel for changes to take effect: Kernel → Restart Kernel

Step 4: Run QBioCode Tutorials#

Open a tutorial notebook:
- In the Jupyter file browser, navigate to QBioCode/tutorial/
- Click on any tutorial notebook to open it:
  - Artificial_data_generation/example_data_generation.ipynb
  - QProfiler/example_qprofiler.ipynb
  - QSage/qsage.ipynb
  - Quantum_Projection_Learning/QPL_example.ipynb
Run the tutorial:
- Execute cells sequentially using Shift+Enter
- Follow the instructions in each notebook

Tips for Using Galaxy#

Tip

Best Practices:

Save your work frequently: Use File → Save to preserve your progress
Download important results: Export notebooks and data files to your local machine
Monitor resource usage: Galaxy sessions have time limits; plan accordingly
Use version control: Consider connecting to GitHub for better workflow management

Warning

Important Limitations:

Galaxy sessions may timeout after inactivity (typically 1-2 hours)
Computational resources are shared; quantum simulations may be slower
Large datasets may require local installation for better performance
IBM Quantum hardware access requires separate IBM Quantum account setup

Troubleshooting Galaxy Installation#

Issue: pip install fails

# Try upgrading pip first
pip install --upgrade pip
pip install .

Issue: Import errors

# Restart the kernel: Kernel → Restart Kernel
# Then re-import
import qbiocode

Issue: XGBoost errors on macOS

# Install OpenMP library
brew install libomp
pip install --force-reinstall xgboost

Issue: Session timeout

Save your work regularly
Download notebooks before closing
Restart the interactive tool if needed

Alternative: Google Colab#

Another cloud-based option is Google Colab:

# In a Colab notebook cell:
!git clone https://github.com/IBM/QBioCode.git
%cd QBioCode
!pip install .

Then upload tutorial notebooks from the tutorial/ directory.