-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
175 lines (141 loc) · 6.68 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
LISA
Large-selection Interface for Sampling Algorithms
===============================================================================
Author : Michael D. Himes University of Central Florida
Contact: [email protected]
Advisor: Joseph Harrington University of Central Florida
Contributors:
Acknowledgements
----------------
This research was supported by the NASA Fellowship Activity under NASA Grant
80NSSC20K0682. We gratefully thank Nvidia Corporation for the Titan Xp GPU
that was used throughout development of the software.
Summary
=======
LISA provides an interface for a variety of sampling algorithms. Currently,
the following sampling methods are available:
DE-MC (ter Braak 2006), via a fork (https://github.com/mdhimes/mc3/tree/mpi)
of MC3 (https://github.com/pcubillos/mc3)
DE-MC with snooker updates (ter Braak & Vrugt 2008), via MC3 fork
DNest4 (Brewer & Foreman-Mackey 2018)
DREAM with snooker updates and multi-try (Laloy & Vrugt 2012), via PyDREAM
(https://github.com/LoLab-VU/PyDREAM)
dynesty (Speagle 2019; https://github.com/joshspeagle/dynesty)
MULTINEST (Feroz et al. 2009), via PyMultiNest (Buchner et al. 2014;
https://github.com/JohannesBuchner/PyMultiNest)
PolyChord (Handley et al. 2015a, 2015b;
https://github.com/PolyChord/PolyChordLite)
UltraNest (Buchner 2014, 2019; https://github.com/JohannesBuchner/UltraNest)
LISA comes with complete documentation as well as a user manual to assist
in its usage. Users can find the latest LISA User Manual at
https://exosports.github.io/LISA/doc/LISA_User_Manual.html.
LISA is an open-source project that welcomes improvements from the community
to be submitted via pull requests on Github. To be accepted, such improvements
must be generally consistent with the existing coding style, and all changes
must be updated in associated documentation.
LISA is released under the Reproducible Research Software License. Users are
free to use the software for personal reasons. Users publishing results from
LISA or modified versions of it in a peer-reviewed journal are required to
publicly release all necessary code/data to reproduce the published work.
Modified versions of LISA are required to also be released open source under
the same Reproducible Research License. For more details, see the text of the
license.
Files & Directories
===================
LISA contains various files and directories, described here.
doc/ - Contains documentation for LISA. The User Manual contains
the information in the README with more detail, as well as a
walkthrough for setup and running an example.
environment.yml - Contains the required packages for LISA.
example/ - Contains examples of executing LISA.
LICENSE - Contains the text of the sfotware's license.
lisa/ - Contains the LISA package.
__init__.py - Contains the main functions to use LISA.
modules/ - Contains submodules for some sampling algorithms.
MCcubed - MC3 package.
PolyChordLite - polychord's public release on Github.
_version.py - Tracks the code's version.
wrappers/ - Contains wrappers for the sampling algorithms.
helper.py - Contains the parent class for samplers.
Makefile - Handles building MC3.
README - This file!
setup.py - Used to install the package.
Note that all .py files have complete documentation; consult a specific file
for more details.
Installation
============
To build the supplied conda environment, enter
conda env create -f environment.yml
and activate it:
conda activate lisa
On some systems, this approach may fail. For a more robust approach that
requires additional steps, enter
conda create -n lisa python=3.7.2
conda activate lisa
conda env update --file environment.yml
This will build a base Python 3.7.2 environment, activate it, and then update
it with the packages necessary to run LISA.
Mac users may need to install additional tools:
xcode-select --install
This installs make, gcc, git, and other utilities needed.
Now, install LISA:
python setup.py install
This will compile required submodules and build an importable package.
To check that everything installed properly, start up a Python session and try
import lisa
If it succeeds without warnings about missing MultiNest files,
you are now ready to use LISA!
Executing LISA
===============
LISA is designed to be imported into existing projects. LISA provides two
functions for usage: setup instantiates a sampler, while run performs setup,
runs the inference, and produces posterior plots. For example,
import lisa
sampler = lisa.setup('demc')
will set up a DEMC sampler object. Users would then need to specify required
parameters, such as the data, uncertainties, phase space, etc. For a list of
the required parameters,
print(sampler.reqpar)
These parameters are attributes of the sampler object, and must be set to
execute the inference. For example, if my data were y = x from 0 through 9,
sampler.data = np.arange(10)
Optional parameters are also available. View those via
print(sampler.optpar)
To get more information about some parameter P, there are two options:
sampler.help('P')
print(sampler.helpinfo['P'])
Once all required parameters are specified, execute the inference via
sampler.run()
If the sampler object is not properly set up, LISA will print to terminal
the issues that must be corrected, provided that the `verb` parameter is at
least 1. After fixing them, call the run() method as before.
To make plots of the posterior, enter
sampler.make_plots()
Alternatively, if users already know what parameters to include,
sampler = lisa.run(algorithm, keyword1=parameter1, keyword2=parameter2, ...)
If a required parameter is missing, users can follow the above instructions
for adding the required parameters, run it, and produce plots.
For more examples of how to incorporate LISA into your project, see the
example/ directory.
Versions
========
LISA was developed on a Unix/Linux machine using the following
versions of packages:
- Python 3.7.2
- Numpy 1.16.2
- Matplotlib 3.0.2
- mpi4py 3.0.3
- Scipy 1.5.3
- h5py 2.9.0
- MULTINEST 3.10
- PyMultiNest 2.10
- UltraNest 2.2.2
- dynesty 1.0.1
- dnest4 0.2.4
- PyDREAM 2.0.0
Be kind
=======
Please note that this software has not been officially released yet; see the
license for some restrictions on its usage prior to release. Upon release,
we will add the relevant citation here, with a Bibtex entry.
Thanks!