Batch fitness evaluator#

class pygmo.bfe(udbfe=default_bfe())#

Batch fitness evaluator.

This class implements the evaluation of decision vectors in batch mode. That is, whereas a pygmo.problem provides the means to evaluate a single decision vector via the pygmo.problem.fitness() method, a bfe (short for batch fitness evaluator) enables a problem to evaluate the fitnesses of a group (or a batch) of decision vectors, possibly in a parallel/vectorised fashion.

Together with the pygmo.problem.batch_fitness() method, bfe is one of the mechanisms provided by pagmo to enable a form of parallelism on a finer level than the archipelago and island classes. However, while the pygmo.problem.batch_fitness() method must be implemented on a UDP-by-UDP basis, a bfe provides generic batch fitness evaluation capabilities for any problem, and it can thus be used also with UDPs which do not implement the pygmo.problem.batch_fitness() method.

Like problem, algorithm, and many other pagmo classes, bfe is a generic container which stores internally a user-defined batch fitness evaluator (UDBFE for short) which actually implements the fitness evaluation in batch mode. Users are free to either use one of the evaluators provided with pagmo, or to write their own UDBFE.

Every UDBFE must be a callable (i.e., a function or a class with a call operator) with a signature equivalent to

def __call__(self, prob, dvs):
  ...

UDBFEs receive in input a problem and a batch of decision vectors stored contiguously in an array-like object, and they return a NumPy array containing the fitness vectors corresponding to the input batch of decision vectors (as evaluated by the input problem and stored contiguously).

UDBFEs can also implement the following (optional) methods:

def get_name(self):
  ...
def get_extra_info(self):
  ...

See the documentation of the corresponding methods in this class for details on how the optional methods in the UDBFE are used by bfe.

This class is the Python counterpart of the C++ class pagmo::bfe.

Parameters

udbfe – a user-defined batch fitness evaluator, either C++ or Python

Raises

  • NotImplementedError – if udbfe does not implement the mandatory methods detailed above

  • unspecified – any exception thrown by methods of the UDBFE invoked during construction, the deep copy of the UDBFE, the constructor of the underlying C++ class, or failures at the intersection between C++ and Python (e.g., type conversion errors, mismatched function signatures, etc.)

__call__(prob, dvs)#

Call operator.

The call operator will invoke the internal UDBFE instance to perform the evaluation in batch mode of the decision vectors stored in dvs using the input problem or UDP prob, and it will return the corresponding fitness vectors.

The input decision vectors must be stored contiguously in dvs: for a problem with dimension \(n\), the first decision vector in dvs occupies the index range \(\left[0, n\right)\), the second decision vector occupies the range \(\left[n, 2n\right)\), and so on. Similarly, the output fitness vectors must be laid out contiguously in the return value: for a problem with fitness dimension \(f\), the first fitness vector will occupy the index range \(\left[0, f\right)\), the second fitness vector will occupy the range \(\left[f, 2f\right)\), and so on.

This function will perform a variety of sanity checks on both dvs and on the return value.

Parameters

  • prob (problem or a UDP) – the input problem

  • dvs (array-like object) – the input decision vectors that will be evaluated in batch mode

Returns

the fitness vectors corresponding to the input decision vectors in dvs

Return type

1D NumPy float array

Raises

  • ValueError – if dvs or the return value produced by the UDBFE are incompatible with the input problem prob

  • unspecified – any exception raised by the invocation of the UDBFE, or by failures at the intersection between C++ and Python (e.g., type conversion errors, mismatched function signatures, etc.)

__init__()#
__repr__()#

Return repr(self).

extract(t)#

Extract the user-defined batch fitness evaluator (bfe).

This method allows to extract a reference to the user-defined bfe (UDBFE) stored within this bfe instance. The behaviour of this function depends on the value of t (which must be a type) and on the type of the internal UDBFE:

  • if the type of the UDBFE is t, then a reference to the UDBFE will be returned (this mirrors the behaviour of the corresponding C++ method pagmo::bfe::extract()),

  • if t is object and the UDBFE is a Python object (as opposed to an exposed C++ bfe), then a reference to the UDBFE will be returned (this allows to extract a Python UDBFE without knowing its type),

  • otherwise, None will be returned.

Parameters

t (type) – the type of the user-defined bfe to extract

Returns

a reference to the internal user-defined bfe, or None if the extraction fails

Raises

TypeError – if t is not a type

Examples

>>> import pygmo as pg
>>> a1 = pg.bfe(pg.thread_bfe())
>>> a1.extract(pg.thread_bfe) 
<pygmo.core.thread_bfe at 0x7f8e4792b670>
>>> a1.extract(pg.member_bfe) is None
True
>>> def custom_bfe(p, dvs): pass
>>> a2 = pg.bfe(custom_bfe)
>>> a2.extract(object) 
<__main__.custom_bfe at 0x7f8e478c04e0>
>>> a2.extract(custom_bfe) 
<__main__.custom_bfe at 0x7f8e478c04e0>
>>> a2.extract(pg.thread_bfe) is None
True
get_extra_info()#

Bfe’s extra info.

If the UDBFE provides a get_extra_info() method, then this method will return the output of its get_extra_info() method. Otherwise, an empty string will be returned.

Returns

extra info about the UDBFE

Return type

str

Raises

unspecified – any exception thrown by the get_extra_info() method of the UDBFE

get_name()#

Bfe’s name.

If the UDBFE provides a get_name() method, then this method will return the output of its get_name() method. Otherwise, an implementation-defined name based on the type of the UDBFE will be returned.

Returns

the bfe’s name

Return type

str

get_thread_safety()#

Bfe’s thread safety level.

This method will return a value of the enum pygmo.thread_safety which indicates the thread safety level of the UDBFE. Unlike in C++, in Python it is not possible to re-implement this method in the UDBFE. That is, for C++ UDBFEs, the returned value will be the value returned by the get_thread_safety() method of the UDBFE. For Python UDBFEs, the returned value will be unconditionally none.

Returns

the thread safety level of the UDBFE

Return type

a value of pygmo.thread_safety

is_(t)#

Check the type of the user-defined batch fitness evaluator.

This method returns False if extract(t) returns None, and True otherwise.

Parameters

t (type) – the type that will be compared to the type of the UDBFE

Returns

whether the UDBFE is of type t or not

Return type

bool

Raises

unspecified – any exception thrown by extract()