.. _imf-label:


The ``IMF`` module
==================

.. currentmodule:: pNbody.Mockimgs


The ``IMF`` modules provides a set of tools to handle initial mass functions (IMFs).
In particular, it can be used to generate individual particles that sample a
given IMF.

Definition
----------

An IMF is defined by a set of affine function (defined basically by a slope),
each defined in a mass interval (:math:`[m_i,m_{i+1}]`) that provide the mass
fraction of stars per unit mass interval:

  .. math::
        
    \Phi(m)_{[m_i,m_{i+1}]} = b_i\, m^a_i  
  
Here, :math:`a_i` is the slope (in a given mass range)
and :math:`b_i` is a normalization factor automatically
determined to guarantee that

  .. math::
        
    \int_{M_{\rm{min}}}^{M_{\rm{max}}}  \Phi(m) \, \textrm{d}m
    = \sum_i \int_{m_i}^{m_{i+1}}  b_i\, m^a_i  \, \textrm{d}m = 1,
    
with :math:`M_{\rm{min}}` and :math:`M_{\rm{max}}` the minimal and maximal
masses considered for the IMF.
    
All units are in solar mass.


Examples
--------

In the ``python`` interpreter, 
First import the  ``IMF`` module::

  from pNbody.IMF import IMF


Optionally, you can define a set of parameters that defines the IMF itself::

  params = {}
  params["Mmax"] = 50.                     # maximal imf mass in Msol
  params["Mmin"] = 0.05                    # minimal imf mass in Msol
  params["as"] = [0.7,-0.8,-1.7,-1.3]      # imf slope in a given mass range
  params["ms"] = [0.08,0.5,1.0]            # mass range for the imf slope


An IMF with one single slope -1.3 will be parameterized by::

  params = {}
  params["Mmax"] = 50.                     
  params["Mmin"] = 0.05                   
  params["as"] = [-1.3]      
  params["ms"] = []            
  
  
Then, create an ``IMF`` with a total mass of 1e5 solar mass, using the default
``pNbody`` IMF (Kroupa 2001)::

  imf = IMF(params=params,M0=1e5)

or use the parameters you defined above::

  imf = IMF(M0=1e5)

Once created, you can get information on the IMF::

  imf.info()

.. code-block:: text
                
  IMF mass in solar mass
  M0 = 100000

  Total number of stars in the IMF
  N = 351273

  IMF minimal and maximal masses in solar mass
  mmin = 0.05
  mmax = 50

  IMF slopes
  as = [0.7, -0.8, -1.7, -1.3]

  IMF masses ranges
  ms = [0.08, 0.5, 1.0]

  Current random seed
  seed = 0

  
To generate individual stellar masses, use::

  masses = imf.Sample()
  

the variable ``masses``, an ``numpy`` array will contains their values.
To plot the IMF with ``matplotlib``, use something like::

  from matplotlib import pylab as plt
  import numpy as np

  mmin = imf.getMinMass()
  mmax = imf.getMaxMass()

  bins = np.logspace(np.log10(mmin)-0.1,np.log10(mmax)+0.1,100)

  plt.hist(masses,bins=bins)
  plt.xscale('log')
  plt.yscale('log')
  plt.xlabel("Stellar Mass [Solar Mass]")
  plt.show() 
  

  

``pNbody.IMF`` module
---------------------

.. currentmodule:: pNbody.IMF

The ``IMF`` class
.................

.. autoclass:: IMF    
   :members:

Scripts
-------


``imf_sample_IMF``
..................

.. program-output:: imf_sample_IMF -h