synthpop.modules.post_processing.process_dark_compact_objects
=============================================================

.. py:module:: synthpop.modules.post_processing.process_dark_compact_objects

.. autoapi-nested-parse::

   Post-processing to account for dim compact objects, based on PopSyCLE (Rose et al 2022).

   The module will take all objects that have evolved past the MIST grid, and assign them a final
   mass, removing their photometry. Optionally, one can just remove all of these objects instead.

   It can also optionally add random kick velocities to neutron stars and black holes, according to 
   a Maxwellian distribution with a user-input mean.



Classes
-------

.. autoapisummary::

   synthpop.modules.post_processing.process_dark_compact_objects.ProcessDarkCompactObjects


Module Contents
---------------

.. py:class:: ProcessDarkCompactObjects(model, logger, remove=False, ifmr_name='SukhboldN20', kick_mean_bh=0, kick_mean_ns=0, **kwargs)

   Bases: :py:obj:`synthpop.modules.post_processing._post_processing.PostProcessing`


   Post-processing to account for dim compact objects, based on PopSyCLE (Rose et al 2022).

   Attributes
   ----------
   remove=False : boolean
       if true, remove dark compact objects from the catalog
   ifmr_name='SukhboldN20' : string
       selected initial-final mass relation;
       options are 'SukhboldN20', 'Raithel18', 'Spera15'
   kick_mean_bh=0 : float
       mean of the maxwellian kick distribution for black holes (km/s)
   kick_mean_ns=0 : float
       mean of the maxwellian kick distribution for neutron stars (km/s)


   .. py:attribute:: remove
      :value: False



   .. py:attribute:: ifmr_name
      :value: 'SukhboldN20'



   .. py:attribute:: kick_mean_ns
      :value: 0



   .. py:attribute:: kick_mean_bh
      :value: 0



   .. py:method:: mass_bh(m_zams, feh, f_ej=0.9)

      Black hole mass calculation for Raithel18 and SukhboldN20

      Parameters
      ----------
      m_zams
          float or array of float values for initial stellar mass in units of solar mass
      f_ej
          float value representing the ejection fraction,
          or how much of the star's envelope is ejected in the supernova
          default value 0.9 adopted from Lam et al. (2020)

      Returns
      -------
      m_bh
          float or array of float values for final black hole mass in units of solar mass



   .. py:method:: mass_ns(m_zams)

      Neutron star final mass calculation, adopting the 1.36 Msun average
      with a standard deviation of 0.09.
      Based on PopSyCLE (Rose et al, 2022)

      Parameters
      ----------
      m_zams
          float or array of float values for initial stellar mass in units of solar mass

      Returns
      -------
      m_ns
          float or array of float values for final neutron star mass in units of solar mass



   .. py:method:: mass_wd(m_zams)

      White dwarf final mass calculation.
      Based on PopSyCLE (Rose et al. 2022)

      Parameters
      ----------
      m_zams
          float or array of float values for initial stellar mass in units of solar mass

      Returns
      -------
      m_wd
          float or array of float values for final white dwarf mass in units of solar mass



   .. py:method:: mass_spera15(m_zams, feh)

      Remnant mass calculation from Spera et al 2015, appendix C
      Takes in the m_zams and Fe/H as lists



   .. py:method:: compact_type_from_final(m_fin)

      Determination of compact object type from final mass
      Based on PopSyCLE (Lam et al 2020; Rose et al 2022)
      Which pulls from Spera et al 2015

      Parameters
      ----------
      m_fin
          float value for final mass in units of solar mass
      Returns
      -------
      m_type
          integer value indicating object type
          1 = dim white dwarf
          2 = neutron star
          3 = black hole



   .. py:method:: compact_type_validation(m_type, m_prelim, m_ns)

      Reassign low-mass BHs to NSs
      Based on PopSyCLE (Lam et al 2020; Rose et al 2022)

      Parameters
      ----------
      m_type
          int value for assigned compact object type
      m_prelim
          float value for compact object mass in units of solar mass
      m_ns
          float neutron star mass generated for the objects
      Returns
      -------
      m_type
          integer value indicating updated object type
          2 = neutron star
          3 = black hole
      m_compact
          updated mass of NS or BH



   .. py:method:: compact_type_from_initial(m_zams, feh)

      Probabilistic drawing of compact object types
      Based on PopSyCLE (Lam et al 2020; Rose et al 2022)
      Which pulls from Rathiel et al 2018 and Sukhbold et al 2020

      Parameters
      ----------
      m_zams
          array of float values for initial stellar mass in units of solar mass
      feh
          array of float values for initial metallicity [Fe/H]
      Returns
      -------
      m_type
          array of integer values indicating object type
          0 = non-compact object or luminous white dwarf
          1 = dim white dwarf
          2 = neutron star
          3 = black hole



   .. py:method:: do_post_processing(dataframe: pandas.DataFrame) -> pandas.DataFrame

      Perform the post-processing and return the modified DataFrame.