Circumbinary disk framework

compas_python_utils/preprocessing/compasConfigDefault.yaml

@@ -1,5 +1,5 @@
 ##~!!~## COMPAS option values
-##~!!~## File Created Mon Feb  2 10:03:24 2026 by COMPAS v03.29.00
+##~!!~## File Created Sun Nov  1 20:57:27 2026 by COMPAS v03.31.00
 ##~!!~##
 ##~!!~## The default COMPAS YAML file (``compasConfigDefault.yaml``), as distributed, has
 ##~!!~## all COMPAS option entries commented so that the COMPAS default value for the
@@ -53,6 +53,9 @@ booleanChoices:
 #    --common-envelope-lambda-nanjing-use-rejuvenated-mass: False          # Default: False
 #    --revised-energy-formalism-nandez-ivanova: False                      # Default: False
 
+    ### CIRCUMBINARY DISK
+#    --circumbinary-disk: False                                            # Default: False
+
     ### SUPERNOVAE, KICKS AND REMNANTS
 #    --allow-non-stripped-ECSN: False                                      # Default: False
 #    --pair-instability-supernovae: True                                   # Default: True
@@ -169,6 +172,17 @@ numericalChoices:
 #    --common-envelope-second-stage-beta: 0.000000                         # Default: 0.000000
 #    --common-envelope-slope-kruckow: -0.833333                            # Default: -0.833333
 #    --maximum-mass-donor-nandez-ivanova: 2.000000                         # Default: 2.000000
+#    --post-common-envelope-eccentricity-cap: 0.100000                     # Default: 0.100000
+#    --post-common-envelope-eccentricity-fraction: 0.100000                # Default: 0.100000
+
+    ### CIRCUMBINARY DISK
+#    --circumbinary-disk-beta: 3.000000                                    # Default: 3.000000
+#    --circumbinary-disk-eddington-cap-factor: 1.000000                    # Default: 1.000000
+#    --circumbinary-disk-eddington-ge23-factor: 0.666667                   # Default: 0.666667
+#    --circumbinary-disk-envelope-mass-fraction-supplied: 0.050000         # Default: 0.050000
+#    --circumbinary-disk-inner-radius-over-separation: 2.500000            # Default: 2.500000
+#    --circumbinary-disk-lifetime: 100000.00                               # Default: 100000.00
+#    --circumbinary-disk-structure-factor: 4.000000                        # Default: 4.000000
 
     ### SUPERNOVAE, KICKS AND REMNANTS
 #    --eddington-accretion-factor: 1.000000                                # Default: 1.000000                                                                                                                                                                         # multiplication Factor for eddington accretion onto NS&BH
@@ -264,7 +278,7 @@ stringChoices:
 #    --case-BB-stability-prescription: 'ALWAYS_STABLE'                     # Default: 'ALWAYS_STABLE'               # Options: ['ALWAYS_UNSTABLE','TREAT_AS_OTHER_MT','ALWAYS_STABLE_ONTO_NSBH','ALWAYS_STABLE']
 #    --critical-mass-ratio-prescription: 'NONE'                            # Default: 'NONE'                        # Options: ['HURLEY_HJELLMING_WEBBINK','GE','GE_IC','CLAEYS','NONE']
 #    --stellar-zeta-prescription: 'SOBERMAN'                               # Default: 'SOBERMAN'                    # Options: ['ARBITRARY','HURLEY','SOBERMAN']
-#    --mass-transfer-angular-momentum-loss-prescription: 'ISOTROPIC'       # Default: 'ISOTROPIC'                   # Options: ['ARBITRARY','KLENCKI_LINEAR','MACLEOD_LINEAR','CIRCUMBINARY','ISOTROPIC','JEANS']
+#    --mass-transfer-angular-momentum-loss-prescription: 'ISOTROPIC'       # Default: 'ISOTROPIC'                   # Options: ['MIN','ARBITRARY','KLENCKI_LINEAR','MACLEOD_LINEAR','CIRCUMBINARY','ISOTROPIC','JEANS']
 #    --mass-transfer-accretion-efficiency-prescription: 'THERMAL'          # Default: 'THERMAL'                     # Options: ['HAMSTARS','FIXED','THERMAL']
 #    --mass-transfer-rejuvenation-prescription: 'STARTRACK'                # Default: 'STARTRACK'                   # Options: ['STARTRACK','HURLEY']
 #    --mass-transfer-thermal-limit-accretor-multiplier: 'CFACTOR'          # Default: 'CFACTOR'                     # Options: ['ROCHELOBE','CFACTOR']
@@ -274,7 +288,11 @@ stringChoices:
 #    --common-envelope-formalism: 'ENERGY'                                 # Default: 'ENERGY'                      # Options: ['TWO_STAGE','ENERGY']
 #    --common-envelope-lambda-prescription: 'LAMBDA_NANJING'               # Default: 'LAMBDA_NANJING'              # Options: ['LAMBDA_DEWI','LAMBDA_KRUCKOW','LAMBDA_NANJING','LAMBDA_LOVERIDGE','LAMBDA_FIXED']                                                     # Xu & Li 2010
 #    --common-envelope-mass-accretion-prescription: 'ZERO'                 # Default: 'ZERO'                        # Options: ['CHEVALIER','MACLEOD','UNIFORM','CONSTANT','ZERO']
-#    --common-envelope-second-stage-gamma-prescription: 'ISOTROPIC'        # Default: 'ISOTROPIC'                   # Options: ['ARBITRARY','KLENCKI_LINEAR','MACLEOD_LINEAR','CIRCUMBINARY','ISOTROPIC','JEANS']
+#    --common-envelope-second-stage-gamma-prescription: 'ISOTROPIC'        # Default: 'ISOTROPIC'                   # Options: ['MIN','ARBITRARY','KLENCKI_LINEAR','MACLEOD_LINEAR','CIRCUMBINARY','ISOTROPIC','JEANS']
+#    --post-common-envelope-eccentricity-prescription: 'CIRCULAR'          # Default: 'CIRCULAR'                    # Options: ['PRE_RLOF_FRACTION','PRE_RLOF_CAP','CIRCULAR']
+
+    ### CIRCUMBINARY DISK
+#    --circumbinary-disk-eddington-mode: 'GE23'                            # Default: 'GE23'                        # Options: ['TM23','GE23','CAP']
 
     ### TIDES
 #    --tides-prescription: 'NONE'                                          # Default: 'NONE'                        # Options: ['ZAHN1977','KAPIL2026','PERFECT','NONE']

online-docs/pages/Getting started/getting-started.rst

@@ -11,7 +11,7 @@ To start using COMPAS, `git clone` the code, install dependencies and build COMP
 Install dependencies
 --------------------
 
-COMPAS requires a ``C++`` compiler, and the ``gsl``, ``boost``, and ``hdf5`` libraries.  ``Python`` is required for the COMPAS post-processing tools.
+COMPAS requires a ``C++`` compiler, and the ``gsl``, ``boost``, and ``hdf5`` libraries.  ``Python`` is required for the COMPAS post-processing tools. Use of the circumbinary disk module requires installing `spindler-c <https://github.com/ruggero-valli/spindler-c>`_.
 
 
 .. tabs::

online-docs/pages/User guide/COMPAS output/standard-logfiles-default-record-specifications-BSE-circumbinary-disks.rst

@@ -0,0 +1,21 @@
+BSE circumbinary disks
+======================
+
+Default record definition for the BSE Circumbinary Disks log file::
+
+    const ANY_PROPERTY_VECTOR BSE_CIRCUMBINARY_DISKS_REC = {
+        BINARY_PROPERTY::RANDOM_SEED,
+        BINARY_PROPERTY::CIRCUMBINARY_DISK_FORMATION_TIME,
+        BINARY_PROPERTY::CIRCUMBINARY_DISK_INITIAL_MASS,
+        BINARY_PROPERTY::CIRCUMBINARY_DISK_MASS_SUPPLIED,
+        BINARY_PROPERTY::CIRCUMBINARY_DISK_MASS_RETAINED_1,
+        BINARY_PROPERTY::CIRCUMBINARY_DISK_MASS_RETAINED_2,
+        BINARY_PROPERTY::CIRCUMBINARY_DISK_SEMI_MAJOR_AXIS_PRE,
+        BINARY_PROPERTY::CIRCUMBINARY_DISK_SEMI_MAJOR_AXIS_POST,
+        BINARY_PROPERTY::CIRCUMBINARY_DISK_ECCENTRICITY_PRE,
+        BINARY_PROPERTY::CIRCUMBINARY_DISK_ECCENTRICITY_POST,
+        BINARY_PROPERTY::CIRCUMBINARY_DISK_MASS_1_AT_FORMATION,
+        BINARY_PROPERTY::CIRCUMBINARY_DISK_STELLAR_TYPE_1_AT_FORMATION,
+        BINARY_PROPERTY::CIRCUMBINARY_DISK_MASS_2_AT_FORMATION,
+        BINARY_PROPERTY::CIRCUMBINARY_DISK_STELLAR_TYPE_2_AT_FORMATION
+    };

online-docs/pages/User guide/COMPAS output/standard-logfiles-default-record-specifications.rst

@@ -27,6 +27,7 @@ For Binary Star Evolution (BSE):
    standard-logfiles-default-record-specifications-BSE-supernovae
    standard-logfiles-default-record-specifications-BSE-dco
    standard-logfiles-default-record-specifications-BSE-ce
+   standard-logfiles-default-record-specifications-BSE-circumbinary-disks
    standard-logfiles-default-record-specifications-BSE-pulsars
    standard-logfiles-default-record-specifications-BSE-rlof
    standard-logfiles-default-record-specifications-BSE-switchlog

online-docs/pages/User guide/COMPAS output/standard-logfiles-record-specification-binary.rst

@@ -49,6 +49,240 @@ Binary Properties
    * - Header String:
      - Tau_Circ
 
+
+.. flat-table::
+   :widths: 25 75 1 1
+   :header-rows: 0
+   :class: aligned-text
+
+   * - :cspan:`2` **CIRCUMBINARY_DISK_FORMED**
+     -
+   * - Data type:
+     - BOOL
+   * - COMPAS variable:
+     - BaseBinaryStar::m_CircumbinaryDiskDetails.formed
+   * - Description:
+     - Flag to indicate if a post-common-envelope circumbinary disk formed and was evolved.
+   * - Header String:
+     - CBD
+
+
+.. flat-table::
+   :widths: 25 75 1 1
+   :header-rows: 0
+   :class: aligned-text
+
+   * - :cspan:`2` **CIRCUMBINARY_DISK_MASS_SUPPLIED**
+     -
+   * - Data type:
+     - DOUBLE
+   * - COMPAS variable:
+     - BaseBinaryStar::m_CircumbinaryDiskDetails.massSupplied
+   * - Description:
+     - Mass supplied to the binary through the circumbinary disk, potentially less than the initial reservoir if interrupted (\ :math:`M_\odot`).
+   * - Header String:
+     - CBD_Mass_Supplied
+
+
+.. flat-table::
+   :widths: 25 75 1 1
+   :header-rows: 0
+   :class: aligned-text
+
+   * - :cspan:`2` **CIRCUMBINARY_DISK_MASS_RETAINED_1**
+     -
+   * - Data type:
+     - DOUBLE
+   * - COMPAS variable:
+     - BaseBinaryStar::m_CircumbinaryDiskDetails.massRetained1
+   * - Description:
+     - Mass retained by star 1 during circumbinary disk accretion (\ :math:`M_\odot`).
+   * - Header String:
+     - CBD_Mass_Retained(1)
+
+
+.. flat-table::
+   :widths: 25 75 1 1
+   :header-rows: 0
+   :class: aligned-text
+
+   * - :cspan:`2` **CIRCUMBINARY_DISK_MASS_RETAINED_2**
+     -
+   * - Data type:
+     - DOUBLE
+   * - COMPAS variable:
+     - BaseBinaryStar::m_CircumbinaryDiskDetails.massRetained2
+   * - Description:
+     - Mass retained by star 2 during circumbinary disk accretion (\ :math:`M_\odot`).
+   * - Header String:
+     - CBD_Mass_Retained(2)
+
+
+.. flat-table::
+   :widths: 25 75 1 1
+   :header-rows: 0
+   :class: aligned-text
+
+   * - :cspan:`2` **CIRCUMBINARY_DISK_SEMI_MAJOR_AXIS_PRE**
+     -
+   * - Data type:
+     - DOUBLE
+   * - COMPAS variable:
+     - BaseBinaryStar::m_CircumbinaryDiskDetails.semiMajorAxisPre
+   * - Description:
+     - Semi-major axis before circumbinary disk evolution (\ :math:`R_\odot`).
+   * - Header String:
+     - SemiMajorAxis<CBD
+
+
+.. flat-table::
+   :widths: 25 75 1 1
+   :header-rows: 0
+   :class: aligned-text
+
+   * - :cspan:`2` **CIRCUMBINARY_DISK_SEMI_MAJOR_AXIS_POST**
+     -
+   * - Data type:
+     - DOUBLE
+   * - COMPAS variable:
+     - BaseBinaryStar::m_CircumbinaryDiskDetails.semiMajorAxisPost
+   * - Description:
+     - Semi-major axis after circumbinary disk evolution (\ :math:`R_\odot`).
+   * - Header String:
+     - SemiMajorAxis>CBD
+
+
+.. flat-table::
+   :widths: 25 75 1 1
+   :header-rows: 0
+   :class: aligned-text
+
+   * - :cspan:`2` **CIRCUMBINARY_DISK_ECCENTRICITY_PRE**
+     -
+   * - Data type:
+     - DOUBLE
+   * - COMPAS variable:
+     - BaseBinaryStar::m_CircumbinaryDiskDetails.eccentricityPre
+   * - Description:
+     - Eccentricity before circumbinary disk evolution.
+   * - Header String:
+     - Eccentricity<CBD
+
+
+.. flat-table::
+   :widths: 25 75 1 1
+   :header-rows: 0
+   :class: aligned-text
+
+   * - :cspan:`2` **CIRCUMBINARY_DISK_ECCENTRICITY_POST**
+     -
+   * - Data type:
+     - DOUBLE
+   * - COMPAS variable:
+     - BaseBinaryStar::m_CircumbinaryDiskDetails.eccentricityPost
+   * - Description:
+     - Eccentricity after circumbinary disk evolution.
+   * - Header String:
+     - Eccentricity>CBD
+
+
+
+.. flat-table::
+   :widths: 25 75 1 1
+   :header-rows: 0
+   :class: aligned-text
+
+   * - :cspan:`2` **CIRCUMBINARY_DISK_FORMATION_TIME**
+     -
+   * - Data type:
+     - DOUBLE
+   * - COMPAS variable:
+     - BaseBinaryStar::m_CircumbinaryDiskDetails.formationTime
+   * - Description:
+     - Time at which the disk formed (Myr).
+   * - Header String:
+     - Time
+
+.. flat-table::
+   :widths: 25 75 1 1
+   :header-rows: 0
+   :class: aligned-text
+
+   * - :cspan:`2` **CIRCUMBINARY_DISK_INITIAL_MASS**
+     -
+   * - Data type:
+     - DOUBLE
+   * - COMPAS variable:
+     - BaseBinaryStar::m_CircumbinaryDiskDetails.initialReservoirMass
+   * - Description:
+     - Initial mass assigned to the CBD reservoir (\ :math:`M_\odot`).
+   * - Header String:
+     - Initial_CBD_Mass
+
+.. flat-table::
+   :widths: 25 75 1 1
+   :header-rows: 0
+   :class: aligned-text
+
+   * - :cspan:`2` **CIRCUMBINARY_DISK_MASS_1_AT_FORMATION**
+     -
+   * - Data type:
+     - DOUBLE
+   * - COMPAS variable:
+     - BaseBinaryStar::m_CircumbinaryDiskDetails.mass1AtFormation
+   * - Description:
+     - Mass of star 1 when the CBD formed (\ :math:`M_\odot`).
+   * - Header String:
+     - Mass(1)
+
+.. flat-table::
+   :widths: 25 75 1 1
+   :header-rows: 0
+   :class: aligned-text
+
+   * - :cspan:`2` **CIRCUMBINARY_DISK_MASS_2_AT_FORMATION**
+     -
+   * - Data type:
+     - DOUBLE
+   * - COMPAS variable:
+     - BaseBinaryStar::m_CircumbinaryDiskDetails.mass2AtFormation
+   * - Description:
+     - Mass of star 2 when the CBD formed (\ :math:`M_\odot`).
+   * - Header String:
+     - Mass(2)
+
+.. flat-table::
+   :widths: 25 75 1 1
+   :header-rows: 0
+   :class: aligned-text
+
+   * - :cspan:`2` **CIRCUMBINARY_DISK_STELLAR_TYPE_1_AT_FORMATION**
+     -
+   * - Data type:
+     - STELLAR_TYPE
+   * - COMPAS variable:
+     - BaseBinaryStar::m_CircumbinaryDiskDetails.stellarType1AtFormation
+   * - Description:
+     - Stellar type of star 1 when the CBD formed.
+   * - Header String:
+     - Stellar_Type(1)
+
+.. flat-table::
+   :widths: 25 75 1 1
+   :header-rows: 0
+   :class: aligned-text
+
+   * - :cspan:`2` **CIRCUMBINARY_DISK_STELLAR_TYPE_2_AT_FORMATION**
+     -
+   * - Data type:
+     - STELLAR_TYPE
+   * - COMPAS variable:
+     - BaseBinaryStar::m_CircumbinaryDiskDetails.stellarType2AtFormation
+   * - Description:
+     - Stellar type of star 2 when the CBD formed.
+   * - Header String:
+     - Stellar_Type(2)
+
 .. flat-table::
    :widths: 25 75 1 1
    :header-rows: 0