Welcome to speedystar

Python toolkit for the generation of mock catalogues of high-velocity stars

Description

speedystar allows you to generate, evolve, propagate and perform mock observations of single stars ejected at high velocities. Based on astropy, scipy, galpy, AMUSE, mwdust, pygaia, GaiaUnlimited and others.

Setup & Installation

Download the repository, navigate to the parent directory of speedystar and run

pip install ./

Package requires ~12 MB of space but installation may take a while depending on the number of dependency packages that must be installed (see setup.py or requirements.txt)

Alternatively, if you do not wish to install globally (e.g. if you want to more easily edit the speedystar source code), simply ensure speedystar/ is in the working directory and make sure required packages are installed:

pip install -r requirements.txt

Finally, speedystar is up on PyPI but it is an outdated release. So direct pip installation of speedystar is possible but not recommended.

Documentation

You can access every method's docstring by using the help() function in python.

Getting Started

See examples folder for iPython notebooks with working examples. General work flow is as follows:

1. Define an ejection model, i. e. the ejection mechanisms and associated assumptions.

   import speedystar
   ejmodel = speedystar.eject.Hills()

2. Create an ejection sample. Masses, velocities, ages, flight times, luminosities, radii and evolutionary stages are assigned/computed for each ejected star and become attributes to mysample:

   mysample = speedystar.starsample(ejmodel)

3. Define a Galactic potential and propagate the ejection star sample through the Galaxy. Default integration timestep is 0.1 Myr. Equatorial (position, proper motion, radial velocity, heliocentric distance, parallax) and Galactocentric Cartesian (x, y, z, v_x, v_y, v_z) are computed and become attributes to mysample.

   from galpy.potential.mwpotentials import MWPotential2014
   mysample.propagate(potential=MWPotential2014)

4. Obtain mock observations of each ejected star using the MIST isochrones. Apparent magnitudes in the Johnson-Cousins V, I_c and Gaia G, G_BP, G_RP and G_RVS bands are computed by default and become attributes to mysample. Optionally, magnitudes in other photometric systems can be computed as well, see documentation. Computing apparent magnitudes requires a DustMap object (see mwdust or the speedystar.starsample.fetch_dust() docstring).

   mysample.config_dust('/path/where/large/data/files/are/stored/dust_map.h5')
   mysample.photometry()

5. Select only the stars in your sample which are of interest. e.g. if only stars with total velocities >1000 km/s are interesting, try:

   from astropy import units as u
   idx = (mysample.GCv>1000*u.km/u.s) 
   mysample.subsample(np.where(idx)[0])

   Or, if you only want stars brighter than V=16:

   import numpy as np
   idx = (mysample.V<16)
   mysample.subsample(np.where(idx)[0])

   Some cuts, most notably those which determine which stars are detectable in different Gaia data releases, are hard-coded in, see the speedystar.starsample.subsample() docstring. They can be invoked with the appropriate string argument to .subsample(), e.g.

   mysample.subsample('Gaia_6D_DR3')

6. Save the final sample and all its attributes to file. Catalogue can also be saved following any of the steps above. Pre-existing catalogues can be loaded with speedystar.starsample(filename). Currently the only available input/output format is as a .fits table

   mysample.save('./my_catalogue.fits')

Have fun!

Tips, Tricks and Troubleshooting

• Depending on your science case, the distance from the Sun to the Galactic Centre and the circular velocity of the Milky Way at the Solar position may impact results. These are set in the .galpyrc configuration file.

• By default, stars only live up to the end of the main sequence before they are considered 'dead' and removed from the sample. Evolution up until the beginning of the AGB branch can be achieved using AMUSE by setting amuseflag=True in the ejection model definition. The AMUSE installation process can be very non-trivial, however, see here

• A lot of speedup can be gained by calling speedystar.subsample immediately after creating the ejection sample. This allows you to not waste time propagating or performing mock observations on stars which are not interesting for your science case. For example, if you are certain that only stars more massive than 1 M_☉ will be detectable by your survey or instrument of interest, you can call .subsample() before .propagate() like so:

  idx = (mysample.m >= 1*u.Msun)
  mysample.subsample(np.where(idx)[0])

• Selecting fast stars detectable by modern-day telescopes/surveys (e.g. Gaia) often means selecting only the rarest, brightest stars in the sample. Final samples may therefore be quite small and results will be stochastic. In such cases we recommend averaging results over many iterations of ejections+propagation+observation.

• Recall that galpy uses a left-handed Galactocentric coordinate system, meaning the Sun is located on the positive x axis, not negative. This is important if, e.g. you are dealing with astropy coordinates as well, which places the Sun on the negative x axis. The best way to avoid this mix-up is to use only galpy or astropy coordinates.

• Exercise caution when allowing stars with low ejection velocities (v₀ ≲ 200 km/s) to be propagated. Since stars are ejected directly radially away from the Galactic Centre, slow-ejected stars will quickly return towards Sgr A* on extremely eccentric orbits. Fully integrating these orbits can incur substantial energy error. A timeout condition is implemented to automatically skip an orbit propagation if it takes longer than five seconds.

Citation

If you use speedystar, please cite Contigiani et al. 2018 and Evans et al. 2022. If discussing the speedystar.eject.Hills implementation specifically, please also cite Rossi et al. 2017 and Marchetti et al. 2018.

This package makes heavy use of other python packages both widely-used and obscure. When relevant, please credit other works or packages as well:

• astropy for units, I/O, conversions
• scipy for under-the-hood math stuff
• galpy for orbital integration and coordinate transformations
• mwdust for Galactic dust maps
• pygaia for Gaia astrometric/spectroscopic errors
• scanninglaw for Gaia astrometric spread function
• imf for initial mass function utilities
• GaiaUnlimited for Gaia selection functions

Development & Bug Reports

Development of speedystar takes place on GitHub, at https://github.com/speedystar. Bug reports, feature requests, or other issues can be filed there or via email to fraser.evans@utoronto.ca. Contributions to the software are welcome.

Authors

• Fraser Evans (fraser.evans@utoronto.ca)
• Based on code base originally developed by Omar Contigiani
• Significant contributions from Tommaso Marchetti
• Additional contributions from Josephine Baggen, Sanne Bloot, Amber Remmelzwaal, Isabella Armstrong
• Thanks to Niccolò Veronesi for setup & installation debugging