Detailed API documentation

This page contains documentation for the user-facing parts of the dyPolyChord package. For details of the internal workings of the package, look at the source code and its documentation at https://github.com/ejhigson/dyPolyChord.

run_dynamic_ns

This module contains dyPolyChord’s high-level functionality for performing dynamic nested sampling calculations. This is done using the algorithm described in Appendix F of “Dynamic nested sampling: an improved algorithm for parameter estimation and evidence calculation” (Higson et al., 2019). For more details see the dyPolyChord doumentation at https://dypolychord.readthedocs.io/en/latest/.

dyPolyChord.run_dynamic_ns.run_dypolychord(run_polychord, dynamic_goal, settings_dict_in, \*\*kwargs)[source]

Performs dynamic nested sampling using the algorithm described in Appendix F of “Dynamic nested sampling: an improved algorithm for parameter estimation and evidence calculation” (Higson et al., 2019). The likelihood, prior and PolyChord sampler are contained in the run_polychord callable (first argument).

Dynamic nested sampling is performed in 4 steps:

1) Generate an initial nested sampling run with a constant number of live points n_init. This process is run in chunks using PolyChord’s max_ndead setting to allow periodic saving of .resume files so the initial run can be resumed at different points.

2) Calculate an allocation of the number of live points at each likelihood for use in step 3. Also clean up resume files and save relevant information.

3) Generate a dynamic nested sampling run using the calculated live point allocation from step 2.

4) Combine the initial and dynamic runs and write combined output files in the PolyChord format. Remove the intermediate output files produced which are no longer needed.

The output files are of the same format produced by PolyChord, and contain posterior samples and an estimate of the Bayesian evidence. Further analysis, including estimating uncertainties, can be performed with the nestcheck package.

Like for PolyChord, the output files are saved in base_dir (specified in settings_dict_in, default value is ‘chains’). Their names are determined by file_root (also specified in settings_dict_in). dyPolyChord ensures the following following files are always produced:

  • [base_dir]/[file_root].stats: run statistics including an estimate of the Bayesian evidence;

  • [base_dir]/[file_root]_dead.txt: posterior samples;

  • [base_dir]/[file_root]_dead-birth.txt: as above but with an extra column containing information about when points were sampled.

For more information about the output format, see PolyChord’s documentation. Note that dyPolyChord is not able to produce all of the types of output files made by PolyChord - see check_settings’ documentation for more information. In addition, a number of intermediate files are produced during the dynamic nested sampling process which are removed by default when the process finishes. See clean_extra_output’s documentation for more details.

Parameters
run_polychord: callable

A callable which performs nested sampling using PolyChord for a given likelihood and prior, and takes a settings dictionary as its argument. Note that the likelihood and prior must be specified within the run_polychord callable. For helper functions for creating such callables, see the documentation for dyPolyChord.pypolychord (Python likelihoods) and dyPolyChord.polychord (C++ and Fortran likelihoods). Examples can be found at: https://dypolychord.readthedocs.io/en/latest/demo.html

dynamic_goal: float or int

Number in [0, 1] which determines how to allocate computational effort between parameter estimation and evidence calculation. See the dynamic nested sampling paper for more details.

settings_dict: dict

PolyChord settings to use (see check_settings for information on allowed and default settings).

nlive_const: int, optional

Used to calculate total number of samples if max_ndead not specified in settings. The total number of samples used in this case is the estimated number that would be taken by a nested sampling run with a constant number of live points nlive_const.

ninit: int, optional

Number of live points to use for the initial exploratory run (Step 1).

ninit_step: int, optional

Number of samples taken between saving .resume files in Step 1.

seed_increment: int, optional

If random seeding is used (PolyChord seed setting >= 0), this increment is added to PolyChord’s random seed each time it is run to avoid repeated points. When running in parallel using MPI, PolyChord hashes the seed with the MPI rank using IEOR. Hence you need seed_increment to be > number of processors to ensure no two processes use the same seed. When running repeated results you need to increment the seed used for each run by some number > seed_increment.

smoothing_filter: func or None, optional

Smoothing function to apply to the nlive allocation array of target live points. Use smoothing_filter=None for no smoothing.

comm: None or mpi4py MPI.COMM object, optional

For MPI parallelisation.

stats_means_errs: bool, optional

Whether to include estimates of the log evidence logZ and the parameter mean values and their uncertainties in the .stats file. This is passed to nestcheck’s write_run_output; see its documentation for more details.

clean: bool, optional

Clean the additional output files made by dyPolyChord, leaving only output files for the combined run in PolyChord format. When debugging this can be set to False to allow inspection of intermediate output.

resume_dyn_run: bool, optional

Resume a partially completed dyPolyChord run using its cached output files. Resuming is only possible if the initial exploratory run finished and the process reached the dynamic run stage. If the run is resumed with different settings to what were used the first time then this may give unexpected results.

polychord_utils

Functions for running dyPolyChord using compiled PolyChord C++ or Fortran likelihoods.

class dyPolyChord.polychord_utils.RunCompiledPolyChord(executable_path, prior_str, **kwargs)[source]

Object for running a compiled PolyChord executable with specified inputs.

__call__(self, settings_dict, comm=None)[source]

Run PolyChord with the input settings by writing a .ini file then using the compiled likelihood specified in executable_path.

See the PolyChord documentation for more details.

Parameters
settings_dict: dict

Input PolyChord settings.

comm: None, optional

Not used. Included only so __call__ has the same arguments as the equivalent python function (which uses the comm argument for runnign with MPI).

__init__(self, executable_path, prior_str, \*\*kwargs)[source]

Specify path to executable, priors and derived parameters.

Parameters
executable_path: str

Path to compiled likelihood. If this is in the directory from which dyPolyChord is being run, you may need to prepend “./” to the executable name for it to work.

prior_str: str

String specifying prior in the format required for PolyChord .ini files (see get_prior_block_str for more details).

config_str: str, optional

String to be written to [root].cfg file if required.

derived_str: str or None, optional

String specifying prior in the format required for PolyChord .ini files (see prior_str for more details).

mpi_str: str or None, optional

Optional mpi command to preprend to run command. For example to run with 8 processors, use mpi_str = ‘mprun -np 8’. Note that PolyChord must be installed with MPI enabled to allow running with MPI.

__weakref__

list of weak references to the object (if defined)

ini_string(self, settings)[source]

Get a PolyChord format .ini file string based on the input settings.

Parameters
settings: dict
Returns
string: str
dyPolyChord.polychord_utils.format_setting(setting)[source]

Return setting as string in the format needed for PolyChord’s .ini files. These use ‘T’ for True and ‘F’ for False, and require lists of numbers written separated by spaces and without commas or brackets.

Parameters
setting: (can be any type for which str(settings) works)
Returns
str
dyPolyChord.polychord_utils.get_prior_block_str(prior_name, prior_params, nparam, \*\*kwargs)[source]

Returns a PolyChord format prior block for inclusion in PolyChord .ini files.

See the PolyChord documentation for more details.

Parameters
prior_name: str

Name of prior. See the PolyChord documentation for a list of currently available priors and details of how to add your own.

prior_params: str, float or list of strs and floats

Parameters for the prior function.

nparam: int

Number of parameters.

start_param: int, optional

Where to start param numbering. For when multiple prior blocks are being used.

block: int, optional

Number of block (only needed when using multiple prior blocks).

speed: int, optional

Use to specify fast and slow parameters if required. See the PolyChord documentation for more details.

Returns
block_str: str

PolyChord format prior block string for ini file.

dyPolyChord.polychord_utils.python_block_prior_to_str(bp_obj)[source]

As for python_prior_to_str, but for BlockPrior objects of the type defined in python_priors.py. python_prior_to_str is called seperately on every block.

Parameters
prior_obj: python prior object

Of the type defined in python_priors.py.

kwargs: dict, optional

Passed to get_prior_block_str (see its docstring for more details).

Returns
block_str: str

PolyChord format prior block string for ini file.

dyPolyChord.polychord_utils.python_prior_to_str(prior, \*\*kwargs)[source]

Utility function for mapping python priors (of the type in python_priors.py) to ini file format strings used for compiled (C++ or Fortran) likelihoods.

The input prior must correspond to a prior function set up in PolyChord/src/polychord/priors.f90. You can easily add your own too. Note that some of the priors are only available in PolyChord >= v1.15.

Parameters
prior_obj: python prior object

Of the type defined in python_priors.py

kwargs: dict, optional

Passed to get_prior_block_str (see its docstring for more details).

Returns
block_str: str

PolyChord format prior block string for ini file.

pypolychord_utils

Functions for running dyPolyChord using pypolychord (PolyChord’s built-in python wrapper) using with python likelihoods and priors.

Note that pypolychord was called PyPolyChord before PolyChord v1.15; if pypolychord cannot be imported then we try importing it using its old name instead for backwards compatibility.

class dyPolyChord.pypolychord_utils.RunPyPolyChord(likelihood, prior, ndim, nderived=0)[source]

Callable class for running PolyChord in Python with specified the settings.

__call__(self, settings_dict, comm=None)[source]

Runs pypolychord with specified inputs and writes output files. See the pypolychord documentation for more details.

Parameters
settings_dict: dict

Input PolyChord settings.

comm: None or mpi4py MPI.COMM object, optional

For MPI parallelisation.

__init__(self, likelihood, prior, ndim, nderived=0)[source]

Specify likelihood, prior and number of dimensions in calculation.

Parameters
likelihood: func
prior: func
ndim: int
nderived: int, optional
__weakref__

list of weak references to the object (if defined)