mcfacts.physics.migration

Module for calculating the timescale of migrations.

mcfacts.physics.migration.jimenezmasset17_thermal_torque_coeff(smbh_mass, disk_surf_density_func, disk_opacity_func, disk_aspect_ratio_func, disk_temp_func, disk_bh_eddington_ratio, orbs_a, orbs_ecc, orb_ecc_crit, bh_masses, flag_thermal_feedback, disk_dlog10pressure_dlog10R_func, r_g_in_meters)

Return the Jimenez & Masset (2017) thermal torque coefficient for Type 1 migration Jimenez-Masset_thermal_torque_coeff = Torque_hot*(4mu_thermal/(1+4.*mu_thermal))+ Torque_cold*(2mu_thermal/(1+2.*mu_thermal))

Given Torque_hot=thermal_factor*(L/L_c)

Torque_cold =-thermal_factor

with L= 4piGm_bh*c/kappa_e_scattering (assuming f_Edd=1, the Eddington fraction of the luminosity) and L_c = 4pi G*m_bh*rho*Xi/gamma = 4pi G*m_bh Sigma x c_s/gamma since Xi=xH^2*Omega=x*c_s*H and with thermal_factor = 1.61*(gamma-1/gamma)*(x_c/lambda) where x_c = (dP/dr)*H^2/(3*gamma*R), lambda = sqrt(2Xi/3*gamma*Omega) & (x_c << lambda is assumed for approximation)

and mu_thermal = Xi/c_s*r_Bondi = x*H/r_Bondi where r_Bondi maximum is capped at H (cannot accrete from outside disk!) where c_s is local sound speed, r_Bondi = GM/c_s^2 and Xi = x*H^2*Omega =x*c_s*H where x=(16/3)*gamma*(gamma-1)*sigma_SB*T^4/kappa*rho^2*H^4*Omega^3

with gamma is the adiabatic index (Cp/Cv=5/3=1.66 for monatomic gas; 1.4 for diatomic gas): sigma_SB = Stefan Boltzmann constant (5.67*10^-8 J s^-1 m^-2 K^-4) kappa = disk opacity at location a rho = disk density at location a H = disk height at location a Omega = orbital frequency at location a
Note can rewrite x using Sigma = rho*H = rho*a*h: so rho^2H^4 = (rho*H)^2*H^2 = Sigma^2 (a*h)^2 and so x=(16/3)*gamma*(gamma-1)*sigma_SB*T^4/kappa*Sigma^2*a^2*h^2*Omega^3

mcfacts.physics.migration.jimenezmasset17_torque(smbh_mass, disk_surf_density_func, disk_opacity_func, disk_aspect_ratio_func, disk_temp_func, orbs_a, orbs_ecc, orb_ecc_crit, disk_dlog10surfdens_dlog10R_func, disk_dlog10temp_dlog10R_func, r_g_in_meters)

Return the Jimenez & Masset (2017) torque coefficient for Type 1 migration Jimenez-Masset_torque = [0.46 + 0.96dSigmadR -1/8dTdR]/gamma

+[-2.34 -0.1dSigmadR +1.5dTdR]*factor

where factor = ((x/2)^{1/2} + (1/gamma))/((x/2)^{1/2} + 1) and x=(16/3)*gamma*(gamma-1)*sigma_SB*T^4/kappa*rho^2*H^4*Omega^3 with gamma is the adiabatic index (Cp/Cv=5/3=1.66 for monatomic gas; 1.4 for diatomic gas)

sigma_SB = Stefan Boltzmann constant (5.67*10^-8 J s^-1 m^-2 K^-4) kappa = disk opacity at location a rho = disk density at location a H = disk height at location a Omega = orbital frequency at location a

Can rewrite x using Sigma = rho*H = rho*a*h
so rho^2H^4 = (rho*H)^2*H^2 = Sigma^2 (a*h)^2 and so x=(16/3)*gamma*(gamma-1)*sigma_SB*T^4/kappa*Sigma^2*a^2*h^2*Omega^3

mcfacts.physics.migration.normalized_torque(smbh_mass, orbs_a, masses, orbs_ecc, orb_ecc_crit, disk_surf_density_func, disk_aspect_ratio_func, r_g_in_meters)

Calculates the normalized torque from e.g. Grishin et al. ‘24 Gamma_0 = (q/h)^2 * Sigma* a^4 * Omega^2

where q= mass_of_bh/smbh_mass, h= disk aspect ratio at location of bh (a_bh), Sigma= disk surface density at a_bh, a=a_bh, Omega = bh orbital frequency at a_bh. Units are kg m^-2 * m^4 *s^-2 = kg (m s^-1)^2 = Nm (= J)

Parameters:

smbh_mass – float
SMBH (Mass [M_sun] of the)

orbs_anumpy.ndarray: Orbital semi-major axes [r_{g,SMBH}] wrt to SMBH of objects at start of a timestep (math:r_g=GM_{SMBH}/c^2) with float type
massesnumpy.ndarray: Masses [M_sun] of objects at start of timestep with float type
orbs_eccnumpy.ndarray: Orbital ecc [unitless] wrt to SMBH of objects at start of timestep :math:`mathtt{disk_radius_trap}. Floor in orbital ecc given by e_crit.
orb_ecc_critfloat: Critical value of orbital eccentricity [unitless] below which we assume Type 1 migration must occur. Do not damp orb ecc below this (e_crit=0.01 is default)
disk_surf_density_funcfunction: Returns AGN gas disk surface density [kg/m^2] given a distance [r_{g,SMBH}] from the SMBH can accept a simple float (constant), but this is deprecated
disk_aspect_ratio_funcfunction: Returns AGN gas disk aspect ratio [unitless] given a distance [r_{g,SMBH}] from the SMBH can accept a simple float (constant), but this is deprecated
r_g_in_meters: float: Gravitational radius of the SMBH in meters

mcfacts.physics.migration.paardekooper10_torque(orbs_a, orbs_ecc, orb_ecc_crit, disk_dlog10surfdens_dlog10R_func, disk_dlog10temp_dlog10R_func): Return the Paardekooper (2010) torque coefficient for Type 1 migration Paardekooper_Coeff = [-0.85+0.9dTdR +dSigmadR]

mcfacts.physics.migration.torque_mig_timescale(smbh_mass, orbs_a, masses, orbs_ecc, orb_ecc_crit, migration_torque, r_g_in_meters)

Calculates the migration timescale using an input migration torque t_mig = a/-(dot(a)) where dot(a)=-2aGamma_tot/L so t_mig = L/2Gamma_tot with Gamma_tot=migration torque, L = orb ang mom = m (GMa)^1/2=m Omega a^2 and so t_mig = m Omega a^2/2Gamma_tot in units of s. Gamma_0 = (q/h)^2 * Sigma* a^4 * Omega^2

where q= mass_of_bh/smbh_mass, h= disk aspect ratio at location of bh (a_bh), Sigma= disk surface density at a_bh, a=a_bh, Omega = bh orbital frequency at a_bh. Units are kg m^-2 * m^4 *s^-2 = kg (m s^-1)^2 = Nm (= J)

Parameters:

smbh_mass – float
SMBH (Mass [M_sun] of the)

orbs_anumpy.ndarray: Orbital semi-major axes [r_{g,SMBH}] wrt to SMBH of objects at start of a timestep (math:r_g=GM_{SMBH}/c^2) with float type
massesnumpy.ndarray: Masses [M_sun] of objects at start of timestep with float type
orbs_eccnumpy.ndarray: Orbital ecc [unitless] wrt to SMBH of objects at start of timestep :math:`mathtt{disk_radius_trap}. Floor in orbital ecc given by e_crit.
orb_ecc_critfloat: Critical value of orbital eccentricity [unitless] below which we assume Type 1 migration must occur. Do not damp orb ecc below this (e_crit=0.01 is default)
migration_torquenumpy.ndarray: Migration torque array. E.g. calculated from torque_paardekooper (units = Nm=J)
r_g_in_meters: float: Gravitational radius of the SMBH in meters

mcfacts.physics.migration.type1_migration(smbh_mass, orbs_a, masses, orbs_ecc, orb_ecc_crit, disk_surf_density_func, disk_aspect_ratio_func, disk_feedback_ratio_func, disk_radius_trap, disk_radius_outer, timestep_duration_yr)

Calculates how far an object migrates in an AGN gas disk in a single timestep

Assumes a gas disk surface density and aspect ratio profile, for objects of specified masses and starting locations, and returns their new locations after migration over one timestep.

This function replaces dr_migration which did not include smbh mass and was unreadable.

Parameters:

smbh_mass (float) – Mass [M_sun] of the SMBH
orbs_a (numpy.ndarray) – Orbital semi-major axes [r_{g,SMBH}] wrt to SMBH of objects at start of a timestep (math:r_g=GM_{SMBH}/c^2) with float type
masses (numpy.ndarray) – Masses [M_sun] of objects at start of timestep with float type
orbs_ecc (numpy.ndarray) – Orbital ecc [unitless] wrt to SMBH of objects at start of timestep :math:`mathtt{disk_radius_trap}. Floor in orbital ecc given by e_crit.
orb_ecc_crit (float) – Critical value of orbital eccentricity [unitless] below which we assume Type 1 migration must occur. Do not damp orb ecc below this (e_crit=0.01 is default)
disk_surf_density_func (function) – Returns AGN gas disk surface density [kg/m^2] given a distance [r_{g,SMBH}] from the SMBH can accept a simple float (constant), but this is deprecated
disk_aspect_ratio_func (function) – Returns AGN gas disk aspect ratio [unitless] given a distance [r_{g,SMBH}] from the SMBH can accept a simple float (constant), but this is deprecated
disk_feedback_ratio_func (function) – Ratio of heating/migration torque [unitless]. If ratio <1, migration inwards, but slows by factor tau_mig/(1-R) if ratio >1, migration outwards on timescale tau_mig/(R-1)
disk_radius_trap (float) – Radius [r_{g,SMBH}] of disk migration trap
disk_radius_outer (float) – Radius [r_{g,SMBH}] of outer edge of disk
timestep_duration_yr (float) – Length of timestep [yr]

Returns:

orbs_a – Semi-major axes [r_{g,SMBH}] of objects at end of timestep

Return type:

float array

mcfacts.physics.migration.type1_migration_binary(smbh_mass, bin_mass_1, bin_mass_2, bin_orb_a, bin_orb_ecc, orb_ecc_crit, disk_surf_density_func, disk_aspect_ratio_func, disk_feedback_ratio_func, disk_radius_trap, disk_radius_outer, timestep_duration_yr)

Wrapper function for type1_migration for binaries in the disk.

Assumes a gas disk surface density and aspect ratio profile, for objects of specified masses and starting locations, and returns their new locations after migration over one timestep.

This function replaces dr_migration which did not include smbh mass and was unreadable.

Parameters:

smbh_mass (float) – Mass [M_sun] of the SMBH
blackholes_binary (AGNBinaryBlackHole) – Binary black hole parameters, including mass_1, mass_2, bin_orb_a, and bin_orb_ecc
orb_ecc_crit (float) – Critical value of orbital eccentricity [unitless] below which we assume Type 1 migration must occur. Do not damp orb ecc below this (e_crit=0.01 is default)
disk_surf_density_func (function) – Returns AGN gas disk surface density [kg/m^2] given a distance [r_{g,SMBH}] from the SMBH can accept a simple float (constant), but this is deprecated
disk_aspect_ratio_func (function) – Returns AGN gas disk aspect ratio [unitless] given a distance [r_{g,SMBH}] from the SMBH can accept a simple float (constant), but this is deprecated
disk_feedback_ratio_func (function) – Ratio of heating/migration torque [unitless]. If ratio <1, migration inwards, but slows by factor tau_mig/(1-R) if ratio >1, migration outwards on timescale tau_mig/(R-1)
disk_radius_trap (float) – Radius [r_{g,SMBH}] of disk migration trap
disk_radius_outer (float) – Radius [r_{g,SMBH}] of outer edge of disk
timestep_duration_yr (float) – Length of timestep [yr]

Returns:

orbs_a – Semi-major axes [r_{g,SMBH}] of objects at end of timestep

Return type:

float array

mcfacts.physics.migration.type1_migration_distance(smbh_mass, orbs_a, masses, orbs_ecc, orb_ecc_crit, torque_mig_timescale, disk_feedback_ratio, disk_radius_trap, disk_radius_anti_trap, disk_radius_outer, timestep_duration_yr, flag_phenom_turb, phenom_turb_centroid, phenom_turb_std_dev, bh_min_mass, torque_prescription)

Calculates how far an object migrates in an AGN gas disk in a single timestep given a torque migration timescale calculated elsewhere (e.g. torque_migration_timescale) Returns their new locations after migration over one timestep.

Parameters:

smbh_mass (float) – Mass [M_sun] of the SMBH
orbs_a (numpy.ndarray) – Orbital semi-major axes [r_{g,SMBH}] wrt to SMBH of objects at start of a timestep (math:r_g=GM_{SMBH}/c^2) with float type
masses (numpy.ndarray) – Masses [M_sun] of objects at start of timestep with float type
orbs_ecc (numpy.ndarray) – Orbital ecc [unitless] wrt to SMBH of objects at start of timestep :math:`mathtt{disk_radius_trap}. Floor in orbital ecc given by e_crit.
orb_ecc_crit (float) – Critical value of orbital eccentricity [unitless] below which we assume Type 1 migration must occur. Do not damp orb ecc below this (e_crit=0.01 is default)
torque_mig_timescale (numpy.ndarray) – Array of timescale of torque to migrate onto SMBH (units in seconds)
disk_feedback_ratio (function) – Ratio of heating/migration torque [unitless]. If ratio <1, migration inwards, but slows by factor tau_mig/(1-R) if ratio >1, migration outwards on timescale tau_mig/(R-1)
disk_radius_trap (float) – Radius [r_{g,SMBH}] of disk migration trap
disk_radius_antitrap (float) – Radius [r_{g,SMBH}] of disk anti-trap (divergent trap)
disk_radius_outer (float) – Radius [r_{g,SMBH}] of outer edge of disk
timestep_duration_yr (float) – Length of timestep [yr]
flag_phenom_turb (int) – Is phenomenological turbulence model on (1) or off (0).
phenom_turb_centroid (float) – Centroid of Gaussian draw of turbulent modification to migration distance (default is 0: no net drift!)
phenom_turb_std_dev (float) – Standard deviation of Gaussian draw of turbulent perturbation (default is 0.1)
bh_min_mass (float) – Minimum mass of BH IMF. Phenom. turbulence is largest for this value. Decreases with bh_mass^2 since normalized torque propto m_bh^2.
torque_prescription (str) – Torque prescription ‘paardekooper’ or ‘jimenez_masset’ (‘old’ is deprecated)

Returns:

orbs_a – Semi-major axes [r_{g,SMBH}] of objects at end of timestep

Return type:

float array

mcfacts.physics.migration.type1_migration_single(smbh_mass, orbs_a, masses, orbs_ecc, orb_ecc_crit, disk_surf_density_func, disk_aspect_ratio_func, disk_feedback_ratio_func, disk_radius_trap, disk_radius_outer, timestep_duration_yr)

Wrapper function for type1_migration for single objects in the disk.

Assumes a gas disk surface density and aspect ratio profile, for objects of specified masses and starting locations, and returns their new locations after migration over one timestep.

This function replaces dr_migration which did not include smbh mass and was unreadable.

Parameters:

smbh_mass (float) – Mass [M_sun] of the SMBH
orbs_a (numpy.ndarray) – Orbital semi-major axes [r_{g,SMBH}] wrt to SMBH of objects at start of a timestep (math:r_g=GM_{SMBH}/c^2) with float type
masses (numpy.ndarray) – Masses [M_sun] of objects at start of timestep with float type
orbs_ecc (numpy.ndarray) – Orbital ecc [unitless] wrt to SMBH of objects at start of timestep :math:`mathtt{disk_radius_trap}. Floor in orbital ecc given by e_crit.
orb_ecc_crit (float) – Critical value of orbital eccentricity [unitless] below which we assume Type 1 migration must occur. Do not damp orb ecc below this (e_crit=0.01 is default)
disk_surf_density_func (function) – Returns AGN gas disk surface density [kg/m^2] given a distance [r_{g,SMBH}] from the SMBH can accept a simple float (constant), but this is deprecated
disk_aspect_ratio_func (function) – Returns AGN gas disk aspect ratio [unitless] given a distance [r_{g,SMBH}] from the SMBH can accept a simple float (constant), but this is deprecated
disk_feedback_ratio_func (function) – Ratio of heating/migration torque [unitless]. If ratio <1, migration inwards, but slows by factor tau_mig/(1-R) if ratio >1, migration outwards on timescale tau_mig/(R-1)
disk_radius_trap (float) – Radius [r_{g,SMBH}] of disk migration trap
disk_radius_outer (float) – Radius [r_{g,SMBH}] of outer edge of disk
timestep_duration_yr (float) – Length of timestep [yr]

Returns:

new_orbs_a – Semi-major axes [r_{g,SMBH}] of objects at end of timestep

Return type:

float array