Topology#
- class pygmo.topology(udt=unconnected())#
Topology.
In the jargon of pagmo, a topology is an object that represents connections among
islands
in anarchipelago
. In essence, a topology is a weighted directed graph in whichthe 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 byarchipelago
.In a
topology
, vertices in the graph are identified by a zero-based unique integral index. This integral index corresponds to the index of anisland
in anarchipelago
.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 indexn
, 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 towardsn
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. Thepush_back()
method is invoked bypygmo.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, afterN
calls topush_back()
on an initially-empty topology, the topology should containN
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 atype
) 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
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 exceptionValueError – 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 itsget_extra_info()
method. Otherwise, an empty string will be returned.- Returns
extra info about the UDT
- Return type
- 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 itsget_name()
method. Otherwise, an implementation-defined name based on the type of the UDT will be returned.- Returns
the topology’s name
- Return type
- is_(t)#
Check the type of the user-defined topology.
This method returns
False
ifextract(t)
returnsNone
, andTrue
otherwise.
- push_back(n=1)#
Add vertices.
This method will invoke the
push_back()
method of the UDT n times. Thepush_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 thepush_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 aweight
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
- Raises
NotImplementedError – if the UDT does not provide a
to_networkx()
methodTypeError – 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
attributeunspecified – any exception thrown by the
to_networkx()
method of the UDT