Quickstart Guide#

Introduction#

Galaxy clusters are the largest gravitationally bound objects in the universe and the current endpoints of the process of cosmological structure formation. Clusters are made of dark matter (DM), the hot, magnetized, and X-ray-emitting gas known as the intracluster medium (ICM), and their constituent galaxies.

For many applications, especially those focusing on the properties of the DM and ICM, clusters can be approximated as roughly spherically symmetric objects. This is often done using standard radial profiles for the various physical properties of the cluster, as well as assuming hydrostatic and virial equilibrium.

These models are especially useful for semi-analytic studies and idealized N-body / (magneto)hydrodynamic simulations of clusters, whether of single objects or mergers between two or more. This is the purpose of the cluster_generator package, which generates equilibrium cluster models from radial profile inputs. These models can be used to produce distributions of gas, DM, and star particles in hydrostatic and virial equilibrium for input into simulations. There is also the ability to create magnetic or velocity fields in three dimensions based on the properties of the cluster(s) which are modeled. Finally, cluster_generator can be used to set up initial conditions for single-cluster or merger simulations for a number of N-body/hydrodynamic codes used in the astrophysics community.

Installing the Package#

The cluster_generator package can be obtained for python versions 3.8 and up. The first step towards working with CG is obtaining the package. There are a few ways to do this, we encourage you to choose the best option from those below and follow their instructions to obtain the package:

🌐 From PyPI

Not Yet Implemented

Pardon our dust, we’ve not quite finished implementing this feature. We will update this page once this feature is finished.

📡 From PIP

Not Yet Implemented

Pardon our dust, we’ve not quite finished implementing this feature. We will update this page once this feature is finished.

🐍 From CONDA

Not Yet Implemented

Pardon our dust, we’ve not quite finished implementing this feature. We will update this page once this feature is finished.

📃 From Source [Recommended]

Installing the library directly from the source code is surprisingly easy! To get started, navigate to the directory in which you would like to place the raw source code and use the following git command:

pip install git+https://www.github.com/jzuhone/cluster_generator

This will generate a clone of the code in your local directory and install the software all at the same time.

Dependencies#

cluster_generator is compatible with Python 3.8+, and requires the following Python packages:

  • unyt [Units and quantity manipulations]

  • numpy [Numerical operations]

  • scipy [Interpolation and curve fitting]

  • h5py [h5 file interaction]

  • tqdm [Progress bars]

  • ruamel.yaml [yaml support]

  • dill [Serialization]

  • halo [Progress Spinners]

  • pandas [Dataset Manipulations]

These will be installed automatically if you use pip or conda as detailed below.

Note

There are a variety of additional libraries which provide very useful interfacing utilities for CG. Though not required, we do recommend installing the following libraries to maximize the utility of the package:

  • [yt project]: Used to generate in-memory, 3D-grid datasets for the models and ICs generated in cluster generator. This can be used to generate plots, measure profiles and complete other useful pre-simulation tasks.

  • [PyXSIM]: PyXSIM can be used to generate simulated photon lists from yt datasets which can then be analyzed to get spectra and which can be passed to an instrumentation simulator for mock observation.

  • [SOXS]: Complementing PyXSIM, SOXS is an instrument simulator which allows users to convert photon lists from PyXSIM into mock observations to be studied.

Getting Started#

To begin using cluster_generator, first install the library by following the instructions in the Installing the Package section.

Once you’ve installed the package, have a look at the note on unit conventions (here). Once you’re familiar with the units, we recommend you begin on this page by reading through our quickstart guide to get your feet wet.

Quickstart Guides#

Your First Journey with CG

Learn the basics of CG while taking a model of galaxy cluster Abell 133 all the way from literature to RAMSES simulation. This guide will show you the basic pipeline from analytical profiles to actually running a simulation.

beginner 20min

The Gravitational Wonderland

Learn the is and outs of CG’s non-Newtonian gravitational theories in this step by step guide for producing MONDian simulations.

beginner 20min feature nyi

Collections

Learn how to pull cluster models directly from literature using the collection module.

beginner 10min feature nyi

Virialization Methods

Learn about the ins and outs of virialization in CG’s initial conditions.

intermediate 20min nyi

Correcting Non-Physical Behaviors

In this guide, we consider the cluster A133 and its analytical model, which is non-physical in certain radii. We show the tools available for correcting these issues.

beginner 20min nyi

If you’re already somewhat familiar with the code and you’re looking for something a little more in depth, the following sections may provide a more concrete introduction to many of the core aspects of the code:

The best place to start is Radial Profiles, to see which analytical radial profile models for gas, DM, and star properties can be used to create equilibrium models, which are discussed in the Cluster Models section. This section begins with some helpful mathematical background in Cluster Models: Mathematical Overview. For some, this may be all you need.

However, if you want to use these models to generate particles for simulations or other analysis, check out the Particles section. For setting up DM and/or star particles in virial equilibrium, Virial Equilibria: Mathematical Overview provides a mathematical overview.

If you want to create 3-dimensional magnetic or velocity fields based on the cluster properties, check out Generating 3D Cluster Fields.

Finally, though one can follow all of the steps individually to create initial conditions for simulations, cluster_generator provides some handy tools and documentation to create initial conditions for a number of popular codes in the Initial Conditions Generation and Simulation Software sections.

Code examples are given throughout the text, but some fully-worked examples of generating models from start to finish are given in the Examples section.

Units#

The unit system assumed in cluster_generator is designed to use units appropriate for cluster scales:

  • Length: \({\rm kpc}\)

  • Time: \({\rm Myr}\)

  • Mass: \({\rm M_\odot}\)

From these three, the units for other quantities, such as density, pressure, specific energy, gravitational potential, etc. are straighforwardly derived. These are the units which will be assumed for all inputs (whether arrays or scalars) to the functions in cluster_generator, unless otherwise specified in the documentation and/or docstrings. What this means in practice is that if one supplies an input without units, it is assumed to be in the above units depending on the type of input (e.g., position, velocity, etc.). If you supply an input with units attached from yt or unyt, it will be converted to the above units internally before performing any calculations.

Some examples:

Most quantities which are returned as outputs of cluster_generator functions have units attached, using unyt. These are usually in the above unit system. For some output quantities, these units are sometimes used:

  • Number density: \({\rm cm^{-3}}\)

  • Temperature: \({\rm keV}\)

  • Entropy: \({\rm keV~cm^2}\)