mcfacts.inputs.ReadInputs
Define input handling functions for mcfacts_sim Inifile ——-
- “disk_model_name”str
‘sirko_goodman’ or ‘thompson_etal’
- “flag_use_pagn”int
Use pAGN to generate disk model?
- “flag_add_stars”int
Add stars to the disk
- “flag_coalesce_initial_stars”int
Keep stars as is (0) or coalesce before time loop starts (1)
- “flag_initial_stars_BH_immortal”: int
If stars over disk_star_initial_mass_cutoff turn into BH (0) or hold at cutoff (1, immortal)
- “smbh_mass”float
Mass of the supermassive black hole (solMass)
- “disk_radius_trap”float
Radius of migration trap in gravitational radii (r_g = G*`smbh_mass`/c^2) Should be set to zero if disk model has no trap
- “disk_radius_outer”float
final element of disk_model_radius_array (units of r_g)
- “disk_radius_max_pc”float
Maximum disk size in parsecs (0. for off)
- “disk_alpha_viscosity”float
disk viscosity ‘alpha’
- “nsc_radius_outer”float
Radius of NSC (units of pc)
- “nsc_mass”float
Mass of NSC (units of M_sun)
- “nsc_radius_crit”float
Radius where NSC density profile flattens (transition to Bahcall-Wolf) (units of pc)
- “nsc_ratio_bh_num_star_num”float
Ratio of number of BH to stars in NSC (typically spans 3x10^-4 to 10^-2 in Generozov+18)
- “nsc_ratio_bh_mass_star_mass”float
Ratio of mass of typical BH to typical star in NSC (typically 10:1 in Generozov+18)
- “nsc_density_index_inner”float
Index of radial density profile of NSC inside r_nsc_crit (usually Bahcall-Wolf, 1.75)
- “nsc_density_index_outer”float
Index of radial density profile of NSC outside r_nsc_crit (e.g. 2.5 in Generozov+18 or 2.25 if Peebles)
- “disk_aspect_ratio_avg”float
Average disk scale height (e.g. about 3% in Sirko & Goodman 2003 out to ~0.3pc)
- “nsc_spheroid_normalization”float
Spheroid normalization
- “nsc_imf_bh_mode”float
Initial mass distribution for stellar bh is assumed to be Pareto with high mass cutoff–mode of initial mass dist (M_sun)
- “nsc_imf_bh_powerlaw_index”float
Initial mass distribution for stellar bh is assumed to be Pareto with high mass cutoff–powerlaw index for Pareto dist
- “nsc_imf_bh_mass_max”float
Initial mass distribution for stellar bh is assumed to be Pareto with high mass cutoff–mass of cutoff (M_sun)
- “nsc_imf_bh_method”str
The name of an IMF method (‘uniform’, ‘default’, ‘gaussian’ or filename for samples)
- “nsc_bh_spin_dist_mu”float
Initial spin distribution for stellar bh is assumed to be Gaussian –mean of spin dist
- “nsc_bh_spin_dist_sigma”float
Initial spin distribution for stellar bh is assumed to be Gaussian –standard deviation of spin dist
- “disk_bh_torque_condition”float
fraction of initial mass required to be accreted before BH spin is torqued fully into alignment with the AGN disk. We don’t know for sure but (Bogdanovic et al. 2007) says between 0.01=1% and 0.1=10% is what is required.
- “disk_bh_eddington_ratio”float
Eddington ratio for disk bh
- “disk_bh_orb_ecc_max_init”float
assumed accretion rate onto stellar bh from disk gas, in units of Eddington accretion rate
- “disk_star_mass_max_init”float
Initial mass distribution for stars is assumed Salpeter
- “disk_star_mass_min_init”float
Initial mass distribution for stars is assumed Salpeter
- “nsc_imf_star_powerlaw_index”float
Initial mass distribution for stars is assumed Salpeter, disk_alpha_viscosity = 2.35
- “disk_star_scale_factor”float
Scale factor to go from number of BH to number of stars.
- “disk_star_initial_mass_cutoff”float
Cutoff for initial star behavior
- “nsc_imf_star_mass_mode”float
Mass mode for star IMF
- “disk_star_torque_condition”float
fraction of initial mass required to be accreted before star spin is torqued fully into alignment with the AGN disk. We don’t know for sure but (Bogdanovic et al. 2007) says between 0.01=1% and 0.1=10% is what is required.
- “disk_star_eddington_ratio”float
assumed accretion rate onto stars from disk gas, in units of Eddington accretion rate
- “disk_star_orb_ecc_max_init”float
assuming initially flat eccentricity distribution among single orbiters around SMBH out to max_initial_eccentricity. Eventually this will become smarter.
- “nsc_star_metallicity_x_init”float
Stellar initial hydrogen mass fraction
- “nsc_star_metallicity_y_init”float
Stellar initial helium mass fraction
- “nsc_star_metallicity_z_init”float
Stellar initial metallicity mass fraction
- “timestep_duration_yr”float
How long is your timestep in years?
- “timestep_num”int
How many timesteps are you taking (timestep*number_of_timesteps = disk_lifetime)
- “galaxy_num”int
Number of galaxies of code run (e.g. 1 for testing, 30 for a quick run)
- “fraction_bin_retro”float
Fraction of BBH that form retrograde to test (q,X_eff) relation. Default retro=0.1
- “flag_thermal_feedback”int
Switch (1) turns feedback from embedded BH on.
- “flag_orb_ecc_damping”int
Switch (1) turns orb. ecc damping on. If switch = 0, assumes all bh are circularized (at e=e_crit)
- “capture_time_yr”float
Capture time in years Secunda et al. (2021) assume capture rate 1/0.1 Myr
- “disk_radius_capture_outer”float
Disk capture outer radius (units of r_g) Secunda et al. (2001) assume <2000r_g from Fabj et al. (2020)
- “disk_bh_pro_orb_ecc_crit”float
Critical eccentricity (limiting eccentricity, below which assumed circular orbit)
- “flag_dynamic_enc”int
Switch (1) turns dynamical encounters between embedded BH on.
- “delta_energy_strong_mu”float
Average energy change per strong interaction. de can be 20% in cluster interactions. May be 10% on average (with gas)
- “delta_energy_strong_sigma”float
Standard deviation for de Gaussian
- “inner_disk_outer_radius”float
Outer radius of the inner disk (Rg)
- “disk_inner_stable_circ_orb”float
Innermost Stable Circular Orbit around SMBH
- “mass_pile_up”float
Pile-up of masses caused by cutoff (M_sun)
- “save_snapshots”int
Save snapshots of the disk and NSC at each timestep
- “harden_energy_delta_mu”float
The Gaussian mean value for the energy change during a strong interaction
- “harden_energy_delta_sigma”float
The Gaussian standard deviation value for the energy change during a strong interaction
- “flag_use_surrogate”int
Switch (0) uses analytical kick prescription from Akiba et al. (2024). Switch (1) uses NRSurrogate model from (paper in prep). Switch (-1) uses precession module from Gerosa & Kesden (2016).
- “flag_use_spin_check”int
Switch (0) allows spin values to pass through without change. Switch (1) applies spin check system that sets 2g spins lower than 0.75 to a random range [0.75, 0.85]; 3g+ spins lower than 0.85 to a random range [0.85, 0.95]
- “flag_dynamics_sweep”int
Use faster dynamics functions which implement sweep function (1 on/0 off)
Module Attributes
Dictionary of types for input parameters |
- mcfacts.inputs.ReadInputs.INPUT_TYPES = {'capture_time_yr': <class 'float'>, 'delta_energy_strong_mu': <class 'float'>, 'delta_energy_strong_sigma': <class 'float'>, 'disk_alpha_viscosity': <class 'float'>, 'disk_aspect_ratio_avg': <class 'float'>, 'disk_bh_eddington_ratio': <class 'float'>, 'disk_bh_orb_ecc_max_init': <class 'float'>, 'disk_bh_pro_orb_ecc_crit': <class 'float'>, 'disk_bh_torque_condition': <class 'float'>, 'disk_inner_stable_circ_orb': <class 'float'>, 'disk_model_name': <class 'str'>, 'disk_radius_capture_outer': <class 'float'>, 'disk_radius_max_pc': <class 'float'>, 'disk_radius_outer': <class 'float'>, 'disk_radius_trap': <class 'float'>, 'disk_star_eddington_ratio': <class 'float'>, 'disk_star_initial_mass_cutoff': <class 'float'>, 'disk_star_mass_max_init': <class 'float'>, 'disk_star_mass_min_init': <class 'float'>, 'disk_star_orb_ecc_max_init': <class 'float'>, 'disk_star_scale_factor': <class 'float'>, 'disk_star_torque_condition': <class 'float'>, 'flag_add_stars': <class 'int'>, 'flag_coalesce_initial_stars': <class 'int'>, 'flag_dynamic_enc': <class 'int'>, 'flag_dynamics_sweep': <class 'int'>, 'flag_initial_stars_BH_immortal': <class 'int'>, 'flag_orb_ecc_damping': <class 'int'>, 'flag_phenom_turb': <class 'int'>, 'flag_thermal_feedback': <class 'int'>, 'flag_use_pagn': <class 'int'>, 'flag_use_spin_check': <class 'int'>, 'flag_use_surrogate': <class 'int'>, 'fraction_bin_retro': <class 'float'>, 'galaxy_num': <class 'int'>, 'harden_energy_delta_mu': <class 'float'>, 'harden_energy_delta_sigma': <class 'float'>, 'inner_disk_outer_radius': <class 'float'>, 'mass_pile_up': <class 'float'>, 'nsc_bh_spin_dist_mu': <class 'float'>, 'nsc_bh_spin_dist_sigma': <class 'float'>, 'nsc_density_index_inner': <class 'float'>, 'nsc_density_index_outer': <class 'float'>, 'nsc_imf_bh_mass_max': <class 'float'>, 'nsc_imf_bh_method': <class 'str'>, 'nsc_imf_bh_mode': <class 'float'>, 'nsc_imf_bh_powerlaw_index': <class 'float'>, 'nsc_imf_star_mass_mode': <class 'float'>, 'nsc_imf_star_powerlaw_index': <class 'float'>, 'nsc_mass': <class 'float'>, 'nsc_radius_crit': <class 'float'>, 'nsc_radius_outer': <class 'float'>, 'nsc_ratio_bh_mass_star_mass': <class 'float'>, 'nsc_ratio_bh_num_star_num': <class 'float'>, 'nsc_spheroid_normalization': <class 'float'>, 'nsc_star_metallicity_x_init': <class 'float'>, 'nsc_star_metallicity_y_init': <class 'float'>, 'nsc_star_metallicity_z_init': <class 'float'>, 'phenom_turb_centroid': <class 'float'>, 'phenom_turb_std_dev': <class 'float'>, 'r_g_in_meters': <class 'astropy.units.quantity.Quantity'>, 'save_snapshots': <class 'int'>, 'smbh_mass': <class 'float'>, 'timestep_duration_yr': <class 'float'>, 'timestep_num': <class 'int'>, 'torque_prescription': <class 'str'>}
Dictionary of types for input parameters
- mcfacts.inputs.ReadInputs.ReadInputs_ini(fname_ini, verbose=0)
Input file parser
This function reads your input choices from a file user specifies or default (inputs/model_choice.txt), and returns the chosen variables for manipulation by main.
Required input formats and units are given in IOdocumentation.txt file.
- mcfacts.inputs.ReadInputs.ReadInputs_prior_mergers(fname='recipes/sg1Myrx2_survivors.dat', verbose=0)
This function reads your prior mergers from a file user specifies or default (recipies/prior_mergers_population.dat), and returns the chosen variables for manipulation by main.
Required input formats and units are given in IOdocumentation.txt file.
See below for full output list, including units & formats
Example
To run, ensure a prior_mergers_population.dat is in the same directory and type:
$ python ReadInputs_prior_mergers.py
Notes
Function will tell you what it is doing via print statements along the way.
- Output variables
- mcfacts.inputs.ReadInputs.spin_angle_bh
Angle of BH spin wrt L_disk (radians). 0(pi) radians = aligned (anti-aligned) with L_disk
- Type:
- mcfacts.inputs.ReadInputs.gen_bh
Generation of BH (integer). 1.0 =1st gen (wasn’t involved in merger in previous episode; but accretion=mass/spin changed)
- Type:
- )
- mcfacts.inputs.ReadInputs.construct_disk_direct(disk_model_name, disk_radius_outer, verbose=0)
Construct a disk interpolation without pAGN
- Construct a disk interpolation without pAGN by reading
files with the load_disk_arrays function
- Parameters:
- Returns:
disk_surf_dens_func (lambda) – Surface density (radius)
disk_aspect_ratio_func (lambda) – Aspect ratio (radius)
disk_opacity_func (lambda) – Opacity (radius)
sound_speed_func (lambda) – sound speed (radius) [m/s]
disk_model_properties (dict) – Other disk model things we may want
- mcfacts.inputs.ReadInputs.construct_disk_interp(smbh_mass, disk_radius_outer, disk_model_name, disk_alpha_viscosity, disk_bh_eddington_ratio, disk_radius_max_pc=0.0, flag_use_pagn=0, verbose=0)
Construct the disk array interpolators
- Parameters:
smbh_mass (float) – Mass of the supermassive black hole (M_sun)
disk_radius_outer (float) – final element of disk_model_radius_array (units of r_g)
disk_alpha_viscosity (float) – disk viscosity ‘alpha’
disk_radius_max_pc (float) – Maximum disk size in parsecs (0. for off)
flag_use_pagn (int) – use pAGN if 1. Default is 0.
disk_model_name (str) – Choice of disk model
verbose (int) – Print extra stuff if 1. Default is 0.
- Returns:
disk_surf_dens_func (lambda) – Surface density (radius)
disk_aspect_ratio_func (lambda) – Aspect ratio (radius)
disk_opacity_func (lambda) – Opacity (radius)
- mcfacts.inputs.ReadInputs.construct_disk_pAGN(disk_model_name, smbh_mass, disk_radius_outer, disk_alpha_viscosity, disk_bh_eddington_ratio, rad_efficiency=0.1)
Construct AGN disk model using the pAGN code.
Get 1d functions of radius for your choice of disk model. Disk model can be Sirko & Goodman (2003) or Thompson, Quataert, & Murray (2005)
Sirko and Goodman. “Spectral Energy Distributions of Marginally Self-Gravitating Quasi-Stellar Object Discs.” 2003MNRAS.341..501S. [DOI](https://doi.org/10.1046/j.1365-8711.2003.06431.x).
Thompson, Quataert, & Murray. “Radiation Pressure-Supported Starburst Disks and Active Galactic Nucleus Fueling.” 2005ApJ.630..167. [DOI](https://doi.org/10.1086/431923).
- Parameters:
- Returns:
disk_surf_dens_func (lambda) – Surface density (radius)
disk_aspect_ratio_func (lambda) – Aspect ratio (radius)
disk_opacity_func (lambda) – Opacity (radius)
sound_speed_func (lambda) – sound speed (radius) [m/s]
disk_density_func (lambda) – disk density (radius) [kg/m^3]
disk_model_properties (dict) – Other disk model things we may want
bonus_structures (dict) – Other disk model things we may want, which are only available for pAGN models
- mcfacts.inputs.ReadInputs.initialize_r_g(input_variables)
Initilializes the r_g value in meters
This function precomputes the r_g value which would otherwise be calculated anew with each call to si_from_r_g, using the input SMBH_MASS value.
It mutates the input_variables dictionary in place, adding a r_g_in_meters key to it containing the r_g value in meters.
- Parameters:
input_variables (dict) – Dictionary of input variables
- mcfacts.inputs.ReadInputs.load_disk_arrays(disk_model_name, disk_radius_outer, verbose=0)
Load the dictionary arrays from file (pAGN_off)
Use import resources to load datafile from src/mcfacts/inputs/data
- Parameters:
- Returns:
truncated_disk_radii (NumPy array (float)) – The disk radius array
truncated_surface_densities (NumPy array (float)) – The surface density array
truncated_aspect_ratio (NumPy array (float)) – The aspect ratio array
truncated_temperature (NumPy array (float)) – The temperature array