Tycho

AMUSE (Astrophysical Multipurpose Software Environment) community code for observing star-star scattering effects on exoplanets in stellar clusters.

TYCHO is a simulation suite used in observing the effects of star-star scattering on exoplanets within clustered natal environments. It is dependent on multiple community codes provided by the Astrophysical Multipurpose Software Environment (AMUSE; amusecode.org).

Developers' Note

The current master branch of TYCHO supports Python 3.8+ and AMUSE 13.1+. Should the need arrise, a version validated against the last release of Python 2.7 has been tagged as release v0.8 and works well for AMUSE 11. Should you wish to utilize the GPU-acceleration of ph4, you will need to build AMUSE from source instead of using the pip-installation mentioned below. This can be found at: https://github.com/amusecode/amuse

Breakdown of Included Scripts

• sim_cluster.py: Used in simulating a star cluster according to user-defined initial conditions. Additionally, it records all stellar close-encounters into an easy to process pickle format. If desired, this can also include a Jovian population to track the sub-brown dwarf population in the cluster.
• cut_encounters.py: Used to place predefined data cuts on the close-encounter database generated by sim_cluster.py.
• gen_RandEncounters.py: Used to create the starting conditions for sim_encounters.py by generating random orientations of the desired planetary systems for each encounter specified in the reduced encounter database.
• sim_encounters.py: Used in simulating stellar close-encounters created and stored by gen_RandEncounters.py.
• gen_init-final_database.py: A useful script which generates the initial and final conditions of planetary systems after sim_encounters.py has been run.

Installation on Ubuntu 18 LTS

Before you install Tycho, you need to install the following software prerequisites:

$ sudo apt-get install build-essential gfortran python3-dev \
  libopenmpi-dev openmpi-bin \
  libgsl-dev cmake libfftw3-3 libfftw3-dev \
  libgmp3-dev libmpfr6 libmpfr-dev \
  libhdf5-serial-dev hdf5-tools \
  git

Additionally, you will need an updated Python distribution, such as Anaconda3. This can be achieved by completing the following:

$ cd Downloads
$ wget https://repo.anaconda.com/archive/Anaconda3-2020.02-Linux-x86_64.sh
$ bash Anaconda3-2020.02-Linux-x86_64.sh

You'll want to initialize conda when prompted. After starting a new terminal session, run the following:

$ pip install numpy nose docutils mpi4py h5py wheel scipy astropy jupyter pandas seaborn rebound
$ pip install amuse-framework
$ pip install amuse-ph4 amuse-kepler amuse-sse amuse-seba amuse-smalln

Finally, switch to a directory that you'd like for Tycho to be installed into and run:

$ cd ABSOLUTE_PATH_TO_REPOSITORY/
$ git clone https://github.com/JPGlaser/Tycho.git

You'll need to add the src folder inside of the git repository to your $PYTHONPATH:

$ nano .profile

Add the following to the end of the file:

export PYTHONPATH="ABSOLUTE_PATH_TO_REPOSITORY/Tycho/src:$PYTHONPATH"

Production Walk-Through

Before you begin using Tycho, you'll need to assemble the following initial conditions for your cluster. Tycho handles its large-scale N-Body dynamics within the sim_cluster.py script. These are as follows:

• The number of primordial stellar systems, which is set with the -s / --num-stars tags.
  • If you would like primordial stellar binary systems to be generated, which can be enabled by the -b / --doBinaries tags.
• The number of primordial planetary systems (marked by Jovians), which is set with the -p / --num-psys tags.
  • Note: Should you wish to not follow the statistics of rogue planets in the greater cluster dynamics and the effects of their capture on other systems, you do not need to include this tag.
• The King Density parameter , which is set by the -w / --w0 tags.
• The timestep of the Bridge in Myr, which is set by the -t / --timestep tags. This defaults to 0.002 Myr.
• The desired time at which to end the simulation in Myr, which is set by the -T / --end-time tags. This defaults to 1 Myr.

Once you have these core parameters addressed, additional tags are need to be set depending on your situation:

• The name of the cluster for file management purposes, which is set by the -c / --cluster-name tags.
• The random seed used in several random number generators, which is set by the -S / --seed tags. It defaults to 42.
• If you would like NOT to use GPU-acceleration, you can disable this feature by passing the -g / --no-gpu* tags.
• Should you want to use GPU-acceleration and wish to use a single GPU worker card, you may address it specifically by giving the -i / --gpu-id with the integer value of the card's ID value (for example 0, 1, etc).
• Should you wish to use multiple GPU cards for large systems, you may do so by indicating the number of ph4-gpu-workers you wish to have running with the -N / --grav_workers tags.
• Should you have a cluster coming from another project, you may use the -P / --pregen-flag tag which will load the HDF5 located in the execution directory.
  • Note: This feature was originally intended for use with the output coming from TORCH simulations and is still undergoing generalization modifications.

Once your cluster simulation has finished, you'll be left with a good amount of data that can be used for various deep-drills into the evolution of the cluster's properties. However, we're specifically interested in the encounter states located within CLUSTERNAME_encounters.pkl.

To proceed forward with TYCHO, you'll need to first run cut_encounters.py, which will reduce the encounters database through several physical cuts (as detailed in Glaser et al, 2020). Next, you'll need to run gen_RandEncounters.py, which will create the initial conditions for encounters in the manner explained Glaser et al (2020), saving them into a pickled dictionary.

Finally, you'll want to run sim_encounters.py which will actually simulate all of the encounters to completion generated in the previous step. Afterwards, all of the data will be stored as temporarily AMUSE particle sets stored in CLUSTERNAME/Encounters/STARID/Enc-X_Rot_Y.hdf5. If you have multiple clusters that you would like to run at the same time, you can use the -M tag while within a root folder containing all cluster directories.

Should you wish to catalog all of your encounters in an easier to digest manner, you can use the get_init-final_database.py. This will produce a Pickled database of the initial and final conditions of your planetary systems. Again, you may run this on multiple clusters via the same method as described for sim_encounters.py.