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)
-
-
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)
-