Package: prospect-public
PROSPECT: A profile likelihood code for frequentist cosmological inferenceAuthor:Emil Brinch Holm (ebholm@phys.au.dk)Documentation:Documentation at GitHub pagesInstallation:pip install prospect-publicRelease paper:arXiv:2312.02972How to useInstall PROSPECT by runningpip install prospect-publicin a terminal.Note:PROSPECTrequires Python version 3.10 or later.PROSPECT runs either fron an input yaml file or from a folder made by a previous run of PROSPECT (it will detect by itself what type of input is given). To run it from the command line, doprospect my_input_file.yamlorprospect my_prospect_output_folderIn particular, you can resume PROSPECT runs that were cancelled using the latter command.Run modes: PROSPECT supports running serially, threaded or in parallel using MPI. You can specify the run mode in the input file as demonstrated in fileinput/explanatory.yaml. If you are running using MPI, remember to call PROSPECT using MPI, for example asmpirun -n N_PROCS prospect input/example_montepython/example_montepython.yaml.Example filesTo check that PROSPECT is installed correctly, you can try running some of the example files provided in theinput/directory.example_toy/example_toy.yaml: An analytical 30-dimensional Gaussian likelihood. Since this evaluates quickly, it is a good first test of using PROSPECT.example_montepython/example_montepython.yaml: A simple 2-parameter example with a Gaussian likelihood on the Hubble constant, showing how to interface PROSPECT withMontePython. Before using this, you must set the correctpathto yourmontepython_public/montepythondirectory in the yaml fileexample_montepython.yamland specify the correct paths to your CLASS installation inexample_montepython/example.conf.example_montepython/base2018TTTEEE.yaml: A profile of the Hubble constant using the example filebase2018TTTEEE.paramof MontePython, which employs Planck high-ell TTTEEE and low-ell EE and TT data. Remember to also set the correctpathinbase2018TTTEEE.yamlas well as the correct paths to CLASS and clik inexample.conf, as above. In this example, we have set the optimiser settings such that the profiles should converge somewhat quickly (i.e. each optimisation should take on the order of 2 hours on 8 CPU cores) such that you can use them as a starting point for your own optimisation.example_cobaya/example_cobaya.yaml: A simple example showing how to interface PROSPECT withcobaya.To learn how to create your own PROSPECT input files, consultinput/explanatory.yamlwhich presents the possible options for input arguments.Tip: The example files have hardcoded relative paths, so make sure to run them outside of theinput/example_*subdirectory.Loading a profile in PythonFrom a PROSPECT run that has completed an analysis task, the profile likelihood data is stored in themy_output/profile/subdirectory of the output folder. The exact contents depend on what you choose in your input file.Tip: You can always analyse an ongoing PROSPECT run by callingprospect-analyse my_prospect_runfrom the terminal.PROSPECT provides a quick tool to load the profile likelihood in Python as follows:from prospect.profile import load_profile
profile_dict = load_profile('path_to_my_run')whenceprofile_dictis a dictionary with the best-fitting parameter values at each point in the profile, along with the associated likelihood values.ReoptimisingNot satisfied with your profile? You can always queue newOptimiseTasks with the reoptimising feature. Add extra tasks from the terminal by runningprospect-reoptimise -y my_reoptimise_settings.yaml -o folder_to_reoptimise (--override)Here,my_reoptimise_settings.yamlshould be a yaml file similar in structure to PROSPECT input files, but only containing the "profile" substructure. For example:profile:
    temperature_schedule: 'exponential'
    temperature_range: [0.2, 0.01]

    step_size_schedule: 'adaptive'
    step_size_adaptive_interval: [0.1999, 0.2001]
    step_size_adaptive_multiplier: 0.4
    step_size_adaptive_initial: 0.25

    steps_per_iteration: 1000
    max_iterations: 15
    repetitions: 3If you add the--overrideflag to the command, all currently queuedOptimiseTasks will be deleted and replaced by new ones according to the schedule chosen inmy_reoptimise_settings.yaml. This is often recommended, since otherwise the newly added tasks may never get run. Note that you can also use this feature to change thevaluessetting, allowing you to add new points to sample the profile likelihood at.NOTE: PROSPECT does not have a working convergence criterion, so you must check the profile yourself to determine whether it is converged. This can be assessed in themy_prospect_output/profile/my_prospect_output_schedule.pdffigure. If the log-likelihoods have not changed much in the last iterations, and the acceptance rate is non-zero, either the profile is converged or needs reoptimising from a larger temperature. If you are still having issues converging your profiles, you should change some of the optimiser settings. The best settings are very problem-dependent. We suggest trying a mixture of the following:Increasing thesteps_per_iteration,max_iterationsandrepetitions. This makes the simulated annealing MCMC more exploratory.Changingtemperature_range: If your input MCMC is not well-converged, starting at larger temperatures can be an advantage. Otherwise, be careful that you have not picked a too small temperature in the second entry.If you are still having problem converging, feel free to write me atebholm@phys.au.dk.PROSPECT snapshotsPROSPECT dumps its current state to the output folder at regular intervals given by the input file. In particular, PROSPECT output folders always contain astatus.txtfile which gives an overview of all finished, failed, queued and ongoing tasks of the run.PROSPECT runs can be loaded and inspected interactively in Python. To do so, from Python, import theloadfunction by runningfrom prospect.run import load.loadtakes the path to an output folder from a previous PROSPECT run, and returns aSchedulerinstance whose tasks can be accessed directly. For example,from prospect.run import load 
my_run = load('path_to_my_run')
all_finished_tasks = my_run.tasks.done.values() # tasks.done is a dict with task id as key and task as valueCheck out thedocumentationfor more detailed instructions on installation, how to define input files, as well as example workflows.Having issues?If you are experiencing problems using PROSPECT, do not hesitate to write a mail atebholm@phys.au.dkor submit an issue on the repository here.How to citeIf you are using PROSPECT for a publication, please cite the PROSPECT release paper:arXiv:2312.02972. In addition, please cite the codes that PROSPECT uses in your work. This could be:An MCMC sampler, eitherMontePythonorcobayaTheory codes, such asCLASSorCAMBData measurements and likelihoods that you use, for example the Planck 2018 data releasearXiv:1807.06209.