amoeba.Util package

Submodules

amoeba.Util.pipeline_util module

amoeba.Util.pipeline_util.intrinsic_signal_propagation_pipeline_for_agn(AGN, intrinsic_light_curve=None, time_axis=None, observer_frame_wavelengths_in_nm=None, speclite_filter=None, return_components=False, **kwargs)

run the pipeline to generate the full AGN intrinsic signal

Parameters:

• AGN – The AGN object to propagate the signal through.

• intrinsic_light_curve – the signal to propogate though the AGN model. Must be in units of days and sampled daily if time_axis is not given.

• time_axis – the time stamps of the driving signal to be specified if the driving signal is not evenly sampled every day.

• observer_frame_wavelengths_in_nm – a wavelength or list of wavelengths in nm.

• speclite_filter – a speclite filter, list of speclite filters, or list of speclite filter names.

• return_components – a bool which allows the return of each component light curve in addition to the combined light curve.

• output_cadence – float/int representing the output cadence in days

Returns:

a list with the length of wavelengths/filters of light curves represented by lists of time axes and amplitudes. If return_components, then the BLR light curves are returned as a dictionary with the key being the BLR index.

amoeba.Util.pipeline_util.visualization_pipeline(AGN, inclination_angle=None, observer_frame_wavelengths_in_nm=None, speclite_filter=None, return_components=None, **kwargs)

This pipeline produces a flux projection object of the combined emission of each agn component. Note that depending on flux ratios between various components, one may easily dominate the flux distribution.

Parameters:

• AGN – The AGN object to project into the source plane

• inclination_angle – the inclination of the source w.r.t. the observer

• observer_frame_wavelengths_in_nm – a [list of] wavelength[s] to project the AGN into. Cannot be used with speclite_filter

• speclite_filter – a [list of] speclite filter[s] to project the AGN into. Cannot be used with observer_frame_wavelengths_in_nm.

• return_components – a boolean toggle to return each component as individual FluxProjection objects before adding them together.

Returns:

A list of FluxProjection objects for each wavelength range or speclite filter given.

amoeba.Util.util module

amoeba.Util.util.accretion_disk_temperature(radius_in_meters, min_radius_in_meters, mass_in_solar_masses, eddington_ratio, disk_acc=None, spin=0, visc_temp_prof='SS', efficiency=0.1, corona_height=6, albedo=1, eta_x_rays=0.1, beta=0, generic_beta=False)

Defines the radial temperature profile of the accretion disk according to the function given in Best et al. 2025, which combines a viscous temperature profile with the irradiated disk profile and the disk + wind profile. The viscous temperature profile may be defined as a Shakura-Sunyaev or Novikov-Thorne profile. Future: update to allow any user-defined radial temperature profile.

Parameters:

• radius_in_meters – radius or list of radii in meters

• min_radius_in_meters – inner radius in meters. Typically taken to be the innermost stable circular orbit, but may be greater than this if the truncated accretion disk model is used

• mass_in_solar_masses – mass of the supermassive black hole (SMBH) in solar masses or an astropy unit. Note this is NOT smbh_mass_exp.

• eddington_ratio – percent of eddington limit the SMBH is accreting at

• disk_acc – Override for accretion rate at inner radius in solar masses per year. This is typically not favored over the Eddingtion ratio, but can be useful in some studies.

• spin – dimensionless spin of the SMBH w.r.t. the accretion disk flow on the range (-1, 1). Negative values represent accretion flows with angular momentum opposing the SMBH, leading to larger innermost stable circular orbits. Required for Novikov-Thorne profile.

• visc_temp_prof – str representing the Shakura-Sunyaev or Novikov-Thorne thermal profile as “SS” or “NT”, respectively. Thanks @ Joshua Fagin for coding the Novikov-Thorne profile.

• efficiency – efficiency of converting gravitational potential energy into radiation. Typical values are ~0.1, and may be as large as ~0.42 for maximally spinning black holes.

• corona_height – The height of the irradiating source in gravitational radii in the lamppost geometry (Cacket et al. 2007). The default value of 6 represents the Schwarzschild ISCO case.

• albedo – reflection coefficent of the accretion disk such that 0 causes perfect absorption and 1 causing perfect reflection of X-ray energy. Default is 1, meaning no thermal contribution from the lamppost term. Experimental: a 2 dimensional array may be used in addition to simulate a changing albedo with radius.

• eta_x_rays – efficiency coefficient of lamppost source, defined as Lx = eta_x_rays * L_bol. Due to conservation of energy, the sum of eta_x_rays and efficiency should NOT exceed 1, since the total energy must come from some physical source.

• beta – wind strength providing the following accretion rate relationship m_dot = m0_dot * (r / r_in)^beta from Sun et al. 2018. Note that this can greatly increase the total radiated energy and the Eddington ratio is no longer conserved.

• generic_beta – boolean toggle to force a thermal profile of the form r^(-beta). This is done by computing the beta required to make this dependence occur.

Returns:

temperature in Kelvins

amoeba.Util.util.calculate_angular_diameter_distance(redshift, OmM=0.3, H0=70)

This funciton takes in a redshift value, and calculates the angular diameter distance. This is given as the output. This assumes LCDM model. Follows Distance measures in cosmology (Hogg 1999)

Parameters:

• redshift – redshift of the object

• OmM – total fraction of the universe’s energy budget is in mass.

• H0 – Hubble constant in units km/s/Mpc

Returns:

angular diameter distance in units meters, assuming a flat lambda-CDM universe

amoeba.Util.util.calculate_angular_diameter_distance_difference(redshift_lens, redshift_source, OmM=0.3, H0=70)

This function takes in 2 redshifts, designed to represent z1 = redshift (lens) and z2 = redshift (source). This assumes LCDM model. Follows Distance measures in cosmology (Hogg 1999)

Parameters:

• redshift_lens – redshift the gravitational lens

• redshift_source – redshift the source

• OmM – total fraction of the universe’s energy budget is in mass

• H0 – Hubble constant in units km/s/Mpc

Returns:

angular diameter distance difference in units meters

amoeba.Util.util.calculate_angular_einstein_radius(redshift_lens=None, redshift_source=None, mean_microlens_mass_in_kg=<Quantity 1.98840987e+30 kg>, OmM=0.3, H0=70, D_lens=None, D_source=None, D_LS=None)

This function calculates the Einstein radius of the microlens in radians assuming the LCDM model.

Parameters:

• redshift_lens – redshift of the lens. Required if D_lens is None.

• redshift_source – redshift of the source object. Required if D_source is None.

• mean_microlens_mass_in_kg – average mass of microlenses in the lensing galaxy. This is typically modeled between 0.1 and 1.0 solar masses. Note that this formula is used for any compact object which may be approximated by a point source, and is valid for relatively compact strongly lensing galaxies.

• OmM – energy budget of the universe in mass

• H0 – Hubble constant in units km/s/Mpc

• D_lens – angular diameter distance of the lens. Will be computed if None.

• D_source – angular diameter distance of the source. Will be computed if None.

• D_LS – angular diameter distance difference between the lens and source. Will be computed if None.

Returns:

Einstein radius of the lens in radians

amoeba.Util.util.calculate_blr_transfer_function(blr_density_rz_grid, blr_vertical_velocity_grid, blr_radial_velocity_grid, inclination_angle, smbh_mass_exp, velocity_range=[-1, 1], weighting_grid=None, radial_resolution=1, vertical_resolution=1, magnification_array=None, number_of_microlens_einstein_radii=25, redshift_lens=None, redshift_source=None, mean_microlens_mass_in_kg=<Quantity 1.98840987e+30 kg>, x_position=None, y_position=None, random_seed=None, relative_orientation=0, OmM=0.3, H0=70)

Calculate the response function of the BLR by assuming weighting factors for some given wavelength range. The BLR emission is assumed to be proportional to the particle density and the weighting factor.

Todo: this is a relatively slow function. If there’s a way to project the BLR into the 3-dimensional cylindrical grid faster then compute the time lags as a function of (R, Z, phi) and take a single histogram over the whole space, that would probably speed it up significantly. Notes: It sped up by reducing the resolution of the blr transfer function, but still could be faster. Additional note: I tried generating the 3d space using a 3 dimensional grid, but it was actually slower than looping through each height slab. It’s possible it was slower due to the significant RAM required and my testing Macbook was using swap-files to handle the task. Still requires further testing.

Parameters:

• blr_density_rz_grid – a 2d array of values representing the density of the blr at each point in (R, Z) coords.

• blr_vertical_velocity_grid – a 2d array of v_{z} values, normalized by the speed of light.

• blr_radial_velocity_grid – a 2d array of v_{r} values, normalized by the speed of light

• inclination_angle – the inclination of the agn w.r.t. the observer in degrees.

• smbh_mass_exp – the solution of log_{10} (M_{bh} / M_{sun})

• velocity_range – the range of line-of-sight velocities which are accepted, in units of speed of light. We take the convention of positive values are aimed towards the observer, and are therefore blueshifted.

• weighting_grid – a 2d array of values which correspond to weighting factors in the blr_density_rz_grid

• radial_resolution – the spacing between radial coordinates in gravitational radii

• vertical_resolution – the spacing between vertical coordinates in gravitational radii

Returns:

a 1d array representing the normalized response function of the BLR w.r.t. the optical accretion disk approximated as emitting from the SMBH in units of gravitational radii

amoeba.Util.util.calculate_dt_dlx(temp_array, radii_array, phi_array, smbh_mass_exp, corona_height, axis_offset_in_gravitational_radii=0, angle_offset_in_degrees=0, height_array=None, albedo_array=None)

Approximates the change in temperature due to the change in lamppost flux assuming the irradiated disk model, following the Taylor expansion.

delta_t / delta_lx ~ geometric_disk_factor / (4 * disk_temp**3)

As such, this primarily uses calculate_geometric_disk_factor() and weights it by the temperature at each coordinate.

Parameters:

• temp_array – a 2d array representing the effective temperature of the accretion disk

• radii_array – a 2d array representing the radii from the smbh in gravitational radii

• phi_array – a 2d array representing the azimuths on the accretion disk in radians

• smbh_mass_exp – the solution of log10(m_smbh / m_sun)

• corona_height – the lamppost height in gravitational radii

• axis_offset_in_gravitational_radii – the cylindrical offset of the lamppost in gravitational radii with respect to the black hole

• angle_offset_in_degrees – the azimuth of the offset of the lamppost in degrees

• height_array – array of heights to calculate the disk at. Allows for greater flexability in disk model. Note, this is experimental!

• albedo_array – int, float, or array of albedos (reflectivities) to use for the disk

Returns:

a 2d array representing the change in effective temperature with respect to the luminosity of the x-ray source

amoeba.Util.util.calculate_einstein_radius_in_meters(redshift_lens=None, redshift_source=None, mean_microlens_mass_in_kg=<Quantity 1.98840987e+30 kg>, OmM=0.3, H0=70, D_lens=None, D_source=None, D_LS=None)

This function determines the einstein radius of the lensing object in meters.

Parameters:

• redshift_lens – redshift of the lens. Required if D_lens is None.

• redshift_source – redshift of the source object. Required if D_source is None.

• mean_microlens_mass_in_kg – average mass of microlenses in the lensing galaxy. This is typically modeled between 0.1 and 1.0 solar masses. Note that this formula is used for any compact object which may be approximated by a point source, and is valid for relatively compact strongly lensing galaxies.

• OmM – energy budget of the universe in mass

• H0 – Hubble constant in units km/s/Mpc

• D_lens – angular diameter distance of the lens. Will be computed if None.

• D_source – angular diameter distance of the source. Will be computed if None.

• D_LS – angular diameter distance difference between the lens and source. Will be computed if None.

Returns:

Einstein radius of the lens in meters

amoeba.Util.util.calculate_geometric_disk_factor(temp_array, radii_array, phi_array, smbh_mass_exp, corona_height, axis_offset_in_gravitational_radii=0, angle_offset_in_degrees=0, height_array=None, albedo_array=None)

Calculate the geometric factor of the accretion disk due to lamppost heating according to.

f_geo = (1 - A) cos(theta_x) / (4 * pi * sigma_sb * r_{*}^{2}}

where: A is the albedo of the material theta_x is the angle of incidence of a ray of radiation pi = 3.14… sigma_sb = the Stefan-Boltzman constant r_{*} = the distance of any 3 dimensional position to the source

This gets weighted by the lamppost X-ray flux L_{x} (eq. 2 in Cackett+ 2007)

Parameters:

• temp_array – a 2d array of effective temperatures in Kelvin

• radii_array – a 2d array of radii in gravitational radii

• phi_array – a 2d array of azimuth angles in radians

• smbh_mass_exp – the solution of log10(m_smbh / m_sun)

• corona_height – the height of the source in gravitational radii

• axis_offset_in_gravitational_radii – the cylindrical axis offset of the lamppost w.r.t. axis of symmetry

• angle_offset_in_degrees – azimuth position of the offset lamppost

• height_array – array of heights to calculate the disk at. Allows for greater flexability in disk model. Note this is experimental!

• albedo_array – int, float, or array of albedos (reflectivities) to use for the disk

Returns:

a 2d array of geometric disk factors which determine the flux reprocessing of the lamppost by the accretion disk

amoeba.Util.util.calculate_gravitational_radius(mass_in_solar_masses)

Calculate the gravitational radius of a massive object following gravitational_radius = R_g = G M / c^2.

Parameters:

mass_in_solar_masses – mass of the object in units of solar masses or as an astropy quantity

Returns:

length of one gravitational radius in meters.

amoeba.Util.util.calculate_keplerian_velocity(radius_in_meters, mass_in_solar_masses)

Helper function to calculate the magnitude of Keplerian velocity of a circular orbit around a massive object.

v_orbit = sqrt(GM/r)

Parameters:

• radius_in_meters – radius in units meters or an astropy quantity

• mass_in_solar_masses – mass in units solar masses or an astropy quantity

Returns:

keplerian velocity represented as a fraction of the speed of light

amoeba.Util.util.calculate_luminosity_distance(redshift, OmM=0.3, H0=70)

This calculates the luminosity distance using the calculate_angular_diameter_distance formula for flat lambda-CDM model. Follows Distance measures in cosmology (Hogg 1999)

Parameters:

• redshift – redshift of the object

• OmM – mass fraction of the universe’s energy budget

• H0 – Hubble constant in units km/s/Mpc

Returns:

luminosity distance of the object in meters

amoeba.Util.util.calculate_microlensed_transfer_function(magnification_array, redshift_lens, redshift_source, rest_wavelength_in_nm, temp_array=None, radii_array=None, phi_array=None, g_array=None, inclination_angle=None, smbh_mass_exp=None, corona_height=None, mean_microlens_mass_in_kg=<Quantity 1.98840987e+30 kg>, number_of_microlens_einstein_radii=25, number_of_smbh_gravitational_radii=1000, relative_orientation=0, OmM=0.3, H0=70, axis_offset_in_gravitational_radii=0, angle_offset_in_degrees=0, height_array=None, albedo_array=None, x_position=None, y_position=None, return_response_array_and_lags=False, return_descaled_response_array_and_lags=False, return_magnification_map_crop=False, random_seed=None, response_array=None, time_lag_array=None)

Calculate the transfer function assuming the response of the disk can be amplified by microlensing. Essentially this is done by calculating the response and time lag maps of the accretion disk, determining the scale ratio between sizes in the source plane, rescaling the accretion disk’s arrays to the resolution of the magnification map, weighting each pixel by its corresponding magnification, then computing the transfer function. Extended to allow for response arrays of BLR.

Parameters:

• magnification_array – a 2d array of magnifications in the source plane

• redshift_lens – int/float representing the redshift of the lens

• redshift_source – int/float representing the redshift of the source

• mean_microlens_mass_in_kg – average mass of the microlensing objects in kg. Typical values range from 0.1 to 1.0 M_sun.

• number_of_microlens_einstein_radii – number of R_e the magnification map covers along one edge.

• relative_orientation – orientation of the accretion disk w.r.t. the magnification map

• OmM – mass contribution to the energy budget of the universe

• H0 – Hubble constant in units km/s/Mpc

• x_position – an optional x coordinate location to use on the magnification map. Otherwise, will be chosen randomly

• y_position – an optional y coordinate location to use on the magnification map. Otherwise, will be chosen randomly

• return_response_array_and_lags – boolean toggle to return a representation of the amplified response and time lags before the caluclation of the transfer function. Also returns x and y positions of where the microlensing was assumed to take place.

• return_descaled_response_array_and_lags – boolean toggle to return a representation of the amplified response and time lags at the resolution of the magnification map. Also returns x and y positions of where the microlensing was assumed to take place.

• return_magnification_map_crop – boolean toggle to return the section of the magnification map which amplifies the response function.

• random_seed – random seed to use for reproducibility

• rest_wavelength_in_nm – rest frame wavelength in nanometers to calculate the transfer function at

• temp_array – a 2d array representing the effective temperatures of the accretion disk

• radii_array – a 2d array representing the radii of each pixel in the source plane with units of gravitational radii

• phi_array – a 2d array representing the azimuths of each pixel in the source plane in radians

• g_array – a 2d array representing the redshift factors due to relativistic effects.

• inclination_angle – inclination of the accretion disk w.r.t. the observer in degrees

• smbh_mass_exp – the solution of log10(m_smbh / m_sun)

• corona_height – height of the lamppost in gravitational radii

• number_of_smbh_gravitational_radii – maximum radius of the accretion disk in R_g

• axis_offset_in_gravitational_radii – the cylindrical radial offset of the irradiation source in gravitational radii

• angle_offset_in_degrees – the azimuth of the offset of the lamppost in degrees

• height_array – array of heights to calculate the disk at. Allows for greater flexability in disk model. Note that this is experimental!

• albedo_array – int, float, or array of albedos (reflectivities) to use for the disk

• response_array – a 2d array representing the responsivity of the object. Must be equal in shape to the time_lag_array. Calculated innately for accretion disk.

• time_lag_array – a 2d array representing the time delay to each point on the response_array. Must be equal in shape to response_array. Calculated innately for accretion disk.

Returns:

transfer function calculated assuming the response of the disk is amplified by the magnification_array

amoeba.Util.util.calculate_time_lag_array(radii_array, phi_array, inclination_angle, corona_height, axis_offset_in_gravitational_radii=0, angle_offset_in_degrees=0, height_array=None)

Calculate the time lag between a lamppost source and every position on the accretion disk’s plane in units of R_g / c.

Parameters:

• radii_array – a 2d array of radial values in units of gravitational radii

• phi_array – a 2d array of azimuth values in radians

• inclination_angle – the inclination of the object w.r.t. the observer in degrees

• corona_height – the height of the source in gravitational radii

• axis_offset_in_gravitational_radii – the cylindrical radial distance from the SMBH axis of symmetry to be used as the source position

• angle_offset_in_degrees – azimuth angle in degrees of the offset lamppost. Note that 0 degrees is nearest to the observer and 180 degrees is furthest away.

• height_array – an optional 2d array of the height values in gravitational radii. Note that height array is experimental!

Returns:

a 2d array of time lags in units R_g / c

amoeba.Util.util.construct_accretion_disk_transfer_function(rest_wavelength_in_nm, temp_array, radii_array, phi_array, g_array, inclination_angle, smbh_mass_exp, corona_height, axis_offset_in_gravitational_radii=0, angle_offset_in_degrees=0, height_array=None, albedo_array=None, return_response_array_and_lags=False)

This calculates the accretion disk’s transfer function in the lamppost geometry for some given effective temperature mapping. Does not rely on a particular temperature profile or disk geometry, but it does assume black-body radiation.

Parameters:

• rest_wavelength_in_nm – rest wavelength to calculate the transfer function at, in nm

• temp_array – a 2d array of effective temperatures of the accretion disk

• radii_array – a 2d array of radii across the accretion disk in gravitational radii

• phi_array – a 2d array of azimuths on the accretion disk in radians

• g_array – a 2d array representing the relativistic redshifts on the accretion disk

• inclination_angle – the inclination of the accretion disk w.r.t. to the observer, in degrees

• smbh_mass_exp – the solution to log10(m_smbh / m_sun)

• corona_height – height of the lamppost in gravitational radii

• axis_offset_in_gravitational_radii – the cylindrical radial distance of the source from the smbh

• angle_offset_in_degrees – azimuth angle in degrees of the offset lamppost. Note that 0 degrees is nearest to the observer and 180 degrees is furthest away.

• height_array – an optional 2d array of the height values in gravitational radii

• albedo_array – float, int, or array of albedo (reflectivity) values to use

• return_response_array_and_lags – boolean toggle to return the response map and time lags instead of the transfer function

Returns:

a normalized 1d representation of the transfer function of the accretion disk with time lags represented in units R_g / c.

amoeba.Util.util.convert_1d_array_to_2d_array(array_1d)

Converts a 1 dimensional list of rays into its 2 dimensional representation. Gerlumph maps are stored as a binary file, as a single list of values. This requires a square magnification map.

Parameters:

array_1d – A 1d array (or list) of values which must be restacked into a 2d array. Note this array must correspond to a square output array.

Returns:

A 2d numpy array representation of the input

amoeba.Util.util.convert_cartesian_to_polar(x, y)

Converts coordinate pair (x, y) into (r, phi) coordinates. Rotates the phi direction such that phi=0 points in the negative y direction (towards the observer in our model).

Param:

x value or coordinate

Param:

y value or coordinate in same dimensions as x value

Returns:

tuple representation of radius and azimuth coordinates

amoeba.Util.util.convert_eddington_ratio_to_accreted_mass(mass_in_solar_masses, eddington_ratio, efficiency=0.1)

This function converts an Eddington Ratio (i.e. 0.15) into the corresponding accretion rate in physical units assuming bol_lum = eddington_ratio * edd_lum.

The following equations hold:

edd_lum = 4 * pi * G * M * M_proton * c / (sigma_T) bol_lum = M_dot * c^2 * efficiency

therefore:

M_dot = edd_lum / (efficiency * c^2)

where:

edd_lum = Eddingtion luminosity (the maximum luminosity allowed by Bondi

accretion where the gravitational force is balanced by the radiation pressure

pi = 3.14… G = Gravitational constant M = mass of the accreting body M_proton = mass of the proton c = speed of light sigma_T = Thompson cross section of the electron bol_lum = bolometric luminosity of the accretion disk assuming energy is released

proportional to the mass of the accreted material with some efficiency factor

efficiency = defines the efficiency of conversion of gravitational potential energy

to radiation energy

M_dot = accreted matter required for the disk to radiate at the given Eddington ratio

Parameters:

• mass_in_solar_masses – mass of SMBH in solar masses or astropy quantity. Note this is NOT smbh_mass_exp!

• eddington_ratio – percentage of theoretical Bondi limit of accretion rate

• efficiency – conversion efficiency between gravitational potential energy and thermal energy

Returns:

accreted mass as astropy units

amoeba.Util.util.convert_polar_to_cartesian(r, phi)

Converts coordinate pair (r, phi) into (x, y) coordinates.

Parameters:

• r – radius in polar coordinates

• phi – azimuth angle in radians within our azimuth convention

Returns:

tuple representation of x and y coordinates

amoeba.Util.util.convert_speclite_filter_to_wavelength_range(filter_string, min_threshold=0.01)

This function takes a speclite filter object or a string associated with speclite filters and outputs a wavelength range corresponding to the passband greater than minimum threshold.

Parameters:

• filter_string – speclite object or string associated with a speclite object.

• min_threshold – value to use in order to define the minimum and maximum wavelengths.

Returns:

list of wavelength ranges in nm

amoeba.Util.util.convert_spin_to_isco_radius(spin)

This helper function converts the dimensionless spin parameter into the ISCO size in units R_g.

Parameters:

spin – dimensionless spin of the SMBH on range (-1, 1). Note that spin may approach +/- 1, but should not naturally exceeed 0.998 (Thorne 1974).

Returns:

The size of the innermost stable circular orbit in units R_g

amoeba.Util.util.convolve_signal_with_transfer_function(smbh_mass_exp=None, driving_signal=None, initial_time_axis=None, transfer_function=None, redshift_source=0, desired_cadence_in_days=1)

Helper function to convolve a signal with a transfer function which has spacing in gravitational radii. If the initial time axis is not given, the function assumes that the spacing in the signal is in days in the source frame. Hypersampling is used to enforce that we have the desired observational cadence after redshifting.

Parameters:

• smbh_mass_exp – solution to log10(m_smbh/m_sun).

• driving_signal – driving signal to convolve with the transfer function. Assumed to be in units of days unless the initial time axis is given.

• initial_time_axis – time axis of the driving signal in units days, but may have interday values.

• transfer_function – transfer function which represents the response of an AGN component to an impulse, assumed to be normalized and with spacing of gravitational radii.

• redshift_source – redshift of the system

• desired_cadence_in_days – desired sampling of the output signal in units days. This will be enforced via linear interpolation.

Returns:

array representing the time axis and an array representing the reprocessed signal

amoeba.Util.util.create_maps(smbh_mass_exp, redshift_source=0, number_grav_radii=500, inclination_angle=0, resolution=500, spin=0, eddington_ratio=0.1, temp_beta=0, corona_height=6, albedo=0, eta_x=0.0, generic_beta=False, disk_acc=None, height_array=None, OmM=0.3, H0=70, efficiency=0.1, visc_temp_prof='SS', name='')

This function sets up a dictionary used to create the AccretionDisk object in Amoeba. The dictionary may be modified afterwards as long as particular items are kept in the same shape (e.g. the set of arrays corresponding to radii, azimuths, redshifting, temperature, heights, and albedos). Note that the mass of the supermassive black hole (SMBH) both affects the size scale and the physical temperature profile of the accretion disk, so a new accretion disk should be produced if the mass is changed. The temperature profile generated follows that found in Best et al. 2025. The viscous temperature profile may be modeled as either the Shakura-Sunyaev or Novikov-Thorne (SS or NT, respectively) temperature profile. This may be further modified by the disk-wind model of Sun et al. 2018 and the irradiated disk model of Cackett et al. 2007.

Parameters:

• smbh_mass_exp – the solution of log10(m_smbh / m_sun)

• redshift_source – the redshift of the accretion disk

• number_grav_radii – the max radius of the accretion disk in gravitational radii (R_g). Typical optical accretion disks require between 500 and 2000 R_g to capture most of the flux.

• inclination_angle – the inclination of the accretion disk w.r.t. the observer, in degrees

• resolution – the number of pixels along one axis the images are resolved to. All images are created square.

• spin – the dimensionless spin parameter of the black hole, ranging from [-1, 1]. Negative values represent retrograde accretion orbits w.r.t. the angular momentum of the black hole.

• eddington_ratio – the eddington ratio which the accretion disk is emitting radiation at. Thin disks typically range from 0.01 to 0.2, where lower and higher eddington ratios require different accretion modes (e.g. slim disk, ADAF).

• temp_beta – a wind parameter which serves to adjust the temperature profile (see Sun et al. 2018). Note that using the parameter “generic_beta==True” will force r^-beta dependence instead.

• corona_height – number of R_g above the accretion disk the assumed lamppost is. Determines the geometric factor in the irradiated accretion disk model (see Cackett et al. 2007)

• albedo – reflectivity of disk. Setting to 0 will make the disk absorb emission, heating it up. Experimental: may be defined as a 2-dimensional array.

• eta_x – lamppost source luminosity coefficient. Defined as Lx = eta * M_dot * c^2. Note that this is similar but not the same as the eta associated with the efficiency of energy conversion to calculate Bolometric flux. Ideally, the sum of this eta and the eta associated with the spin of the black hole (typically ~0.10, which peaks around 0.42, and actually defined in code as “efficiency”) should not exceed 1 due to conservation of energy.

• generic_beta – boolean toggle to r^{-beta} dependence of the accretion disk. If true, the beta value of the equation in Sun et al. 2018 will be calculated from the beta parameter.

• disk_acc – optional amount of mass accreted by the accretion disk per time. If a number is given, units of solar_masses/year are assumed. However, using the eddingtion ratio parameter is more typical.

• height_array – a 2 dimensional array representing the height of the accretion disk at each coordinate. Note that this is an experimental feature.

• OmM – mass contribution to the energy budget of the universe

• H0 – Hubble constant in units km/s/Mpc

• efficiency – efficiency of the conversion of gravitational potential energy to thermal energy. Typially taken to be ~0.1, may be spin dependent with a maximum efficiency of ~0.42, and minimum ~0.02.

• visc_temp_prof – string representing viscous temperature profile to use. Currently implemented are “SS” for Shakura-Sunyaev and “NT” for Novikov-Thorne. Future implimentation: allow for a 1d array representing any radial temperature profile.

• name – string representing a name or identifier for the accretion disk. Cosmetic.

Returns:

a dictionary designed to be passed into the AccretionDisk object with all relevant metadata.

amoeba.Util.util.determine_emission_line_velocities(rest_frame_emitted_wavelength, minimum_admitted_wavelength, maximum_admitted_wavelength, redshift)

Helper function to define the velocity range of an emission line due to Doppler broadening which is required to shift the emission line into the desired filter.

Parameters:

• rest_frame_emitted_wavelength – emission line wavelength in rest frame. Units must match passband units, but may be arbitrary.

• minimum_admitted_wavelength – minimum wavelength of the passband (filter). Units may be arbitrary, but must match rest_frame_emitted_wavelength.

• maximum_admitted_wavelength – maximum wavelength of the passband (filter). Units may be arbitrary, but must match rest_frame_emitted_wavelength.

• redshift – cosmological redshift factor

Returns:

list of [minimum, maximum] velocities which will shift the emission line into the desired filter at redshift.

amoeba.Util.util.extract_light_curve(convolution_array, pixel_size, effective_transverse_velocity, light_curve_time_in_years, pixel_shift=0, x_start_position=None, y_start_position=None, phi_travel_direction=None, return_track_coords=False, random_seed=None)

Extracts a light curve from the convolution between two arrays by selecting a trajectory and calling pull_value_from_grid at each relevant point. If the light curve is too long, or the size of the object is too large, a “light curve” representing a constant magnification is returned.

Parameters:

• convolution_array – The convolution between a flux distribtion and the magnification array due to microlensing. Note coordinates on arrays have (y, x) signature.

• pixel_size – Physical size of a pixel in the source plane, in meters

• effective_transverse_velocity – effective transverse velocity in the source plane, in km / s

• light_curve_time_in_years – duration of the light curve to generate, in years

• pixel_shift – offset of the SMBH with respect to the convolved map, in pixels

• x_start_position – None or the x coordinate to start pulling a light curve from, in pixels

• y_start_position – None or the y coordinate to start pulling a light curve from, in pixels

• phi_travel_direction – None or the angular direction of travel along the convolution, in degrees

• return_track_coords – boolean toggle to return the x and y coordinates of the track in pixels

Returns:

list representing the microlensing light curve

amoeba.Util.util.generate_drw_signal(length_of_light_curve, time_step, sf_infinity, tau_drw, random_seed=None)

Generate a damped random walk using typical parameters as defined in Kelly+ 2009. Uses recursion, so this is not as fast as generating directly from the psd.

Parameters:

• length_of_light_curve – the length of the light curve in arbitrary units

• time_step – the spacing of the light curve, in identical units to maximum_time

• sf_infinity – the asymptotic structure function of the damped random walk

• tau_drw – the characteristic time scale of the variability in units equivalent to length_of_light_curve and time_step

• random_seed – random seed to use for reproducibility

Returns:

an array representing the damped random walk

amoeba.Util.util.generate_signal_from_psd(length_of_light_curve, power_spectrum, frequencies, random_seed=None)

Generate a signal from any power spectrum using the methods of Timmer+.

length_of_light_curve and frequencies must be recipricol units. the output light curve will be normalized to have mean 0, standard deviation 1. Thanks @ Joshua Fagin for assistance on writing this function. Thanks at James H.H. Chan and the rest of the FutureLens group for discussions.

Parameters:

• length_of_light_curve – maximum length of the light curve to generate. Note that this maximum value is dependent on the input frequencies, since the frequencies can only generate a light curve ranging from values between the Nyquist frequency [1/(2 * max(frequency))] and 1/min(frequency)

• power_spectrum – array representing the input power spectrum of the stochastic signal at each fourier frequency defined in the frequencies parameter.

• frequencies – the input fourier frequencies associated with the power spectrum. Note these should be defined in linear space as: np.linspace(1/length_of_light_curve, 1/(2 * desired_time_resolution), int(length_of_light_curve)+1)

• random_seed – random seed to use for reproducibility

Returns:

signal generated from the power spectrum ith length defined by length_of_light_curve.

amoeba.Util.util.generate_snapshots_of_radiation_pattern(rest_wavelength_in_nm, time_stamps, temp_array, radii_array, phi_array, g_array, smbh_mass_exp, driving_signal, driving_signal_fractional_strength, corona_height, inclination_angle, axis_offset_in_gravitational_radii=0, angle_offset_in_degrees=0, height_array=None, albedo_array=None)

Generate the radiation pattern at particular time steps labeled in time_stamps.

Parameters:

• rest_wavelength_in_nm – rest frame wavelength in nm

• time_stamps – list of dates to extract the radiation pattern at, in days

• temp_array – a 2d array of the effective temperatures of the accretion disk in Kelvins

• radii_array – a 2d array of radii of the accretion disk, in gravitational radii

• phi_array – a 2d array of azimuth values on the accretion disk, in radians

• g_array – a 2d array representing the relativistic redshift factor

• smbh_mass_exp – the solution to log10(m_smbh / m_sun)

• driving_signal – a list representing the underlying driving signal which produces the radiation pattern on the accretion disk. Must be evenly spaced in days.

• driving_signal_fractional_strength – relative strength of the total flux due to the reprocessing, on a scale of (0, 1). 0 represents no contribution while 1 represnts no static flux contribution.

• corona_height – height of the lamppost corona in gravitational radii

• inclination_angle – the inclination of the accretion disk w.r.t. to the observer, in degrees

• axis_offset_in_gravitational_radii – the cylindrical radial offset of the lamppost in gravitational radii

• angle_offset_in_degrees – the azimuth of the offset of the lamppost in degrees

• height_array – array of heights to calculate the disk at. Note that this is an experimental feature!

• albedo_array – int, float, or array of albedos (reflectivities) to use for the disk

Returns:

a series of 2d arrays representing the radiation pattern at each value of time_stamps

amoeba.Util.util.perform_microlensing_convolution(magnification_array, flux_array, redshift_lens, redshift_source, smbh_mass_exp=8.0, mean_microlens_mass_in_kg=<Quantity 1.98840987e+30 kg>, number_of_microlens_einstein_radii=25, number_of_smbh_gravitational_radii=1000, relative_orientation=0, OmM=0.3, H0=70, return_preconvolution_information=False, random_seed=None)

This takes a magnification map and convolves it with a 2 dimensional array (usually associated with a FluxProjection object).

Parameters:

• magnification_array – a 2d array representation of the magnifications due to microlenses

• flux_array – a 2d array representation of the flux distribution

• redshift_lens – an int/float representing the cosmological redshift of the lens

• redshift_source – an int/float representing the cosmological redshift of the source

• smbh_mass_exp – a float representing the solution to log_{10} (M_{smbh} / M_sun)

• mean_microlens_mass_in_kg – the mean mass in kg of the microlenses, typically between 0.1 and 1.0 M_sun

• number_of_microlens_einstein_radii – size of the magnification map in Einstein radii (R_e)

• number_of_smbh_gravitational_radii – radial size of the flux_array (e.g. half of one square side)

• relative_orientation – angular rotation of flux distribution w.r.t. microlensing magnification distribution. If int or float, this defines the specific orientation. Any other input will be assigned a random value.

• OmM – mass fraction of the Universe in the lambda-CDM model

• H0 – Hubble constant in units km/s/Mpc

• return_preconvolution_information – return the rescaled flux_array instead of the convolution

Returns:

a 2d array representing the real valued convolution between the magnification_array and flux_array and the pixel_shift to locate the smbh location

amoeba.Util.util.planck_law(temperature, rest_wavelength_in_nm)

Calculates the spectral radiance of a black body in [W m^-2 m^-1]. Keep in mind this is in mks units, making this represent a very long wavelength range! This is not in [W m^-2 nm^-1] or [W m^-2 Hz]. To effectively use this to calculate flux, you should integrate over some wavelength range. This is efficiently done by converting the spectral radiance to some small wavelength range and then approximating the integration as a sum over wavelengths.

Parameters:

• temperature – int or array of temperature in Kelvins

• rest_wavelength_in_nm – int/float representing the rest frame wavelength in nanometers or as an astropy unit

Returns:

Spectral radiance of a black body in [W/m^2/m].

amoeba.Util.util.planck_law_derivative(temperature, rest_wavelength_in_nm)

Numerical approximation of the temperature derivative of the Planck law

calculated through limit definition of the derivative. For all typical temperatures associated with black body radiation, one Kelvin is a small change and effective at computing the derivative. We note that there is a closed form of this integral, but the simplicity of this method avoids potential overflows.

delta_B pprox

rac{B(T + delta_T, lam) - B(T, lam)}{delta_T}

with delta_T = 1 Kelvin

param temperature:

int or array of temperature in Kelvins

param rest_wavelength_in_nm:

rest frame wavelength in nanometers or astropy unit

return:

dervative of the spectral radiance w.r.t. temperature, in units [W/m^2/m/K]

amoeba.Util.util.project_blr_to_source_plane(blr_density_rz_grid, blr_vertical_velocity_grid, blr_radial_velocity_grid, inclination_angle, smbh_mass_exp, velocity_range=[-1, 1], weighting_grid=None, radial_resolution=1, vertical_resolution=1)

Takes an axi-symmetric grid of density values and weighting grid with (R, Z) coordinates and projects it to the source plane. It also can select particular velocity ranges to isolate projections into particular filters.

Parameters:

• blr_density_rz_grid – a 2d array of values representing the density of the BLR at each point in (R, Z) coords.

• blr_vertical_velocity_grid – a 2d array of v_{z} values, normalized by the speed of light.

• blr_radial_velocity_grid – a 2d array of v_{r} values, normalized by the speed of light

• inclination_angle – the inclination of the agn w.r.t. the observer in degrees.

• smbh_mass_exp – the solution of log10(m_smbh/m_sun)

• velocity_range – the range of line-of-sight velocities which are accepted, in units of speed of light. We take the convention of positive values are aimed towards the observer. Note that the BLR object will compute this for a given speclite filter.

• weighting_grid – a 2d array of values which correspond to weighting factors in the blr_density_rz_grid to represent additional weighting by the local optimally emitting cloud model

• radial_resolution – the spacing between radial coordinates in gravitational radii

• vertical_resolution – the spacing between vertical coordinates in gravitational radii

Returns:

a 2d array representing the projected BLR in the source plane with pixel resolution equal to radial_resolution and the maximum radius required for creating a FluxProjection object.

amoeba.Util.util.pull_value_from_grid(array_2d, x_position, y_position)

This approximates the point (x_position, y_position) in a 2d array of values. x_position and y_position may be decimals, and are assumed to be measured in pixels. This uses bilinear interpolation (or linear interpolation if one value is an integer).

Parameters:

• array_2d – 2 dimensional array of values.

• x_position – x coordinate in array_2d in pixels

• y_position – y coordinate in array_2d in pixels

Returns:

approximation of array_2d at point (x_position, y_position)

amoeba.Util.util.rand(d0, d1, ..., dn)

Random values in a given shape.

Note

This is a convenience function for users porting code from Matlab, and wraps random_sample. That function takes a tuple to specify the size of the output, which is consistent with other NumPy functions like numpy.zeros and numpy.ones.

Create an array of the given shape and populate it with random samples from a uniform distribution over [0, 1).

Parameters:

• d0 (int, optional) – The dimensions of the returned array, must be non-negative. If no argument is given a single Python float is returned.

• d1 (int, optional) – The dimensions of the returned array, must be non-negative. If no argument is given a single Python float is returned.

• ... (int, optional) – The dimensions of the returned array, must be non-negative. If no argument is given a single Python float is returned.

• dn (int, optional) – The dimensions of the returned array, must be non-negative. If no argument is given a single Python float is returned.

Returns:

out – Random values.

Return type:

ndarray, shape (d0, d1, ..., dn)

See also

random

Examples

>>> np.random.rand(3,2)
array([[ 0.14022471,  0.96360618],  #random
       [ 0.37601032,  0.25528411],  #random
       [ 0.49313049,  0.94909878]]) #random

Module contents