clustertools

clustertools is a Python package for analysing star cluster simulations. The package is built around the StarCluster class, which will store all the necessary information from a given star cluster simulation to be used for anaylsis. All functions within clustertools are then designed to act on a StarCluster. clustertools can be used for unit and coordinate transformations, the calculation of key structural and kinematic parameters, analysis of the cluster’s orbit and tidal tails (with the help of galpy , and measuring common cluster properties like its mass function, density profile, and velocity dispersion profile (among others). While originally designed with star clusters in mind, clustertools can be used to study other types of N-body systems, including stellar streams and dark matter sub-halos.

The package contains functions for loading data from commonly used N-body codes, generic snapshots, and codes for generating initial conditions.

clustertools is developed on Github. Please go to https://github.com/webbjj/clustertools to report issues or contribute to the code.

Supported N-Body Simulation Codes, Snapshot Formats, and Packages

AMUSE (Portegies Zwart S., McMillan S., 2018, Astrophysical Recipes; The art ofAMUSE, doi:10.1088/978-0-7503-1320-9)

ASTROPY_TABLE (Astropy Collaboration 2013, A&A, 558, A33)

GALPY (Bovy J., 2015, ApJS, 216, 29)

LIMEPY (Gieles, M. & Zocchi, A. 2015, MNRAS, 454, 576)

NBODY6 (Aarseth S. J., 2003, Gravitational N-Body Simulations)

NBODY6ppGPU (Wang L., Spurzem R., Aarseth S., Nitadori K., Berczik P., Kouwenhoven M. B. N., Naab T., 2015, MNRAS, 450, 4070)

NEMO (Teuben P., 1995, The Stellar Dynamics Toolbox NEMO. p. 398)

Version 1.1 (May 18, 2023)

Thanks to anyone that has been using clustertools while it was in devlopment. I am happy to announce that Version 1.1 has now officially been released and the code has been published in JOSS. Thanks to the reviewers, Steven Rieder and Long Wang, for helpful feedback.

Guide

• Installation
  • github and pip install
  • Requirements
• Initialization
  • The StarCluster Class
  • Units
  • Coordinate Systems
• Loading and Advancing
  • Load
  • Advance
• Analysis
  • Operations
  • Functions
  • Profiles
  • Orbit
  • Tidal Tails
• Utilities
  • Plotting
  • Output
  • Coordinates
  • Recipes
  • Constants
• Observations
• Binaries

Example Notebooks

• Loading and Advancing
• Setup
• Operations
• Functions
• Profiles
• Orbits and Tidal Tails

Acknowledging clustertools

If you use clustertools in a publiclication, please cite the corresponding publication in the Journal of Open Source Software (JOSS):

Webb, J. J., (2023). clustertools: A Python Package for Analyzing Star Cluster Simulations. Journal of Open Source Software, 8(85), 4483, https://doi.org/10.21105/joss.04483

target:

https://doi.org/10.21105/joss.04483

,the Zenodo DOI:

target:

https://zenodo.org/badge/latestdoi/272233602

and link to https://github.com/webbjj/clustertools.

For specific functions, please consult the list below for the appropriate reference (if applicable).

References

alpha_prof - Webb, J.J. & Vesperini, E. 2016, MNRAS, 463, 2383 (ADS)

core_relaxation_time - Stone, N.C. & Ostriker, J.P. 2015, ApJ, 806, 28 (ADS)

ckin - Bianchini, P. et al. 2018, MNRAS, 475, 96 (ADS)

cyl_coords ,``cart_to_cy``,``cyl_to_cart`` - Bovy J., 2015, ApJS, 216, 29 (ADS)

find_centre(density=True) (default) - Harfst, S., Gualandris, A., Merritt, D., et al. 2007, NewA, 12, 357 (ADS) or Casertano, S., Hut, P. 1985, ApJ, 298, 80 (ADS)

half_mass_relaxation_time - Spitzer, L. 1987, Dynamical evolution of globular clusters (ADS)

initialize_orbit, initialize_orbits, interpolate_orbit, interpolate_orbits - Bovy J., 2015, ApJS, 216, 29 (ADS)

load_cluster('limepy','gcname') (default) - Bovy J., 2015, ApJS, 216, 29 (ADS) - Gieles, M. & Zocchi, A. 2015, MNRAS, 454, 576 (ADS) - de Boer, T. J. L., Gieles, M., Balbinot, E., Hénault-Brunet, V., Sollima, A., Watkins, L. L., Claydon, I. 2019, MNRAS, 485, 4906 (ADS) - Vasiliev E., 2019, MNRAS, 484,2832 (ADS)

load_cluster('limepy',gcname', source='harris') - Harris, W.E. 1996 (2010 Edition), AJ, 112, 1487 - Bovy J., 2015, ApJS, 216, 29 (ADS) - Gieles, M. & Zocchi, A. 2015, MNRAS, 454, 576 (ADS) - Vasiliev E., 2019, MNRAS, 484,2832 (ADS)

meq_function, meq_prof - Bianchini, P. et al. 2016, MNRAS, 458, 3644 (ADS)

orbital_path, orbital_path_match - Bovy J., 2015, ApJS, 216, 29 (ADS)

relaxation_time - Spitzer, L. Jr, Hart, M.H. 1971, ApJ, 164, 399 (ADS)

rcore - Casertano, S., Hut, P. 1985, ApJ, 298, 80 (ADS)

rlimiting - Bovy J., 2015, ApJS, 216, 29 (ADS)

rtidal - Bertin, G. & Varri, A.L. 2008, ApJ, 689, 1005 - Bovy J., 2015, ApJS, 216, 29 (ADS) - Webb, J.J., Bovy, J., Carlberg, R.G., Gieles, M. 2019, MNRAS, 448, 4 (ADS)

tail_path, tail_path_match, to_tail - Bovy J., 2015, ApJS, 216, 29 (ADS)

to_centre(method='orthonormal') - GAIA Collaboration, 2018, A&A, 616, A12 (ADS)

to_centre(method='VandeVen') - van de Ven, G. 2005, PhD Thesis, Leiden University (ADS)

to_cluster(method='orthonormal') - GAIA Collaboration, 2018, A&A, 616, A12 (ADS)

to_cluster(method='VandeVen') - van de Ven, G. 2005, PhD Thesis, Leiden University (ADS)

to_sky,``sky_coords``,``cart_to_sky`` - Bovy J., 2015, ApJS, 216, 29 (ADS)

virial_radius(method='critical_density') - Bovy J., 2015, ApJS, 216, 29 (ADS)

virial_radius(method=inverse_distance) - Portegies Zwart S., McMillan S., 2018, Astrophysical Recipes; The art ofAMUSE, doi:10.1088/978-0-7503-1320-9 (ADS)

Contributers

Jo Bovy - https://github.com/jobovy Erik Gillis - https://github.com/e-gillis Nathaniel Starkman - https://github.com/nstarman

Library Reference

• clustertools package
  • Subpackages
    • clustertools.analysis package
      • Submodules
        • clustertools.analysis.functions module
          • ckin()
          • closest_star()
          • core_relaxation_time()
          • energies()
          • eta_function()
          • find_centre()
          • find_centre_of_density()
          • find_centre_of_mass()
          • half_mass_relaxation_time()
          • mass_function()
          • meq_function()
          • rcore()
          • relaxation_time()
          • rlagrange()
          • rlimiting()
          • rtidal()
          • tapered_mass_function()
          • virial_radius()
          • virial_radius_critical_density()
          • virial_radius_inverse_distance()
        • clustertools.analysis.orbits module
          • initialize_orbit()
          • initialize_orbits()
          • interpolate_orbit()
          • interpolate_orbits()
          • orbit_interpolate()
          • orbital_path()
          • orbital_path_match()
          • orbits_interpolate()
        • clustertools.analysis.profiles module
          • alpha_prof()
          • beta_prof()
          • eta_prof()
          • m_prof()
          • rho_prof()
          • sigv_prof()
          • v2_prof()
          • v_prof()
          • vcirc_prof()
    • clustertools.cluster package
      • Submodules
        • clustertools.cluster.cluster module
          • StarCluster
          • overlap_cluster()
          • sub_cluster()
        • clustertools.cluster.operations module
          • add_rotation()
          • from_amuse()
          • reset_nbody_scale()
          • return_cluster()
          • save_cluster()
          • to_WDunits()
          • to_amuse()
          • to_audays()
          • to_centre()
          • to_cluster()
          • to_galaxy()
          • to_galpy()
          • to_kpcgyr()
          • to_kpckms()
          • to_nbody()
          • to_origin()
          • to_pckms()
          • to_pcmyr()
          • to_radec()
          • to_sky()
          • to_sudays()
          • to_units()
          • virialize()
    • clustertools.io package
      • Submodules
        • clustertools.io.amuse module
        • clustertools.io.astropy_table module
        • clustertools.io.galpydf module
        • clustertools.io.gyrfalcon module
        • clustertools.io.limepydf module
          • c_to_w0()
          • w0_to_c()
        • clustertools.io.load module
          • advance_cluster()
          • load_cluster()
        • clustertools.io.nbody6 module
        • clustertools.io.nbody6pp module
        • clustertools.io.orbit module
        • clustertools.io.snapshot module
    • clustertools.tidaltail package
      • Submodules
        • clustertools.tidaltail.tails module
          • tail_path()
          • tail_path_match()
          • to_tail()
    • clustertools.util package
      • Submodules
        • clustertools.util.constants module
          • kwtypes()
        • clustertools.util.coordinates module
          • cart_to_cyl()
          • cart_to_sky()
          • cart_to_sphere()
          • cyl_coords()
          • cyl_to_cart()
          • sky_coords()
          • sphere_coords()
          • sphere_to_cart()
        • clustertools.util.output module
          • fortout()
          • gyrout()
          • snapout()
          • sseout()
        • clustertools.util.plots module
          • skyplot()
          • starplot()
        • clustertools.util.recipes module
          • binmaker()
          • distance()
          • dx_function()
          • interpolate()
          • mean_prof()
          • minimum_distance()
          • nbinmaker()
          • power_law_distribution_function()
          • roaming_binmaker()
          • roaming_nbinmaker()
          • smooth()
          • tapered_dx_function()
          • x_hist()
        • clustertools.util.units module

Planned Future Additions

• Add PeTar to list of readable codes (in progress)

• Allow for the use of astropy units

• Be able to initialize orbits and clusters based on Holger Baumgardt’s Galactic Globular Clusters Database (https://people.smp.uq.edu.au/HolgerBaumgardt/globular/)

• Incorporate other methods for estimating a cluster’s dynamical age (A+, Blue Stragglers)

• More analysis features for binary stars

• Allow for stars to be tagged as members of different subpopulations for the study of multiple populations

• More analysis features that are comparable to standard techniques used by observers

• Include options for planetary systems around individual stars

• A simulation class that reads in all timesteps of a simulation