pimf.sampling.sampling

`pimf.sampling.sampling`

Module Contents

Classes

`IMFSample`	A class to calculate and store properties of a sample, beyond just a list of masses.
`IMFSampleList`	A class to calculate and store properties of several samples, beyond just a list of masses.

Functions

`draw_samples`	Draw samples from the given imf until the target mass is reached within a user specified tolerance.
`optimal_sampling`	Draw stars from the IMF using “optimal sampling”. (Which papers are best to cite here?)
`smith2021_sampling`

Data

rng

API

pimf.sampling.sampling.rng = 'default_rng(...)'

class pimf.sampling.sampling.IMFSample(masses, target_mass, stop_method)

A class to calculate and store properties of a sample, beyond just a list of masses.

Has the ability to store:

Quantity when the IMF has been sampled
The same Quantity when the IMF has been averaged over
The residual, defined as: (Qsampled - Qaveraged) / Qaveraged. for quantities like:
Number of Supernovae
Number of black holes
arbitrary quantities defined on a grid to be interpolated in mass, including ones that vary with time.

If you want to sample from the IMF several times, calculate the same quantities, and compare them, see also IMFSampleList.

Notes

The residual is defined as (Qsampled - Qaveraged) / Qaveraged, so a residual of 1 means the sampled value is twice that of the averaged, or 100%. A value close to 0 means they are similar, far away from 0 means different.

Initialization

__str__(): Return str(self).

add_number_of_supernovae(imf, mass_cutoff=8)

add_number_of_black_holes(imf, mass_cutoff_lower=25, mass_cutoff_higher=100)

add_interpolated_quantity(mass_grid, quantity_grid, imf, name, interp_kwargs={}, imf_extrapolate=False, Mmin=None, Mmax=None)

add_interpolated_quantity_time_dependant(mass_grid, quantity_grid, imf, name, interp_kwargs={}, imf_extrapolate=False, Mmin=None, Mmax=None)

add_quantity(function, imf_averaged_quantity, name)

abstractmethod save(filename)

classmethod load(filename, i=None)

Load single sample from a hdf5 file containing either just that sample or the ith sample of a list.

Single sample corresponds to i=None, ‘default’ but not yet implemented. Alternatively if filename is a sample list, i.e. saved with IMFSampleList.save specifing i loads the ith sample in.

Parameters

filename : string Filename to read from. i : None or int, optional Indexes a list of samples to load just that one, by default None (loads from single file).

Raises

NotImplementedError i=None currently not implemented as IMFSample doesn’t have a working save method. Use IMFSampleList (or contribute!) instead.

class pimf.sampling.sampling.IMFSampleList(sample_list)

A class to calculate and store properties of several samples, beyond just a list of masses.

Has the ability to store:

Quantity when the IMF has been sampled
The same Quantity when the IMF has been averaged over
The residual, defined as: (Qsampled - Qaveraged) / Qaveraged. for quantities like:
Number of Supernovae
Number of black holes
arbitrary quantities defined on a grid to be interpolated in mass, including ones that vary with time.

If you want to sample from the IMF only once, see also IMFSample.

Notes

Initialization

add_total_mass(imf)

add_most_massive_star(imf_max=100)

add_number_of_supernovae(imf, mass_cutoff=8)

add_number_of_black_holes(imf, mass_cutoff_lower=25, mass_cutoff_higher=100)

add_interpolated_quantity(mass_grid, quantity_grid, imf, name, interp_kwargs={}, imf_extrapolate=False, Mmin=None, Mmax=None)

add_interpolated_quantity_time_dependant(mass_grid, quantity_grid, imf, name, interp_kwargs={}, imf_extrapolate=False, Mmin=None, Mmax=None)

add_quantity(function, imf_averaged_quantity, name)

quantile(name, quantiles=[0.1, 0.5, 0.9], residual=False, ignore_nans=False)

save(filename)

Save to filename as a hdf5 file.

Saves: - Number of samples - Each chain of masses representing one realisation - Target mass - Stop method used - All IMF averaged, sampled, and residuals off derivated properties.

Can be loaded using the load class method.

classmethod load(filename): Read sample data from an hdf5 file called filename.

pimf.sampling.sampling.draw_samples(imf, stop_method='below', target_mass=None, full_output=False, rescale=False, rng=rng): Draw samples from the given imf until the target mass is reached within a user specified tolerance.

Parameters

imf : InitialMassFunction subclass The IMF to sample from. Needs to have inverse_cdf() method implemented. stop_method : str from {“below” | “above” | “closest”}, optional The stopping criteria, see notes below for more information, by default “below” target_mass : int or float, optional The target mass to aim for, by default None. If None, use the total mass of the provided IMF. full_output : bool, optional Whether or not to return an IMFSample object (True) or just a numpy array of the sampled masses, by default False (only return mass array). rescale : bool, optional Whether or not to rescale each mass so the final total is the target mass exactly. mi -> mi * Mtarget / Mtotal. By default, False (don’t rescale). rng : instance on numpy random Generator, optional The instance of numpy Generator to use. This is how the user can provide their own seed/random number generation method. By default the result of calling numpy.random.default_rng().

Returns

ndarray or IMFSample object An array of the masses drawn randomly from the IMF if full_output=False (default), or an IMFSample object representing the sample and additional information.

pimf.sampling.sampling.optimal_sampling(imf, target_mass=None, Mmax=100, full_output=False)

Draw stars from the IMF using “optimal sampling”. (Which papers are best to cite here?)

Note that this differs from ~pimf.sampling.draw_samples in that it is deterministic.

WARNING This will mutate imf.

Parameters

imf : InitialMassFunction subclass The IMF to sample from. Needs to have inverse_cdf() method implemented. target_mass : int or float, optional The target mass to aim for, by default None. If None, use the total mass of the provided IMF. full_output : bool, optional Whether or not to return an IMFSample object (True) or just a numpy array of the sampled masses, by default False (only return mass array).

Returns

ndarray or IMFSample object An array of the masses drawn randomly from the IMF if full_output=False (default), or an IMFSample object representing the sample and additional information.

pimf.sampling.sampling.smith2021_sampling(imf, Nsamples, Mtarget=None)