PATATUNE Reference
This reference manual details functions, modules, and objects included in PATATUNE, describing what they are and what they do.
PATATUNE A Python framework for Metaheuristic Multi-Objective Optimization
Modules:
-
metrics–Module implementing various multi-objective optimization metrics.
-
mopso–Module implementing the Multi-Objective Particle Swarm Optimization (MOPSO) algorithm.
-
objective–Objective classes for multi-objective optimization.
-
optimizer–Optimizer module for patatune.
-
util–Utility functions and classes for Patatune.
Module implementing various multi-objective optimization metrics.
Functions:
-
generational_distance–Calculates the generational distance metric, for any dimension of the pareto front.
-
hypervolume_indicator–Calculates the hypervolume indicator metric, for any dimension of the pareto front.
-
inverted_generational_distance–Calculates the inverted generational distance metric, for any dimension of the pareto front.
-
nds–Returns the non-dominated set from the given front.
-
wfg–WFG algorithm for hypervolume calculation
generational_distance(pareto_front, reference_front)
Calculates the generational distance metric, for any dimension of the pareto front.
The generational distance (GD) measures the average distance of points in the obtained Pareto front to the nearest point in the true Pareto front.
Parameters:
-
pareto_front(ndarray) –Represents the pareto front obtained from the optimization algorithm.
-
reference_front(ndarray) –Represents the true pareto front.
Returns:
-
float–The generational distance metric value.
hypervolume_indicator(pareto_front, reference_point, reference_hv=1, max_evaluations=10000000)
Calculates the hypervolume indicator metric, for any dimension of the pareto front.
The hypervolume indicator (HV) measures the volume of the objective space dominated by the obtained Pareto front and bounded by a reference point.
Parameters:
-
pareto_front(ndarray) –Represents the pareto front obtained from the optimization algorithm.
-
reference_point(list or ndarray) –A reference point in the objective space, typically chosen to be worse than any point in the pareto front.
-
reference_hv(float, default:1) –The hypervolume of the reference front for normalization (default: 1).
-
max_evaluations(int, default:10000000) –Maximum number of evaluations to perform during hypervolume calculation (default: 10,000,000). Maximum number of evaluations to perform during hypervolume calculation (default: 10,000,000).
Returns:
-
float–The hypervolume indicator metric value normalized by the reference hypervolume.
inverted_generational_distance(pareto_front, reference_front)
Calculates the inverted generational distance metric, for any dimension of the pareto front.
The inverted generational distance (IGD) measures the average distance of points in the true Pareto front to the nearest point in the obtained Pareto front.
Parameters:
-
pareto_front(ndarray) –Represents the pareto front obtained from the optimization algorithm.
-
reference_front(ndarray) –Represents the true pareto front.
Returns:
-
float–The inverted generational distance metric value.
nds(front)
Returns the non-dominated set from the given front.
Uses the get_dominated utility function to identify dominated points and filters them out.
Parameters:
-
front(ndarray) –Represents a set of points in the objective space.
Returns: (np.ndarray): The non-dominated subset of the input front.
wfg(pareto_front, reference_point, counter, max_evaluations)
WFG algorithm for hypervolume calculation Reference: While, L., Bradstreet, L., & Barone, L. (2012). A fast way of calculating exact hypervolumes. IEEE Transactions on Evolutionary Computation, 16(1), 86-95. DOI: 10.1109/TEVC.2010.2077298
Parameters:
-
pareto_front(ndarray) –Represents the pareto front obtained from the optimization algorithm.
-
reference_point(list or ndarray) –A reference point in the objective space, typically chosen to be worse than any point in the pareto front.
-
counter(list) –A list containing a single integer to keep track of the number of evaluations performed.
-
max_evaluations(int) –Maximum number of evaluations to perform during hypervolume calculation.
Returns:
-
float–The hypervolume of the pareto front with respect to the reference point.
Note
Optionally uses numba's njit for performance optimization.
Module implementing the Multi-Objective Particle Swarm Optimization (MOPSO) algorithm.
Modules:
-
mopso–Multi-Objective Particle Swarm Optimization (MOPSO) algorithm implementation.
-
particle–Module defining the Particle class for the MOPSO algorithm.
Multi-Objective Particle Swarm Optimization (MOPSO) algorithm implementation.
Classes:
-
MOPSO–Multi-Objective Particle Swarm Optimization (MOPSO) algorithm.
MOPSO(objective, lower_bounds, upper_bounds, param_names=None, num_particles=50, inertia_weight=0.5, cognitive_coefficient=1, social_coefficient=1, initial_particles_position='random', default_point=None, exploring_particles=False, topology='random', max_pareto_length=-1)
Bases: Optimizer
Multi-Objective Particle Swarm Optimization (MOPSO) algorithm.
The MOPSO class implements the MOPSO algorithm for multi-objective optimization problems. It inherits from the base Optimizer class and provides methods for initializing particles, updating their positions and velocities, evaluating their fitness, and maintaining the Pareto front.
Attributes:
-
objective(Objective) –The functions to optimize.
-
lower_bounds(list) –List of lower bounds for each parameter.
-
upper_bounds(list) –List of upper bounds for each parameter. lower and upper bounds are used to check the type of each parameter (int, float, bool)
-
param_names(list) –List of parameter names.
-
num_particles(int) –Number of particles in the swarm.
-
inertia_weight(float) –Inertia weight for velocity update.
-
cognitive_coefficient(float) –Cognitive coefficient for velocity update.
-
social_coefficient(float) –Social coefficient for velocity update.
-
initial_particles_position(str) –Method for initializing particle positions. Options are
lower_bounds,upper_bounds,random,gaussian.-
if
lower_bounds, all particles are initialized at the lower bounds; -
if
upper_bounds, all particles are initialized at the upper bounds; -
if
random, particles are initialized randomly within the bounds; -
if
gaussian, particles are initialized using a truncated Gaussian distribution centered around default_point.
-
-
default_point(list) –Default point for
gaussianinitialization.- if None, the center between lower and upper bounds is used.
-
exploring_particles(bool) –If True, particles that do not improve for a certain number of iterations are scattered.
-
topology(str) –Topology for social interaction among particles. Options are
random,lower_weighted_crowding_distance,higher_weighted_crowding_distance,round_robin.See Particle.get_pareto_leader for more information.
-
max_pareto_length(int) –Maximum length of the Pareto front. If -1, no limit is applied.
Methods:
-
calculate_crowding_distance–Calculates the crowding distance for each particle in the Pareto front.
-
check_types–Check that lower_bounds and upper_bounds have acceptable types and are consistent.
-
export_state–Exports the current state of the MOPSO optimizer to CSV files.
-
get_metric–Calculates a specified metric for the current Pareto front.
-
load_state–Loads the MOPSO optimizer state from a checkpoint file.
-
optimize–Runs the MOPSO optimization process for a specified number of iterations.
-
save_state–Saves the current state of the MOPSO optimizer to a checkpoint file.
-
scatter_particle–Scatters a particle that has not improved for a certain number of iterations.
-
step–Performs a single optimization step in the MOPSO algorithm.
-
update_pareto_front–Updates the Pareto front based on the current particles' fitness.
calculate_crowding_distance(pareto_front)
check_types()
Check that lower_bounds and upper_bounds have acceptable types and are consistent.
Raises:
-
ValueError–If any lower or upper bound has an unacceptable type, or if lower_bounds and upper_bounds have inconsistent types.
export_state()
Exports the current state of the MOPSO optimizer to CSV files.
Uses the FileManager to export
- the states of individual particles to 'checkpoint/individual_states.csv'
- the current Pareto front to 'checkpoint/pareto_front.csv'.
get_metric(metric)
load_state()
Loads the MOPSO optimizer state from a checkpoint file.
Uses the FileManager to deserialize and restore the MOPSO object from 'checkpoint/mopso.pkl'.
optimize(num_iterations=100, max_iterations_without_improvement=None)
Runs the MOPSO optimization process for a specified number of iterations.
Uses the step method to perform optimization steps and manages the overall optimization loop.
Parameters:
-
num_iterations(int, default:100) –Total number of iterations to perform.
-
max_iterations_without_improvement(int, default:None) –Maximum number of iterations a particle can go without improvement before being scattered. If None, no scattering is performed.
Returns:
-
list–The final Pareto front after optimization.
save_state()
Saves the current state of the MOPSO optimizer to a checkpoint file.
Uses the FileManager to serialize and save the MOPSO object to 'checkpoint/mopso.pkl'.
scatter_particle(particle: Particle)
Scatters a particle that has not improved for a certain number of iterations.
The particle's velocity is adjusted to move it towards less crowded areas of the search space.
Parameters:
-
particle(Particle) –The particle to be scattered.
step(max_iterations_without_improvement=None)
Performs a single optimization step in the MOPSO algorithm.
Parameters:
-
max_iterations_without_improvement(int, default:None) –Maximum number of iterations a particle can go without improvement before being scattered. If None, no scattering is performed.
update_pareto_front()
Updates the Pareto front based on the current particles' fitness.
Returns:
-
dict–A dictionary mapping each particle in the Pareto front to its crowding distance.
Module defining the Particle class for the MOPSO algorithm.
Classes:
-
Particle–Class representing a particle in the MOPSO algorithm.
Functions:
-
boltzmann–Computes a probability distribution function (PDF) based on crowding distances.
-
round_robin_topology–Selects a leader particle from the Pareto front in a round-robin fashion.
-
weighted_crowding_distance_topology–Selects a leader particle from the Pareto front based on crowding distances.
Particle(lower_bound, num_objectives, num_particles, id, topology)
Class representing a particle in the MOPSO algorithm.
Attributes:
-
position(ndarray) –Current position of the particle in the search space.
-
num_objectives(int) –Number of objectives in the optimization problem.
-
num_particles(int) –Total number of particles in the swarm.
-
velocity(ndarray) –Current velocity of the particle.
-
fitness(ndarray) –Current fitness values of the particle for each objective.
-
local_best_fitnesses(list) –List of local best fitness values found by the particle.
-
local_best_positions(list) –List of positions corresponding to the local best fitnesses.
-
iterations_with_no_improvement(int) –Counter for iterations without improvement.
-
id(int) –Unique identifier for the particle.
-
topology(str) –Topology strategy for selecting global best in the swarm.
Methods:
-
get_pareto_leader–Selects a leader particle from the Pareto front based on the specified topology.
-
set_fitness–Sets the fitness of the particle and updates its local best if necessary.
-
set_position–Sets the position of the particle.
-
set_state–Sets the complete state of the particle.
-
update_best–Updates the local best fitnesses and positions of the particle based on its current fitness.
-
update_position–Updates the position of the particle based on its velocity and the problem boundaries.
-
update_velocity–Updates the velocity of the particle based on its local best and the global best.
get_pareto_leader(pareto_front, crowding_distances)
Selects a leader particle from the Pareto front based on the specified topology.
If the topology is "random", a random particle from the Pareto front is selected. If the topology is "lower_weighted_crowding_distance", a particle is selected with a probability inversely proportional to its crowding distance calling the weighted_crowding_distance_topology function. If the topology is "higher_weighted_crowding_distance", a particle is selected with a probability proportional to its crowding distance calling the weighted_crowding_distance_topology function. If the topology is "round_robin", particles are selected in a round-robin fashion based on the particle's ID calling the round_robin_topology function.
Parameters:
set_fitness(fitness)
Sets the fitness of the particle and updates its local best if necessary.
Parameters:
-
fitness(ndarray) –New fitness values for the particle.
set_position(position)
set_state(velocity, position, best_position, fitness, best_fitness)
Sets the complete state of the particle.
Parameters:
-
velocity(ndarray) –New velocity for the particle.
-
position(ndarray) –New position for the particle.
-
best_position(list) –New list of local best positions for the particle.
-
fitness(ndarray) –New fitness values for the particle.
-
best_fitness(list) –New list of local best fitness values for the particle.
update_best()
Updates the local best fitnesses and positions of the particle based on its current fitness.
Uses the get_dominated utility function to identify non-dominated solutions. Resets the iterations_with_no_improvement counter if there is an improvement.
update_position(lower_bound, upper_bound)
Updates the position of the particle based on its velocity and the problem boundaries.
If the variable is of integer type, the new position is rounded. If the variable is of boolean type, the new position is determined by a threshold of 0.5.
Parameters:
update_velocity(pareto_front, crowding_distances, inertia_weight=0.5, cognitive_coefficient=1, social_coefficient=1)
Updates the velocity of the particle based on its local best and the global best.
Parameters:
-
pareto_front(list) –List of particles representing the current Pareto front.
-
crowding_distances(dict) –Dictionary mapping particles to their crowding distances.
-
inertia_weight(float, default:0.5) –Weight for the inertia component (default: 0.5).
-
cognitive_coefficient(float, default:1) –Coefficient for the cognitive component (default: 1).
-
social_coefficient(float, default:1) –Coefficient for the social component (default: 1).
boltzmann(crowding_distances, higher)
Computes a probability distribution function (PDF) based on crowding distances.
Parameters:
-
crowding_distances(dict) –Dictionary mapping particles to their crowding distances.
-
higher(bool) –If True, computes PDF favoring higher crowding distances. If False, computes PDF favoring lower crowding distances.
Returns:
-
list–A list representing the probability distribution function for selecting particles.
round_robin_topology(pareto_front, id)
Selects a leader particle from the Pareto front in a round-robin fashion.
The particle is selected based on its ID modulo the size of the Pareto front. If the ID exceeds the size of the Pareto front, it wraps around.
Parameters:
-
pareto_front(list) –List of particles representing the current Pareto front.
-
id(int) –Unique identifier for the particle.
Returns:
-
Particle–The selected leader particle from the Pareto front.
weighted_crowding_distance_topology(pareto_front, crowding_distances, higher)
Selects a leader particle from the Pareto front based on crowding distances.
Parameters:
-
pareto_front(list) –List of particles representing the current Pareto front.
-
crowding_distances(dict) –Dictionary mapping particles to their crowding distances.
-
higher(bool) –If True, selects particles with higher crowding distances with higher probability. If False, selects particles with lower crowding distances with higher probability.
Returns:
-
Particle–The selected leader particle from the Pareto front.
Objective classes for multi-objective optimization.
Provides a base Objective and concrete implementations for
element-wise, batched and asynchronous evaluations.
Classes:
-
AsyncElementWiseObjective–Asynchronous element-wise objective class.
-
BatchObjective–Batch objective class.
-
ElementWiseObjective–Element-wise objective class.
-
Objective–Base class for defining objective functions.
AsyncElementWiseObjective(objective_functions, num_objectives=None, directions=None, objective_names=None, true_pareto=None)
BatchObjective(objective_functions, batch_size, num_objectives=None, directions=None, objective_names=None, true_pareto=None)
Bases: Objective
Batch objective class.
Inherits from the base Objective class and implements the evaluate method to evaluate each objective function on batches of items asynchronously.
Attributes: batch_size (int): Size of each batch for evaluation.
Methods:
-
evaluate–Passes items in batches to each objective function asynchronously and collects the results.
evaluate(items)
ElementWiseObjective(objective_functions, num_objectives=None, directions=None, objective_names=None, true_pareto=None)
Bases: Objective
Element-wise objective class.
Inherits from the base Objective class and implements the evaluate method to evaluate each objective function on individual items.
Methods:
-
evaluate–Passes each item one by one to each objective function and collects the results.
evaluate(items)
Objective(objective_functions, num_objectives=None, directions=None, objective_names=None, true_pareto=None)
Base class for defining objective functions.
The class is used to evaluate multiple objective functions for all particles simultaneously.
The classes that inherit from this one should implement the evaluate method.
Parameters:
-
objective_functions(list | callable) –A list of callables (or a single callable) that compute objective values.
-
num_objectives(int, default:None) –Number of objectives. Defaults to
len(objective_functions). -
directions(list[str], default:None) –List of 'minimize' or 'maximize' for each objective. Defaults to all 'minimize'.
-
objective_names(list[str], default:None) –Names for each objective.
-
true_pareto(callable, default:None) –Function that returns the true Pareto front. Takes as input the number of points and returns a 2D array of shape
(num_points, num_objectives).
Methods:
-
evaluate–Passes all items to each objective function and collects the results.
Optimizer module for patatune.
This module contains the base Optimizer class that other optimizers in
patatune should inherit from.
Classes:
-
Optimizer–Base class for optimization algorithms.
Optimizer()
Base class for optimization algorithms.
Subclasses must implement __init__,
step, and
optimize.
Raises:
-
NotImplementedError–If methods are not implemented by subclasses.
Methods:
optimize()
Run the optimization loop.
This method should coordinate repeated calls to :meth:step and any
required setup/teardown.
step()
Perform a single optimization step.
Subclasses should update internal state (particles/parameters) in this method.
Utility functions and classes for Patatune.
This module provides various utility functions and classes used throughout the patatune package, including file management, logging, randomization, and dominance checking.
The import of numba and zarr is optional to allow for flexibility in environments where these packages may not be installed.
If numba is not installed, a dummy njit decorator is provided that does nothing.
If zarr is not installed, a warning is logged and Zarr functionality is disabled.
A default logger named "patatune" is configured with a custom formatter that adds colors based on log level. (See CustomFormatter for details.)
A system-wide exception handler is set up to log uncaught exceptions using the patatune logger. (See handle_exception for details.)
Classes:
-
CustomFormatter–Custom logging formatter to add colors based on log level.
-
FileManager–File management utility class for saving and loading data in various formats.
-
Randomizer–Random number generator utility class.
Functions:
-
get_dominated–Determine which particles are dominated within a population.
-
handle_exception–Global exception handler to log uncaught exceptions.
Bases: Formatter
Custom logging formatter to add colors based on log level.
Notes
This class customizes the log format by adding color codes for different log levels. DEBUG and INFO messages are grey, WARNING messages are yellow, ERROR messages are red, and CRITICAL messages are bold red.
The log is formatted as:
%(asctime)s - %(name)s - %(levelname)s - %(message)s (%(filename)s:%(lineno)d)
For example:
2024-01-01 12:00:00,000 - patatune - WARNING - numba package is not installed. The code will run slower. (util.py:206)
File management utility class for saving and loading data in various formats.
This class provides methods to save and load data in CSV, JSON, Zarr, and Pickle formats.
Attributes:
-
saving_enabled(bool) –Global flag to enable/disable saving.
-
saving_csv_enabled(bool) –Flag to enable/disable CSV saving.
-
saving_json_enabled(bool) –Flag to enable/disable JSON saving.
-
saving_zarr_enabled(bool) –Flag to enable/disable Zarr saving.
-
saving_pickle_enabled(bool) –Flag to enable/disable Pickle saving.
-
loading_enabled(bool) –Global flag to enable/disable loading.
-
headers_enabled(bool) –Flag to enable/disable headers when saving/loading CSV files.
-
working_dir(str) –Directory where files will be saved/loaded from.
Methods:
-
load_csv–Load data from a CSV file.
-
load_json–Load a dictionary from a JSON file.
-
load_pickle–Load an object from a Pickle file.
-
save_csv–Save a list of lists or 2D array to a CSV file.
-
save_json–Save a dictionary to a JSON file.
-
save_pickle–Save an object to a Pickle file.
-
save_zarr–Save a dictionary of arrays to a Zarr file.
classmethod
load_csv(filename)
Load data from a CSV file.
The method loads data from a CSV file in the working_dir path.
If headers_enabled is True, it assumes the first row contains headers.
Parameters:
-
filename(str) –Name of the input CSV file.
Returns:
-
tuple–A tuple containing the data as a NumPy array of floats and the headers (if any) as a NumPy array of strings.
classmethod
load_json(filename)
classmethod
load_pickle(filename)
classmethod
save_csv(csv_list, filename='file.csv', headers=None)
Save a list of lists or 2D array to a CSV file.
The method saves the data to a CSV file in the working_dir path.
The CSV file is comma-separated and the data is written as floats with 18 decimal places and dot as decimal separator.
The method creates the necessary directories if they do not exist.
If headers are provided and headers_enabled is True, they will be written as the first row.
Parameters:
classmethod
save_json(dictionary, filename)
classmethod
save_pickle(obj, filename)
classmethod
save_zarr(obj, filename, **kwargs)
Save a dictionary of arrays to a Zarr file.
The method saves a dictionary of arrays to a Zarr file in the working_dir path.
It creates the necessary directories if they do not exist.
The keys of the dictionary are used as group names in the Zarr file.
If a key is an integer, it is prefixed with "iteration_" to form the group name.
Additional attributes can be added to the root group via kwargs.
Parameters:
Random number generator utility class.
Implements a class-level random number generator using NumPy's default_rng.
This class provides a shared random number generator that can be used throughout the package.
Can be accessed via Randomizer.rng.
For example, to set a seed:
Randomizer.rng = np.random.default_rng(seed=42)
get_dominated(particles, pareto_length)
Determine which particles are dominated within a population.
A particle is considered dominated if there exists at least one other particle that is better or equal in all objectives and strictly better in at least one objective.
Parameters:
-
particles(ndarray) –2-D array of objective values for each particle (shape: [n_particles, n_objectives]).
-
pareto_length(int) –Number of particles considered part of the current Pareto set (these are skipped in comparisons).
Returns:
-
ndarray–Boolean array of length
len(particles)where True means the particle is dominated by at least one other particle.
Notes
The function is decorated with a (possible) njit to allow optional numba acceleration.
handle_exception(exc_type, exc_value, exc_traceback)