This project has been tested and is compatible with Python versions 3.9, 3.10, 3.11, and 3.12. While it might work on other versions, these are the officially supported and tested ones.

Getting Started#

Before you can run this project, you need to have python installed on your system

Option 1: Setting up a Python Virtual Enviroment (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 project dependencies: Once the virtual enviroment is activated, you can install the required packages listed in the requirements.txt file:

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
```
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.