BEACON-M: Continuous Benchmark problems with Explicit Adjustable COrrelatioN control

# BEACON-M: Continuous Benchmark problems with Explicit Adjustable COrrelatioN control

BEACON-M is a framework for generating continuous many-objective optimisation problems (MOPs) where the correlation between the objectives can be explicitly controlled. It utilizes Random Fourier Features (RFF) of the Radial Basis Function (RBF) kernel and a linear transformation to create landscape functions that adhere to a specified correlation matrix.

## Installation

To run this project, you need Python installed along with several scientific computing libraries.

### Prerequisites

Create a virtual environment (recommended) and install the dependencies.

**Important Note on Pymoo:**

This project relies on `pymoo`, and for performance reasons, it is highly recommended to use the version with compiled C extensions. The standard pip installation might not include these extensions for all platforms or configurations.

See https://pymoo.org/installation.html for insttuctions on installing the compiled version.

Then install the remaining dependencies:

```bash

pip install -r requirements.txt

```

## Structure

The core logic is contained within `beaconm_generator.py`:

* **`BEACONMProblemSampler`**: This class defines the problem parameters. It handles sampling problems and saving/loading them as well

* **`BEACONMProblem`**: A wrapper class that inherits from `pymoo.core.problem.Problem`. It connects the `BEACONMProblemSampler` to the `pymoo` interface, allowing `pymoo` algorithms to interact with the generated problem.

* **`BEACONMOptimiser`**: A utility class to streamline the execution of optimisation algorithms on a `BEACONMProblem`. It handles running the algorithm and saving results.

* **`BEACONMCallback`**: A simple callback for `pymoo` to track metrics

Functions for generating grouped correlation matrices are in `utils.py`.

## Usage

### Running Experiments

Run the experiments with:

```bash

python3 experiments.py

```

##### Please note that these experiments are run on a single core. We used extensive multi-threading on powerful computers to run our experiments. Running experiments this way will yield the same results... but it may take a while...

### Example: Single Problem Execution

Here is how to generate a single problem instance and evaluate a point:

```python

import numpy as np

import torch

from beaconm import *

from utils import CorrelationMatrix

# 1. Define parameters

# Hyperparameters - we reccmmend not to change them

num_features = 1000

lengthscale = 0.01

# Problem parameters

input_dim = 10 # number of decision variables

output_dim = 3 # number of objectives

lb=0.0 # remains the same for all decision variables

ub=1.0 # remains the same for all decision variables

# corr matrix based on Group-structure - define single group or two group matrix structure. For example, if you want a single group, a correlation matrix with single correlation value among objectives can look like this.

single_group = CorrelationMatrix(M=3).single_group(rho=0.5)

# If you want to two group matrix structure, a correlation matrix with two correlation values (intra and inter group) among objectives can look like this ..., where ... is intra-group and ... is inter group

two_group = CorrelationMatrix(M=3).two_group(rho_w=0.5, rho_b=-0.5)

# Optionally you can define just `rho_w`, in which case `rho_b = -rho_w` by default

two_group = CorrelationMatrix(M=3).two_group(rho_w=0.5)

# Or you can define your own correlation matrix (as long as it is positive definite)

corr_matrix = np.array([

[1, 0.5, 0.5],

[0.5, 1, 0.5],

[0.5, 0.5, 1]

])

# 3. Instantiate the BEACON-M sampler

beaconm_sampler = BEACONMProblemSampler(

correlation_matrix=corr_matrix,

num_features=num_features,

input_dim=input_dim,

output_dim=output_dim,

lengthscale=lengthscale,

identifier='example_problem'

)

# 4. Save the problem instance (the filepath will be chosen from a combination of objective space dimensionality, decision space dimensionality and the 'itentifier' value)

beaconm_sampler.save_problem(lb=lb, ub=ub)

# ---------------------------------------

# 5. Sampling the problem - meaning getting the objective function values. An example is shown below:

# Randomly sample points from the problem

# decision variable values

decision_points = np.random.uniform(lb, ub, size=(1000, input_dim))

decision_points = torch.tensor(decision_points, dtype=torch.float64)

# objective function samples

samples = beaconm_sampler.sample(decision_points)

# 6. An example of solving rhe multi-objective problem with NSGA-II

from pymoo.algorithms.moo.nsga2 import NSGA2

# Convert the problem to a Pymoo problem

problem = BEACONMProblem(

beaconm_sampler=beaconm_sampler,

lb=lb,

ub=ub

)

# Initialise the optimiser wrapper for BEACON-M in Pymoo

algorithm = NSGA2(pop_size=100)

optimizer = BEACONMOptimiser(

problem=problem,

algorithm=algorithm,

iteration=0

)

# Run the optimization

res = optimizer.minimise_problem(

n_gen=1000,

save_data=True

)

```