coco.h File Reference

All public COCO functions, constants and variables are defined in this file. More...

#include <stddef.h>
#include <stdint.h>
#include <math.h>
#include <float.h>

Go to the source code of this file.

Macros
#define	NAN   8.8888e88
	Definition of NAN to be used only if undefined by the included headers. More...
#define	isnan(x)   (0)
	Definition of isnan to be used only if undefined by the included headers. More...
#define	INFINITY   1e22
	Definition of INFINITY to be used only if undefined by the included headers. More...
#define	isinf(x)   (0)
	Definition of isinf to be used only if undefined by the included headers. More...

Typedefs
typedef struct coco_problem_s	coco_problem_t
	The COCO problem type. More...
typedef struct coco_suite_s	coco_suite_t
	The COCO suite type. More...
typedef struct coco_observer_s	coco_observer_t
	The COCO observer type. More...
typedef struct coco_archive_s	coco_archive_t
	The COCO archive type. More...
typedef struct coco_random_state_s	coco_random_state_t
	The COCO random state type. More...

Enumerations
enum	coco_log_level_type_e { COCO_ERROR, COCO_WARNING, COCO_INFO, COCO_DEBUG }
	Logging level type. More...

Functions
Methods regarding COCO suite
coco_suite_t *	coco_suite (const char *suite_name, const char *suite_instance, const char *suite_options)
	Constructs a COCO suite. More...
void	coco_suite_free (coco_suite_t *suite)
	Frees the given suite. More...
coco_problem_t *	coco_suite_get_next_problem (coco_suite_t *suite, coco_observer_t *observer)
	Returns the next (observed) problem of the suite or NULL if there is no next problem left. More...
coco_problem_t *	coco_suite_get_problem (coco_suite_t *suite, const size_t problem_index)
	Returns the problem of the suite defined by problem_index. More...
coco_problem_t *	coco_suite_get_problem_by_function_dimension_instance (coco_suite_t *suite, const size_t function, const size_t dimension, const size_t instance)
	Returns the first problem of the suite defined by function, dimension and instance numbers. More...
size_t	coco_suite_get_number_of_problems (const coco_suite_t *suite)
	Returns the number of problems in the given suite. More...
size_t	coco_suite_get_function_from_function_index (const coco_suite_t *suite, const size_t function_idx)
	Returns the function number in the suite in position function_idx (counting from 0). More...
size_t	coco_suite_get_dimension_from_dimension_index (const coco_suite_t *suite, const size_t dimension_idx)
	Returns the dimension number in the suite in position dimension_idx (counting from 0). More...
size_t	coco_suite_get_instance_from_instance_index (const coco_suite_t *suite, const size_t instance_idx)
	Returns the instance number in the suite in position instance_idx (counting from 0). More...
Encoding/decoding problem index
General schema for encoding/decoding a problem index. Note that the index depends on the number of instances a suite is defined with (it should be called a suite-instance-depending index...). Also, while functions, instances and dimensions start from 1, function_idx, instance_idx and dimension_idx as well as suite_dep_index start from 0! Showing an example with 2 dimensions (2, 3), 5 instances (6, 7, 8, 9, 10) and 2 functions (1, 2): index | instance | function | dimension ------+----------+----------+----------- 0 | 6 | 1 | 2 1 | 7 | 1 | 2 2 | 8 | 1 | 2 3 | 9 | 1 | 2 4 | 10 | 1 | 2 5 | 6 | 2 | 2 6 | 7 | 2 | 2 7 | 8 | 2 | 2 8 | 9 | 2 | 2 9 | 10 | 2 | 2 10 | 6 | 1 | 3 11 | 7 | 1 | 3 12 | 8 | 1 | 3 13 | 9 | 1 | 3 14 | 10 | 1 | 3 15 | 6 | 2 | 2 16 | 7 | 2 | 3 17 | 8 | 2 | 3 18 | 9 | 2 | 3 19 | 10 | 2 | 3 index | instance_idx | function_idx | dimension_idx ------+--------------+--------------+--------------- 0 | 0 | 0 | 0 1 | 1 | 0 | 0 2 | 2 | 0 | 0 3 | 3 | 0 | 0 4 | 4 | 0 | 0 5 | 0 | 1 | 0 6 | 1 | 1 | 0 7 | 2 | 1 | 0 8 | 3 | 1 | 0 9 | 4 | 1 | 0 10 | 0 | 0 | 1 11 | 1 | 0 | 1 12 | 2 | 0 | 1 13 | 3 | 0 | 1 14 | 4 | 0 | 1 15 | 0 | 1 | 1 16 | 1 | 1 | 1 17 | 2 | 1 | 1 18 | 3 | 1 | 1 19 | 4 | 1 | 1
size_t	coco_suite_encode_problem_index (const coco_suite_t *suite, const size_t function_idx, const size_t dimension_idx, const size_t instance_idx)
	Computes the index of the problem in the suite that corresponds to the given function, dimension and instance indices. More...
void	coco_suite_decode_problem_index (const coco_suite_t *suite, const size_t problem_index, size_t *function_idx, size_t *dimension_idx, size_t *instance_idx)
	Computes the function, dimension and instance indexes of the problem with problem_index in the given suite. More...
Methods regarding COCO observer
coco_observer_t *	coco_observer (const char *observer_name, const char *options)
	Constructs a COCO observer. More...
void	coco_observer_free (coco_observer_t *observer)
	Frees the given observer. More...
coco_problem_t *	coco_problem_add_observer (coco_problem_t *problem, coco_observer_t *observer)
	Adds an observer to the given problem. More...
coco_problem_t *	coco_problem_remove_observer (coco_problem_t *problem, coco_observer_t *observer)
	Removes an observer from the given problem. More...
const char *	coco_observer_get_result_folder (const coco_observer_t *observer)
	Returns result folder name, where logger output is written. More...
Methods regarding COCO problem
void	coco_evaluate_function (coco_problem_t *problem, const double *x, double *y)
	Evaluates the problem function in point x and save the result in y. More...
void	coco_evaluate_constraint (coco_problem_t *problem, const double *x, double *y)
	Evaluates the problem constraints in point x and save the result in y. More...
void	coco_recommend_solution (coco_problem_t *problem, const double *x)
	Recommends a solution as the current best guesses to the problem. Not implemented yet. More...
void	coco_problem_free (coco_problem_t *problem)
	Frees the given problem. More...
const char *	coco_problem_get_name (const coco_problem_t *problem)
	Returns the name of the problem. More...
const char *	coco_problem_get_id (const coco_problem_t *problem)
	Returns the ID of the problem. More...
const char *	coco_problem_get_type (const coco_problem_t *problem)
	Returns the type of the problem. More...
size_t	coco_problem_get_dimension (const coco_problem_t *problem)
	Returns the number of variables i.e. the dimension of the problem. More...
size_t	coco_problem_get_number_of_objectives (const coco_problem_t *problem)
	Returns the number of objectives of the problem. More...
size_t	coco_problem_get_number_of_constraints (const coco_problem_t *problem)
	Returns the number of constraints of the problem. More...
size_t	coco_problem_get_evaluations (const coco_problem_t *problem)
	Returns the number of objective function evaluations done on the problem. More...
size_t	coco_problem_get_evaluations_constraints (const coco_problem_t *problem)
	Returns the number of constraint function evaluations done on the problem. More...
int	coco_problem_final_target_hit (const coco_problem_t *problem)
	Returns 1 if the final target was hit, 0 otherwise. More...
double	coco_problem_get_best_observed_fvalue1 (const coco_problem_t *problem)
	Returns the best observed value for the first objective. More...
double	depreciated_coco_problem_get_final_target_fvalue1 (const coco_problem_t *problem)
	Returns the target value for the first objective. More...
const double *	coco_problem_get_smallest_values_of_interest (const coco_problem_t *problem)
	Returns a vector of size 'dimension' with lower bounds of the region of interest in the decision space. More...
const double *	coco_problem_get_largest_values_of_interest (const coco_problem_t *problem)
	Returns a vector of size 'dimension' with upper bounds of the region of interest in the decision space. More...
size_t	coco_problem_get_number_of_integer_variables (const coco_problem_t *problem)
	Returns the number of integer variables. If > 0, all integer variables come before any continuous ones. More...
const double *	coco_problem_get_largest_fvalues_of_interest (const coco_problem_t *problem)
	For multi-objective problems, returns a vector of largest values of interest in each objective. Currently, this equals the nadir point. For single-objective problems it raises an error. More...
size_t	coco_problem_get_suite_dep_index (const coco_problem_t *problem)
	Returns the problem_index of the problem in its current suite. More...
void	coco_problem_get_initial_solution (const coco_problem_t *problem, double *initial_solution)
	Returns an initial solution, i.e. a feasible variable setting, to the problem. More...
Methods regarding random numbers
coco_random_state_t *	coco_random_new (uint32_t seed)
	Creates and returns a new random number state using the given seed. More...
void	coco_random_free (coco_random_state_t *state)
	Frees all memory associated with the random state. More...
double	coco_random_uniform (coco_random_state_t *state)
	Returns one uniform [0, 1) random value from the random number generator associated with the given state. More...
double	coco_random_normal (coco_random_state_t *state)
	Generates an approximately normal random number. More...
Methods managing memory
void *	coco_allocate_memory (const size_t size)
	Safe memory allocation that either succeeds or triggers a coco_error. More...
double *	coco_allocate_vector (const size_t size)
	Safe memory allocation for a vector of doubles that either succeeds or triggers a coco_error. More...
void	coco_free_memory (void *data)
	Frees the allocated memory. More...
Methods regarding COCO messages
void	coco_error (const char *message,...)
	Signals a fatal error. More...
void	coco_warning (const char *message,...)
	Warns about error conditions. More...
void	coco_info (const char *message,...)
	Outputs some information. More...
void	coco_info_partial (const char *message,...)
	Prints only the given message without any prefix and new line. More...
void	coco_debug (const char *message,...)
	Outputs detailed information usually used for debugging. More...
const char *	coco_set_log_level (const char *level)
	Sets the COCO log level to the given value and returns the previous value of the log level. More...
Methods regarding COCO archives and log files (used when pre-processing MO data)
coco_archive_t *	coco_archive (const char *suite_name, const size_t function, const size_t dimension, const size_t instance)
	Constructs a COCO archive. More...
int	coco_archive_add_solution (coco_archive_t *archive, const double y1, const double y2, const char *text)
	Adds a solution with objectives (y1, y2) to the archive if none of the existing solutions in the archive dominates it. In this case, returns 1, otherwise the archive is not updated and the method returns 0. More...
size_t	coco_archive_get_number_of_solutions (coco_archive_t *archive)
	Returns the number of (non-dominated) solutions in the archive (computed first, if needed). More...
double	coco_archive_get_hypervolume (coco_archive_t *archive)
	Returns the hypervolume of the archive (computed first, if needed). More...
const char *	coco_archive_get_next_solution_text (coco_archive_t *archive)
	Returns the text of the next (non-dominated) solution in the archive and "" when there are no solutions left. The first two solutions are always the extreme ones. More...
void	coco_archive_free (coco_archive_t *archive)
	Frees the archive. More...
int	coco_logger_biobj_feed_solution (coco_problem_t *problem, const size_t evaluation, const double *y)
	Feeds the solution to the bi-objective logger for logger output reconstruction purposes. More...
Other useful methods
int	coco_remove_directory (const char *path)
	Removes the given directory and all its contents. More...
char *	coco_strdupf (const char *str,...)
	Formatted string duplication. More...

Variables
static const char	coco_version [32] = "$COCO_VERSION"
	COCO's version. More...
static const double	coco_pi = 3.14159265358979323846
	COCO's own pi constant. Simplifies the case, when the value of pi changes. More...
static const double	coco_two_pi = 2.0 * 3.14159265358979323846
	COCO's own pi constant. Simplifies the case, when the value of pi changes. More...

Detailed Description

All public COCO functions, constants and variables are defined in this file.

It is the authoritative reference, if any function deviates from the documented behavior it is considered a bug. See the function definitions for their detailed descriptions.

Macro Definition Documentation

#define INFINITY   1e22

Definition of INFINITY to be used only if undefined by the included headers.

#define isinf

(

x

)

(0)

Definition of isinf to be used only if undefined by the included headers.

#define isnan

(

x

)

(0)

Definition of isnan to be used only if undefined by the included headers.

#define NAN   8.8888e88

Definition of NAN to be used only if undefined by the included headers.

Typedef Documentation

typedef struct coco_archive_s coco_archive_t

The COCO archive type.

See coco_archive_s for more information on its fields.

typedef struct coco_observer_s coco_observer_t

The COCO observer type.

See coco_observer_s for more information on its fields.

typedef struct coco_problem_s coco_problem_t

The COCO problem type.

See coco_problem_s for more information on its fields.

typedef struct coco_random_state_s coco_random_state_t

The COCO random state type.

See coco_random_state_s for more information on its fields.

typedef struct coco_suite_s coco_suite_t

The COCO suite type.

See coco_suite_s for more information on its fields.

Enumeration Type Documentation

enum coco_log_level_type_e

Logging level type.

Enumerator
COCO_ERROR	only error messages are output
COCO_WARNING	error and warning messages are output
COCO_INFO	error, warning and info messages are output
COCO_DEBUG	error, warning, info and debug messages are output

Function Documentation

void* coco_allocate_memory

(

const size_t

size

)

Safe memory allocation that either succeeds or triggers a coco_error.

double* coco_allocate_vector

(

const size_t

size

)

Safe memory allocation for a vector of doubles that either succeeds or triggers a coco_error.

coco_archive_t* coco_archive	(	const char *	suite_name,
		const size_t	function,
		const size_t	dimension,
		const size_t	instance
	)

Constructs a COCO archive.

The archive always contains the two extreme solutions

int coco_archive_add_solution	(	coco_archive_t *	archive,
		const double	y1,
		const double	y2,
		const char *	text
	)

Adds a solution with objectives (y1, y2) to the archive if none of the existing solutions in the archive dominates it. In this case, returns 1, otherwise the archive is not updated and the method returns 0.

void coco_archive_free

(

coco_archive_t *

archive

)

Frees the archive.

double coco_archive_get_hypervolume

(

coco_archive_t *

archive

)

Returns the hypervolume of the archive (computed first, if needed).

const char* coco_archive_get_next_solution_text

(

coco_archive_t *

archive

)

Returns the text of the next (non-dominated) solution in the archive and "" when there are no solutions left. The first two solutions are always the extreme ones.

size_t coco_archive_get_number_of_solutions

(

coco_archive_t *

archive

)

Returns the number of (non-dominated) solutions in the archive (computed first, if needed).

void coco_debug	(	const char *	message,
			...
	)

Outputs detailed information usually used for debugging.

void coco_error	(	const char *	message,
			...
	)

Signals a fatal error.

void coco_evaluate_constraint	(	coco_problem_t *	problem,
		const double *	x,
		double *	y
	)

Evaluates the problem constraints in point x and save the result in y.

Evaluates the problem constraint.

Note

Both x and y must point to correctly sized allocated memory regions.

Parameters

problem	The given COCO problem.
x	The decision vector.
y	The vector of constraints that is the result of the evaluation.

void coco_evaluate_function	(	coco_problem_t *	problem,
		const double *	x,
		double *	y
	)

Evaluates the problem function in point x and save the result in y.

Evaluates the problem function, increases the number of evaluations and updates the best observed value and the best observed evaluation number.

Note

Both x and y must point to correctly sized allocated memory regions.

Parameters

problem	The given COCO problem.
x	The decision vector.
y	The objective vector that is the result of the evaluation (in single-objective problems only the first vector item is being set).

void coco_free_memory

(

void *

data

)

Frees the allocated memory.

void coco_info	(	const char *	message,
			...
	)

Outputs some information.

void coco_info_partial	(	const char *	message,
			...
	)

Prints only the given message without any prefix and new line.

A function similar to coco_info but producing no additional text than the given message.

The output is only produced if coco_log_level >= COCO_INFO.

A function similar to coco_info that prints only the given message without any prefix and without adding a new line.

int coco_logger_biobj_feed_solution	(	coco_problem_t *	problem,
		const size_t	evaluation,
		const double *	y
	)

Feeds the solution to the bi-objective logger for logger output reconstruction purposes.

Sets the number of evaluations, adds the objective vector to the archive and outputs information according to observer options (but does not output the archive).

Note

Vector y must point to a correctly sized allocated memory region and the given evaluation number must be larger than the existing one.

Parameters

problem	The given COCO problem.
evaluation	The number of evaluations.
y	The objective vector.

Returns

1 if archive was updated was done and 0 otherwise.

coco_observer_t* coco_observer	(	const char *	observer_name,
		const char *	observer_options
	)

Constructs a COCO observer.

Currently, three observers are supported:

• "bbob" is the observer for single-objective (both noisy and noiseless) problems with known optima, which creates *.info, *.dat, *.tdat and *.rdat files and logs the distance to the optimum.
• "bbob-biobj" is the observer for bi-objective problems, which creates *.info, *.dat and *.tdat files for the given indicators, as well as an archive folder with *.adat files containing nondominated solutions.
• "toy" is a simple observer that logs when a target has been hit.

Parameters

observer_name

A string containing the name of the observer. Currently supported observer names are "bbob", "bbob-biobj", "toy". Strings "no_observer", "" or NULL return NULL.

observer_options

A string of pairs "key: value" used to pass the options to the observer. Some observer options are general, while others are specific to some observers. Here we list only the general options, see observer_bbob, observer_biobj and observer_toy for options of the specific observers. "result_folder: NAME" determines the folder within the "exdata" folder into which the results will be output. If the folder with the given name already exists, first NAME_001 will be tried, then NAME_002 and so on. The default value is "default". "algorithm_name: NAME", where NAME is a short name of the algorithm that will be used in plots (no spaces are allowed). The default value is "ALG". "algorithm_info: STRING" stores the description of the algorithm. If it contains spaces, it must be surrounded by double quotes. The default value is "" (no description). "number_target_triggers: VALUE" defines the number of targets between each 10**i and 10**(i+1) (equally spaced in the logarithmic scale) that trigger logging. The default value is 100. "target_precision: VALUE" defines the precision used for targets (there are no targets for abs(values) < target_precision). The default value is 1e-8. "number_evaluation_triggers: VALUE" defines the number of evaluations to be logged between each 10**i and 10**(i+1). The default value is 20. "base_evaluation_triggers: VALUES" defines the base evaluations used to produce an additional evaluation-based logging. The numbers of evaluations that trigger logging are every base_evaluation * dimension * (10**i). For example, if base_evaluation_triggers = "1,2,5", the logger will be triggered by evaluations dim*1, dim*2, dim*5, 10*dim*1, 10*dim*2, 10*dim*5, 100*dim*1, 100*dim*2, 100*dim*5, ... The default value is "1,2,5". "precision_x: VALUE" defines the precision used when outputting variables and corresponds to the number of digits to be printed after the decimal point. The default value is 8. "precision_f: VALUE" defines the precision used when outputting f values and corresponds to the number of digits to be printed after the decimal point. The default value is 15. "precision_g: VALUE" defines the precision used when outputting constraints and corresponds to the number of digits to be printed after the decimal point. The default value is 3. "log_discrete_as_int: VALUE" determines whether the values of integer variables (in mixed-integer problems) are logged as integers (1) or not (0 - in this case they are logged as doubles). The default value is 0.

Returns

The constructed observer object or NULL if observer_name equals NULL, "" or "no_observer".

void coco_observer_free

(

coco_observer_t *

observer

)

Frees the given observer.

const char* coco_observer_get_result_folder

(

const coco_observer_t *

observer

)

Returns result folder name, where logger output is written.

Get the result folder name, which is a unique folder name constructed from the result_folder option.

Parameters

observer

The COCO observer, whose logger may be wrapping a problem.

Returns

The result folder name, where the logger writes its output.

coco_problem_t* coco_problem_add_observer	(	coco_problem_t *	problem,
		coco_observer_t *	observer
	)

Adds an observer to the given problem.

Wraps the observer's logger around the problem if the observer is not NULL and invokes the initialization of this logger.

Parameters

problem	The given COCO problem.
observer	The COCO observer, whose logger will wrap the problem.

Returns

The observed problem in the form of a new COCO problem instance or the same problem if the observer is NULL.

int coco_problem_final_target_hit

(

const coco_problem_t *

problem

)

Returns 1 if the final target was hit, 0 otherwise.

Note

Can be used to prevent unnecessary burning of CPU time.

void coco_problem_free

(

coco_problem_t *

problem

)

Frees the given problem.

double coco_problem_get_best_observed_fvalue1

(

const coco_problem_t *

problem

)

Returns the best observed value for the first objective.

Note

Tentative...

size_t coco_problem_get_dimension

(

const coco_problem_t *

problem

)

Returns the number of variables i.e. the dimension of the problem.

size_t coco_problem_get_evaluations

(

const coco_problem_t *

problem

)

Returns the number of objective function evaluations done on the problem.

size_t coco_problem_get_evaluations_constraints

(

const coco_problem_t *

problem

)

Returns the number of constraint function evaluations done on the problem.

const char* coco_problem_get_id

(

const coco_problem_t *

problem

)

Returns the ID of the problem.

The ID is guaranteed to contain only characters in the set [a-z0-9_-]. It should therefore be safe to use it to construct filenames or other identifiers.

Each problem ID should be unique within each benchmark suite.

Note

Do not modify the returned string! If you free the problem, the returned pointer becomes invalid. When in doubt, use coco_strdup() on the returned value.

void coco_problem_get_initial_solution	(	const coco_problem_t *	problem,
		double *	initial_solution
	)

Returns an initial solution, i.e. a feasible variable setting, to the problem.

Copies problem->initial_solution into initial_solution if not null, otherwise the center of the problem's region of interest is the initial solution. Takes care of rounding the solution in case of integer variables.

Parameters

problem	The given COCO problem.
initial_solution	The pointer to the initial solution being set by this method.

const double* coco_problem_get_largest_fvalues_of_interest

(

const coco_problem_t *

problem

)

For multi-objective problems, returns a vector of largest values of interest in each objective. Currently, this equals the nadir point. For single-objective problems it raises an error.

const double* coco_problem_get_largest_values_of_interest

(

const coco_problem_t *

problem

)

Returns a vector of size 'dimension' with upper bounds of the region of interest in the decision space.

const char* coco_problem_get_name

(

const coco_problem_t *

problem

)

Returns the name of the problem.

Note

Do not modify the returned string! If you free the problem, the returned pointer becomes invalid. When in doubt, use coco_strdup() on the returned value.

size_t coco_problem_get_number_of_constraints

(

const coco_problem_t *

problem

)

Returns the number of constraints of the problem.

size_t coco_problem_get_number_of_integer_variables

(

const coco_problem_t *

problem

)

Returns the number of integer variables. If > 0, all integer variables come before any continuous ones.

size_t coco_problem_get_number_of_objectives

(

const coco_problem_t *

problem

)

Returns the number of objectives of the problem.

const double* coco_problem_get_smallest_values_of_interest

(

const coco_problem_t *

problem

)

Returns a vector of size 'dimension' with lower bounds of the region of interest in the decision space.

size_t coco_problem_get_suite_dep_index

(

const coco_problem_t *

problem

)

Returns the problem_index of the problem in its current suite.

const char* coco_problem_get_type

(

const coco_problem_t *

problem

)

Returns the type of the problem.

coco_problem_t* coco_problem_remove_observer	(	coco_problem_t *	problem,
		coco_observer_t *	observer
	)

Removes an observer from the given problem.

Frees the observer's logger and returns the inner problem.

Parameters

problem	The observed COCO problem.
observer	The COCO observer, whose logger was wrapping the problem.

Returns

The unobserved problem as a pointer to the inner problem or the same problem if the problem was not observed.

void coco_random_free

(

coco_random_state_t *

state

)

Frees all memory associated with the random state.

coco_random_state_t* coco_random_new

(

uint32_t

seed

)

Creates and returns a new random number state using the given seed.

double coco_random_normal

(

coco_random_state_t *

state

)

Generates an approximately normal random number.

Instead of using the (expensive) polar method, we may cheat and abuse the central limit theorem. The sum of 12 uniform random values has mean 6, variance 1 and is approximately normal. Subtract 6 and you get an approximately N(0, 1) random number.

double coco_random_uniform

(

coco_random_state_t *

state

)

Returns one uniform [0, 1) random value from the random number generator associated with the given state.

void coco_recommend_solution	(	coco_problem_t *	problem,
		const double *	x
	)

Recommends a solution as the current best guesses to the problem. Not implemented yet.

Evaluates and logs the given solution (as the coco_evaluate_function), but does not return the evaluated value.

Note

None of the observers implements this function yet!

x must point to a correctly sized allocated memory region.

Parameters

problem	The given COCO problem.
x	The decision vector.

int coco_remove_directory

(

const char *

path

)

Removes the given directory and all its contents.

The method should work across different platforms/compilers.

The path to the directory

Returns

0 on successful completion, and -1 on error.

const char* coco_set_log_level

(

const char *

log_level

)

Sets the COCO log level to the given value and returns the previous value of the log level.

Parameters

log_level

Denotes the level of information given to the user through the standard output and error streams. Can take on the values: "error" (only error messages are output), "warning" (only error and warning messages are output), "info" (only error, warning and info messages are output) and "debug" (all messages are output). "" does not set a new value The default value is info.

Returns

The previous coco_log_level value as an immutable string.

char* coco_strdupf	(	const char *	str,
			...
	)

Formatted string duplication.

Optional arguments are used like in sprintf.

coco_suite_t* coco_suite	(	const char *	suite_name,
		const char *	suite_instance,
		const char *	suite_options
	)

Constructs a COCO suite.

Currently, seven suites are supported:

• "bbob" contains 24 single-objective functions in 6 dimensions (2, 3, 5, 10, 20, 40)
• "bbob-biobj" contains 55 bi-objective functions in 6 dimensions (2, 3, 5, 10, 20, 40)
• "bbob-biobj-ext" as an extension of "bbob-biobj" contains 92 bi-objective functions in 6 dimensions (2, 3, 5, 10, 20, 40)
• "bbob-largescale" contains 24 single-objective functions in 6 large dimensions (40, 80, 160, 320, 640, 1280)
• "bbob-constrained" contains 48 linearly-constrained problems, which are combinations of 8 single objective functions with 6 different numbers of linear constraints (1, 2, 10, dimension/2, dimension-1, dimension+1), in 6 dimensions (2, 3, 5, 10, 20, 40).
• "bbob-mixint" contains mixed-integer single-objective functions in 6 dimensions (2, 3, 5, 10, 20, 40)
• "bbob-biobj-mixint" contains 92 mixed-integer bi-objective functions in 6 dimensions (2, 3, 5, 10, 20, 40)
• "toy" contains 6 single-objective functions in 5 dimensions (2, 3, 5, 10, 20)

Only the suite_name parameter needs to be non-empty. The suite_instance and suite_options can be "" or NULL. In this case, default values are taken (default instances of a suite are those used in the last year and the suite is not filtered by default).

Parameters

suite_name	A string containing the name of the suite. Currently supported suite names are "bbob", "bbob-biobj", "bbob-biobj-ext", "bbob-largescale", "bbob-constrained", and "toy".
suite_instance	A string used for defining the suite instances. Two ways are supported: "year: YEAR", where YEAR is the year of the BBOB workshop, includes the instances (to be) used in that year's workshop; "instances: VALUES", where VALUES are instance numbers from 1 on written as a comma-separated list or a range m-n.
suite_options	A string of pairs "key: value" used to filter the suite (especially useful for parallelizing the experiments). Supported options: "dimensions: LIST", where LIST is the list of dimensions to keep in the suite (range-style syntax is not allowed here), "dimension_indices: VALUES", where VALUES is a list or a range of dimension indices (starting from 1) to keep in the suite, and "function_indices: VALUES", where VALUES is a list or a range of function indices (starting from 1) to keep in the suite, and "instance_indices: VALUES", where VALUES is a list or a range of instance indices (starting from 1) to keep in the suite.

Returns

The constructed suite object.

void coco_suite_decode_problem_index	(	const coco_suite_t *	suite,
		const size_t	problem_index,
		size_t *	function_idx,
		size_t *	dimension_idx,
		size_t *	instance_idx
	)

Computes the function, dimension and instance indexes of the problem with problem_index in the given suite.

Parameters

suite	The suite.
problem_index	Index of the problem in the suite (starting with 0).
function_idx	Pointer to the index of the function, which is set by this function.
dimension_idx	Pointer to the index of the dimension, which is set by this function.
instance_idx	Pointer to the index of the instance, which is set by this function.

size_t coco_suite_encode_problem_index	(	const coco_suite_t *	suite,
		const size_t	function_idx,
		const size_t	dimension_idx,
		const size_t	instance_idx
	)

Computes the index of the problem in the suite that corresponds to the given function, dimension and instance indices.

Parameters

suite	The suite.
function_idx	Index of the function (starting with 0).
dimension_idx	Index of the dimension (starting with 0).
instance_idx	Index of the instance (starting with 0).

Returns

The problem index in the suite computed from function_idx, dimension_idx and instance_idx.

void coco_suite_free

(

coco_suite_t *

suite

)

Frees the given suite.

size_t coco_suite_get_dimension_from_dimension_index	(	const coco_suite_t *	suite,
		const size_t	dimension_idx
	)

Returns the dimension number in the suite in position dimension_idx (counting from 0).

Parameters

suite	The given suite.
dimension_idx	The index of the dimension in question (starting from 0).

Returns

The dimension number in position dimension_idx in the suite. If the dimension has been filtered out through suite_options in the coco_suite function, the result is 0.

size_t coco_suite_get_function_from_function_index	(	const coco_suite_t *	suite,
		const size_t	function_idx
	)

Returns the function number in the suite in position function_idx (counting from 0).

Parameters

suite	The given suite.
function_idx	The index of the function in question (starting from 0).

Returns

The function number in position function_idx in the suite. If the function has been filtered out through suite_options in the coco_suite function, the result is 0.

size_t coco_suite_get_instance_from_instance_index	(	const coco_suite_t *	suite,
		const size_t	instance_idx
	)

Returns the instance number in the suite in position instance_idx (counting from 0).

Parameters

suite	The given suite.
instance_idx	The index of the instance in question (starting from 0).

Returns

The instance number in position instance_idx in the suite. If the instance has been filtered out through suite_options in the coco_suite function, the result is 0.

coco_problem_t* coco_suite_get_next_problem	(	coco_suite_t *	suite,
		coco_observer_t *	observer
	)

Returns the next (observed) problem of the suite or NULL if there is no next problem left.

Iterates through the suite first by instances, then by functions and finally by dimensions. The instances/functions/dimensions that have been filtered out using the suite_options of the coco_suite function are skipped. Outputs some information regarding the current place in the iteration. The returned problem is wrapped with the observer. If the observer is NULL, the returned problem is unobserved.

Parameters

suite	The given suite.
observer	The observer used to wrap the problem. If NULL, the problem is returned unobserved.

Returns

The next problem of the suite or NULL if there is no next problem left.

size_t coco_suite_get_number_of_problems

(

const coco_suite_t *

suite

)

Returns the number of problems in the given suite.

The number of problems in the suite is computed as a product of the number of instances, number of functions and number of dimensions and therefore doesn't account for any filtering done through the suite_options parameter of the coco_suite function.

Parameters

suite

The given suite.

Returns

The number of problems in the suite.

coco_problem_t* coco_suite_get_problem	(	coco_suite_t *	suite,
		const size_t	problem_index
	)

Returns the problem of the suite defined by problem_index.

Note that the problem_index depends on the number of instances a suite is defined with.

Parameters

suite	The given suite.
problem_index	The index of the problem to be returned.

Returns

The problem of the suite defined by problem_index (NULL if this problem has been filtered out from the suite).

coco_problem_t* coco_suite_get_problem_by_function_dimension_instance	(	coco_suite_t *	suite,
		const size_t	function,
		const size_t	dimension,
		const size_t	instance
	)

Returns the first problem of the suite defined by function, dimension and instance numbers.

Note

: While a suite can contain multiple problems with equal function, dimension and instance, this function always returns the first problem in the suite with the given function, dimension and instance values. If the given values don't correspond to a problem, the function returns NULL.

void coco_warning	(	const char *	message,
			...
	)

Warns about error conditions.

double depreciated_coco_problem_get_final_target_fvalue1

(

const coco_problem_t *

problem

)

Returns the target value for the first objective.

Variable Documentation

const double coco_pi = 3.14159265358979323846

static

COCO's own pi constant. Simplifies the case, when the value of pi changes.

const double coco_two_pi = 2.0 * 3.14159265358979323846

static

COCO's own pi constant. Simplifies the case, when the value of pi changes.

const char coco_version[32] = "$COCO_VERSION"

static

COCO's version.

Automatically updated by do.py.