The DIAMONDS Code
Total Page:16
File Type:pdf, Size:1020Kb
The DIAMONDS code Jul 08, 2020 Contents 1 Authors 3 2 Description 5 3 Navigation 7 3.1 Package Content.............................................7 3.2 Installation................................................ 12 3.3 User Guide Manual............................................ 16 3.4 Publications............................................... 17 3.5 Events.................................................. 19 3.6 Logo................................................... 20 i ii The DIAMONDS code Contents 1 The DIAMONDS code 2 Contents CHAPTER 1 Authors • Enrico Corsaro • Joris De Ridder 3 The DIAMONDS code 4 Chapter 1. Authors CHAPTER 2 Description The DIAMONDS (high-DImensional And multi-MOdal NesteD Sampling) code presented in this website is devel- oped in C++11 and structured in classes in order to be as much flexible and configurable as possible. The working scheme from the main function is as follow: • Read an input dataset • Set up model, likelihood, and prior distributions to be used in the Bayesian inference • Set up a drawing algorithm for the nested sampling • Configure and start the nested sampling • Compute and print the final results The code can be used for any application involving Bayesian parameter estimation and/or model selection problems. Users can supply new models, likelihood functions, and prior distributions whenever needed by taking the advantage of C++ class polymorphism and inheritance. Any new model, likelihood, and prior distribution can be defined and implemented upon a basic template. In addition, it is possible to feed the basic nested sample with different drawing algorithms based on clustering, as well as different clustering algorithms can in principle be used. The original paper publication that presents DIAMONDS and its application to asteroseismology is available atE. Corsaro & J. De Ridder 2014 A&A, 571, 71 5 The DIAMONDS code 6 Chapter 2. Description CHAPTER 3 Navigation 3.1 Package Content The DIAMONDS code is available in a public GitHub repository. The repository, named DIAMONDS, contains the basic package that includes many demos, some of which presented in the main paper of the code, and the modules related to different likelihood functions and prior distributions, useful for a wide range of applications. 3.1.1 Downloading the Basic Package If you want to retrieve the code you have two options: 1. [Recommended] Open a Git Client (e.g. see SourceTree, available for free). In this case you will have to clone the public repository into your local machine. If you want to clone our public GitHub repository, you need to create a new repository in SourceTree by choosing the option “Clone from URL” and specifying as URL the one of the public repository of DIAMONDS, namely https://github.com/EnricoCorsaro/DIAMONDS. When you clone the repository, we suggest you provide as repository name Diamonds. This option is the best way of retrieving the code because any update, even if small, will always be visible for you using the Git Client. You can then decide to pull the new change, so that the code will be updated without the need to re-download the entire package. 2. Download the code from the GitHub repository (by clicking on the download as a ZIP file button in the website, see image below). After your download is completed, you unzip the code package file, DIAMONDS-master.zip, and you rename the folder Diamonds-master into Diamonds. Warning: If your folder name does not match the one listed in the CMake file of the code, then you will not be able to compile the code. Please make sure that this step is carefully accomplished as it may easily represent a failure step when installing the code.. 7 The DIAMONDS code 3.1.2 DIAMONDS Basic Package The content of the package is divided into different folders, which are described below: • include: this folder contains the header files of the different C++ classes of Diamonds, namely files having extension .h that contain the class function prototypes. • source: this folder contains the source files of the different C++ classes of Diamonds defined in the folder “include”, namely files having extension .cpp that contain the full implementation of all classes functions defined in their corresponding header files. • demos: this folder contains a set of demos to test the performance of the code, some of which are presented in the main paper of the code. Each demo has two files with the name coming from the name of the test distribution used in the demo, one with extension .h containing the likelihood function of the demo and its implementation, and the other with extension .cpp containing the main function with the configuration of the Diamonds code and used to run the demo itself. The demos folder also contains a file named mergeMultipleRuns.cpp which can be compiled and used separately for merging multiple runs. • tutorials: this folder contains ready-to-use tutorials that can be promptly compiled and executed by the user. These tutorials can be useful as a starting point to implement your own application for parameter estimation and model comparison with DIAMONDS. • docs: this folder contains the User Guide manual of the code and the original peer reviewed publication in Astronomy & Astrophysics. Additionally, four files are also included inside the folder Diamonds. These files are: • CMakeLists.txt. Used for compiling the code files. More information on how to configure the compiling file can be found in the installation guide page. • LICENSE.txt. Contains the license of the code. • README.md. Contains a short description of the code. • improvements.todo. Contains a list of future improvements that we will need to apply to the code. 8 Chapter 3. Navigation The DIAMONDS code 3.1.3 File Structure We discourage the user, especially if not familiar with the working mechanism of the code, from modifying the content of the source and header files provided in the package. This is to avoid severe impairment of the correct working of the code and of its capability of producing reliable results. For this purpose, the code has been tested to correctly work in the form available by download in this website and any changes to the original files may cause its malfunction. Header and Implementation files Header files and their corresponding implementations are divided in different categories, based on the role that the particular class has in the computation process. The categories can be identified by their filename. We use here asterisks legend specifying on which level the user is supposed to change existing classes and/or add new ones: • *** for categories whose classes should never be changed (at the risk to disrupt the correct functioning of the entire code). • ** for categories that can in principle be replaced and/or changed but at the risk that computation efficiency may be considerably affected (it is recommended to use those provided in the package). • * for categories whose classes should in principle be usable for the most variety of applications and do not require any change or additions. These categories can however be enriched with new classes for purposes that were not contemplated in the basic version of the code. • [no asterisk] for categories whose classes need to be created and configured by the user based on the problem one wants to investigate. Sampler*** The main class is termed NestedSampler and constitutes the core of the nested sampling computation. The current version of the NestedSampler relies on the usage of a cluster algortihm as a basic algortihm for the sampling. Other implementations that can be provided in the future may include different algorithms than the clustering ones. Derivate classes (concrete) provided in the basic package are: • MultiEllipsoidalSampler - This class implements the Simultaneous Ellipsoidal Sampling algorithm, presented in the main paper of DIAMONDS. This class relies on the use of a clustering algortihm and can in principle be replaced by another sampler class which relies on a cluster algorithm too. • ZeroSampler - Empty sampler used in the merger file. Clusterer** The main class (abstract) is termed Clusterer. Derivate classes (concrete) provided in the basic package are: • KmeansClusterer - The generalized k-means algortihm (X means) for clustering a sample of points, based on the use of the Bayesian Information Criterion. • GaussianMixtureClusterer - A Gaussian Mixture model based on Expectation-Maximization algorithm for clustering a sample of points. • ZeroClusterer - Empty clusterer used in the merger file. Reducer** The main class (abstract) is termed LivePointsReducer. Derivate classes (concrete) provided in the basic package are: • PowerlawReducer - A reducer made for removing live points from the nested sampling process to be con- centrated toward the end of the computation. 3.1. Package Content 9 The DIAMONDS code • FerozReducer - The live points reducer introduced by Feroz et al. 2009 in the first version of MultiNest. Projector** The main class (abstract) is termed Projector. Derivate classes (concrete) provided in the basic package are: • PrincipalComponentProjector - a Principal Component analysis feature projector to reduce the di- mensionality of the inference problem when correlations among free parameters of the model are present. Metric** The main class (abstract) is termed Metric. Derivate classes (concrete) provided in the basic package are: • EuclideanMetric - Standard Euclidean metric to define the distance between two points in the parameter space. • ManhattanMetric - Manhattan metric to define the distance