About BQPhy Matlab Toolkit
Prerequisites
In order to use the BQPhy toolbox, the following dependencies are needed,
- Matlab Software (Linux/Windows)
- gcc 13
Installation Procedure
Once the toolbox is delivered, double clicking it should automatically install it in the Matlab application.
Verify its installation through Home -> Add-ons -> Manage Add-ons. The installed toolkit must appear as "BQPhyToolbox"
To ensure the toolbox is working, navigate to the Samples folder and run an application of your choice. The Application will run and produce the desired output along with stating that the "Optimization has been completed sucessfully" in the Matlab terminal
How to use BQPhy Toolbox
Once the toolbox is installed, it becomes available to the matlab .m applications that are being developed.
Setting the configuration details for BQPhy Toolbox
The toolbox is configured. This can be done either by creating the object and then filling in the required inputs (option 1) OR by creating the object with the configuration details specified (option 2)
Option 1: Sequential Dot Notation
Builds an empty struct incrementally by assigning fields one by one, ideal for readability during development or when fields depend on prior values.
config = struct();
config.numPopulation = 100;
config.maxGeneration = 100;
config.deltaTheta = 0.05;
config.designVariables = 2;
config.typeOfOptimisation = 'CONTINOUS';
config.stringLength = 16; % optional, defaults to 16
config.lowerBounds = [-5.12, -5.12];
config.upperBounds = [5.12, 5.12];
config.debsApproach = false; % optional
Option 2: Compact Struct Function
Defines all fields in a single struct() call using name-value pairs, most concise for static configurations like your optimization parameters.
config = struct( ...
"numPopulation", 100, ...
"maxGeneration", 200, ...
"deltaTheta", 0.05, ...
"designVariables", 2, ...
"typeOfOptimisation", 'CONTINUOUS', ...
"debsApproach", false, ...
"lowerBounds", [-5.12, -5.12], ...
"upperBounds", [5.12, 5.12]);
Option 3: Hybrid Dynamic Initialization
Starts with core fields via struct(), then computes bounds based on designVariables, best for scalable setups in genetic algorithms or CFD parameter sweeps.
config = struct( ...
"numPopulation", 100, ...
"maxGeneration", 200, ...
"deltaTheta", 0.05, ...
"designVariables", 2, ...
"typeOfOptimisation", 'CONTINUOUS', ...
"debsApproach", false ...
);
config.lowerBounds = -5 * ones(1, config.designVariables);
config.upperBounds = 5 * ones(1, config.designVariables);
Calling the BQPhy Toolbox
[result, Fitness] = BQPhy_Mex(config, myFun, 'cpu');
result contains optimized parameters; Fitness holds history.
Tutorials
Tutorial 1: Running a continuous optimization with function in same .m file
This MATLAB tutorial demonstrates the BQPhy's quantum-inspired continuous optimization using Rastrigin function with error handling and three config creation methods.
Step 1: Configuration Structure Options
config = struct( ...
"numPopulation", 100, ...
"maxGeneration", 200, ...
"deltaTheta", 0.05, ...
"designVariables", 2, ...
"typeOfOptimisation", 'CONTINUOUS', ...
"debsApproach", false, ...
"lowerBounds", [-5.12, -5.12], ...
"upperBounds", [5.12, 5.12]);
Step 2: Define Rastrigin Objective Function
Define a Vectorized function handle for entire population evaluation concurrently.
myFun = @(x) (10 * 2) + sum(x.^2 - 10 * cos(2 * pi * x), 2);
Step 3: Execute BQPhy MEX with Error Handling
disp('Configuration:'); disp(config);
try
[result, Fitness] = BQPhy_Mex(config, myFun, 'cpu'); % 'gpu' for NVIDIA acceleration
disp(['Result: ', num2str(result)]);
catch ME
disp('Error occurred:'); disp(ME.message);
end
Step 4: Visualize Convergence
filtered = Fitness(1);
current_min = Fitness(1);
for i = 2:length(Fitness)
if Fitness(i) < current_min
filtered(i) = Fitness(i);
current_min = Fitness(i);
else
filtered(i) = current_min;
end
end
plot(Fitness, '-o'); % Full history
hold on; plot(filtered); % Monotonic improvement
Tutorial 2: Running a continuous optimization with function in different .m file
This MATLAB tutorial demonstrates solving continuous optimization problems using BQPhy's quantum-inspired optimizer for low-dimensional design spaces (2 variables).
Step 1: Define Problem Parameters
Set up design variables, bounds, and population size:
desVar = 2; % Number of continuous variables
lb = -5 * ones(1, desVar); % Lower bounds [-5, -5]
ub = 5 * ones(1, desVar); % Upper bounds [5, 5]
popSize = 200; % Population size per generation
Step 2: Define Objective Function
Create vectorized model function as function handle:
myFun = @(x) myModel(x, desVar);
It is expected that myModel is defined in a separate .m file. It accepts batch matrix x (popSize × desVar) and returns vector of fitness values. Example for Rastrigin:
% Separate .m file
function f = myModel(x, desVar)
f = (10 * desVar) + sum(x.^2 - 10 * cos(2 * pi * x), 2);
end
Step 3: Run BQPhy Continuous Optimizer
[Design_X, MinFitness, Fitness] = BQPhy_Optimiser(myFun, ...
'numChromosomes', popSize, ... % 200 individuals
'dimension', desVar, ... % 2 design variables
'deltaTheta', 0.05, ... % Quantum rotation angle
'maxGen', 200, ... % Maximum generations
'typeOfOptimization', 'CONTINUOUS', ...
'lowerBounds', lb, ...
'upperBounds', ub);
Step 4: Visualize Convergence
Filter fitness history to show only improving solutions:
filtered = Fitness(1);
current_min = Fitness(1);
for i = 2:length(Fitness)
if Fitness(i) < current_min
filtered(i) = Fitness(i);
current_min = Fitness(i);
else
filtered(i) = current_min;
end
end
plot(filtered, '-o');
xlabel('Generation Id'); ylabel('Fitness value');
title('BQPhy Continuous Optimization Convergence');
Tutorial 3: Running a discrete optimization with function in same .m file
This MATLAB tutorial demonstrates solving the 0/1 Knapsack problem using BQPhy's quantum-inspired optimizer for binary optimization on large-scale instances (314 items).
Step 1: Load Problem Data
Define item values, weights, and knapsack capacity for a challenging instance:
Values = [47, 107, 53, ...]; % 314 item values [0,200]
Weights = [29, 76, 30, ...]; % 314 item weights [1,200]
knapsackCapacity = 25233; % Target capacity
nVars = length(Values); % 314 binary decision variables
Step 2: Define Objective and Constraints
Create vectorized functions for batch population evaluation:
objFun = @(x) knapsackObjective(x, Values); % f = -∑(x_i * v_i)
nonlcon = @(x) knapsackConstraint(x, Weights, knapsackCapacity);
Step 3: Configure and Run BQPhy Optimizer
Define the configuration parameters for BQPhy Optimization toolbox
[BestDesign, BestFitness, GenFitness] = BQPhy_Optimiser(objFun, ...
'constraint', nonlcon, ...
'typeOfOptimization', 'BINARY', ...
'numChromosomes', 200, ... % Population size
'dimension', nVars, ... % 314 variables
'maxGen', 200, ... % Generations
'penaltyFactor', 2, ...
'initialPenalty', 10, ...
'maxOuterIter', 5); % Augmented Lagrangian iterations
Step 4: Post-Process Results
Filter fitness history to show only improving best solutions:
filtered = GenFitness(1);
current_min = GenFitness(1);
for i = 2:length(GenFitness)
if GenFitness(i) < current_min
filtered(i) = GenFitness(i);
current_min = GenFitness(i);
else
filtered(i) = current_min;
end
end
plot(filtered, '-o'); % Monotonic decreasing curve
Applications and Use-cases
Troubleshooting
- Error regarding mismatched GLIBCXX version.
-
Cause: Matlab ships with a default libstd.so.6 version. This version may not have the appropriate symbols library (GLIBCXX) that is required by the BQPhy toolbox
-
Remedy: In order to solve this problem, the Ubuntu OS must have gcc 13 with GLIBCXX support up to 3.4.33. This is the default setting in Ubuntu 24.04 upwards To force the Matlab to use the Ubuntu 24.04's libstd.so.6, run the following commands on the matlab terminal LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6 /home/matlab.team/matlab_R2024b/bin/matlab