bossa package

Submodules

bossa.constants module

bossa.constants.BINARIES_CORRELATED_TABLE_PATH = PosixPath('/home/runner/work/BOSSA/BOSSA/data/correlated_mp_qe_table.h5')

Path to the equiprobable binary parameters h5 file, generated from the Moe & Di Stefano distibutions.

Type:

path_like

bossa.constants.BINARIES_UNCORRELATED_TABLE_PATH = PosixPath('/home/runner/work/BOSSA/BOSSA/data/canonical_mp_qe_table.h5')

Path to the equiprobable binary parameters h5 file, generated from the uncorrelated distributions.

The File is structured in 200 Groups, corresponding to 200

equiprobable m1 values drawn from a Salpeter IMF [1]_. Each Group is structure in 100 Tables, each corresponding to one of 100 equiprobable logp values drawn for that m1 from the CompanionFrequencyDistribution class. Each Table holds 1000 lines, each of which contains one of 1000 equiprobable q,e pairs, from 10 possible q and 10 possible e, drawn from the MassRatioDistribution and EccentricityDistribution classes. The orbital parameter distributions are due to Moe & Di Stefano (2017) [2]_.

Type:

path_like

bossa.constants.C20_CORRECTIONS_PATH = PosixPath('/home/runner/work/BOSSA/BOSSA/data/C20_Results/IGIMF3_SFR_corrections_extended.dat')

Path to the SFRD variant IMF corretions.

Originally from Chruslinska et al. (2020). Extended grid kindly provided by Martyna Chruslinska.

Type:

path_like

bossa.constants.C20_DIR_PATH = PosixPath('/home/runner/work/BOSSA/BOSSA/data/C20_Results/SFRD_Z_z_data')

Path to the folder containing the SFRD grids by Chruslinska et al. (2020).

Type:

path_like

bossa.constants.COMPACT_OBJ_DIR_PATH = PosixPath('/home/runner/work/BOSSA/BOSSA/data/compact_object_samples')

Path to the compact binary samples folder.

Type:

path_like

bossa.constants.COMPAS_12XX_GRIDS_PATH = PosixPath('/home/runner/work/BOSSA/BOSSA/data/2023_12XX_compas_grids')

Path to the variant IMF, correlated orbital parameters, COMPAS gridfiles folder.

Type:

path_like

bossa.constants.COMPAS_12XX_PROC_OUTPUT_DIR_PATH = PosixPath('/home/runner/work/BOSSA/BOSSA/data/2023_12XX_proc_compas_output')

Path to the processed COMPAS output folder, using a variant IMF and correlated orbital parameters.

Type:

path_like

bossa.constants.COMPAS_21XX_GRIDS_PATH = PosixPath('/home/runner/work/BOSSA/BOSSA/data/2023_21XX_compas_grids')

Path to the invariant IMF, uncorrelated orbital parameters, COMPAS gridfiles folder.

Type:

path_like

bossa.constants.COMPAS_21XX_PROC_OUTPUT_DIR_PATH = PosixPath('/home/runner/work/BOSSA/BOSSA/data/2023_21XX_proc_compas_output')

Path to the processed COMPAS output folder, using an invariant IMF and uncorrelated orbital parameters.

Type:

path_like

bossa.constants.COMPAS_PROC_OUTPUT_DIR_PATH = PosixPath('/home/runner/work/BOSSA/BOSSA/data/2023_proc_compas_output')

Path to the processed COMPAS output folder, generic placeholder folder.

Type:

path_like

bossa.constants.COMPAS_UNPROC_OUTPUT_DIR_PATH = PosixPath('/home/runner/work/BOSSA/BOSSA/data/2023_unproc_compas_output')

Path to the unprocessed COMPAS output folder.

Type:

path_like

bossa.constants.COMPAS_WORK_PATH = PosixPath('/home/runner/work/BOSSA/BOSSA/COMPAS')

Path to the COMPAS working directory.

Type:

path_like

bossa.constants.DATA_PATH = PosixPath('/home/runner/work/BOSSA/BOSSA/data')

Path to the Data folder.

Type:

path_like

bossa.constants.GALAXYGRID_DIR_PATH = PosixPath('/home/runner/work/BOSSA/BOSSA/data/galaxy_grids')

Path to the galaxy parameter grids folder.

Type:

path_like

bossa.constants.IGIMF_ZAMS_DIR_PATH = PosixPath('/home/runner/work/BOSSA/BOSSA/data/zams_samples')

Path to the ZAMS binary samples folder.

Type:

path_like

bossa.constants.LN10 = np.float64(2.302585092994046)

ln(10)

Type:

float

bossa.constants.LOGE = np.float64(0.4342944819032518)

log10(e)

Type:

float

bossa.constants.LOG_PATH = PosixPath('/home/runner/work/BOSSA/BOSSA/logs')

Path to the logs folder.

Type:

path_like

bossa.constants.PHYSICAL_CORE_COUNT = 2

Number of local physical cores. Default number of parallel process set to the integer half of it.

Type:

path_like

bossa.constants.ROOT = PosixPath('/home/runner/work/BOSSA/BOSSA')

Path to root folder.

Type:

path_like

bossa.constants.TOTAL_PHYSICAL_MEMORY = 16772685824

Physical memory.

Type:

float

bossa.imf module

Star, embedded cluster and galaxy mass functions.

class bossa.imf.EmbeddedCluster(sfr=1.0, formation_time=10000000.0, m_tot=None)

Bases: PowerLawIMF

Compute the embedded cluster initial mass function.

Compute the embedded cluster initial mass function (eIMF) specific to a given galaxy with a set star formation rate (SFR) and star formation duration (time). The eIMF is a simple power law between M_TRUNC_MIN and M_max. The index beta is given as a function of the SFR, while the normalization constant, k, and m_max result from the numerical solution of two adequate constraints.

Attributes

beta sfr : float

Galactic SFR.

timefloat

Duration of ECL formation.

_m_maxfloat

Maximum mass of an ECL.

kfloat

Normalization constant of the eIMF.

Methods

get_mmax_k()

Solves the system of equations made up of methods f1 and f2 to determine m_max and k.

Notes

The eIMF is as given by Jerabkova et al. (2018) [3]_. M_TRUNC_MIN is

set to the default 5 Msun, and the maximum mass m_max is at most 1e9 Msun. k and m_max are determined from two constraints.

A constant star formation history (SFH) is assumed. Given the duration of the period of formation of new ECLs within a galaxy, time, the total galactic stellar ECL mass is m_tot=time*SFR. The first constraint is obtained by imposing that the total stellar mass of all ECLs be equal to m_tot, i.e., by equaling to m_tot the integral of the eIMF between M_TRUNC_MIN and m_max.

The second constraint is obtained by imposing that only one ECL be found with stellar mass equal to or greater than m_max, i.e., by equaling to unity the integral of the eIMF between m_max and 1e9.

All masses in this class are given in units of solar mass. The SFR is given in units of solar masses per year. The ECL formation time is given in years.

M_TRUNC_MAX = 1000000000.0

M_TRUNC_MIN = 5.0

property beta

eIMF exponent beta. Function of the SFR.

get_mmax_k()

Use Scipy’s fsolve to solve the constraints with an adequate initial guess and determine the maximum mass.

Use Scipy’s fsolve to solve the constraints with an adequate initial guess from the initial_guess method and determine _m_max.

Notes

This method must be run before get_k, otherwise get_k will return None.

class bossa.imf.IGIMF(sfr=1.0, feh=0.0)

Bases: object

Compute the galactic initial mass function.

The galactic IMF (gIMF) is computed according to the integrated galaxy-wide IMF (IGIMF) framework by integrating the product between the embedded cluster (ECL) and stellar IMFs (eIMF and sIMF, respectively) over all embedded clusters in the galaxy. This corresponds to integrating over the product of the imf methods of the Star and EmbeddedCluster classes with respect to ECL mass, with all other parameters (including stellar mass) fixed.

Attributes

sfrfloat

SFR of the galaxy.

fehfloat

[Fe/H] metallicity of the galaxy.

timefloat

Duration of the period of ECL formation in the galaxy.

m_trunc_minfloat

Minimum possible stellar mass.

m_trunc_maxfloat

Maximum possible stellar mass.

m_ecl_minfloat

Minimum possible embedded cluster mass.

m_ecl_maxfloat

Maximum mass of embedded clusters in the galaxy.

clustersEmbeddedCluster object

Calculates the eIMF of the galaxy.

m_ecl_arraynumpy array

Array of ECL masses over which to compute the sIMF for interpolation.

stellar_imf_ip: scipy.interpolate interp1d

Interpolation of the sIMF over ECL masses, for a fixed star mass.

Methods

get_clusters()

Instantiate an EmbeddedCluster object and compute the maximum embedded cluster mass.

imf(m)

Integrate the product of the sIMF and eIMF with respect to the ECL mass, for a given stellar mass.

Warns:

UserWarning – If method imf(m) is run before get_clusters().

Notes

The IGIMF framework is applied as described in Jerabkova et al. (2018) [3]_, Yan et al. (2017) [4]_ and references therein. Explicitly, the gIMF at a given stellar mass m is

\[\xi_\mathrm{g}(m|\mathrm{SFR},\mathrm{Z}) = \int_0^\infty \mathrm{d}M\, \xi_\mathrm{s}(m|M,\mathrm{Z})\, \xi_\mathrm{e}(M|\mathrm{SFR}),\]

where M is the ECL stellar mass; Z the galaxy metallicity, assumed homogeneous. The integration interval is broken into log-uniform intervals. Integration is performed with Scipy’s quad function.

This constitutes a spatial integration over the whole galaxy for all the stars formed within the ECLs during a time interval time, without taking into account the spatial distribution of star-forming regions or their differing chemical properties. Thus, the entire galaxy is specified by SFR and feh.

The SFR is given in solar masses per year. The metallicity is expressed as [Fe/H]. Time is given in years. All masses are given in solar masses.

References

[4]

Yan, Z., Jerabkova, T., Kroupa, P. (2017). The optimally sampled galaxy-wide stellar initial mass function: Observational tests and the publicly available GalIMF code. A&A, 607, A126. doi:10.1051/0004-6361/201730987

imf(m)

Integrate the product of the sIMF and the eIMF with respect to ECL mass, for a given stellar mass.

Integrate the product of the sIMF and the eIMF with respect to ECL mass, for a given stellar mass, using Scipy’s quad function.

Parameters:

m (float) – Star mass at which to compute the imf.

Returns:

imf – IMF value at mass m.

Return type:

float

Warns:

UserWarning – If ‘clusters’ is not defined (get_clusters() has not been run).

set_clusters()

Instantiate an EmbeddedCluster object and compute the maximum ECL mass.

Instantiate an EmbeddedCluster object and compute the maximum ECL mass, which is also saved as an instance attribute.

Warning

Must be called before the imf method, otherwise the eIMF will not be available for integration.

class bossa.imf.PowerLawIMF(m_tot: float = 10000000000.0, m_trunc_min: float = 0.08, m_trunc_max: float = 150.0, m_max: float = 150.0, breaks: list[float] = [0.08, 1.0, 150.0], exponents: list[float] = [-1.3, -2.3], norms: list[float] | None = None)

Bases: object

Generic broken power-law initial mass function.

This class contains the attributes that are expected by the module from any choice of broken power-law IMF with an arbitrary number of breaks, as well as methods for returning dN/dM and integrating the IMF within an arbitrary interval.

m_totfloat

Total mass of the population described by the IMF.

m_trunc_minfloat

Lower truncation mass, taken as the IMF lower limit.

m_trunc_maxfloat

Upper truncation the same, can be >= m_max.

m_maxfloat

IMF upper limit.

breakslist

Power-law breaks.

exponentslist

Power law exponents with padding. Carries the sign.

normslist

Normalization constants for each range, with padding.

imf(m)

Return dN/dM at mass m.

integrate(m0, m1, mass=False, normalized=True)

Return the integral of imf(m) or m*imf(m) between m0 and m1, for the IMF normalized to m_tot.

In keeping with the convention suggested by Hopkins (2018) [1]_, the power law index is defined to have the same signal as the power law slope, i.e.,

\[dN/dM = k M^a.\]

This class is written so that breaks, exponents and norms may be set by subclasses. These properties’ setters add appropriate padding that is expected by the imf and integrate methods and by the norms setter. The m_tot, m_trunc_min and m_trunc_max properties are defined so that this class will not overwrite those of a subclass instance for which they are already set.

All masses are given and expected in solar masses.

[1]

Hopkins, A. (2018). The Dawes Review 8: Measuring the Stellar Initial Mass Function. PASA, 35, E039. doi:10.1017/pasa.2018.29

Star : subclass for a variable stellar IMF. EmbeddedCluster : subclass for a variable cluster IMF. IGIMF : a galaxy IMF from Star and EmbeddedCluster.

property breaks

Power-law breaks.

property exponents

Padded broken power-law exponents.

Padded broken power-law exponents. The first and last exponents are repeated in the padding. The padding is expected when computing the norms and locating the appropriate region for masses are passed to imf(m) and integrate(m0, m1).

imf(m)

Compute dN/dM at a given mass.

Compute dN/dM at mass m. As some subclasses migh require a set_mmax_k() method to be run to compute m_max and the normalization constants, warn the user if m_mas is None.

Parameters:

m (float) – Mass at which to compute dN/dM.

Returns:

dN/dM at m.

Return type:

float

Warns:

UserWarning – If m_max is None (set_mmax_k not run).

integrate(m0, m1, mass=False, normalized=True)

Integrate for number or mass with or without normalization.

Parameters:

• m0 (float) – Lower integration limit.

• m1 (float) – Upper integration limit.

• mass (bool, default : False) – Whether to integrate for nuber (False) or mass (True).

• normalized (bool, default : True) – Whether to multiply (True) or not (False) by norms.

Returns:

integral – Result of the integration.

Return type:

float

property m_max

Upper limit of the IMF.

Upper limit of the IMF. Will not overwrite itself in a child class if also defined there.

property m_tot

Total mass represented by the IMF.

Total mass represented by the IMF. Will not overwrite itself in a child class if also defined there.

property m_trunc_max

Upper truncation mass of the IMF.

Upper truncation mass of the IMF. Will not overwrite itself in a child class if also defined there.

property m_trunc_min

Lower truncation mass of the IMF.

Lower truncation mass of the IMF. Treated as the lower limit of the IMF. Will not overwrite itself in a child class if also defined there.

property norms

Padded broken power-law normalization constants.

Padded broken power-law normalization constants. Zeros are added in the padding. The padding is expected when computing the norms and when locating the appropriate region for masses passed to imf(m) and integrate(m0, m1).

class bossa.imf.Star(m_ecl=10000000.0, m_ecl_min=5.0, feh=0.0, invariant=False)

Bases: PowerLawIMF

Compute the stellar initial mass function.

Compute the stellar initial mass function (sIMF) specific to a given star-forming region (embedded cluster, or ECL), with a set [Fe/H], and a total ECL stellar mass, m_tot. According to the invariant attribute, the sIMF might either follow an invariant Kroupa (2001) [2]_ IMF or a metallicity- and star formation rate- dependent Jerabkova et al. (2018) [3]_ IMF.

Attributes

x g1 g2 feh : float

Embedded cluster metallicity in [Fe/H].

m_ecl_minfloat

Absolute minimum embedded cluster mass.

_m_maxfloat

Maximum stellar mass. Embedded cluster-specific.

k1float

m<0.5 IMF normalization constant.

k2float

0.5<=m<1 IMF normalization constant.

k3float

1<= IMF normalization constant.

a1float

First interval power-law index.

a2float

Second interval power-law index.

a3: float

Third interval power-law index.

Methods

get_mmax_k()

Solves the system of equations made up of methods f1 and f2 to determine m_max and k1.

Notes

If invariant is set to False, the sIMF is as given by Jerabkova et al. (2018) [3]_. M_TRUNC_MIN is set at the hydrogen burning threshold of 0.08 Msun. Normalization constants k1 and k2 are found from k3 by continuity. k3 and m_max are determined from two constraints.

M_TRUNC_MAX sets the mass of the most massive formable star, m_max, but is not equal to it. Thus, the first constraint is obtained by imposing that the number of stars found with mass equal to or higher than m_max be one, i.e., by equating the integral of the IMF between m_max and M_TRUNC_MAX to unity. This constraint is expressed in method f1.

m_tot does set the total formed stellar mass. Thus, the second constraint is obtained by integrating m*imf(m) between M_TRUNC_MIN and m_max. This constraint is expressed in methods f1 and f2.

Solving f1 and f2 simultaneously determines m_max and k3, which also determines k1 and k2. This is done by the method get_mmax_k.

All masses are given and expected in solar masses.

References

[2]

Kroupa, P. (2001). On the variation of the initial mass function. MNRAS, 322, 231. doi:10.1046/j.1365-8711.2001.04022.x

[3]

Jerabkova, T., Zonoozi, A. H., Kroupa, P., Beccari, G., Yan, Z., Vazdekis, A., Zhang, Z.-Y. (2018). Impact of metallicity and star formation rate on the time-dependent, galaxy-wide stellar initial mass function. A&A, 620, A39. doi:10.1051/0004-6361/20183

BREAKS = [0.08, 0.5, 1.0, 150.0]

Power-law breaks shared between both IMFs.

M_TRUNC_MAX = 150.0

Upper truncation mass.

M_TRUNC_MIN = 0.08

Lower truncation mass.

property a1

IMF exponent for m < 0.5 Msun. Function of [Fe/H].

property a2

IMF exponent for 0.5 Msun <= m < 1.0 Msun. Function of [Fe/H].

property a3

IMF exponent for m >= 1.0 Msun. Dependent on [Fe/H] and m_tot through the auxiliary variable x.

property g1

Auxiliary variable g1. Related to the IMF integral over low masses.

property g2

Auxiliary variable g2. Related to the IMF integral over intermediary masses.

get_mmax_k()

Use Scipy’s fsolve to solve the two constraints with adequate initial guesses for k3 and _m_max.

After solving for k3 and _m_max, k1 and k2 are immediately determined. Automatically sets the IMF to zero for all masses if the star-forming region mass is below a minimum of 5 solar masses.

property x

Auxiliary variable. Function of [Fe/H] and m_tot.

bossa.postprocessing module

class bossa.postprocessing.COMPASOutputTrimmer(compas_output_option, compas_sample_option, only_load_dcos=True, load_unbound_systems=False, save_pulsar_columns=False, parent_logger=None)

Bases: object

BASE_COLS_TOSAVE = ['Mass_ZAMS1', 'Mass_ZAMS2', 'Stellar_Type1', 'Stellar_Type2', 'Metallicity_ZAMS', 'SemiMajorAxis_ZAMS', 'Eccentricity_ZAMS', 'Mass_PostSN1', 'Mass_PostSN2', 'Coalescence_Time', 'SEED', 'Chirp_Mass', 'Total_Mass_PostSN', 'Total_Mass_ZAMS', 'Mass_Ratio_PostSN', 'Mass_Ratio_ZAMS', 'LogP_ZAMS', 'Binary_Type']

DCOTAB_COLS_TOLOAD = ['Mass(1)', 'Mass(2)', 'Coalescence_Time']

PSRTAB_COLS_TOLOAD = ['MT_History', 'Mass(1)', 'Mass(2)', 'Pulsar_Mag_Field(1)', 'Pulsar_Mag_Field(2)', 'Pulsar_Spin_Down(1)', 'Pulsar_Spin_Down(2)', 'Pulsar_Spin_Freq(1)', 'Pulsar_Spin_Freq(2)', 'SemiMajorAxis', 'Stellar_Type(1)', 'Stellar_Type(2)', 'Time', 'dT']

PSR_COLS_TOSAVE = ['Mass_ZAMS1', 'Mass_ZAMS2', 'Stellar_Type1', 'Stellar_Type2', 'Metallicity_ZAMS', 'SemiMajorAxis_ZAMS', 'Eccentricity_ZAMS', 'Mass_PostSN1', 'Mass_PostSN2', 'Coalescence_Time', 'SEED', 'Chirp_Mass', 'Total_Mass_PostSN', 'Total_Mass_ZAMS', 'Mass_Ratio_PostSN', 'Mass_Ratio_ZAMS', 'LogP_ZAMS', 'Binary_Type', 'PSR_MT_History', 'PSR_Mass1', 'PSR_Mass2', 'PSR_B1', 'PSR_B2', 'PSR_Pdot1', 'PSR_Pdot2', 'PSR_Omega1', 'PSR_Omega2', 'PSR_SemiMajorAxis', 'PSR_Type1', 'PSR_Type2', 'PSR_Time', 'PSR_dT', 'PSR_SN_Mass_Core1', 'PSR_SN_Mass_Core2', 'PSR_SN_Mass_He_Core1', 'PSR_SN_Mass_He_Core2', 'PSR_SN_Mass_CO_Core1', 'PSR_SN_Mass_CO_Core2', 'PSR_SN_Fallback_Fraction1', 'PSR_SN_Fallback_Fraction2', 'PSR_SN_Kick_Magnitude1', 'PSR_SN_Kick_Magnitude2', 'PSR_SN_SystemicSpeed1', 'PSR_SN_SystemicSpeed2']

PSR_DO_COLS_TOSAVE = ['PSR_DO_PreSN_Time', 'PSR_DO_PreSN_Omega1', 'PSR_DO_PreSN_Omega2', 'PSR_DO_PreSN_Radius1', 'PSR_DO_PreSN_Radius2']

PSR_SN_DOUBLE_COLS_TOSAVE = ['PSR_SN_Mass_Core1', 'PSR_SN_Mass_Core2', 'PSR_SN_Mass_He_Core1', 'PSR_SN_Mass_He_Core2', 'PSR_SN_Mass_CO_Core1', 'PSR_SN_Mass_CO_Core2', 'PSR_SN_Fallback_Fraction1', 'PSR_SN_Fallback_Fraction2', 'PSR_SN_Kick_Magnitude1', 'PSR_SN_Kick_Magnitude2', 'PSR_SN_SystemicSpeed1', 'PSR_SN_SystemicSpeed2']

SNTAB_BASE_COLS_TOLOAD = ['Mass(SN)', 'Mass(CP)', 'Unbound']

SNTAB_PSR_COLS_TOLOAD = ['Mass_Core@CO(SN)', 'Mass_He_Core@CO(SN)', 'Mass_CO_Core@CO(SN)', 'Fallback_Fraction(SN)', 'Kick_Magnitude(uK)', 'SystemicSpeed', 'Time']

SYSPARAMTAB_COLS_TOLOAD = ['Initial_Mass(1)', 'Initial_Mass(2)', 'Mass_Ratio', 'Stellar_Type(1)', 'Stellar_Type(2)', 'Metallicity@ZAMS(1)', 'SemiMajorAxis@ZAMS', 'Eccentricity@ZAMS']

property columns_to_load

property columns_to_save

property float32_cols

gen_subdfs(df)

trim()

class bossa.postprocessing.CompactBinaryPopulation(print_progress=True, parent_logger=None, canonical_distributions=False)

Bases: object

Cross-match generated ZAMS populations and COMPAS output to produce a binary compact object population.

property compas_grids_folder

property compas_proc_output_dir_path

crossmatch_sample()

class bossa.postprocessing.LogPFinder

Bases: object

a_to_logp_table(a, m_tot)

get_closest_logp(logp)

set_m1(m1)

class bossa.postprocessing.MergerRates(sample_dir_path, zams_grid_path, sfrd_model, invariant_imf=False, extended_load=False, load_bcos_only=False, min_redshift=0.0, max_redshift=10.0, min_feh=-5.0, max_feh=0.5, progenitor_m_min=0.8, progenitor_m_max=150.0, convert_time=True, new_method=False, parent_logger=None)

Bases: object

CATEGORY_COLS = ['Unbound', 'Binary_Type', 'CompanionNumber']

COLS_TO_LOAD_ESSENTIAL = ['Unbound', 'Coalescence_Time', 'Mass_ZAMS1_Found', 'Mass_PostSN1', 'Mass_PostSN2', 'Binary_Type', 'SystemMass', 'CompanionNumber']

COLS_TO_LOAD_EXTENDED = ['Mass_ZAMS2_Found', 'Mass_ZAMS3_Found', 'Mass_ZAMS4_Found', 'Mass_ZAMS5_Found', 'LogOrbitalPeriod_ZAMS', 'Eccentricity_ZAMS', 'Unbound', 'Coalescence_Time', 'Mass_ZAMS1_Found', 'Mass_PostSN1', 'Mass_PostSN2', 'Binary_Type', 'SystemMass', 'CompanionNumber']

property canon_sfrd

Whether the star formation rate grid to be loaded should assume a Canonical Kroupa IMF.

property cols_to_load

delete_sample_df_from_memory()

get_mtot_per_ncomp()

get_starforming_masses(mass_normalization=False, debugging=False)

load_sample_to_memory(batches_n=1)

property sample_paths

set_merger_df(merger_class)

property sfrd_model

Which star formation rate density model from Chrulinska et al. (2020) to use.

bossa.sampling module

Sampling of arbitrary distributions, galaxy parameters and binary populations.

class bossa.sampling.CompositeBinaryPopulation(galaxy_grid_path, mmin, mmax, max_comp_number, mass_poolsize, qe_max_tries, only_binaries=False, invariant_imf=False, correlated_orbital_parameters=True, parent_logger=None, n_parallel_processes=1, memory_limit=13418148659.2, save_dir=None)

Bases: object

Sample binary populations for a grid of galaxies.

load_grid()

sample_grid()

class bossa.sampling.GalaxyGrid(n_redshift: int, redshift_min: int = 0.0, redshift_max: float = 10.0, force_boundary_redshift: bool = True, logm_per_redshift: int = 3, logm_min: float = 6.0, logm_max: float = 12.0, mzr_model: str = 'KK04', sfmr_flattening: str = 'none', gsmf_slope_fixed: bool = True, sampling_mode: str = 'sfr', scatter_model: str = 'none', apply_igimf_corrections: bool = True, random_state: bool = None)

Bases: object

Generate a grid of galaxy properties over redshift.

This class uses the galaxy stellar mass function (GSMF), star formation-mass relation (SFMR) and mass-metallicity relation (MZR) models from the sfh module to sample the space of galaxy parameters (stellar mass, redshift, star formation rate and metallicity).

A set of n_redshift redshifts is sampled first, and only then are the other three parameters sampled, logm_per_redshift sets per redshift. Unless scatter_model is set to normal, the redshift plus any one parameter fully determines the others.

Mass is given in solar masses, star formation rate in solar masses per year, and the metallicity is [Fe/H].

Parameters:

• n_redshift (int) – Number of redshift to sample.

• redshift_min (float, default : 0.) – Minimum redshift to sample.

• redshift_max (float, default : 10.) – Maximum redshift to sample.

• force_boundary_redshift (bool, default : True,) – Whether to manually add redshift_min and redshift_max to the sample.

• logm_per_redshift (int, default : 3) – Number of masses to sample per redshift.

• logm_min (float, default : 7) – Minimum log10(mass) to sample.

• logm_max (float, default : 12) – Maximum log10(mass) to sample.

• mzr_model ({'KK04', 'T04', 'M09', 'PP04'}, default: 'KK04') – Option of MZR model.

• sfmr_flattening ({'none', 'moderate', 'sharp'}, default: 'none') – SFMR model flattening option.

• gsmf_slope_fixed (bool, default: True) – Whether to use the fixed (True) or the varying (False) GSMF low-mass slope model.

• sampling_mode ({'mass', 'number', 'uniform'}, default : 'mass') – Method for sampling masse from the GSMF.

• scatter_model (str, default : 'none') – Scatter model to use in the SFMR and MZR.

• apply_igimf_corrections (bool, default : True,) – Whether to correct the SFR for imf.IGIMF.

• random_state (int) – Random number generator seed.

Attributes

n_redshiftint

Number of redshift values in the grid.

redshift_minfloat

Minimum redshift to sample.

redshift_maxfloat

Maximum redshift to sample.

force_boundary_redshiftbool

Whether to forcefully add redshifts redshift_min and redshift_min to the sample, thus making its size (n_redshift+2)*logm_per_redshift.

logm_per_redshiftint

Number of galactic stellar masses to sample per redshift.

logm_minfloat

Minimum log10(mass) to sample.

logm_maxfloat

Maximum log10(mass) to sample.

sample_redshift_arrayNDArray

Redshift sample defining the grid.

sample_redshift_binsNDArray

Limits of the bins represented by sample_redshift_array.

sample_logm_arrayNDArray

Galaxy stellar mass samples for each redshift in sample_redshift_array.

sample_logm_binsNDArray

Limits of the bins represented by sample_logm_array, per redshift.

gsmf_slope_fixedbool

Whether the GSMF low-mass slope should be fixed or not.

random_stateint

Random number generator seed.

apply_igimf_correctionsbool

Whether to correct the SFR for imf.IGIMF.

zoh_bin_arrayNDArray

Edges of Z_OH bins represented by zoh_array.

zoh_arrayNDArray

Z_OH values sampled at each redshift.

ndensity_arrayNDArray

Number density of galaxies represented by each grid point.

density_arrayNDArray

Stellar mass density of galaxies represented by each grid point.

mass_listlist

List of n_redshift arrays, containing the galaxy stellar masses sampled at each redshift.

log_gsmf_listlist

List of n_redshift arrays, containing the log10(gsmf) values (galaxy number density) sampled at each redshift.

zoh_listlist

List of n_redshift arrays, containing the Z_OH values sampled at each redshift.

feh_listlist

List of n_redshift, containing the [Fe/H] values sampled at each redshift.

sfr_listlist

List of n_redshift arrays, containing the SFR values sampled at each redshift.

grid_arraynumpy_array

Shape (n_redshift, logm_per_redshift, 6) array containing the full grid of galaxy properties.

Notes

This class first samples the redshift, and then for each redshift a fixed number of “galaxies”, i.e., (mass, metallicity, SFR) sets. The final grid of galaxies is stored as grid_array, and can also be written to disk as a .pkl file with Pandas by calling save_grid(). The _array attributes are used to build grid_array. The _list attributes are not used internally, but were instead necessary for older versions of data analysis/processing and test notebooks.

sample_redshift_array is initialized as a sample of evenly-space redshifts between the set minimum and maximum. sample_redshift() must be run to get a sample from the GSMF.

It is recommended not to rely on the _list attributes, as they should be removed in the future.

References

[1]

Chruslinska, M., Jerabkova, T., Nelemans, G., Yan, Z. (2020). The effect of the environment-dependent IMF on the formation and metallicities of stars over cosmic history. A&A, 636, A10. doi:10.1051/0004-6361/202037688

[2]

Jerabkova, T., Zonoozi, A. H., Kroupa, P., Beccari, G., Yan, Z., Vazdekis, A., Zhang, Z.-Y. (2018). Impact of metallicity and star formation rate on the time-dependent, galaxy-wide stellar initial mass function. A&A, 620, A39. doi:10.1051/0004-6361/20183

get_sample() → None

property mzr_model: str

Mass-(gas) metallicity relation model choice.

sample_redshift() → None

Sample redshifts from the GSMF integrated over mass.

Integrating the GSMF over mass yields a star forming mass-over- redshift distribution. A redshift sample is building by dividing the redshift range redshift_min-redshift_max into n_redshift quantiles and assigning each one its mass-weighted average redshift. If force_boundary_redshift is True, the redshift upper and lower limits are also added to the sample.

property sampling_mode: str

Sampling mode choice.

save_grid() → None

Save grid_array to disk.

property save_path: Path

Path which to save the grid to.

Type:

pathlib.Path

property scatter_model: str

Scattering model choice for the SFMR and the MZR.

property sfmr_flattening: str

Star formation-mass relation model choice.

class bossa.sampling.GalaxyStellarMassSampling(gsmf: GSMF, logm_min: float = 7.0, logm_max: float = 12.0, size: int = 3, sampling: str = 'number')

Bases: object

Sample galaxy stellar masses from a GSMF.

This class performs a number- or mass-weighted sampling of galaxy stellar mass from the galaxy stellar mass function (GSMF) in sfh.GSMF.

Parameters:

• gsmf (sfh.GSMF) – GSMF to sample.

• logm_min (float) – Log of sampling interval lower limit.

• logm_max (float) – Log of sampling interval upper limit.

• size (int) – Sample size.

• sampling ({'number', 'mass', 'uniform'}, default : 'number') – Whether to sample by galaxy number, stellar mass, or with uniform mass bins.

Attributes

gsmfsfh.GSMF

GSMF to sample.

logm_minfloat

Log of sampling interval lower limit.

logm_maxfloat

Log of sampling interval upper limit.

sample_sizeint

Sample size.

bin_limitsNDArray

Limits of sampled mass bins.

grid_ndensity_arrayNDArray

Number density within each mass bin.

grid_density_arrayNDArray

Mass density within each mass bin.

grid_logmassesNDArray

Sampled log galaxy stellar masses.

See Also

GalaxyGrid :

Implements this class to generate a grid of galaxy metallicities and star-formation rates over redshift.

Notes

The sampling method implemented in this class is equivalent to computing sample_size quantiles of the GSMF and assigning each one its average stellar mass. Option sampling='number' implements this for the GSMF(m) directly, while option sampling='number' does it for m*GSMF(m). In the future this class might be streamlined with Numpy’s quantile function.

Option sampling='uniform' sets sample_size uniform-width log mass bins.

Sampling is performed for a fixed redshift (defined within gsmf). Besides the log stellar masses (grid_logmasses), this class also stores the total mass and number densities contained by each mass bin (grid_density_array and grid_ndensity_array respectively).

Examples

>>> from bossa.sfh import GSMF
>>> gsmf = GSMF(redshift=0)
>>> galaxy_mass_sampler = GalaxyStellarMassSampling(gsmf,size=10)
>>> galaxy_mass_sampler.sample()
>>> galaxy_mass_sampler.grid_logmasses
array([9.89241753, 8.99773241, 8.50334364, 8.14752827, 7.86839714,
       7.64216579, 7.45822559, 7.30385785, 7.17084443, 7.05398244])

sample() → None

Sample galaxy stellar masses from the GSMF.

Generates the galaxy stellar mass samples according to sampling and stores it in grid_logmasses. Number and mass densities of galaxies in each bin are also computed and stored in grid_density_array and grid_ndensity_array, respectively.

property sampling: str

Whether to sample by galaxy number or stellar mass.

Type:

str

bossa.sampling.IMFLike

Classes from imf with an imf(m) method.

alias of Star | EmbeddedCluster | IGIMF

class bossa.sampling.RandomSampling(imf: Star | EmbeddedCluster | IGIMF, discretization_points: int = 100)

Bases: object

Randomly sample an arbitrary IMF.

This class is meant to speed up the sampling of an IMF defined as a numerical integral, as with imf.IGIMF, by setting up an interpolator to compute probabilities.

Parameters:

• imf (IMFLike) – Instance of an IMF class with an imf(m) method.

• discretization_points (int) – Number of masses on which to compute the IMF.

Attributes

imfIMFLike

Instance of an IMF class with an imf(m) method.

m_trunc_minfloat

Lower truncation mass.

m_trunc_maxfloat

Upper truncation mass.

sampleNDArray

Last drawn sample.

compute_imf() → None

Compute the IMF for interpolation.

Computes the IMF at discretization_points mass values for the interpolator.

property discretization_masses: ndarray[tuple[int, ...], dtype[float]]

Masses on which to compute the IMF.

Type:

NDArray

get_sample(m_min: float, m_max: float, n: int) → ndarray[tuple[int, ...], dtype[float]]

Return a sample of size n from m_min to m_max.

Returns a sample of size n between mmin and m_max and stores it as sample.

Parameters:

• m_min (float) – Sampling interval lower limit.

• m_max (float) – Sampling interval upper limit.

• n (int) – Sample size.

Returns:

sample – (n,)-shaped array containing the sample.

Return type:

NDArray

class bossa.sampling.SimpleBinaryPopulation(redshift, sfr, feh, m_min, m_max, max_comp_number, poolsize, qe_max_tries=1, only_binaries=False, invariant_imf=False, correlated_orbital_parameters=True, galaxy_descriptor='', parent_logger=None, prioritize_high_masses=False, print_progress=True, save_dir=None)

Bases: object

Generate a sample of zero-age main sequence binaries.

For a given redshift, star formation rate (SFR) and [Fe/H], generate a sample of multiple systems with component masses between m_min and m_max, and up to max_comp_number companions. Each system is represented by the parameters of its innermost binaries and its total corresponding mass, including all companions. Masses are drawn from the integrated galaxy-wide initial mass function (IGIMF) and orbital parameters from correlated distributions.

Attributes

save_path redshift : float

Redshift at which to generate the sample.

sfrfloat

SFR for which to generate the samples, in Msun yr-1.

fehfloat

[Fe/H] metallicity for which to generate the sample.

z_absfloat

Metallicity feh in Z.

m_minfloat

Minimum sampled mass.

m_maxfloat

Maximum sampled mass.

max_comp_numberint

Maximum number of companions.

poolsizeint

Size of the pool from which masses are drawn, without repetition.

col_nint

Number of columns (parameters) defining a binary.

samplenumpy array

(n, col_n) array of n binaries, each defined by a set of col_n parameters.

sample_massfloat

Total sample mass, including all system components.

qe_max_triesint

Maximum number of attempts to draw a valid system for a given primary mass, orbital period pair.

galaxy_descriptorstr

String describing the sampled population, to be appended to the sample filename.

m1_minfloat

Minimum primary mass allowed.

lowmass_powerlaw_indexfloat

Index of the power law from which < 0.8 Msun mass options are drawn.

lowmass_powerlaw_normfloat

Norm of the power law from which < 0.8 Msun mass options are drawn.

igimf_arrnumpy array

Array of >= 0.8 Msun mass options drawn from the IGIMF.

sampling_poolnumpy array

Complete pool of mass options for sampling.

prioritize_high_massesbool

Whether to bias the sampler towards drawing higher masses first or not.

print_progressbool

Whether to print progress updates (percentage, elapsed time, remaining time) to stdout or not.

Methods

set_sampling_pool()

Compute the array of mass options for sampling.

get_sample()

Generate full sample, save parameters to sample and the total mass to sample_mass.

save_sample()

Save sample to a parquet file at _save_path.

Warns:

• UserWarning – If get_sample() is run before set_sampling_pool().

• UserWarning – If sample is empty when save_sample() is called.

Warning

For a pool of poolsize possible masses, a sample of <~ 0.7*poolsize/2 binaries is generated. This is because two mass arrays are generated, one above and one below 0.8 Msun, containing poolsize/2 elements each; and because as the sampling pool is exhausted, remaining possible multiples tend to be invalid (fail the tolerance test in class ZAMSSystemGenerator), and the sampling stops after a certain number of consecutive failed iterations.

See Also

zams.ZAMSSystemGenerator

Sampling of an individual multiple system.

zams.MultipleFraction

Sampling of the number of companions.

Notes

This sampler generates a population that simultaneously follows to correlated orbital parameter distributions by Moe & Di Stefano (2017) [3]_ and the IGIMF by Jerabkova et al. (2018) [2]_. The sample is only representative of the IGIMF between 0.8 and 150 Msun, because the sampling of the primary mass m1 is restricted to this range in order as per the minimum mass sampled by the orbital parameter distributions. Components with masses between 0.08 and 0.8 Msun appear as companions, but they will not reproduce the IGIMF below 0.8 Msun as all < 0.8 Msun primaries and their companions will be missing. On the other hand, because for the mass ratio 0.1 <= q <= 1.0, the range between 0.8 and 150 Msun should be complete to good approximation, as discussed in OUR WORK.

References

[3]

Moe, M., Di Stefano, R. (2017). Mind Your Ps and Qs: The Interrelation between Period (P) and Mass-ratio (Q) Distributions of Binary Stars. ApJS, 230(2), 55. doi:10.3847/1538-4365/aa6fb6

get_sample()

Generate the binary sample.

inner_binary_sample_columns = ['Mass_ZAMS1_Found', 'Mass_ZAMS1_Choice', 'RelDev_Mass_ZAMS1', 'Mass_ZAMS2_Found', 'Mass_ZAMS2_Choice', 'RelDev_Mass_ZAMS2', 'MassRatioFound_ZAMS', 'MassRatioChoice_ZAMS', 'LogOrbitalPeriod_ZAMS', 'Eccentricity_ZAMS', 'CompanionNumber', 'SystemMass']

Column titles for the 12 parameters identifying each inner binary.

outer_pair_columns = ['Mass_ZAMS3_Found', 'Mass_ZAMS3_Choice', 'LogOrbitalPeriod_ZAMS3', 'Eccentricity_ZAMS3']

Columns saved for each further outer companion.

property pairs_table_path

Path to the orbital parameter sampling table.

property sample_columns

Sample column titles.

property save_path

Path to which to save the sample as a parquet file.

save_sample()

set_sampling_pool()

Set the mass pool from which to draw the sample.

Set the mass pool from which to draw the final sample as a random sampling of poolsize/2 from the IGIMF, above m1_min; and of a power law with the same area between m_min and m1_min as the IGIMF between m1_min and m_max, below m1_min.

Notes

Because the primary mass sampling is limited to m1 >= m1_min, in any case the IMF cannot be reproduced in the m < m1_min region; at the same time, an IMF at < m1_min is still necessary for the sampling of light companions. Thus the IMF for m < m1_min is defined to be a power law continuous with the IGIMF at m >= m1_min, with a slope such that its area below m1_min is the same as that of the IGIMF above. This choice is made in order to conform with the drawing of the same amount poolsize/2 of masses from both sides of m1_min.

bossa.sampling.powerlaw(x, k, a)

Return power-law with norm k and index a at x.

bossa.sfh module

Galaxy parameter distributions.

class bossa.sfh.BoogaardSFMR(redshift: float)

Bases: object

Redshift-dependent SFMR with no flattening at high masses.

Computes the redshift-dependent star formation-mass relation (SFMR) with no flattening at high masses, for a given redshift. Allows calculating either the star-formation rate (SFR) from the galaxy stellar mass, or the galaxy stellar mass from the SFR. Meant to be implemented trough sfr.SFMR().

Parameters:

redshift (float) – Redshift at which to compute the relation.

Attributes

redshiftfloat

Redshift at which to compute the relation.

Notes

The model is by Boogaard et al. (2018) [1]_ , with the SFR as a log-linear function of the mass, a the slope and b the intercept.

See Also

SFMR : Implements this class.

References

[1]

Boogaard,L. A., Brinchmann, J., Bouche, N. et al. (2018). The MUSE Hubble Ultra Deep Field Survey - XI. Constraining the low-mass end of the stellar mass-star formation rate relation at z<1. A&A, 619, A27. doi:10.1051/0004-6361/201833136

A = 0.83

Slope of the log-linear SFR(m).

Type:

float

property b: float

Log-linear SFR(m) intercept. Redshift-dependent.

Type:

float

property c: float

SFMR auxiliary variable. Redshift-dependent.

Type:

float

class bossa.sfh.ChruslinskaSFRD(model: str = 'midmet', canon: bool = False, per_redshift_met_bin: bool = False)

Bases: object

Star formation rate density grid.

Loads the precomputed star formation rate density (SFRD) grid over redshift (z) and metallicity (Z_OH) and finds the SFRD corresponding to the (z,Z) pair closest to the (z,Z) provided by the user. Allows for choosing between the extreme low- and high-metallicity models, or a moderate-metallicity model.

Parameters:

• model ({'midmet', 'lowmet', 'highmet'}, default: 'midmet') – Option of SFRD grid model.

• canon (bool, default : False) – Whether to assume an invariant IMF or not.

• per_redshift_met_bin (bool, default : False) –

  Alters the SFRD computation. For testing purposes only.

  Deprecated since version 1.0: Keep to default value.

Attributes

modelstr

Choice of SFRD grid model.

canonstr

Whether to assume an invariant IMF or not.

sfrd_redshift_arrayNDArray

Array of redshifts corresponding to the SFRD grid.

sfrd_dtime_arraynumpy array

Array of time steps defining the SFRD grid redshifts.

logsfrd_arraynumpy array

SFRD log array over the redshift-metallicity grid.

Warns:

UserWarning – If get_logsfrd() is run before set_grid().

Warning

The per_redshift_met_bin parameter is for testing purposes only and will result in a wrong computation of the star formation rate. It should be kept to the default value (False).

Notes

The precomputed SFRD grids are by Chruslinska et al. (2020) [9] and were calculated with the same GSMF, SFMR and MZR relations employed in this module. These grids already take into account the corrections for the environment-dependent IMF from sfh.Corrections.

At the moment only three permutations are included. These correspond to the high, moderate and low metallicity , defined by Chruslinska & Nelemans (2019) [4_]. They are,

• Low metallicity: combines sfh.MZR(model='PP04'), sfh.SFMR(flattening='sharp') and sfh.GSMF(fixed_slope=True).

• Moderate metallicity: combines sfh.MZR(model='M09'), sfh.SFMR(flattening='moderate') and sfh.GSMF(fixed_slope=True).

• High metallicity: combines sfh.MZR(model='KK04'), sfh.SFMR(flattening='none') and sfh.GSMF(fixed_slope=True).

CANON_MODEL_PATH_DICT = {'highmet': PosixPath('/home/runner/work/BOSSA/BOSSA/data/C20_Results/SFRD_Z_z_data/302w14_FOH_z_dM.dat'), 'lowmet': PosixPath('/home/runner/work/BOSSA/BOSSA/data/C20_Results/SFRD_Z_z_data/204w14_FOH_z_dM.dat'), 'midmet': PosixPath('/home/runner/work/BOSSA/BOSSA/data/C20_Results/SFRD_Z_z_data/103w14_FOH_z_dM.dat')}

Path to invariant IMF SFRD model files.

Type:

dict

MODEL_PATH_DICT = {'highmet': PosixPath('/home/runner/work/BOSSA/BOSSA/data/C20_Results/SFRD_Z_z_data/302w14vIMF3aeh_FOH_z_dM.dat'), 'lowmet': PosixPath('/home/runner/work/BOSSA/BOSSA/data/C20_Results/SFRD_Z_z_data/204w14vIMF3aeh_FOH_z_dM.dat'), 'midmet': PosixPath('/home/runner/work/BOSSA/BOSSA/data/C20_Results/SFRD_Z_z_data/103w14vIMF3aeh_FOH_z_dM.dat')}

Paths to variant IMF SFRD model files.

Type:

dict

SFRD_FEH_ARRAY = array([-4.03 , -4.008, -3.986, -3.964, -3.942, -3.92 , -3.898, -3.876,        -3.854, -3.832, -3.81 , -3.788, -3.766, -3.744, -3.722, -3.7  ,        -3.678, -3.656, -3.634, -3.612, -3.59 , -3.568, -3.546, -3.524,        -3.502, -3.48 , -3.458, -3.436, -3.414, -3.392, -3.37 , -3.348,        -3.326, -3.304, -3.282, -3.26 , -3.238, -3.216, -3.194, -3.172,        -3.15 , -3.128, -3.106, -3.084, -3.062, -3.04 , -3.018, -2.996,        -2.974, -2.952, -2.93 , -2.908, -2.886, -2.864, -2.842, -2.82 ,        -2.798, -2.776, -2.754, -2.732, -2.71 , -2.688, -2.666, -2.644,        -2.622, -2.6  , -2.578, -2.556, -2.534, -2.512, -2.49 , -2.468,        -2.446, -2.424, -2.402, -2.38 , -2.358, -2.336, -2.314, -2.292,        -2.27 , -2.248, -2.226, -2.204, -2.182, -2.16 , -2.138, -2.116,        -2.094, -2.072, -2.05 , -2.028, -2.006, -1.984, -1.962, -1.94 ,        -1.918, -1.896, -1.874, -1.852, -1.83 , -1.808, -1.786, -1.764,        -1.742, -1.72 , -1.698, -1.676, -1.654, -1.632, -1.61 , -1.588,        -1.566, -1.544, -1.522, -1.5  , -1.478, -1.456, -1.434, -1.412,        -1.39 , -1.368, -1.346, -1.324, -1.302, -1.28 , -1.258, -1.236,        -1.214, -1.192, -1.17 , -1.148, -1.126, -1.104, -1.082, -1.06 ,        -1.038, -1.016, -0.988, -0.944, -0.9  , -0.856, -0.812, -0.768,        -0.724, -0.68 , -0.636, -0.592, -0.548, -0.504, -0.46 , -0.416,        -0.372, -0.328, -0.284, -0.24 , -0.196, -0.152, -0.108, -0.064,        -0.02 ,  0.024,  0.068,  0.112,  0.156,  0.2  ,  0.244,  0.288,         0.332,  0.376,  0.42 ,  0.464,  0.508,  0.552,  0.596,  0.64 ,         0.684,  0.728,  0.772,  0.816,  0.86 ,  0.904,  0.948,  0.992,         1.036,  1.08 ,  1.124,  1.168,  1.212,  1.256,  1.3  ,  1.344,         1.388,  1.432,  1.476,  1.52 ,  1.564,  1.608,  1.652,  1.696,         1.74 ])

SFRD grid [Fe/H] bin edges.

Type:

NDArray

SFRD_ZOH_ARRAY = array([5.3  , 5.322, 5.344, 5.366, 5.388, 5.41 , 5.432, 5.454, 5.476,        5.498, 5.52 , 5.542, 5.564, 5.586, 5.608, 5.63 , 5.652, 5.674,        5.696, 5.718, 5.74 , 5.762, 5.784, 5.806, 5.828, 5.85 , 5.872,        5.894, 5.916, 5.938, 5.96 , 5.982, 6.004, 6.026, 6.048, 6.07 ,        6.092, 6.114, 6.136, 6.158, 6.18 , 6.202, 6.224, 6.246, 6.268,        6.29 , 6.312, 6.334, 6.356, 6.378, 6.4  , 6.422, 6.444, 6.466,        6.488, 6.51 , 6.532, 6.554, 6.576, 6.598, 6.62 , 6.642, 6.664,        6.686, 6.708, 6.73 , 6.752, 6.774, 6.796, 6.818, 6.84 , 6.862,        6.884, 6.906, 6.928, 6.95 , 6.972, 6.994, 7.016, 7.038, 7.06 ,        7.082, 7.104, 7.126, 7.148, 7.17 , 7.192, 7.214, 7.236, 7.258,        7.28 , 7.302, 7.324, 7.346, 7.368, 7.39 , 7.412, 7.434, 7.456,        7.478, 7.5  , 7.522, 7.544, 7.566, 7.588, 7.61 , 7.632, 7.654,        7.676, 7.698, 7.72 , 7.742, 7.764, 7.786, 7.808, 7.83 , 7.852,        7.874, 7.896, 7.918, 7.94 , 7.962, 7.984, 8.006, 8.028, 8.05 ,        8.072, 8.094, 8.116, 8.138, 8.16 , 8.182, 8.204, 8.226, 8.248,        8.27 , 8.292, 8.314, 8.336, 8.358, 8.38 , 8.402, 8.424, 8.446,        8.468, 8.49 , 8.512, 8.534, 8.556, 8.578, 8.6  , 8.622, 8.644,        8.666, 8.688, 8.71 , 8.732, 8.754, 8.776, 8.798, 8.82 , 8.842,        8.864, 8.886, 8.908, 8.93 , 8.952, 8.974, 8.996, 9.018, 9.04 ,        9.062, 9.084, 9.106, 9.128, 9.15 , 9.172, 9.194, 9.216, 9.238,        9.26 , 9.282, 9.304, 9.326, 9.348, 9.37 , 9.392, 9.414, 9.436,        9.458, 9.48 , 9.502, 9.524, 9.546, 9.568, 9.59 , 9.612, 9.634,        9.656, 9.678, 9.7  ])

SFRD grid Z_OH bin edges.

Type:

NDArray

SFRD_ZOH_CENTERS_ARRAY = array([5.3       , 5.32211055, 5.34422111, 5.36633166, 5.38844221,        5.41055276, 5.43266332, 5.45477387, 5.47688442, 5.49899497,        5.52110553, 5.54321608, 5.56532663, 5.58743719, 5.60954774,        5.63165829, 5.65376884, 5.6758794 , 5.69798995, 5.7201005 ,        5.74221106, 5.76432161, 5.78643216, 5.80854271, 5.83065327,        5.85276382, 5.87487437, 5.89698492, 5.91909548, 5.94120603,        5.96331658, 5.98542714, 6.00753769, 6.02964824, 6.05175879,        6.07386935, 6.0959799 , 6.11809045, 6.14020101, 6.16231156,        6.18442211, 6.20653266, 6.22864322, 6.25075377, 6.27286432,        6.29497487, 6.31708543, 6.33919598, 6.36130653, 6.38341709,        6.40552764, 6.42763819, 6.44974874, 6.4718593 , 6.49396985,        6.5160804 , 6.53819095, 6.56030151, 6.58241206, 6.60452261,        6.62663317, 6.64874372, 6.67085427, 6.69296482, 6.71507538,        6.73718593, 6.75929648, 6.78140704, 6.80351759, 6.82562814,        6.84773869, 6.86984925, 6.8919598 , 6.91407035, 6.9361809 ,        6.95829146, 6.98040201, 7.00251256, 7.02462312, 7.04673367,        7.06884422, 7.09095477, 7.11306533, 7.13517588, 7.15728643,        7.17939698, 7.20150754, 7.22361809, 7.24572864, 7.2678392 ,        7.28994975, 7.3120603 , 7.33417085, 7.35628141, 7.37839196,        7.40050251, 7.42261307, 7.44472362, 7.46683417, 7.48894472,        7.51105528, 7.53316583, 7.55527638, 7.57738693, 7.59949749,        7.62160804, 7.64371859, 7.66582915, 7.6879397 , 7.71005025,        7.7321608 , 7.75427136, 7.77638191, 7.79849246, 7.82060302,        7.84271357, 7.86482412, 7.88693467, 7.90904523, 7.93115578,        7.95326633, 7.97537688, 7.99748744, 8.01959799, 8.04170854,        8.0638191 , 8.08592965, 8.1080402 , 8.13015075, 8.15226131,        8.17437186, 8.19648241, 8.21859296, 8.24070352, 8.26281407,        8.28492462, 8.30703518, 8.32914573, 8.35125628, 8.37336683,        8.39547739, 8.41758794, 8.43969849, 8.46180905, 8.4839196 ,        8.50603015, 8.5281407 , 8.55025126, 8.57236181, 8.59447236,        8.61658291, 8.63869347, 8.66080402, 8.68291457, 8.70502513,        8.72713568, 8.74924623, 8.77135678, 8.79346734, 8.81557789,        8.83768844, 8.85979899, 8.88190955, 8.9040201 , 8.92613065,        8.94824121, 8.97035176, 8.99246231, 9.01457286, 9.03668342,        9.05879397, 9.08090452, 9.10301508, 9.12512563, 9.14723618,        9.16934673, 9.19145729, 9.21356784, 9.23567839, 9.25778894,        9.2798995 , 9.30201005, 9.3241206 , 9.34623116, 9.36834171,        9.39045226, 9.41256281, 9.43467337, 9.45678392, 9.47889447,        9.50100503, 9.52311558, 9.54522613, 9.56733668, 9.58944724,        9.61155779, 9.63366834, 9.65577889, 9.67788945, 9.7       ])

SFRD grid Z_OH bin centers.

Type:

NDArray

SFRD_Z_ARRAY = array([1.32522111e-06, 1.39408208e-06, 1.46652120e-06, 1.54272439e-06,        1.62288724e-06, 1.70721550e-06, 1.79592561e-06, 1.88924527e-06,        1.98741400e-06, 2.09068375e-06, 2.19931960e-06, 2.31360037e-06,        2.43381938e-06, 2.56028519e-06, 2.69332241e-06, 2.83327249e-06,        2.98049463e-06, 3.13536672e-06, 3.29828625e-06, 3.46967138e-06,        3.64996201e-06, 3.83962088e-06, 4.03913477e-06, 4.24901578e-06,        4.46980261e-06, 4.70206193e-06, 4.94638987e-06, 5.20341356e-06,        5.47379268e-06, 5.75822120e-06, 6.05742917e-06, 6.37218454e-06,        6.70329519e-06, 7.05161096e-06, 7.41802588e-06, 7.80348041e-06,        8.20896387e-06, 8.63551702e-06, 9.08423466e-06, 9.55626852e-06,        1.00528301e-05, 1.05751940e-05, 1.11247009e-05, 1.17027612e-05,        1.23108586e-05, 1.29505539e-05, 1.36234890e-05, 1.43313910e-05,        1.50760769e-05, 1.58594581e-05, 1.66835453e-05, 1.75504536e-05,        1.84624080e-05, 1.94217493e-05, 2.04309398e-05, 2.14925697e-05,        2.26093639e-05, 2.37841888e-05, 2.50200599e-05, 2.63201491e-05,        2.76877933e-05, 2.91265029e-05, 3.06399706e-05, 3.22320809e-05,        3.39069202e-05, 3.56687873e-05, 3.75222044e-05, 3.94719284e-05,        4.15229638e-05, 4.36805748e-05, 4.59502993e-05, 4.83379629e-05,        5.08496941e-05, 5.34919395e-05, 5.62714809e-05, 5.91954525e-05,        6.22713591e-05, 6.55070956e-05, 6.89109670e-05, 7.24917100e-05,        7.62585151e-05, 8.02210504e-05, 8.43894865e-05, 8.87745224e-05,        9.33874129e-05, 9.82399979e-05, 1.03344732e-04, 1.08714718e-04,        1.14363739e-04, 1.20306293e-04, 1.26557633e-04, 1.33133805e-04,        1.40051687e-04, 1.47329035e-04, 1.54984528e-04, 1.63037814e-04,        1.71509565e-04, 1.80421523e-04, 1.89796563e-04, 1.99658748e-04,        2.10033391e-04, 2.20947120e-04, 2.32427946e-04, 2.44505338e-04,        2.57210293e-04, 2.70575422e-04, 2.84635028e-04, 2.99425197e-04,        3.14983892e-04, 3.31351045e-04, 3.48568666e-04, 3.66680947e-04,        3.85734376e-04, 4.05777857e-04, 4.26862835e-04, 4.49043428e-04,        4.72376566e-04, 4.96922137e-04, 5.22743143e-04, 5.49905856e-04,        5.78479994e-04, 6.08538899e-04, 6.40159720e-04, 6.73423619e-04,        7.08415972e-04, 7.45226594e-04, 7.83949964e-04, 8.24685473e-04,        8.67537675e-04, 9.12616559e-04, 9.60037825e-04, 1.00992319e-03,        1.06240069e-03, 1.11760502e-03, 1.17567787e-03, 1.23676830e-03,        1.30103310e-03, 1.36863721e-03, 1.45978314e-03, 1.61543075e-03,        1.78767408e-03, 1.97828266e-03, 2.18921464e-03, 2.42263699e-03,        2.68094772e-03, 2.96680051e-03, 3.28313200e-03, 3.63319196e-03,        4.02057663e-03, 4.44926573e-03, 4.92366328e-03, 5.44864289e-03,        6.02959781e-03, 6.67249634e-03, 7.38394315e-03, 8.17124711e-03,        9.04249640e-03, 1.00066416e-02, 1.10735876e-02, 1.22542954e-02,        1.35608947e-02, 1.50068086e-02, 1.66068914e-02, 1.83775809e-02,        2.03370682e-02, 2.25054833e-02, 2.49051031e-02, 2.75605795e-02,        3.04991927e-02, 3.37511321e-02, 3.73498055e-02, 4.13321831e-02,        4.57391768e-02, 5.06160609e-02, 5.60129369e-02, 6.19852482e-02,        6.85943499e-02, 7.59081390e-02, 8.40017521e-02, 9.29583367e-02,        1.02869906e-01, 1.13838285e-01, 1.25976154e-01, 1.39408208e-01,        1.54272439e-01, 1.70721550e-01, 1.88924527e-01, 2.09068375e-01,        2.31360037e-01, 2.56028519e-01, 2.83327249e-01, 3.13536672e-01,        3.46967138e-01, 3.83962088e-01, 4.24901578e-01, 4.70206193e-01,        5.20341356e-01, 5.75822120e-01, 6.37218454e-01, 7.05161096e-01,        7.80348041e-01])

SFRD grid Z bin edges.

Type:

NDArray

SFRD_Z_CENTERS_ARRAY = array([1.32522111e-06, 1.39443700e-06, 1.46726801e-06, 1.54390297e-06,        1.62454055e-06, 1.70938980e-06, 1.79867070e-06, 1.89261472e-06,        1.99146541e-06, 2.09547903e-06, 2.20492526e-06, 2.32008782e-06,        2.44126530e-06, 2.56877183e-06, 2.70293799e-06, 2.84411161e-06,        2.99265869e-06, 3.14896433e-06, 3.31343377e-06, 3.48649340e-06,        3.66859187e-06, 3.86020130e-06, 4.06181842e-06, 4.27396595e-06,        4.49719388e-06, 4.73208093e-06, 4.97923606e-06, 5.23930003e-06,        5.51294706e-06, 5.80088659e-06, 6.10386511e-06, 6.42266810e-06,        6.75812208e-06, 7.11109672e-06, 7.48250711e-06, 7.87331616e-06,        8.28453704e-06, 8.71723586e-06, 9.17253440e-06, 9.65161305e-06,        1.01557138e-05, 1.06861436e-05, 1.12442776e-05, 1.18315628e-05,        1.24495217e-05, 1.30997564e-05, 1.37839526e-05, 1.45038842e-05,        1.52614176e-05, 1.60585168e-05, 1.68972482e-05, 1.77797862e-05,        1.87084190e-05, 1.96855540e-05, 2.07137244e-05, 2.17955959e-05,        2.29339731e-05, 2.41318075e-05, 2.53922044e-05, 2.67184314e-05,        2.81139268e-05, 2.95823086e-05, 3.11273835e-05, 3.27531571e-05,        3.44638444e-05, 3.62638804e-05, 3.81579317e-05, 4.01509088e-05,        4.22479784e-05, 4.44545773e-05, 4.67764262e-05, 4.92195445e-05,        5.17902662e-05, 5.44952559e-05, 5.73415263e-05, 6.03364566e-05,        6.34878112e-05, 6.68037600e-05, 7.02928998e-05, 7.39642764e-05,        7.78274078e-05, 8.18923093e-05, 8.61695195e-05, 9.06701269e-05,        9.54057998e-05, 1.00388815e-04, 1.05632092e-04, 1.11149224e-04,        1.16954514e-04, 1.23063012e-04, 1.29490555e-04, 1.36253807e-04,        1.43370302e-04, 1.50858488e-04, 1.58737781e-04, 1.67028606e-04,        1.75752459e-04, 1.84931956e-04, 1.94590895e-04, 2.04754317e-04,        2.15448572e-04, 2.26701385e-04, 2.38541929e-04, 2.51000900e-04,        2.64110600e-04, 2.77905015e-04, 2.92419909e-04, 3.07692911e-04,        3.23763617e-04, 3.40673691e-04, 3.58466973e-04, 3.77189593e-04,        3.96890089e-04, 4.17619536e-04, 4.39431676e-04, 4.62383057e-04,        4.86533182e-04, 5.11944661e-04, 5.38683373e-04, 5.66818639e-04,        5.96423403e-04, 6.27574413e-04, 6.60352432e-04, 6.94842436e-04,        7.31133843e-04, 7.69320739e-04, 8.09502124e-04, 8.51782171e-04,        8.96270492e-04, 9.43082424e-04, 9.92339328e-04, 1.04416891e-03,        1.09870553e-03, 1.15609058e-03, 1.21647283e-03, 1.28000884e-03,        1.34686330e-03, 1.41720956e-03, 1.56603299e-03, 1.73389188e-03,        1.91974311e-03, 2.12551524e-03, 2.35334354e-03, 2.60559214e-03,        2.88487859e-03, 3.19410101e-03, 3.53646815e-03, 3.91553272e-03,        4.33522819e-03, 4.79990971e-03, 5.31439919e-03, 5.88403543e-03,        6.51472945e-03, 7.21302587e-03, 7.98617083e-03, 8.84218712e-03,        9.78995751e-03, 1.08393169e-02, 1.20011543e-02, 1.32875259e-02,        1.47117802e-02, 1.62886966e-02, 1.80346384e-02, 1.99677231e-02,        2.21080099e-02, 2.44777084e-02, 2.71014085e-02, 3.00063360e-02,        3.32226349e-02, 3.67836802e-02, 4.07264245e-02, 4.50917811e-02,        4.99250485e-02, 5.52763809e-02, 6.12013083e-02, 6.77613129e-02,        7.50244667e-02, 8.30661387e-02, 9.19697759e-02, 1.01827770e-01,        1.12742417e-01, 1.24826975e-01, 1.38206844e-01, 1.53020866e-01,        1.69422764e-01, 1.87582736e-01, 2.07689228e-01, 2.29950881e-01,        2.54598701e-01, 2.81888455e-01, 3.12103324e-01, 3.45556845e-01,        3.82596159e-01, 4.23605618e-01, 4.69010771e-01, 5.19282781e-01,        5.74943314e-01, 6.36569950e-01, 7.04802180e-01, 7.80348041e-01])

SFRD grid Z bin centers.

Type:

NDArray

get_logsfrd(feh, redshift) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return SFRD closest to (feh, redshift).

Searches for the closest (feh, redshift) in the SFRD grid and returns the corresponding SFRD log value.

Parameters:

• feh (float) – The desired [Fe/H].

• redshift (float) – The desired redshift.

Returns:

logsfrd – SFRD log corresponding to the closest point in the grid.

Return type:

float

Warns:

UserWarning – If load_grid() has not been called yet.

Warning

The user should bear in mind the grids range from -4 to 1.7 in [Fe/H] and 0 to 10 in redshift. Passing values outside these ranges will always return the edges of the grid.

set_grid() → None

Build redshift and SFRD arrays corresponding to SFRD grid.

class bossa.sfh.Corrections(metallicity: ndarray[tuple[int, ...], dtype[float]], sfr: ndarray[tuple[int, ...], dtype[float]])

Bases: object

Corrections to a Kroupa IMF-based star formation rate.

Calculates corrections to a star formation rate (SFR) measured by assuming a Kroupa initial mass function (IMF), from imf.Star(invariant=True), for the environment-dependent IMF from imf.IGIMF. The corrections are a multiplicative factor dependent on the SFR and associated [Fe/H].

Parameters:

• metallicity (NDArray) – Array of metallicities at which to compute the corrections.

• sfr (NDArray) – Array of kSFR values for which to compute corrections.

Attributes

metallicityNDArray

Array of metallicities at which to compute the corrections.

sfr_kroupaNDArray

Array of kSFR values correspondent to each metallicity for

which to compute corrections.

correctionsNDArray

Array of calculated corrections for the given SFR-metallicity pairs.

metallicity_dataNDArray

Metallicity column from the precalculated grid.

sfr_kroupa_dataNDArray

kSFR column from the precalculated grid.

sfr_correction_dataNDArray

Correction columns from the precalculated grid.

Notes

The corrections are obtained for arbitrary values of SFR and metallicity by interpolation of the SFR density grid from Chruslinska et al. (2020) [9], kindly made available by Martyna Chruslinska.

All metallicities are given as [Fe/H].

References

[9] (1,2)

Chruslinska, M., Jerabkova, T., Nelemans, G., Yan, Z. (2020). The effect of the environment-dependent IMF on the formation and metallicities of stars over cosmic history. A&A, 636, A10. doi:10.1051/0004-6361/202037688

get_corrections() → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Compute corrections for metallicity, sfr.

Computes a 2D grid of corrections for all SFR-metallicity pairs from sfr and metallicity.

Returns:

corrections – Correction array of shape (len(`metallicity`), len(`sfr`)).

Return type:

NDArray

load_data() → None

Load original correction data.

class bossa.sfh.GSMF(redshift: float, fixed_slope: bool = True)

Bases: object

Compute the redshift-dependent galaxy stellar mass function.

Compute the redshift-dependent galaxy stellar mass function (GSMF) as a Schechter function at high masses, and as power-law with either fixed of redshift-dependent slope at low masses. The GSMF returns a galaxy number density *per stellar mass *.

Attributes

redshiftfloat

Redshift at which to compute the GSMF.

fixed_slopebool

Whether to use the fixed (True) or the varying (False) low-mass slope model.

Notes

This class implements the GSMF model from Chruslisnka & Nelemans (2019) [4]_. For galaxy stellar masses (log) greater than logm_break, it is a Schechter function,

\[\Phi(M_\ast) = \Phi_\ast e^{-M/M_\ast} \left(\frac{M_\ast}{M_\mathrm{co}}\right)^{a}.\]

Its three parameters (phi, M_co and a) are redshift-dependent. The values of log(phi), log(M_co) and a at 13 redshifts between 0.05 and 9 (corresponding to Table 1 of Chruslinska & Nelemans, 2019) [4]_ are kept in CHR19_GSMF.

For z<= 0.05, the parameters are assumed to be the same as at 0.05. For 0.05<z<=9, they are interpolated from CHR19_GSMF. Beyond, log(M_co) and a retain their z=9 values, while log(phi) is assumed to increase linearly with its mean variation rate between z=8-9.

Below the break, the GSMF is modeled as a power-law, with a slope low_mass_slope. Depending on fixed_slope, it can either be fixed to -1.45, or increase as

\[f(z) = 7.8 + 0.4 z\]

up to z=8 and be constant beyond.

log_gsmf(logm: float) → float

Log of the GSMF as function of log of the mass.

Parameters:

logm (float) – Logarithm of the galaxy stellar mass.

Returns:

log_gsmf – Logarithm of the GSMF at 10**logm.

Return type:

float

property logm_break: float

Break mass log between Schechter and power-law components.

property low_mass_slope: float

Slope of the simple power law at low masses.

class bossa.sfh.MZR(redshift: float, model: str = 'KK04', scatter_model: str = 'none')

Bases: object

General redshift-dependent metallicity-mass relation class.

Compute the redshift-dependent mass-(gas) metallicity relation (MZR) for one of four parameter sets: : “KK04”, “T04”, “M09” or “PP04”. The MZR takes the form of a power-law at low masses with slope gamma, which flattens around a turnover mass m_to to an asymptotic metallicity z_a. Metallicity given and expected as

\[\mathrm{Z}_\mathrm{OH} = 12 + \log(\mathrm{O}/\mathrm{H}).\]

Parameters:

• redshift (float) – Redshift at which to compute the relation.

• model ({"KK04", "T04", "M09", "PP04"}, default: "KK04") – Option of MZR parameter set.

• scatter_model ({"none", "normal", "max", "min"}, default : "none") – Model for metallicity scatter about the MZR.

Attributes

redshiftfloat

Redshift at which to compute the relation.

mzr_modelstr

Option of MZR parameter set.

z_afloat

Asymptotic Z_OH metallicity of the high-mass end of the relation. Redshift-dependent.

logm_tofloat

Turnover mass, i.e., mass at which the relation begins to flatten to the asymptotic z_a.

gammafloat

Low-mass end slope. Redshift-dependent.

dzfloat

Mean variation rate of the MZR between z=2.2 and z=3.5.

Warns:

UserWarning – If methods zoh(m) or m(zoh) are run before set_params().

Notes

This class implements the MZR models in from Chruslinska & Nelemans (2019) [4]_. They choose a parametrization

\[12 + \log[\mathrm{O/H}] = \mathrm{Z}_a - \log\left[ 1 + \left(\frac{M_\ast}{M_\mathrm{TO}}\right)^{-\gamma} \right],\]

where the parameters are the asymptotic metallicity z_a, the turn-off mass (log) logm_to and the low-mass end slope :attr:`gamma.

Four sets of parameters are collected by Chruslinska & Nelemans (2019) [4]_: Tremontini et al. (2004) [5] (T04), Kobulnicky & Kewley [6] (2004) (KK04), Pettini & Pagel [7] (2004) (PP04) and Mannucci et al. [8] (2009) (M09).

The relation is fitted for four redshift bins z ~ 0.07, 0.7, 2.2, 3.5, such that each model provides four sets of corresponding MZR parameters. In order to get the MZR at arbitrary redshift, a (mass, metallicity) array is generated at each of the four original z and, for each mass, the metallicity is interpolated to the desired z. Fitting of the MZR to the interpolated points sets the parameters at that z.

For z > 3.5, parameters are kept as for z=3.5, but it is assumed that the normalization varies linearly with redshift with the same rate as the average rate (dz) between z=2.2 and z=3.5.

References

[5]

Tremontini, C. A., Heckamn, T. M., Kauffmann, G. et al. (2004). The Origin of the Mass-Metallicity Relation: Insights from 53,000 Star-forming Galaxies in the Sloan Digital Sky Survey. ApJ, 613, 898. doi:10.1086/423264

[6]

Kobulnicky, H. A., Kewley, L. J. (2004). Metallicities of 0.3 < z < 1.0 Galaxies in the GOODS-North Field. ApJ, 617, 240. doi:10.1086/425299

[7]

Pettini, M., Pagel, B. E. J. (2004). [Oiii]/[Nii] as an abundance indicator at high redshift. MNRAS, 348(3), L59. doi:10.1111/j.1365-2966.2004.07591.x

[8]

Mannucci, F., Cresci, G., Maiolino, R. et al. (2009). LSD: Lyman-break galaxies Stellar populations and Dynamics - I. Mass, metallicity and gas at z~3.1. MNRAS, 398(4), 1915. doi:10.1111/j.1365-2966.2009.15185.x

IP_ARRAYS_LEN = 50

Length of mass array to use for interpolation.

Type:

int

IP_REDSHIFT_ARRAY = array([0. , 0.7, 2.2, 3.5])

Redshifts from which to interpolate.

Type:

NDArray

LOGM_MAX = 12.0

Maximum mass log for interpolation.

Type:

float

LOGM_MIN = 7.0

Minimum mass log for interpolation.

Type:

float

property ip_param_array: list

Array of MZR parameters from the chosen model.

Contains parameters for all fit redshifts simultaneously, for use in interpolation to arbitrary redshift. Lines are z = 0.07, 0.7, 2.2, 3.5; columns are z_a, logm_to, gamma, dz.

logm(zoh: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → float | ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Inverse of the MZR with no scatter.

Parameters:

zoh (array_like) – Z_OH metallicity. Either a scalar or an array-like (e.g., list, NDArray).

Returns:

Logarithm of the galaxy stellar mass. Either a float or an array according to input metallicity.

Return type:

float or NDArray

Raises:

AttributeError – If set_params() has not been called yet.

property scatter: Callable[[float], float]

Return a value for metallicity scatter around the MZR.

Depending on scatter_model, will be a normal distribution with mean 0 and standard deviation equal to DISPERSION (if flattening is “norm”); or fixed to either 0 (if flattening is “none”), DISPERSION (if flattening is “min”) or -DISPERSION (if flattening is “max”).

set_params() → None

Interpolate MZR parameters to redshift.

zoh(logm: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → float | ndarray[tuple[int, ...], dtype[_ScalarType_co]]

MZR with chosen scatter.

Parameters:

logm (array_like) – Logarithm of the galaxy stellar mass. Either a scalar or an array-like (e.g., list, NDArray).

Returns:

Z_OH metallicity. Either a float or array according to input mass.

Return type:

float or NDArray

Raises:

AttributeError – If set_params() has not been called yet.

class bossa.sfh.SFMR(redshift: float, flattening: str = 'none', scatter_model: str = 'none')

Bases: object

General redshift-dependent star-formation mass relation class.

General SFMR class, with options for no, moderate or sharp flattening at high masses. Provides a unified way to access the three SFMR classes: BoogaardSFMR (no flattening), SpeagleSFMR (moderate flattening) and TomczakSFMR (sharp flattening).

Parameters:

• redshift (float) – Redshift at which to compute the relation.

• flattening ({'none', 'moderate', 'sharp'}, default: 'none') – SFMR flattening mode.

• scatter_model ({'none', 'normal', 'min', 'max'}, default : 'none') – Model for SFR scatter_model about the SFMR.

Attributes

redshiftfloat

Redshift at which to compute the relation.

Notes

Follows Chruslinska & Nelemans (2019) [4]_.

References

[4]

Chruslinska, M. & Nelemans, G. (2019). Metallicity of stars formed throughout the cosmic history based on the observational properties of star-forming galaxies. MNRAS, 488(4), 5300. doi:10.1093/mnras/stz2057

DISPERSION = 0.3

Empirical SFR dispersion around the SFMR.

From Chruslisnka & Nelemans (2019). [4]_

Type:

float

INTERNAL_DISPERION = 0.14

Galaxy internal Z_OH dispersion.

From Chruslisnka & Nelemans (2019). [4]_

Type:

float

logsfr(logm: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]

Compute the SFR for a galaxy stellar mass log.

property scatter: Callable[[], float]

Return a value for SFR scatter around the SFMR.

Depending on flattening, will be a normal distribution with mean 0 and standard deviation equal to DISPERSION (if flattening is “norm”); or fixed to either 0 (if flattening is “none”), DISPERSION (if flattening is “min”) or -DISPERSION (if flattening is “max”).

property sfmr: BoogaardSFMR | SpeagleSFMR | TomczakSFMR

Instance of one of the SFMR model classes.

class bossa.sfh.SpeagleSFMR(redshift: float)

Bases: object

Redshift-dependent SFMR with moderate flattening at high masses.

Computes the redshift-dependent star formation-mass relation (SFMR) with moderate flattening at high masses, while keeping a BoogaardSFMR at low masses, for a given redshift. Allows calculating the star-formation rate (SFR) from the galaxy stellar mass. Meant to be implemented trough sfr.SFMR().

Parameters:

redshift (float) – Redshift at which to compute the relation.

Attributes

redshiftfloat

Redshift at which to compute the relation.

lowmass_sfmrsfr.BoogaardSFMR.

SFMR below LOGM_BREAK.

Notes

The SFR is modeled as a log-linear function of the mass, with a as the slope and b the intercept. Below a break mass :const:LOGM_BREAK, the SFMR is given by a BoogaardSFMR (Boogaard et al., 2018) [1]_. Above the break, the log-linear form is kept, but the slope becomes redshift-dependent, following the model by Speagle et al. (2014) [2]_. The intercept is defined by continuity with the Boogaard SFMR.

References

[2]

Speagle, J. S., Steinhardt, C. L., Capak, P. L., Silverman, J. D. (2014). A highly consistent framework for the evolution of the star-forming “main sequence” from z~0-6. ApJS, 214, 15. doi:10.1088/0067-0049/214/2/15.

LOGM_BREAK = 9.7

Break mass between Boogaard and Speagle SFMRs.

Type:

float

property a: float

Log-linear SFR(m) slope. Redshift-dependent.

Type:

float

property b: float

Log-linear SFR(m) intercept. Redshift-dependent.

Type:

float

property time: float

Age of the universe, in Gyr, at redshift.

Type:

float

class bossa.sfh.TomczakSFMR(redshift: float)

Bases: object

Redshift-dependent SFMR with sharp flattening at high masses.

Computes the redshift-dependent star formation-mass relation (SFMR) with sharp flattening at high masses, while keeping a BoogaardSFMR at low masses, for a given redshift. Allows calculating the star-formation rate (SFR) from the galaxy stellar mass. Meant to be implemented trough sfr.SFMR().

Parameters:

redshift (float) – Redshift at which to compute the relation.

Attributes

redshiftfloat

Redshift at which to compute the relation.

lowmass_sfmrsfh.BoogaardSFMR

SFMR below logm_break.

Notes

Tomczak et al. (2016) [3]_ model the SFMR as a power-law with slope GAMMA at low masses, which saturates to s0 above a turn-off mass m_to. Following Chruslinska & Nelemans (2019) [4]_, here the SFMR is given as a sfr.BoogaardSFMR below the turn-off, and by the Tomczak SFMR above it.

References

[3]

Tomczak, A. R., Quadri, R. F., Tran, K.-V. H. et al. (2014). Galaxy stellar mass functions from ZFOURGE/CANDELS: an excess of low-mass galaxies since z=2 and the rapid buildup of quiescent galaxies. ApJ, 783, 95. doi:10.1088/0004-637X/783/2/85

GAMMA = 1.091

Power-law slope.

Type:

float

property break_corr: float

Correction to match the SFMR models at the break.

Type:

float

property logm_break: float

Break mass between Boogaard and Tomczak SFMRs.

Type:

float

property logm_to: float

Turn-off mass log. Redshift-dependent.

Type:

float

property s0: float

High mass saturation SFR log. Redshift-dependent.

Type:

float

bossa.utils module

bossa.utils.FeH_to_OFe(FeH)

bossa.utils.FeH_to_Z(FeH)

class bossa.utils.Length(length: int)

Bases: object

length: int

bossa.utils.ZOH_from_FeH(FeH)

bossa.utils.ZOH_to_FeH(ZOH)

bossa.utils.ZOH_to_FeH2(ZOH)

bossa.utils.a_to_logp(a, m_tot)

bossa.utils.bintype(bintype)

Translate the binary type from numeric ID to a string abbreviation.

bossa.utils.chirp_mass(row)

Calculate the chirp mass for a dataframe row.

bossa.utils.create_logger(name=None, fpath=None, propagate=True, parent=None)

bossa.utils.enumerate_bin_edges(bin_edges)

bossa.utils.fix_unit(x, unit)

If x is an astropy Quantity, return x. Otherwise, return x with the astropy unit ‘unit’.

bossa.utils.float_or_arr_input(func: Callable[[object, float, ...], float]) → Callable[[object, float | ndarray[tuple[int, ...], dtype[float]], ...], float | ndarray[tuple[int, ...], dtype[float]]]

Convert first parameter from float to 1-dimensional array.

bossa.utils.format_time(time)

bossa.utils.get_bin_centers(bin_edges)

bossa.utils.get_bin_frequency_heights(x_array, bin_edges)

bossa.utils.get_linear_fit(xy0, xy1)

bossa.utils.get_linear_fit_area(linear_fit, x0, x1)

bossa.utils.get_uniform_bin_edges(x_array, bin_size)

bossa.utils.input_unit(units: tuple)

Decorator

bossa.utils.interpolate(ipX, ipY, X)

Interpolate between each line of a pair of arrays.

Parameters:

• ipX (numpy array) – 2-dimensional array. Each line corresponds to the x coordinates of one set of points between which to interpolate.

• ipY (numpy array) – 2-dimensional array. Each line corresponds to the y coordinates of one set of points between which to interpolate.

• X (numpy array) – 1-dimensional array. x coordinates for which each line of ipX and ipY will be interpolated.

Returns:

Y – 1-dimensional array. Results of interpolation of ipX and ipY for each element of X.

Return type:

numpy array

bossa.utils.logp_from_row(row)

Recovers the LogP from an appropriately written seed.

bossa.utils.logp_to_a(logp, m_tot)

bossa.utils.mass_ratio(m1, m2)

Calculate the mass ratio q as greater mass/lesser mass.

bossa.utils.pull_snmass(row)

bossa.utils.pull_snmass1(row)

bossa.utils.pull_snmass2(row)

bossa.utils.sample_histogram(sample, N=1, m_min=0.08)

bossa.utils.step(array, index_array, midpoint_i)

bossa.utils.symmetrize_masses(row)

bossa.utils.valley_minimum(array, index_array)

bossa.zams module

Orbital parameter distributions for zero-age main sequence multiple systems.

class bossa.zams.CompanionFrequencyDistribution(m1: float, q_distr: float, uncorrelated: bool = False, extrapolate_uncorrelated_distribution: bool = False)

Bases: CompanionFrequencyDistributionHighQ

Orbital period distribution for a 0.1<=q<=1 ZAMS star pair.

For a primary of mass m1, compute the log orbital period (logp) probability density function (PDF) for a companion with some mass m_cp such that 0.3 <= q <= 1.0 (q=m_cp/m1).

Allows for either a strongly m1- and logp-dependent piecewise function of power-law, linear and exponential components; or a uniform on logp distribution.

All orbital periods are given in days and masses in solar masses.

Parameters:

• m1 (float) – Primary mass.

• q_distr (MassRatioDistribution) – Mass ratio distribution for the same m1.

• uncorrelated (bool) – Whether to assume a correlated distribution or not.

• extrapolate_uncorrelated_distribution (bool) – If an uncorrelated distribution is assumed, whether to extrapolate it to the range of the correlated distribution.

Attributes

q_distrMassRatioDistribution

Mass ratio distribution for the same m1.

n_q03float

Fraction of 0.3 <= q <= 1.0 star pairs with m1.

n_q01float

Fraction of 0.1 <= q < 0.3 star pairs with m1.

Notes

The distribution is by Moe & Di Stefano (2017) [1]_ and covers the 0.2<=logp<=8` range. Most of the observational techniques considered therein are not able to probe pairs below q=0.3, and thus the period distribution is only empirically fitted to the q>0.3 region, yielding the distribution in CompanionFrequencyDistributionHighQ.

However, from the particular observations that do probe 0.1 <= q < 0.3, they are able to empirically fit the mass ratio distribution in that region, in the form of MassRatioDistribution.gamma_smallq. Thus, from the integration of the mass ratio distribution it is possible to compute the ratio n_q01/n_q03 between pairs above and below q=0.3.

This class calculates that ratio, and uses it as a correction factor to obtain, from the companion frequency in 0.3 <= q <= 1.0 (\(f_{\log P; q>0.3}\)), the companion frequency in 0.1 <= q <= 1.0 (\(f_{\log P; q>0.1}\)).

The uncorrelated distribution is a uniform on logp probability distribution between 0.4 and 3, or Öpik’s law [3]_. The extrapolate_uncorrelated_distribution parameter allows extrapolating it to the same range as that of the correlated distribution.

References

[3]

Öpik, E. (1924). Statistical Studies of Double Stars: On the Distribution of Relative Luminosities and Distances of Double Stars in the Harvard Revised Photometry North of Declination -31°. Publications of the Tartu Astrofizica Observatory, 25, 1.

companion_frequency_q01(logp: float) → float

Returns companion frequency at 0.1<=q<=1.0, logp.

class bossa.zams.CompanionFrequencyDistributionHighQ(m1: float)

Bases: object

Orbital period distribution for a 0.3<=q<=1 ZAMS star pair.

For a primary of mass m1, compute the log orbital period (logp) probability density function (PDF) for a companion with some mass m_cp such that 0.3 <= q <= 1.0 (q=m_cp/m1).

The PDF is a strongly m1- and logp-dependent piecewise function of power-law, linear and exponential components.

All orbital periods are given in days and masses in solar masses.

Parameters:

m1 (float) – Primary mass.

Attributes

m1float

Primary mass.

See Also

CompanionFrequencyDistribution :

Inherits from this class and extrapolates the distribution down to q=0.1. Includes an uncorrelated distribution option.

MultipleFraction :

Accounts for higher-order multiples in the companion frequency.

Notes

The distribution is by Moe & Di Stefano (2017) [1]_, with small adjustments as described by de Sá et al. (submitted) [2]_. Although it is referred to as a PDF, the distribution is defined as a companion frequency,

\[f_{\log P; q>0.3} (M_1,P) := \frac{d N_{cp, q>0.3} }{d N_1\, d\log P},\]

i.e., the number of companions, per primary with mass \(M_1\), per orbital period decade, around a period \(P\).

The companion frequency is empirically fitted for 0.2 <= logp < 1, logp = 2.7, logp = 5.5 and 5.5 < logp <= 8.0. For the intermediate intervals, it is set to increase linearly with logp.

A = 0.018

Slope within DELTA_LOGP/2 of logp=2.7.

Type:

float

DELTA_LOGP = 0.7

Half-width of the range where the slope is A.

Type:

float

LOGP_BREAKS = [0.2, 1.0, 2.0, 3.4000000000000004, 5.5, 8.0]

Distribution logp breaks.

Type:

list

LOGP_MAX = 8.0

Maximum allowed logp.

Type:

float

LOGP_MIN = 0.2

Minimum allowed logp.

Type:

float

M1_MAX = 150

Maximum allowed m1.

Type:

float

M1_MIN = 0.8

Minimum allowed m1.

Type:

float

companion_frequency_q03(logp: float) → float

Returns companion frequency at 0.3<=q<=1.0, logp.

property f_logp1_q03: float

First companion frequency constant.

Frequency of companions with 0.2 <= logp < 1 and 0.3 <= q <= 1.0 for primaries of mass m1.

property f_logp27_q03: float

Second companion frequency constant.

Frequency of companions with logp = 2.7 and 0.3 <= q <= 1.0 for primaries of mass :attr:m1.

property f_logp55_q03: float

Third companion frequency constant.

Frequency of companions with logp = 5.5 and 0.3 <= q <= 1.0 for primaries of mass m1.

class bossa.zams.EccentricityDistribution(canonical: bool = False)

Bases: object

Eccentricity probability distribution for a ZAMS star pair.

For a given primary of mass m1 and a companion orbit of log10(period) logp, compute the eccentricity probability density function (PDF) for that orbit. All orbits with logp <= 0.5 (default) are assumed to be circularized. Orbits with logp > 8.0 are not allowed (p=0). Primaries with m1 < 0.8 or m1 > 150.0 are not allowed (p=0).

Allows for either a mass- and orbital-period dependent power-law distribution, or to set all orbits to be circular.

All orbital periods are in days and masses in solar masses.

Parameters:

canonical (bool, default : False) – Whether to assume a correlated distribution or not.

Attributes

etafloat

Index of the eccentricity PDF power law.

kfloat

Normalization constant of the eccentricity PDF power law.

e_maxfloat

Maximum eccentricity set by the <70% Roche lobe filling factor at periastron.

m1float

Mass of the primary.

logpfloat

Log10(period) of the given orbit.

logp_circfloat

Log10(period) below which all orbits are assumed to be circularized. Should always be greater than attr:logp_min.

logp_minfloat

Minimum allowed log10(period).

logp_maxfloat

Maximum allowed log10(period).

m1_minfloat

Minimum allowed m1.

m1_maxfloat

Maximum allowed m1.

Warns:

UserWarning – If prob() is run before set_parameters().

Notes

The correlated distribution is by Moe & Di Stefano (2017) [1]_ with small adjustments as described by de Sá et al. (submitted) [2]_. It takes the shape of a simple power law, with the index eta being dependent on logp; the functional form of this dependency itself depends on m1. A maximum eccentricity is set as a function of logp from the condition that the Roche lobe filling fraction be <70% at periastron.

The minimum, maximum and circularization periods are set as in the original work, with log values 0.2, 8.0 and 0.5, respectively. The minimum m1 is set to 0.8 Msun also in accordance with the original work, but the mass range is extended up to 150.0 Msun.

The uncorrelated option always returns zero eccentricity.

References

[1]

Moe, M., Di Stefano, R. (2017). Mind Your Ps and Qs: The Interrelation between Period (P) and Mass-ratio (Q) Distributions of Binary Stars. ApJS, 230(2), 55. doi:10.3847/1538-4365/aa6fb6

[2]

de Sá, L. M., Bernardo, A., Rocha, L. S., Bachega, R. R. A., Horvath, J. E. (submitted).

prob(e: float) → float

Compute the eccentricity PDF value at the given e.

Parameters:

e (float) – Eccentricity at which to compute the PDF.

Returns:

prob – PDF value at e.

Return type:

float

Warns:

UserWarning – If power law parameters are not set up (set_parameters() has not been called yet).

Notes

If logp <=logp_circ (default 0.5), the method forces e=0 by approximating a delta at e=0 with a finite step. This is done to avoid dividing by zero while still allowing the PDF to integrate to 1. An artificial plateau is also inserted at e <= 0.0001 to avoid the probability exploding for circular systems, at the cost of slightly shifting the PDF’s norm from 1.

set_parameters(m1: float, logp: float) → None

Set power-law parameters at m1, logp.

Sets eta, k and e_max at m1 and :attr:logp. If the distribution is set to uncorrelated, or if m1 and/or logp are out of bounds, all parameters are set to zero.

class bossa.zams.MassRatioDistribution(canonical: bool = False)

Bases: object

Mass ratio probability distribution for a ZAMS star pair.

For a given primary of mass m1 and a companion orbit of log10(period) logp, compute the mass ratio probability density function (PDF) for that orbit. The companion mass being m_cp, the mass ratio is defined as q=m_cp/m1, and is limited to the interval 0.1 <= q <= 1.0.

Allows for either a mass- and orbital-dependent broken power-law with a “twin” (q > 0.95) excess; or an uncorrelated uniform distribution.

All orbital periods are in days and masses in solar masses.

Parameters:

canonical (bool, default : False) – Whether to assume a correlated distribution or not.

Attributes

solar_llimfloat

Lower mass limit of “solar-type” primaries.

solar_ulimfloat

Upper mass limit of “solar-type” primaries.

a_pointfloat

Mass midpoint for A-/late B-type primaries.

ob_llimfloat

Lower mass limit of mid B-, early B- and O-type primaries.

gamma_largeqfloat

Power law PDF index for 0.3 <= q <= 1.0.

gamma_smallqfloat

Power law PDF index for 0.1 <= q < 0.3.

f_twinfloat

Excess fraction of q>0.95 pairs relative to a power-law.

kfloat

Power law PDF normalization constant.

logp_minfloat

Minimum allowed log10(period).

logp_maxfloat

Maximum allowed log10(period).

m1_minfloat

Minimum allowed m1.

m1_maxfloat

Maximum allowed m1.

Warns:

UserWarning – If prob() is run before set_parameters().

Notes

The correlated distribution is by Moe & Di Stefano (2017) [1]_ with small adjustments as described by de Sá et al. (submitted) [2]_. It takes the shape of a two-part power law, with index gamma_smallq for 0.1 <= q < 0.3 and gamma_largeq for 0.3 <= q <= 1.0. It also includes an excess of systems with q > 0.95 (twin pairs) expressed as the twin fraction f_twin, so that at q > 0.95 the PDF is (1+f_twin) * power_law. As this excess is only observed for shorter-period systems, there is a maximum logp for which the excess twin population is present.

Solar-type primaries are defined as having masses 0.8 < m1 < 1.2. The midpoint of A-/late B-type primaries is defined to be at m1 = 3.5. Mid B-, early B- and O-type primaries are defined as having mass m1 > 6.0. The PDF is defined piecewise for each the two ranges and the midpoint. Interpolation gives the PDF in the two intermediary ranges: solar-A (1.2 <= m1 < 3.5) and A-OB (3.5 < m1 <= 6).

The minimum and maximum periods are set as in the original work, with log10 values 0.2 and 8.0, respectively. The minimum m1 is set to 0.8 also in accordance with the original work, but the mass range is extended up to 150.0. The minimum q is set to 0.1 as in the original work.

prob(q: float) → float

Compute the mass ratio PDF value at the given e.

Parameters:

q (float) – Mass ratio at which to compute the PDF.

Returns:

prob – PDF value at q.

Return type:

float

Warns:

UserWarning – If power law parameters are not set up (set_parameters() has not been called yet).

set_parameters(m1: float, logp: float) → None

Set distribution power-law parameters at m1, logp.

Sets gamma_largeq, gamma_smallq, k and f_twin. If the distribution is set to uncorrelated, or if m1 and/or logp are out of bounds, all parameters are set to zero.

class bossa.zams.MultipleFraction(mmin: float = 0.8, mmax: float = 150.0, nmax: int = 3, nmean_max: int = 11, only_binaries: bool = False)

Bases: object

Multiplicity fractions as a function of primary mass.

For a given primary mass m1, compute the probability of having n companions in `` 0.1 <= q <= 1.0`` pairs. The probability distribution over n is discrete, and takes the form of a truncated Poisson distribution.

Can return individual multiplicity fractions for up to nmax companions, or compute a binary fraction by assuming all non-isolated stars are in binaries.

All masses are in solar masses.

Parameters:

• mmin (float) – Minimum primary mass.

• mmax (float) – Maximum primary mass.

• nmax (float) – Maximum companion number.

• nmean_max (float) – Maximum mean companion number, for interpolation.

• only_binaries (bool) – Whether to assume all non-isolated stars are in binaries.

Attributes

q_distrMassRatioDistribution

Necessary to set up the companion frequency distributions.

m1_arrayNDArray

Primary masses to set up the companion frequency distributions.

nmean_arrayNDArray

Mean companion numbers corresponding to the masses in m1_array.

binary_fractionNDArray

Binary fractions corresponding to the primary masses in :attr:m1_array, when all stars are isolated or binaries.

multfreq_to_nmeanscipy.interpolate.interp1d

Multiplicity frequency to mean companion number interpolator.

m1_to_nmeanscipy.interpolate.interp1d

Primary mass to mean companion number interpolator.

nmaxfloat

Maximum companion number.

nmean_maxfloat

Maximum mean companion number, used for interpolation only.

Warns:

UserWarning – If ncomp_mean() is called before solve().

See Also

CompanionFrequencyDistribution :

Its correlated model is the source of the multiplicity fractions as a function of mass.

sampling.SimpleBinaryPopulation :

Implements this class to generate a full ZAMS binary population.

Notes

This class computes multiplicity fractions as suggested by Moe & Di Stefano (2017) [1]_, but for a general case, as described in de Sá et al. (submitted). Computation starts from the companion frequency distributed as in CompanionFrequencyDistribution. The number of companions per primary (multiplicity frequency) is given by integrating the companion frequency over orbital period,

\[f_\mathrm{mult}(M_1) = \int_{0.2}^{0.8} d\log P\, f_{\log P; q>0.3}(M_1,\log P).\]

The multiplicity fraction, \(F_n\), is defined as the fraction of all primaries with a number \(n\) of companions. These relate to the multiplicity frequency as:

\[f_\mathrm{mult}(M_1) = F_1(M_1) + 2F_2(M_1) + 3F_3(M_1) + ...,\]

for a primary mass \(M_1\). The \(F_n\) are not, in general, empirically constrained. This class follows Moe & Di Stefano (2017) [1]_ in extending the observed behavior for solar-type primaries to all primaries. In this case, the number of companions is observed to be distributed over \(M_1\) in the form of a Poissonian distribution, with a \(M_1\)-dependent mean \(n_\mathrm{mean}\) fully determined by imposing the empirical \(f_\mathrm{mult}(M_1)\) as a constraint.

By assuming a Poissonian truncated at nmax, the companion number n is distributed as

\[P_n(M_1) = \left( \sum_{ n=0 }^{ n_\mathrm{max} } \frac{n_\mathrm{mean}^n}{n!} \right)^{-1} \frac{n_\mathrm{mean}^{n}}{n!},\]

and \(F_n(M_1) = P_n(M_1)\). Then, from the definition of \(P_n\) and the \(f_\mathrm{mult}-F_n\) relation, \(f_\mathrm{mult}\) is written as

\[ f_\mathrm{mult}(n_\mathrm{mean}) = \frac{n_\mathrm{mean}}{1 + a/b},\]

with

\[a = {n_\mathrm{mean}}^{n_\mathrm{max}} n_\mathrm{max}!,\]

and

\[b = \sum_{ n=0 }^{ n_\mathrm{max}-1 } \frac{{n_\mathrm{mean}}^n}{n!}.\]

From this relation an array of \((f_\mathrm{mult}, n_\mathrm{mean})\) pairs is calculated, and from it a \(f_\mathrm{mult}\) to \(n_\mathrm{mean}\) interpolator is built. \(f_\mathrm{mult}\) is then determined by integrating the companion frequency for a given mass, as per its definition. This is done for masses m1_array, and the resulting \((m_1, f_\mathrm{mult})\) array yields a \((m_1, n_\mathrm{mean})\) array through the above interpolator. A second, \(m_1\) to \(n_\mathrm{mean}\), interpolator is then built.

get_multiple_fraction(n: int) → ndarray[tuple[int, ...], dtype[float]]

Return fraction of order n multiples for m1_array.

Parameters:

n (int) – Companion number.

Returns:

fracs – (len(m1_array),)-shaped array containing the n-multiplicity fractions for masses in :m1_array().

Return type:

NDArray

ncomp_mean(m1: float) → float

Return mean companion number for a primary mass m1.

Parameters:

m1 (float) – Primary mass.

Returns:

Mean companion number.

Return type:

float

Warns:

UserWarning – If solve() has not been called yet.

prob(l: float, k: int | ndarray[tuple[int, ...], dtype[int]] | list[int]) → ndarray[tuple[int, ...], dtype[float]]

Return probability of k companions given mean l.

solve() → None

Set up companion number probability distribution.

Sets up a series of interpolators necessary for computing the companion number as a function of mean companion number and primary mass. Defines m1_array and the corresponding nmean_array and binary_fraction, and is necessary for ncomp_mean() and get_multiple_fraction().

class bossa.zams.ZAMSSystemGenerator(imf_array: ndarray[tuple[int, ...], dtype[_ScalarType_co]], pairs_table_path: str | PathLike = PosixPath('/home/runner/work/BOSSA/BOSSA/data/canonical_mp_qe_table.h5'), m1_min: float = 0.8, qe_max_tries: int = 1, dmcomp_tol: float = 0.05, parent_logger: Logger | None = None)

Bases: object

Generate ZAMS multiples from a shared mass pool.

Receives an array of pre-sampled initial masses imf_array from which all masses (primary and of companions) are drawn without repetition. Builds zero-age main sequence (ZAMS) multiples by randomly pulling a primary mass from the pool, drawing a companion number; then for each companion drawing its mass from a mass ratio distribution, and looking for the closest match in imf_array, which is accepted if the relative difference between masses is at most dmcomp_tol. Orbital period and eccentricity are drawn from their respective distributions. Allows the user to pull one system at a time until the mass pool is exhausted or becomes unable to produce valid mass pairings. The mass pool allows the sample to follow an arbitrary initial mass function (IMF).

All orbital periods are in days and masses in solar masses.

Parameters:

• imf_array (numpy array) – Array from which to sample primary and companion masses.

• pairs_table_path (path_like, default : constants.BINARIES_UNCORRELATED_TABLE_PATH) – Path to a HDF5 file containing equiprobable (m1,logp,q,e) sets according to the desired orbital parameter distributions.

• m1_min (float, default : 0.8) – Minimum primary mass.

• qe_max_tries (int, default : 1) – Maximum number of attempts at drawing a valid q,e pair for a given m1,logp, before m1 is redrawn.

• dmcomp_tol (float, default : 0.05) – Maximum accepted difference between a companion mass drawn from a q-distribution and the closest value in imf_array, relative to the latter.

• parent_logger (logging Logger, default : None) – Logger of the class or module from which this class was instantiated.

Attributes

pairs_table_pathpath_like

Path to a HDF5 file containing equiprobable (m1,logp,q,e) sets according to the desired orbital parameter distributions.

imf_arrayNDArray

Array from which to sample primary and companion masses.

m1_minfloat

Minimum primary mass.

qe_max_triesint

Maximum number of attempts at drawing a valid q,e pair for a given m1,logp, before m1 is redrawn.

dmcomp_tolfloat

Maximum accepted difference between a companion mass drawn from a q-distribution and the closest value in imf_array, relative to the latter.

pairs_tabletables.File

Table loaded from pairs_table_path

lowmass_imf_arrayNDArray

Subarray of imf_array below m1_min.

highmass_imf_arraynumpy array

Subarray of imf_array above m1_min.

m1array_nint

Live length of highmass_imf_array.

m1array_iint

Index of the last m1 drawn from highmass_imf_array.

m1_arrayfloat32

Last m1 drawn from highmass_imf_array.

m1_tablefloat32

Closest match to m1_array in pairs_table.

dm1float

Difference between m1_table and m1_array relative to the latter.

m1grouptables.Group

Table of equiprobable companions for m1_table, identified by a set (logp,q,e).

loggerlogging.Logger

Instance logger.

See Also

sampling.SimpleBinaryPopulation :

Implements this class to generate a binary population.

Notes

This class allow for sampling multiples of arbitrary order, but it assumes that table pairs_table was built based on distributions appropriate for the desired degree of multiplicity. All companion masses are always removed from imf_array upon a successful draw.

Within triples or higher-order multiples, all orbital periods are drawn simultaneously, i.e., the orbital periods of individual companions are not treated as independent quantities. Orbital parameters are ordered in order of closest farthest companion in the output of sample_system(), to allow evolving only the inner binary. Note that this shifts the binary orbital period distribution to lower periods, as discussed in de Sá et al. [2]_.

Ultimately, orbital periods, mass ratios and eccentricities will be limited to the values in pairs_table, while both m1_table and m1_array are returned by sample_system(). It is expected that the table is composed of root-level groups, each of which corresponds to a primary mass; and that each m1group is composed of tables, each of which corresponding to a logp and containing mass ratio-eccentricity pairs. It is expected that all combinations of the four parameters found in the table are equiprobable. By default, this class loads tables from constants.BINARIES_UNCORRELATED_TABLE_PATH. Check its documentation for description on its construction.

This class can be employed on its own to generate individual systems. Its implementation for the generation of an entire sample of binaries is handled by the sampling.SimpleBinaryPopulation class.

Examples

>>> import numpy as np
>>> systemgenerator = ZAMSSystemGenerator(imf_array=np.logspace(-1, 2, int(1e6)))
>>> systemgenerator.setup_sampler()
>>> m1table_indices = np.random.randint(0, systemgenerator.m1array_n, 2)
>>> systemgenerator.open_m1group(m1table_indices[0])
>>> sampled_pairs1 = systemgenerator.sample_system(ncomp=1, ncomp_max=2)
>>> systemgenerator.open_m1group(m1table_indices[1])
>>> sampled_pairs2 = systemgenerator.sample_system(ncomp=2, ncomp_max=2)
>>> systemgenerator.close_pairs_table()

close_pairs_table() → None

Close the pairs_table file.

open_m1group(index: float) → None

Set the primary mass and open the corresponding group.

Sets m1_array to the the element of highmass_imf_array at index and sets m1_table, m1group and dm1.

sample_system(ncomp: int = 1, ncomp_max: int = 1) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Return parameters of a multiple system.

Generates a multiple system with ncomp companions for a primary set with open_m1group(), assuming up to ncomp_max companions are allowed. Returns ordered inner binary and further pair parameters, as well as companion number and total system mass.

ncomp_max is used for proper output formatting only.

Parameters:

• ncomp (int, default : 1) – Number of companions to the primary. Can be 0 (isolated).

• ncomp_max (int, default : 1) – Maximum number of companions in the underlying population.

Returns:

sample_pairs – (12+4*ncomp_max,)-shaped array of 12 inner binary parameters and 4 parameters per further companion.

Return type:

NDArray

Warns:

UserWarning – If the system fails to be generated.

Notes

For primary masses set with open_m1group(), the orbital period logs logp_table are drawn for all `ncomp` binaries from m1group. Then, starting from the innermost companion and moving toward the outermost one, the corresponding logp_table table is opened in m1group and a q_table,e_table pair is drawn from it. The companion mass is set to mcomp_table=q_table*m1_table, and its closest match in imf_array, mcomp_array, is found. The drawn pair is tested against dmcomp_tol, and if

\[\frac{|m_\mathrm{comp}^\mathrm{array}-m_\mathrm{table}|} {m_\mathrm{comp}^\mathrm{array}} \leq dm_\mathrm{comp}^\mathrm{tol},\]

the pair is accepted. If not, q,e can be drawn for up to qe_max_tries times. If no match can be found, the draw failed, and an empty parameter array is returned.

If at any point a valid pair fails to be found, the whole system is discarded and an empty array is returned. Otherwise, the parameters for the sampled pairs are returned, and the component masses are removed from the imf_array and its sub-arrays.

The 12 first output columns are [Table primary mass, Array primary mass, Relative m1 difference, Table secondary mass, Array secondary mass, Relative m2 difference, Mass ratio from table masses, Mass ratio from array masses, log10(orbital period), Eccentricity, Companion number, Total system mass].

Each further companion appends 4 more columns to the output. They are [Table companion mass, Array companion mass, log10(orbital period), Eccentricity].

setup_sampler() → None

Set up attributes for the sampler.

Loads data from table_path. Sets two mass sub-arrays, lowmass_imf_array and highmass_imf_array, to speed up sampling by assuming that m1 is always in highmass_imf_array and that \(m_\mathrm{comp}<m_1\). Sets the initial value of m1array_n.

bossa.zams.gen_seed(logp, q, e)

Generate an unique system identifier from its logp, q and e parameters.

Module contents