Parallelism - using multiple cores
----------------------------------

Often you will want to evaluate the function on some remote computing
resources. ``adaptive`` works out of the box with any framework that
implements a `PEP 3148 <https://www.python.org/dev/peps/pep-3148/>`__
compliant executor that returns `concurrent.futures.Future` objects.

`concurrent.futures`
~~~~~~~~~~~~~~~~~~~~

On Unix-like systems by default `adaptive.Runner` creates a
`~concurrent.futures.ProcessPoolExecutor`, but you can also pass
one explicitly e.g. to limit the number of workers:

.. code:: python

    from concurrent.futures import ProcessPoolExecutor

    executor = ProcessPoolExecutor(max_workers=4)

    learner = adaptive.Learner1D(f, bounds=(-1, 1))
    runner = adaptive.Runner(learner, executor=executor, goal=lambda l: l.loss() < 0.05)
    runner.live_info()
    runner.live_plot(update_interval=0.1)

`ipyparallel.Client`
~~~~~~~~~~~~~~~~~~~~

.. code:: python

    import ipyparallel

    client = ipyparallel.Client()  # You will need to start an `ipcluster` to make this work

    learner = adaptive.Learner1D(f, bounds=(-1, 1))
    runner = adaptive.Runner(learner, executor=client, goal=lambda l: l.loss() < 0.01)
    runner.live_info()
    runner.live_plot()

`distributed.Client`
~~~~~~~~~~~~~~~~~~~~

On Windows by default `adaptive.Runner` uses a `distributed.Client`.

.. code:: python

    import distributed

    client = distributed.Client()

    learner = adaptive.Learner1D(f, bounds=(-1, 1))
    runner = adaptive.Runner(learner, executor=client, goal=lambda l: l.loss() < 0.01)
    runner.live_info()
    runner.live_plot(update_interval=0.1)

`mpi4py.futures.MPIPoolExecutor`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This makes sense if you want to run a ``Learner`` on a cluster non-interactively using a job script.

For example, you create the following file called ``run_learner.py``:

.. code:: python

    from mpi4py.futures import MPIPoolExecutor

    # use the idiom below, see the warning at
    # https://mpi4py.readthedocs.io/en/stable/mpi4py.futures.html#mpipoolexecutor
    if __name__ == "__main__":

        learner = adaptive.Learner1D(f, bounds=(-1, 1))

        # load the data
        learner.load(fname)

        # run until `goal` is reached with an `MPIPoolExecutor`
        runner = adaptive.Runner(
            learner,
            executor=MPIPoolExecutor(),
            shutdown_executor=True,
            goal=lambda l: l.loss() < 0.01,
        )

        # periodically save the data (in case the job dies)
        runner.start_periodic_saving(dict(fname=fname), interval=600)

        # block until runner goal reached
        runner.ioloop.run_until_complete(runner.task)

        # save one final time before exiting
        learner.save(fname)


On your laptop/desktop you can run this script like:

.. code:: bash

    export MPI4PY_MAX_WORKERS=15
    mpiexec -n 1 python run_learner.py

Or you can pass ``max_workers=15`` programmatically when creating the `MPIPoolExecutor` instance.

Inside the job script using a job queuing system use:

.. code:: bash

    mpiexec -n 16 python -m mpi4py.futures run_learner.py

How you call MPI might depend on your specific queuing system, with SLURM for example it's:

.. code:: bash

    #!/bin/bash
    #SBATCH --job-name adaptive-example
    #SBATCH --ntasks 100

    srun -n $SLURM_NTASKS --mpi=pmi2 ~/miniconda3/envs/py37_min/bin/python -m mpi4py.futures run_learner.py

`loky.get_reusable_executor`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This executor is basically a powered-up version of `~concurrent.futures.ProcessPoolExecutor`, check its `documentation <https://loky.readthedocs.io/>`_.
Among other things, it allows to *reuse* the executor and uses ``cloudpickle`` for serialization.
This means you can even learn closures, lambdas, or other functions that are not picklable with `pickle`.

.. code:: python

    from loky import get_reusable_executor
    ex = get_reusable_executor()

    f = lambda x: x
    learner = adaptive.Learner1D(f, bounds=(-1, 1))

    runner = adaptive.Runner(learner, goal=lambda l: l.loss() < 0.01, executor=ex)
    runner.live_info()