From 0a081285eb8382970a5dd88d4b95d5dc4c6c64e0 Mon Sep 17 00:00:00 2001 From: Francesco Biscani Date: Thu, 11 May 2017 22:09:13 +0200 Subject: [PATCH] A few minor doc fixes and update changelog for release. --- doc/sphinx/changelog.rst | 2 +- .../docs/python/tutorials/coding_udi.rst | 2 +- .../python/tutorials/using_archipelago.rst | 6 ++--- pygmo/_island_test.py | 4 ++-- pygmo/_py_islands.py | 24 +++++++++---------- pygmo/docstrings.cpp | 8 +++---- 6 files changed, 23 insertions(+), 23 deletions(-) diff --git a/doc/sphinx/changelog.rst b/doc/sphinx/changelog.rst index 7477a4de6..43313b37f 100644 --- a/doc/sphinx/changelog.rst +++ b/doc/sphinx/changelog.rst @@ -1,7 +1,7 @@ Changelog ========= -2.2 (unreleased) +2.2 (2017-05-12) ---------------- New diff --git a/doc/sphinx/docs/python/tutorials/coding_udi.rst b/doc/sphinx/docs/python/tutorials/coding_udi.rst index a4877196e..608142776 100644 --- a/doc/sphinx/docs/python/tutorials/coding_udi.rst +++ b/doc/sphinx/docs/python/tutorials/coding_udi.rst @@ -47,7 +47,7 @@ That was easy! Lets now understand what we actually did. The object ``isl`` now But there is a catch. We are in python! So it is not possible, in general, to have the same interpreter execute instructions in parallel as, in most of the popular python language implementations, memory management is not thread-safe. So, while the code above is perfectly fine and will work with pygmo, a set of ``my_isl`` running evolutions will not run in parallel as each :class:`~pygmo.island`, when executing its :func:`~pygmo.island.evolve()` -acquires the GIL (Global Interpreter Lock) and holds it during the :func:`~pygmo.island.evolve()` execution. +method, acquires the GIL (Global Interpreter Lock) and holds it during the :func:`~pygmo.island.evolve()` execution. As a consequence, the following code: diff --git a/doc/sphinx/docs/python/tutorials/using_archipelago.rst b/doc/sphinx/docs/python/tutorials/using_archipelago.rst index ed2b2426f..e0f94b887 100644 --- a/doc/sphinx/docs/python/tutorials/using_archipelago.rst +++ b/doc/sphinx/docs/python/tutorials/using_archipelago.rst @@ -91,7 +91,7 @@ assemble an archipelago, the user can instantiate an empty archipelago and use t .. note:: The island type selected by the :class:`~pygmo.archipelago` constructor is, in this case, the - ``Multiprocessing island``, (:class:`pygmo.py_islands.mp_island`) as we run this example on py36 and + ``multiprocessing island``, (:class:`pygmo.mp_island`) as we run this example on py36 and a linux machine. In general, the exact island chosen is platform, population and algorithm dependent and such choice is described in the docs of the :class:`~pygmo.island` class constructor. @@ -128,7 +128,7 @@ After inspection, let us now run the evolution. 7 Multiprocessing island Self-adaptive constraints handling A toy problem 50 busy ... -Note how the evolution is happening in parallel on 32 separate threads (each one spawning a process, in this case, as a Multiprocessing island is used). +Note how the evolution is happening in parallel on 32 separate threads (each one spawning a process, in this case, as a multiprocessing island is used). The evolution happens asynchronously and thus does not interfere directly with our main process. We then have to call the :func:`pygmo.archipelago.wait()` method to have the main process explicitly wait for all islands to be finished. @@ -158,7 +158,7 @@ constructed using random seeds. Managing exceptions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ What happens if, during the optimization task sent to an :class:`~pygmo.island`, an exception happens? This question is already explored -in the :ref:`py_tutorial_using_island` and since an :class:`~pygmo.archipelago` is, basically, a container for multiple :class:`~pygmo.island` +in the :ref:`island tutorial` and since an :class:`~pygmo.archipelago` is, basically, a container for multiple :class:`~pygmo.island` here we will overlap with part of that tutorial, exploring exceptions thrown in the :class:`~pygmo.archipelago` context. To show how pygmo handles these situations we use the fake problem below throwing as soon as 300 fitness evaluations are made. diff --git a/pygmo/_island_test.py b/pygmo/_island_test.py index 246df6929..3a7e7ed6a 100644 --- a/pygmo/_island_test.py +++ b/pygmo/_island_test.py @@ -203,7 +203,7 @@ def run_serialization_tests(self): class mp_island_test_case(_ut.TestCase): - """Test case for the :class:`~pygmo.py_islands.mp_island` class. + """Test case for the :class:`~pygmo.mp_island` class. """ @@ -256,7 +256,7 @@ def run_basic_tests(self): class ipyparallel_island_test_case(_ut.TestCase): - """Test case for the :class:`~pygmo.py_islands.ipyparallel` class. + """Test case for the :class:`~pygmo.ipyparallel` class. """ diff --git a/pygmo/_py_islands.py b/pygmo/_py_islands.py index 4f84fb7aa..11dc01872 100644 --- a/pygmo/_py_islands.py +++ b/pygmo/_py_islands.py @@ -60,19 +60,19 @@ class mp_island(object): This user-defined island (UDI) will dispatch evolution tasks to a pool of processes created via the standard Python multiprocessing module. The pool is shared between - different instances of :class:`~pygmo.py_islands.mp_island`, and it is created - either implicitly by the construction of the first :class:`~pygmo.py_islands.mp_island` - object or explicitly via the :func:`~pygmo.py_islands.mp_island.init_pool()` static method. + different instances of :class:`~pygmo.mp_island`, and it is created + either implicitly by the construction of the first :class:`~pygmo.mp_island` + object or explicitly via the :func:`~pygmo.mp_island.init_pool()` static method. The default number of processes in the pool is equal to the number of logical CPUs on the - current machine. The pool's size can be queried via :func:`~pygmo.py_islands.mp_island.get_pool_size()`, - and changed via :func:`~pygmo.py_islands.mp_island.resize_pool()`. + current machine. The pool's size can be queried via :func:`~pygmo.mp_island.get_pool_size()`, + and changed via :func:`~pygmo.mp_island.resize_pool()`. .. note:: Due to certain implementation details of CPython, it is not possible to initialise or resize the pool from a thread different from the main one. Normally this is not a problem, but, for instance, if the first - :class:`~pygmo.py_islands.mp_island` instance is created in a thread different from the main one, an error - will be raised. In such a situation, the user should ensure to call :func:`~pygmo.py_islands.mp_island.init_pool()` + :class:`~pygmo.mp_island` instance is created in a thread different from the main one, an error + will be raised. In such a situation, the user should ensure to call :func:`~pygmo.mp_island.init_pool()` from the main thread before spawning the secondary thread. .. note:: @@ -89,7 +89,7 @@ def __init__(self): """ Raises: - unspecified: any exception thrown by :func:`~pygmo.py_islands.mp_island.init_pool()` + unspecified: any exception thrown by :func:`~pygmo.mp_island.init_pool()` """ # Init the process pool, if necessary. @@ -100,7 +100,7 @@ def run_evolve(self, algo, pop): This method will evolve the input :class:`~pygmo.population` *pop* using the input :class:`~pygmo.algorithm` *algo*, and return the evolved population. The evolution - is run on one of the processes of the pool backing backing :class:`~pygmo.py_islands.mp_island`. + is run on one of the processes of the pool backing backing :class:`~pygmo.mp_island`. Args: @@ -182,7 +182,7 @@ def _make_pool(processes): def init_pool(processes=None): """Initialise the process pool. - This method will initialise the process pool backing :class:`~pygmo.py_islands.mp_island`, if the pool + This method will initialise the process pool backing :class:`~pygmo.mp_island`, if the pool has not been initialised yet. Otherwise, this method will have no effects. Args: @@ -232,7 +232,7 @@ def get_pool_size(): def resize_pool(processes): """Resize pool. - This method will resize the process pool backing :class:`~pygmo.py_islands.mp_island`. + This method will resize the process pool backing :class:`~pygmo.mp_island`. Args: @@ -242,7 +242,7 @@ def resize_pool(processes): TypeError: if the *processes* argument is not an ``int`` ValueError: if the *processes* argument is not strictly positive - unspecified: any exception thrown by :func:`~pygmo.py_islands.mp_island.init_pool()` + unspecified: any exception thrown by :func:`~pygmo.mp_island.init_pool()` """ import multiprocessing as mp diff --git a/pygmo/docstrings.cpp b/pygmo/docstrings.cpp index c5ad1c780..a328d384f 100644 --- a/pygmo/docstrings.cpp +++ b/pygmo/docstrings.cpp @@ -3641,8 +3641,8 @@ Through the UDI, the island class manages the asynchronous evolution (or optimis of its :class:`~pygmo.population` via the algorithm's :func:`~pygmo.algorithm.evolve()` method. Depending on the UDI, the evolution might take place in a separate thread (e.g., if the UDI is a :class:`~pygmo.thread_island`), in a separate process (e.g., if the UDI is a -:class:`~pygmo.py_islands.mp_island`) or even in a separate machine (e.g., if the UDI is a -:class:`~pygmo.py_islands.ipyparallel_island`). The evolution is always asynchronous (i.e., running in the +:class:`~pygmo.mp_island`) or even in a separate machine (e.g., if the UDI is a +:class:`~pygmo.ipyparallel_island`). The evolution is always asynchronous (i.e., running in the "background") and it is initiated by a call to the :func:`~pygmo.island.evolve()` method. At any time the user can query the state of the island and fetch its internal data members. The user can explicitly wait for pending evolutions to conclude by calling the :func:`~pygmo.island.wait()` and @@ -3690,8 +3690,8 @@ An island can be initialised in a variety of ways using keyword arguments: * if *algo* and *pop*'s problem provide at least the :attr:`~pygmo.thread_safety.basic` thread safety guarantee, then :class:`~pygmo.thread_island` will be selected as UDI type; - * otherwise, if the current platform is Windows or the Python version is at least 3.4, then :class:`~pygmo.py_islands.mp_island` - will be selected as UDI type, else :class:`~pygmo.py_islands.ipyparallel_island` will be chosen; + * otherwise, if the current platform is Windows or the Python version is at least 3.4, then :class:`~pygmo.mp_island` + will be selected as UDI type, else :class:`~pygmo.ipyparallel_island` will be chosen; * if the arguments list contains *algo*, *prob*, *size* and, optionally, *udi* and *seed*, then a :class:`~pygmo.population` will be constructed from *prob*, *size* and *seed*, and the construction will then proceed in the same way detailed above (i.e., *algo* and the newly-created population are used to initialise the island's algorithm and population,