SysSimExClusters

This repository provides a comprehensive forward modelling framework for studying planetary systems.

We develop and provide several statistical models for describing the intrinsic planetary systems, their architectures, and the correlations within multi-planet systems, using the Kepler population of exoplanet candidates. Our specific models are described in the following papers:

• He, Ford, and Ragozzine (2019), MNRAS, 490, 4575 (30pp) ("Paper I") [arXiv]
• He, Ford, and Ragozzine (2021a)*, AJ, 161, 16 (24pp) ("Paper II") [arXiv]
• He et al. (2020), AJ, 160, 276 (38pp) ("Paper III") [arXiv]
• He and Ford (2026), ApJ, 1001, 78 (34pp) ("Paper IV") [arXiv]

*Paper II was published shortly after Paper III due to an extended referee process.

In addition to these papers describing the new models, the simulated catalogs from these models have been directly used for several other publications:

• Gilbert and Fabrycky (2020), AJ, 159, 281 (17pp) [arXiv]
• Millholland, He, Ford, et al. (2021), AJ, 162, 166 (17pp), [arXiv]
• He, Ford, and Ragozzine (2021b), AJ, 162, 216 (22pp), [arXiv]
• Millholland, He, and Zink (2022), AJ, 164, 72 (15pp), [arXiv]
• He and Ford (2022), AJ, 164, 210 (10pp), [arXiv]

Important: We have a separate code branch for each paper that provides new models or functionality:

• "He_Ford_Ragozzine_2019" branch for He, Ford, and Ragozzine (2019)
• "He_Ford_Ragozzine_2020" branch for He, Ford, and Ragozzine (2021a)
• "He_et_al_2020" branch for He et al. (2020)
• "He_Ford_Ragozzine_2021b" branch for He, Ford, and Ragozzine (2021b)**
• "He_Ford_2026" branch for He & Ford (2026)

**This branch does not introduce any new models, but enables the option of drawing systems from a model conditioned on a given planet (e.g. within a period and radius range, transiting or not, etc.).

These should be used if you want to run our code instead of the master branch, which may be actively updated. In addition, the README file is different for each branch, and we provide more details for the models and code usage specific to each paper/branch. He and Ford (2026) contains the most recent models (the "hybrid models") and thus we recommend using the "He_Ford_2026" branch for simulating new catalogs.

How do I use these models?

We provide a large set of simulated catalogs from our models in the SysSim Catalogs folder. If you simply wish to use these simulated catalogs as examples of our models, then no installation is required! Simply download any of these tables and use them for your own science. To be able to use them, you must understand that we provide two types of catalogs:

• Physical catalog: a set of intrinsic, physical planetary systems (before any observations; contains properties like the true orbital periods, planet radii, etc.)
• Observed catalog: a set of transiting and detected planet candidates derived from a physical catalog (after a Kepler-like mission; contains properties like the measured orbital periods, transit depths, etc.)

Refer to the README of the branch specific to each paper for complete details on what each set of catalogs contains.

How do I simulate my own (physical and observed) catalogs?

Installation:

• You will need to first install the ExoplanetsSysSim package and set up some additional repositories; follow the instructions listed in the README of that page.
• Clone this repository.

git clone git@github.com:ExoJulia/SysSimExClusters.git

• Switch to the branch of this repository containing the model you want to simulate from. For example, to simulate models from the most recent paper, do:

git checkout He_Ford_2026

Usage:

Refer to the README of the branch containing the model you want to simulate from for steps.

How do I make plots similar to those in the papers?

While the core ExoplanetsSysSim and SysSimExClusters code is written in Julia, almost all of the figures produced for the paper are generated from Python (3.7) code written by Matthias He.

📣 UPDATE 09/20/22: 🎉 This code is now available in the pip-installable Python package SysSimPyPlots, with detailed documentation and tutorials!

📣 UPDATE 09/29/22: 🎉 In addition, the pip-installable Python package SysSimPyMMEN is also available and was used to generate the figures in He and Ford (2022).

You do NOT need to download SysSimExClusters in order to use these Python packages (with existing simulated catalogs).

What if I need help?

Feel free to email Matthias He at matthias.he@alumni.utoronto.ca!