.. _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`. --------------- Native Samplers --------------- :code:`bilby` includes several samplers by default: - bilby-mcmc :code:`bilby.bilby_mcmc.sampler.Bilby_MCMC` - dynesty: :code:`bilby.core.sampler.dynesty.Dynesty` - emcee :code:`bilby.core.sampler.emcee.Emcee` ----------------- External Samplers ----------------- In addition to the samplers listed above, :code:`bilby` supports a wide range of external samplers provided by various plugins. If your favourite sampler is missing, please open a PR to add it to the list. MCMC Samplers ============= - kombine: https://github.com/bilby-dev/kombine-bilby - numypyro: https://github.com/ColmTalbot/bilby-numpyro - PTMCMCSampler: https://github.com/bilby-dev/ptmcmsampler-bilby - ptemcee: https://github.com/bilby-dev/ptemcee-bilby - pymc: https://github.com/bilby-dev/pymc-bilby - zeus: https://github.com/bilby-dev/zeus-bilby Nested Samplers =============== - cpnest: https://github.com/bilby-dev/cpnest-bilby - dnest4: https://github.com/bilby-dev/dnest4-bilby - nestle: https://github.com/bilby-dev/nestle-bilby - nessai: https://github.com/bilby-dev/nessai-bilby - pymultinest: https://github.com/bilby-dev/pymultinest-bilby - pypolychord: https://github.com/bilby-dev/pypolychord-bilby - ultranest: https://github.com/bilby-dev/ultranest-bilby Sequential Monte Carlo Samplers =============================== - aspire: https://github.com/mj-will/aspire-bilby - pocomc: https://github.com/mj-will/pocomc-bilby -------------------------- Listing available samplers -------------------------- A list of available samplers can be produced using :py:func:`bilby.core.sampler.get_implemented_samplers`. This will list native bilby samplers and any samplers available via a plugin. If a plugin provides a sampler that is also implemented in bilby, the bilby implementation will be labeled with the prefix `bilby.` to distinguish it from the plugin version. See :ref:`sampler-plugins` for more details. ------------------- Installing samplers ------------------- Native samplers are installed by default when installing :code:`bilby`. External samplers require you to install the corresponding plugin. Most plugins can be installed from `pip `_ or :code:`conda`. For example: .. tab-set:: .. tabe-item:: Pip .. code-block $ pip install nestle-bilby .. tab-item:: Conda .. code-block $ conda install conda-forge::nestle-bilby Once the plugin is installed, the sampler can be by specfiying, for example, :code:`sampler="nestle"`. .. warning:: Some external samplers are only available via :code:`conda` or directly from source. See the installation instructions in the corresponding sampler plugin for more details. ---------------------------- Adding new samplers to bilby ---------------------------- We actively encourage the addition of new samplers to :code:`bilby`. We now recommended adding support for new samplers via the sampler plugins interface. For more details, and a template, see :ref:`sampler-plugins`. If you have a :code:`bilby` sampler plugin that you would like to be listed here, please let us know! ---------------------------- Migrating to sampler plugins ---------------------------- The interface for some samplers are being moved from bilby to external sampler plugins. This does not change how the samplers are used for most users, you still specify :code:`sampler='sampler name'` in :code:`run_sampler`, however, an additional dependency must be installed before using a sampler. .. note:: Samplers that are scheduled to be moved will print a warning when using them. For example, the :code:`nessai` sampler interface has been moved to a plugin. In order for a user to continue using this sampler, they must install the `nessai-bilby` `plugin `_ which is available via PyPI and conda. Once this package is installed, the new interface will automatically be used instead of the native bilby interface. .. warning:: Some samplers may require additional installation steps. For more details about how sampler plugins, including a list of available sampler plugins, see :ref:`sampler-plugins`.