two-phase-galaxy-model 1.0.0
A Two-Phase Scenario of Galaxy Formation
Requires Python: >=3.11

<div align="center">
  <img width="400px" src="https://raw.githubusercontent.com/ChenYangyao/two-phase-galaxy-model/master/site-info/logo-small.png"/>
</div>

# TwoPhaseGalaxyModel - a Two-Phase Scenario of Galaxy Formation

[![Last commit](https://img.shields.io/github/last-commit/ChenYangyao/two-phase-galaxy-model/master)](https://github.com/ChenYangyao/two-phase-galaxy-model/commits/master)
[![Workflow Status](https://img.shields.io/github/actions/workflow/status/ChenYangyao/two-phase-galaxy-model/run-test.yml)](https://github.com/ChenYangyao/two-phase-galaxy-model/actions/workflows/run-test.yml)
[![MIT License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/ChenYangyao/two-phase-galaxy-model/blob/master/LICENSE)
[![PyPI](https://img.shields.io/pypi/v/two-phase-galaxy-model)](https://pypi.org/project/two-phase-galaxy-model/)


This repository contains the code of the semi-analytic implementation of the TwoPhaseGalaxyModel. All data and figures in the publications are also included in the repository.

## Installation

To install, run:
```bash
pip install two-phase-galaxy-model
```
All the dependencies will be installed automatically. Alternatively, you can clone the repository and install the package locally via `pip install -e /path/to/the/repo`.

## Usage 

To use the API in your Python project, import the package by:
```python
import two_phase_galaxy_model as tpgm
```
and then work with it.

Examples can be found in the Jupyter notebooks under `docs/`:
- [star_cluster_model.ipynb](docs/star_cluster_model.ipynb): demonstrates how to define a dark-matter-only subhalo merger tree, pass it to the model, and get the list of galaxies and star clusters.

## Publications

### List of publications

- (Paper-I) A two-phase model of galaxy formation: I. The growth of galaxies and supermassive black holes. *Houjun Mo, Yangyao Chen, and Huiyuan Wang, 2023* ([arxiv](https://arxiv.org/abs/2311.05030), [ads](https://ui.adsabs.harvard.edu/abs/arXiv:2311.05030)).
- (Paper-II) A two-phase model of galaxy formation: II. The size-mass relation of dynamically hot galaxies.
*Yangyao Chen, Houjun Mo, and Huiyuan Wang, 2023* ([arxiv](https://arxiv.org/abs/2311.11713), [ads](https://ui.adsabs.harvard.edu/abs/arXiv:2311.11713)).
- (Paper-III) A two-phase model of galaxy formation: III. The formation of globular clusters. *Yangyao Chen, Houjun Mo, and Huiyuan Wang, 2024* ([arxiv](http://arxiv.org/abs/2405.18735), [ads](https://ui.adsabs.harvard.edu/abs/arXiv:2405.18735)).

### Supplementary Material

- Paper-I: [figures](publications/Paper-I/figures) in the pdf format.
- Paper-II: [figures](publications/Paper-II/figures) in the pdf format.
- Paper-III: [figures](publications/Paper-III/figures) in the pdf format.

## Research Highlights

<div align="center" style="margin-top: 25px;">
    <div align="middle" style="display: flex; justify-content: center; gap: 4%" >
      <img width="28%px" src="https://raw.githubusercontent.com/ChenYangyao/two-phase-galaxy-model/master/site-info/highlights/phase-space-diagram.jpg"/>      
      <img width="28%px" src="https://raw.githubusercontent.com/ChenYangyao/two-phase-galaxy-model/master/site-info/highlights/dynamical-hot-stage.jpg"/>
      <img width="28%px" src="https://raw.githubusercontent.com/ChenYangyao/two-phase-galaxy-model/master/site-info/highlights/smbh-growth-am.jpg"/>
    </div>
    <div style="margin: 3px 10%; padding: 5px 0; background-color: rgba(0, 136, 255, 0.1);">
      <div> <strong>The phase diagram of galaxy formation and SMBH growth</strong> </div>
      <div>
        <strong>Left</strong>: The quadrant diagram showing four combinations of 
          halo assembly rate and the importance of angular momentum in supporting gas.
        <strong>Center</strong>: The formation of dynamically hot gas/stellar system in the fast stage of dark matter halo.
        <strong>Right</strong>: A schematic diagram showing the distribution of specific angular momentum (sAM)
        for gas clouds within a halo. The turbulent motion of gas clouds, 
        driven by fast accretion, yields a broad and uniform distribution 
        (red curve) of sAM. The fraction of gas accreted by the 
        SMBH (gray shaded area) is determined by the maximum capturing 
        angular momentum (see Paper-I).
      </div>
    </div>
</div>

<div align="center" style="margin-top: 25px;">
    <div>
      <img width="800px" src="https://raw.githubusercontent.com/ChenYangyao/two-phase-galaxy-model/master/site-info/highlights/gc-channels.jpg"/>
    </div>
    <div style="margin: 3px 10%; padding: 5px 0; background-color: rgba(0, 136, 255, 0.1);">
      <div> <strong>The two-channels of GC formation</strong> </div>
      <div>
        <strong>Left</strong>: The distribution of modeled GCs in a MW-size system at z=0.
        <strong>Right</strong>: The criteria for the active formation of Pop-I (red, metal-rich) and Pop-II (blue, metal-poor) GCs
        in the halo mass-redshift plane (See Paper-III).
      </div>
    </div>
</div>


<div align="center" style="margin-top: 25px;">
  <div>
    <img width="45%" src="https://raw.githubusercontent.com/ChenYangyao/two-phase-galaxy-model/master/site-info/highlights/tpcf.jpg"/>
  </div>
  <div style="margin: 3px 10%; padding: 5px 0; background-color: rgba(0, 136, 255, 0.1);">
    <div><strong>Cosmic structures traced by GC clustering over > 7 orders of magnitude in spatial extent</strong></div> 
    <div> Two-point auto-correlation functions of 
          GCs at z=0 predicted by the model in this work 
          and the corresponding gas process and cosmic structure at each hierarchy (See Paper-III). 
    </div>
  </div>
</div>


## Acknowledgements

Here we acknowledge the following projects and/or people that helped in the development of 
this code repository. Projects and/or people that are relevant to individual papers
were included in the papers.

Yangyao thanks [Kai Wang](https://www.kosmoswalker.com/) for his enduring 
companionship and support :wink:.

The empirical model 
[UniverseMachine](https://bitbucket.org/pbehroozi/universemachine/src/main/) for halo-galaxy connection,
and [TRINITY](https://github.com/HaowenZhang/TRINITY) for halo-galaxy-SMBH coevolution,
have inspired our work for model design and implementation. Their comprehensive
collection of observational datasets also helps us for model calibration and
comparison.

The SAM of Yingtian Chen, Oleg Y. Gnedin et al. ([source code](https://github.com/ybillchen/GC_formation_model)) 
and the [catalog](https://github.com/ognedin/gc_model_mw) produced by the model have been used for comparison of our model.

The Tsinghua Astrophysics High-Performance Computing platform has been
providing the computational and data storage resources throughout the 
career development of Yangyao.