.. _run_sampler: ======== Sampling ======== Given a :ref:`likelihood` and :ref:`priors`, we run parameter estimation using the :code:`run_sampler` function. This is the core interface which you should use to setup a sampler and switch between different samplers easily. This can be accessed via :code:`bilby.run_sampler` or :code:`bilby.core.sampler.run_sampler`. -------------------------- Switching between samplers -------------------------- :code:`bilby` can use a large number (and growing) of off-the-shelf samplers. Given your likelihood and prior, it is trivial to switch between samplers by changing the argument :code:`sampler` given to :code:`run_sampler`. .. note:: By default, only the :code:`dynesty` sampler is a requirement when installing :code:`bilby`; therefore, other samplers may not be installed on your system. You can try to use them, if they aren't installed a help message will print out. See `installing samplers`_ for help with installation. Different samplers take different arguments to control their behaviour. To handle this, we allow the user to pass arbitrary `keyword arguments `_ into :code:`run_sampler`. To document what keyword arguments are available, below we give the API for each sampler. In each of these, there is an "Other Parameters" section which contains information on all the available keyword arguments that sampler takes. For example, to use the :code:`dynesty` sampler with 250 live points, you would use .. code-block:: python >>> bilby.core.run_sampler(likelihood, priors, sampler='dynesty', nlive=250) .. note:: For some parameters, we map a variety of similar arguments together. E.g., :code:`nlive=250` is equivalent to :code:`npoints`. The full list of these is given in the API information below. Below, we give the detailed API for the samplers. Remember, this API is not recommended for direct use by the user, rather it should be accessed via the :code:`run_sampler`. --------------- Nested Samplers --------------- - Dynesty: :code:`bilby.core.sampler.dynesty.Dynesty` - Nestle :code:`bilby.core.sampler.nestle.Nestle` - CPNest :code:`bilby.core.sampler.cpnest.Cpnest` - PyMultiNest :code:`bilby.core.sampler.pymultinest.Pymultinest` - PyPolyChord :code:`bilby.core.sampler.polychord.PyPolyChord` - UltraNest :code:`bilby.core.sampler.ultranest.Ultranest` - DNest4 :code:`bilby.core.sampler.dnest4.DNest4` - Nessai :code:`bilby.core.sampler.nessai.Nessai` ------------- MCMC samplers ------------- - bilby-mcmc :code:`bilby.bilby_mcmc.sampler.Bilby_MCMC` - emcee :code:`bilby.core.sampler.emcee.Emcee` - ptemcee :code:`bilby.core.sampler.ptemcee.Ptemcee` - pymc :code:`bilby.core.sampler.pymc.Pymc` - zeus :code:`bilby.core.sampler.zeus.Zeus` ------------------- Installing samplers ------------------- pip-installable samplers ======================== Most samplers can be installed using `pip `_ (see exceptions below). E.g., to install the :code:`emcee` .. code:: console $ pip install emcee If you installed :code:`bilby` from source, then all the samplers can be installed using .. code:: console $ pip install -r sampler_requirements.txt where the file `sampler_requirements.txt `_ can be found in the at the top-level of `the repository `_ (Note: if you installed from pip, you can simply download that file and use the command above). Installing PyPolyChord ====================== If you want to use the `PyPolyChord` sampler, you first need the PolyChord library to be installed to work properly. An image of PolyChord can be found on github. Clone the following repository onto your system. Navigate to the folder you want to install PolyChord in and run: .. code-block:: console $ git clone https://github.com/PolyChord/PolyChordLite.git Then navigate into the PolyChord directory and install PolyChord/PyPolyChord with .. code-block:: console $ make pypolychord MPI= $ python setup.py install --user Add a number after `MPI=` to compile with `MPI`. Leave it like it is if you don't wish to compile with MPI. Installing pymultinest ====================== If you want to use the `pymultinest` sampler, you first need the MultiNest library to be installed to work properly. The full instructions can be found here: https://johannesbuchner.github.io/PyMultiNest/install.html. Here is a shortened version: First, install the dependencies (for Ubuntu/Linux): .. code-block:: console $ sudo apt-get install python-{scipy,numpy,matplotlib,progressbar} ipython libblas{3,-dev} liblapack{3,-dev} libatlas{3-base,-dev} cmake build-essential git gfortran For Mac, the advice in the instructions are "If you google for “MultiNest Mac OSX” or “PyMultiNest Mac OSX” you will find installation instructions". The following will place a directory `MultiNest` in your :code:`$HOME` directory, if you want to place it somewhere, adjust the instructions as such. .. code-block:: console $ git clone https://github.com/JohannesBuchner/MultiNest $HOME $ cd $HOME/MultiNest/build $ cmake .. $ make Finally, add the libraries to you path. Add this to the `.bashrc` file ( replacing the path where appropriate) .. code-block:: console $ export LD_LIBRARY_PATH=$HOME/MultiNest/lib: (you'll need to re-source your `.bashrc` after this, i.e. run `bash`). ---------------------------- Adding new samplers to bilby ---------------------------- We actively encourage the addition of new samplers to :code:`bilby`. To help enable this, we have base classes which can be subclassed. Below we provide the API for reference, note that the :code:`NestedSampler` and :code:`MCMCSampler` inherit from the :code:`Sampler` class.