██████╗ ███████╗████████╗ █████╗ ██████╗ 
    ██╔══██╗██╔════╝╚══██╔══╝██╔══██╗██╔══██╗
    ██████╔╝█████╗     ██║   ███████║██████╔╝
    ██╔═══╝ ██╔══╝     ██║   ██╔══██║██╔══██╗
    ██║     ███████╗   ██║   ██║  ██║██║  ██║
    ╚═╝     ╚══════╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝

PeTar is an N-body code specifically designed for modeling collisional stellar systems, where factors such as multiplicity (binaries, triples, etc.) and close encounters play a crucial role in dynamical evolution. PeTar offers several key advantages:

• Precise gravitational force modeling: PeTar does not employ any softening of gravitational force, enabling accurate tracking of the orbital evolution of binaries, triples, and close encounters.

• Incorporation of single and binary stellar evolution: Within the N-body simulation, PeTar dynamically evolves the masses, radii, and stellar types of individual stars. It also tracks significant events like supernovae, mass transfer, common envelope interactions, and binary mergers caused by stellar coalescence/collision and gravitational wave emission.

• Galactic potential inclusion: PeTar allows for the simulation of tidal effects on stellar systems by incorporating the galactic potential.

• Parallel computing capabilities: PeTar leverages multi-CPU processors/threads and GPU acceleration to accelerate simulations. This enables handling of over $10^7$ particles with a $100%$ binary fraction.

• Interoperability with other codes: PeTar can function as a module within other codes, facilitating the simulation of complex stellar environments. This includes compatibility with frameworks like AMUSE and SPH-based hydrodynamical code Asura-bridge.

The core N-body algorithm of PeTar encompasses three distinct methods, each tailored to the separation distance between individual pairs of particles (stars):

• Barnes-Hut tree method: This technique, introduced by Barnes and Hut in 1986, is utilized for computing long-range forces between particles. These forces are then integrated using a second-order symplectic leap-frog integrator.

• Fourth-order Hermite integrator with block time steps: PeTar employs this integrator, inspired by Aarseth's work in 2003, to precisely integrate the orbits of stars and the centers-of-mass of multiple systems. It is particularly effective for handling short-range forces.

• Slow-down algorithmic regularization (SDAR) method: PeTar leverages the SDAR method, developed by Wang, Nitadori, and Makino in 2020, to integrate the dynamics of close-distance multiple systems. This is especially useful for scenarios involving hyperbolic encounters, binaries, and hierarchical few-body systems.

The core implementation of PeTar is predominantly in the C++ programming language. However, external modules within PeTar can be written in various programming languages. The data analysis tool accompanying PeTar is developed in Python 3. Users are required to have a fundamental understanding of Python to effectively interact with the simulation data. In particular, users are encouraged to familiarize themselves with key Python modules such as numpy, dict, and matplotlib. These modules encompass a wide range of functions essential for tasks like data reading, processing, and visualization.

This README document serves as a concise yet comprehensive guide detailing the installation and utilization of the code. It is strongly recommended that users thoroughly review this documentation before reaching out to the developers with any queries.

For a deeper understanding of the algorithms employed, additional details can be found in the work by Wang et al. (2020; available on arXiv: https://arxiv.org/abs/2006.16560). For developers seeking to understand the code structure, please consult the Doxygen documentation.

After completing the installation process, users can quickly get started by exploring three sample scripts located in the sample folder: star_cluster.sh, star_cluster_bse.sh, and star_cluster_bse_galpy.sh. These scripts provide practical demonstrations of simulating a star cluster using the PeTar code. They cover tasks such as generating initial conditions using mcluster, running simulations, and processing data to produce single and binary snapshots, core information, and Lagrangian radii. Here is a brief description of each script:

• star_cluster.sh: Simulates a star cluster for up to 100 Myr with 1000 stars initially, following the Kroupa (2001) IMF and including 95% primordial binaries (refer to the mcluster manual). This simulation uses only gravitational forces.
• star_cluster_bse.sh: Similar to sample.sh but includes single and binary stellar evolution (SSE/BSE) with a metallicity of Z=0.02.
• star_cluster_bse_galpy.sh: Builds upon sample_bse.sh by incorporating the Milky Way potential from Galpy's MWPotential2014 (refer to Bovy 2015 for details).

Furthermore, users can access a Jupyter Notebook titled data_analysis.ipynb, which provides examples of data analysis in Python. By running one of the sample scripts, users can subsequently refer to the demonstrations in this notebook to analyze the simulation results. The data analysis module in PeTar offers greater convenience compared to manually parsing the output files. It is advisable to leverage this module instead of crafting reading code from scratch.

About the version

PeTar code is maintained across multiple branches, and for users seeking stability, it is advisable to obtain the released version. The master branch undergoes regular updates to introduce new features and address bugs. Users can opt for this version if they find the new features beneficial.

Other branches may not function correctly, and users are advised against interacting with them unless they have consulted the developer and comprehended the implementations and existing issues.

Users can retrieve the code version by running petar -h or using petar to start a simulation. The code version will be presented in the format [petar version][suffix]_[SDAR version], where:

• [petar version] represents the commit count of the PeTar code.
• [SDAR version] indicates the commit count of the SDAR code.
• [suffix] signifies the development mode. If absent, it denotes the master version. If [suffix] is e or another term, it indicates an experimental or specialized version.

The major modes are as follows:

• Release mode (r): This mode signifies a stable version recommended for general use. Release versions are infrequently updated, with the initial release currently being prepared.
• Master mode: This mode is suitable for most conditions and is expected to function correctly. Users can use it for production runs.
• Develop mode (e): In this mode, the code should operate correctly but may contain bugs that lead to unexpected results. It is advisable to consult developers before use.
• Test mode (test): This mode is unverified for proper functioning and should not be employed for production purposes.

The subsequent sections provide detailed explanations of the installation process and usage instructions. The final sections offer a brief overview of the methods employed in the code and introduce the AMUSE API.

Content:

• Installation
  • Dependence
    • Galpy
    • Code path
  • Environment requirements
    • For supercomputer
  • Configuration
    • Installation Path
    • Modifying MPI Parallelization Options
    • Manual Compiler Selection
    • Disabling OpenMP parallelization
    • Selecting CPU Architecture
    • Selecting SIMD Instructions
    • Enabling GPU Acceleration
    • Debug mode
    • Utilizing Stellar Evolution
    • Using External Potential
    • Combining Multiple options
  • Compilation and Installation
• Usage
  • Preparing the initial condition
  • Starting a Simulation
  • Resuming a Simulation
  • Using OpenMP
  • Using MPI
  • Using GPU
  • Options
  • Performance Optimization
    • Tree time step
    • Outer changeover radius
    • Neighbor searching radius
    • Multiple group radius
    • Adjusting tree time step and radii
  • Output
    • Printed Information
    • Output Files
    • Units
      • PeTar Units
      • Stellar Evolution Units
      • External Potential Units
      • Output File Units
  • Troubleshooting
    • [Significant Hard energy