Topology#

class pygmo.topology(udt=unconnected())#

Topology.

In the jargon of pagmo, a topology is an object that represents connections among islands in an archipelago. In essence, a topology is a weighted directed graph in which

  • the vertices (or nodes) are islands,

  • the edges (or arcs) are directed connections between islands across which information flows during the optimisation process (via the migration of individuals),

  • the weights of the edges (whose numerical values are the \([0.,1.]\) range) represent the migration probability.

Following the same schema adopted for problem, algorithm, etc., topology exposes a generic interface to user-defined topologies (or UDT for short). UDTs are classes providing a certain set of methods that describe the properties of (and allow to interact with) a topology. Once defined and instantiated, a UDT can then be used to construct an instance of this class, topology, which provides a generic interface to topologies for use by archipelago.

In a topology, vertices in the graph are identified by a zero-based unique integral index. This integral index corresponds to the index of an island in an archipelago.

Every UDT must implement at least the following methods:

def get_connections(self, n):
  ...
def push_back(self):
  ...

The get_connections() method takes as input a vertex index n, and it is expected to return a pair of array-like values containing respectively:

  • the indices of the vertices which are connecting to n (that is, the list of vertices for which a directed edge towards n exists),

  • the weights (i.e., the migration probabilities) of the edges linking the connecting vertices to n.

The push_back() method is expected to add a new vertex to the topology, assigning it the next available index and establishing connections to other vertices. The push_back() method is invoked by pygmo.archipelago.push_back() upon the insertion of a new island into an archipelago, and it is meant to allow the incremental construction of a topology. That is, after N calls to push_back() on an initially-empty topology, the topology should contain N vertices and any number of edges (depending on the specifics of the topology).

Additional optional methods can be implemented in a UDT:

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

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

Topologies are used in asynchronous operations involving migration in archipelagos, and thus they need to provide a certain degree of thread safety. Specifically, the get_connections() method of the UDT might be invoked concurrently with any other method of the UDT interface. It is up to the authors of user-defined topologies to ensure that this safety requirement is satisfied.

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

Parameters

udt – a user-defined topology, either C++ or Python

Raises

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

  • unspecified – any exception thrown by methods of the UDT invoked during construction, the deep copy of the UDT, 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.)

__init__()#
__repr__()#

Return repr(self).

extract(t)#

Extract the user-defined topology.

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

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

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

  • otherwise, None will be returned.

Parameters

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

Returns

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

Raises

TypeError – if t is not a type

Examples

>>> import pygmo as pg
>>> t1 = pg.topology(pg.ring())
>>> t1.extract(pg.ring) 
<pygmo.core.ring at 0x7f8e4792b670>
>>> t1.extract(pg.unconnected) is None
True
>>> class topo:
...     def get_connections(self, n):
...         return [[], []]
...     def push_back(self):
...         return
>>> t2 = pg.topology(topo())
>>> t2.extract(object) 
<__main__.topo at 0x7f8e478c04e0>
>>> t2.extract(topo) 
<__main__.topo at 0x7f8e478c04e0>
>>> t2.extract(pg.unconnected) is None
True
get_connections(n)#

Get the connections to a vertex.

This method will invoke the get_connections() method of the UDT, which is expected to return a pair of array-like objects containing respectively:

  • the indices of the vertices which are connecting to n (that is, the list of vertices for which a directed edge towards n exists),

  • the weights (i.e., the migration probabilities) of the edges linking the connecting vertices to n.

This method will also run sanity checks on the output of the get_connections() method of the UDT.

Parameters

n (int) – the index of the vertex whose incoming connections’ details will be returned

Returns

a pair of arrays describing n’s incoming connections

Return type

Pair of 1D NumPy arrays

Raises

  • RuntimeError – if the object returned by a pythonic UDT is not iterable, or it is an iterable whose number of elements is not exactly 2, or if the invocation of the get_connections() method of the UDT raises an exception

  • ValueError – if the sizes of the returned arrays differ, or if any element of the second array is not in the \([0.,1.]\) range

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

get_extra_info()#

Topology’s extra info.

If the UDT 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 UDT

Return type

str

Raises

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

get_name()#

Topology’s name.

If the UDT 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 UDT will be returned.

Returns

the topology’s name

Return type

str

is_(t)#

Check the type of the user-defined topology.

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 UDT

Returns

whether the UDT is of type t or not

Return type

bool

Raises

unspecified – any exception thrown by extract()

push_back(n=1)#

Add vertices.

This method will invoke the push_back() method of the UDT n times. The push_back() method of the UDT is expected to add a new vertex to the topology, assigning it the next available index and establishing connections to other vertices.

Parameters

n (int) – the number of times the push_back() method of the UDT will be invoked

Raises

  • OverflowError – if n is negative or too large

  • unspecified – any exception thrown by the push_back() method of the UDT

to_networkx()#

New in version 2.15.

Conversion to NetworkX.

If the UDT provides a to_networkx() method, then this method will invoke it and return its output. Otherwise, an error will be raised.

This method is meant to export a representation of the current state of the topology as a NetworkX graph object. The returned object must be a networkx.DiGraph in which the edges have a weight attribute represented as a floating-point value.

Note that this method will strip away all node attributes and edge attributes other than weight from the graph returned by the UDT. It will also redefine the nodes to be numbered sequentially (that is, if the NetworkX graph returned by the UDT has three nodes numbered 0, 1 and 5, the graph returned by this method will have nodes numbered 0, 1 and 2).

Returns

a graph representation of the UDT

Return type

networkx.DiGraph

Raises

  • NotImplementedError – if the UDT does not provide a to_networkx() method

  • TypeError – if the object returned by the UDT is not a networkx.DiGraph

  • ValueError – if the edges of the returned graph do not all have a weight attribute

  • unspecified – any exception thrown by the to_networkx() method of the UDT