[AldanaGrichener]

Summary

This PR adds an optional post-common-envelope circumbinary disk (CBD) framework to COMPAS. The new framework checks whether a CBD can form in post-common-envelope systems containing a compact object (white dwarf, neutron star, or black hole) companion, based on angular-momentum considerations. If a CBD forms, the framework evolves the post-CEE binary under disk-driven accretion and angular-momentum exchange based on an external library called spindler-c. When the compact object accretion rate exceeds the Eddington limit, the framework applies an Eddington-related accretion correction, reducing the actually accreted mass and ejecting the difference as winds, which carry away angular momentum.

The framework is disabled by default, so existing COMPAS behavior is preserved unless the new CBD options are explicitly enabled by the user-supplied boolean option --circumbinary-disk.

I used ChatGPT as a coding assistant while translating my research prototype into main-branch-worthy (hopefully) C++ code. I've continuously reviewed the implementation and tested it against my prototype.

Motivation

Post-common-envelope CBDs affect the orbital separations, eccentricities, and masses of binary systems, and therefore their survival probabilities, merger times, and observable properties. This PR provides a first implementation of such a framework in COMPAS.

Main changes

• Adds a new CircumbinaryDisk module.
• Adds user-facing options controlling CBD formation and evolution.
• Adds CBD-related logging quantities, with output to BSE_Circumbinary_Disks.
• Adds documentation of the physical assumptions, units, and limitations.

Dependencies

Using the CBD module requires installing spindler-c, a library based on Valli et al. 2024, which itself requires librinterpolate. By default, COMPAS will compile without spindler-c, making the CBD module unavailable. COMPAS users who want to use the CBD module will have to supply paths to spindler-c at compile time, using SPINDLER_C_ROOT (and RINTERPOLATE_ROOT if required).

Modified files

• Adds: CircumbinaryDiskFormation.cpp, CircumbinaryDiskEvolutionSpindler.cpp, CircumbinaryDiskEvolutionUnavailable.cpp, and CircumbinaryDisk.h.
• Modifies: BaseBinaryStar.cpp, BaseBinaryStar.h, Log.cpp, Log.h, LogTypedefs.h, Makefile, Options.cpp, Options.h, constants.h, typedefs.h, yaml.h, and changelog.h.

CBD user-supplied options and their defaults

I've added several user-supplied options as part of the CBD framework. Here's a table summarizing the available options:

Option	Default	Allowed values / range	Symbol	Purpose
--circumbinary-disk	false	Boolean	—	Enables post-CEE circumbinary disk formation and evolution.
--circumbinary-disk-envelope-mass-fraction-supplied	0.05	[0, 0.2]; also requires $\beta f_M \leq 1$	$f_M$	Fraction of the total binary mass lost during CEE available for CBD formation.
--circumbinary-disk-beta	3.0	>= 0; also requires $\beta f_M \leq 1$	$\beta$	Ratio between the fraction of the pre-RLOF binary angular momentum and the fraction of the CEE mass loss available for CBD formation.
--circumbinary-disk-lifetime	1.0e5 yr	> 0 yr	$\tau_{CBD}$	Duration over which the supplied CBD mass is delivered.
--circumbinary-disk-structure-factor	4.0	> 1	$\zeta$	Disk structure factor multiplying the CBD angular-momentum threshold.
--circumbinary-disk-inner-radius-over-separation	2.5	>= 1	$R_{CBD,in}/a_{postCE}$	Inner radius of the CBD in units of the post-CE binary separation.
--circumbinary-disk-eddington-mode	GE23	CAP, GE23, TM23	—	Selects the Eddington-related CBD accretion prescription.
--circumbinary-disk-eddington-cap-factor	1.0	> 0	$c_{Edd}$	Multiplier applied to the Eddington accretion rate in CAP mode.
--circumbinary-disk-eddington-ge23-factor	2/3	(0, 1]	$f_{GE23}$	Retained fraction of the requested super-Eddington accretion rate in GE23 mode.
--post-common-envelope-eccentricity-prescription	CIRCULAR	CIRCULAR, PRE_RLOF_CAP, PRE_RLOF_FRACTION	—	Controls the eccentricity assigned immediately after CE.
--post-common-envelope-eccentricity-cap	0.1	[0, 1)	$e_{CE,max}$	Used by PRE_RLOF_CAP: $e_{postCE}=\min(e_{preRLOF},e_{CE,max})$.
--post-common-envelope-eccentricity-fraction	0.1	[0, 1]	$f_e$	Used by PRE_RLOF_FRACTION: $e_{postCE}=f_e e_{preRLOF}$.

CBD logic, options, and assumptions

CBD formation: Following Unger, Grichener & Soker 2026, we assume a CBD of mass $f_M M_{lost,CE}$ is formed whenever the system could retain enough angular momentum in the CE process to form one, where $M_{lost,CE}$ is the decrease in total binary mass during CE. The AM available for CBD formation is parametrized as $J_{avail}=\beta f_M J_{tot}$, where $J_{tot}$ is the binary's pre-RLOF total AM. The AM required to support a CBD with an inner radius $R_{CBD,in}$ is given by the Keplerian AM times the structure factor $\zeta$.

Evolution of the orbit and mass of the binary given a CBD: If a CBD is formed, the binary's total mass, mass ratio, semi-major axis, and eccentricity all evolve according to derivatives provided by spindler-c. The combination of total mass and mass ratio dictates the mass supplied to each binary component. A non-compact star accretes all the supplied mass, while accretion towards a white dwarf, neutron star, or black hole might be suppressed in case of super-Eddington accretion, which isn't accounted for in spindler-c. We thus add to spindler-c's derivatives terms which account for the Eddington limit. We allow three different suppression modes in case of super-Eddington accretion:

1. GE23 – $\dot{M}_{actual} = f_{GE23}\dot{M}_{supplied}$
   Allows for strongly super-Eddington accretion. Based on Ghodla & Eldridge 2023.
2. TM23 – $\dot{M}_{actual} \propto \dot{M}_{supplied} ^ {\frac{2}{5}}$
   Allows for mildly super-Eddington accretion. Based on Tuna & Metzger 2023.
3. CAP – $\dot{M}_{actual} = min(\dot{M}_{supplied}, c_{Edd} \dot{M}_{Edd})$
   Ad hoc option.

In all cases, the difference between the supplied and retained masses is assumed to be launched in winds from the accretor, carrying away its specific orbital angular momentum.

CBD lifetime: The supplied CBD mass is delivered over a user-specified lifetime at a constant rate. The CBD-binary interaction is evolved over successive COMPAS timesteps, concurrently with other processes such as winds and tides. To limit the mass supplied in a single timestep, we impose a maximum of $10^{-3}$ of the current binary mass, corresponding to $0.01,M_\odot$ for a $10,M_\odot$ binary. The disk can also be interrupted by subsequent evolutionary events.

Additional post-CEE eccentricity functionality

COMPAS sets the post-CEE eccentricity to zero by default, which makes sense since it is a big unknown, which usually doesn't impact the results much. However, since the CBD-driven orbital evolution, and particularly eccentricity pumping, is sensitive to the eccentricity at disk formation, I added a user-supplied option for --post-common-envelope-eccentricity-prescription. The options are:

1. CIRCULAR (default) – the regular COMPAS behavior.
2. PRE_RLOF_CAP – the user provides a maximal post-CEE eccentricity through --post-common-envelope-eccentricity-cap; the pre-RLOF eccentricity is retained if it is below the cap.
3. PRE_RLOF_FRACTION – the post-CEE eccentricity is set to a user-provided fraction of the pre-RLOF eccentricity through --post-common-envelope-eccentricity-fraction.

[ilyamandel]

This was thoroughly reviewed in https://github.com/AldanaGrichener/COMPAS-CBD/pull/1 , so happy to approve and merge. Great work, @AldanaGrichener !

[AldanaGrichener]

Thank you so much!! and thank you for all the useful suggestions throughout the process!