Metadata-Version: 2.1
Name: mlgw
Version: 1.2.0
Summary: Machine learning modelling of the gravitational waves generated by black-hole binaries
Home-page: https://github.com/stefanoschmidt1995/MLGW/
Author: Stefano Schmidt
Author-email: stefanoschmidt1995@gmail.com
License: CC by 4.0
Description: mlgw
        ====
        
        **Author** Stefano Schmidt
        
        **email** stefanoschmidt1995@gmail.com
        
        **Copyright** Copyright (C) 2020 Stefano Schmidt
        
        **Licence** CC BY 4.0
        
        **Version** 1.1.0
        
        MACHINE LEARNING MODEL FOR THE GRAVITATIONAL WAVES GENERATED BY BLACK-HOLE BINARIES
        ===================================================================================
        
        ``mlgw`` (Machine Learning Gravitational Waves) is a useful tool to quickly generate a GW waveform for a BBH coalescence. It is part of a Master thesis work at University of Pisa (Italy) under supervision of prof. Walter Del Pozzo.
        It implements a ML model which is able to reproduce waveforms of GWs generated by state-of-the-art models. It is quicker than standard methods and it has the same degree of accuracy.
        
        To generate a wave:
        ::
        
        	import mlgw.GW_generator as generator
        	import numpy as np
        	import matplotlib.pyplot as plt
        	from mpl_toolkits.axes_grid.inset_locator import (inset_axes, InsetPosition,mark_inset)
        
        	#generating the wave
        	generator = generator.GW_generator() #creating an istance of the generator
        	theta = np.array([20,10,0.5,-0.3]) #list of parameters to be given to generator [m1,m2,s1,s2]
        	times = np.linspace(-8,0.02, 100000) #time grid at which waves shall be evaluated
        	h_p, h_c = generator.get_WF(theta, times) #returns amplitude and phase of the wave
        
        	generator.summary() #printing model summary
        
        	#plotting the wave
        	plt.figure(figsize=(15,8))
        	plt.title("GW by a BBH with [m1,m2,s1,s2] = "+str(theta), fontsize = 15)
        	plt.plot(times, h_p[0,:], c='k') #plot the plus polarization
        	plt.xlabel("Time (s)", fontsize = 12)
        	plt.ylabel(r"$h_+$", fontsize = 12)
        	axins = inset_axes(plt.gca(), width="70%", height="30%", loc=2, borderpad = 2.)
        	axins.plot(times[times >= -0.2], h_p[0,times >= -0.2], c='k')
        	plt.show()
        
        The output is: ::
        
        	###### Summary for MLGW model ######
        	   Grid size:     3500 
        	   Minimum time:  0.7999999999999999 s/M_sun
        	   ## Model for Amplitude 
        	      - #PCs:          4
        	      - #Experts:      4 4 4 4
        	      - #Features:     34
        	      - Features:      00 11 22 01 02 12 000 001 002 011 012 022 111 112 122 222 0000 0001 0002 0011 0022 0012 0111 0112 0122 0222 1111 1112 1122 1222 2222
        	   ## Model for Phase 
        	      - #PCs:          4
        	      - #Experts:      4 4 4 4
        	      - #Features:     34
        	      - Features:      00 11 22 01 02 12 000 001 002 011 012 022 111 112 122 222 0000 0001 0002 0011 0022 0012 0111 0112 0122 0222 1111 1112 1122 1222 2222
        	####################################
        
        .. image:: https://raw.githubusercontent.com/stefanoschmidt1995/MLGW/master/MLGW_package/docs/WF_example.png
           :width: 700px
        
        The ML model
        ============
        The model is composed by a PCA + Mixture of Experts model and aims to generate a GW given some input parameter of the BBH. So far the model is fitted only to deal with aligned BH spins.
        
        A PCA model is used to reduce dimensionality, through a linear transformation, of a wave represented in a dense grid. It maps the wave to the linear combination of the first ``K`` principal components of the dataset.
        
        A Mixture of Experts model (MoE) is useful to map the orbital parameters of the black holes to the reduced representation of the wave. A prediction of MoE is a linear combination of regression models (the experts), weighted by the output of a gating function which decides which expert to use. The orbital parameters considered are mass ratio ``q=m1/m2`` and the two BHs z-component spins ``s1`` and ``s2``; the total mass ``m1+m2`` is a scale factor and the dependence on it must not be fitted.
        The experts performs a polynomial regression (using data augmentation in a basis function expansion). The terms in the polynomial are specified at training time.
        
        A complete model includes two PCA models for both phase and amplitude of the wave and a MoE model for each of the PC considered. The expert takes the form of a basis function regression and one can specify the features they want to use for their regression in the training and test data.
        
        A dataset of GW must be created to fit the PCA model. It usually holds waves in time domain; it is advisable to generate them in a fixed reduced grid ``t' = t/M_tot`` where M_tot is the total mass of the BBH. The grid is such that the merger time is at ``t = 0``.
        
        Usage of mlgw
        =============
        It outputs the GW strain:
        
        .. image:: https://raw.githubusercontent.com/stefanoschmidt1995/MLGW/master/MLGW_package/docs/strain.png
           :width: 700px
        
        where m_i and s_i are BH masses and spins, d_L the luminosity distance from the source, i is the inclination angle and phi is a reference phase.
        
        Package ``mlgw`` consists in five modules.
        
           * **GW_generator**: the module holds class ``GW_generator`` which builds up all the model components (i.e. PCA + regressions for each PC) and performs some post processing of the waveform for dealing with known dependence on other physical quantities. It also compute the gradients of the waveform with respct to the relevant physical paramters.
           * **EM_MoE**: holds an implementation of a MoE model as well as the softmax classifier required for it
           * **ML_routines**: holds an implementation of the PCA model as well a GDA classifier and a routine to do data augmentation
           * **GW_helper**: provides some routines to generate a dataset and to evaluate the closeness between waves. This is useful to assess model ability to reproduce original waves
           * **fit_model**: provides some routines useful to fit the MoE + PCA model.
        
        Class ``GW_generator`` provides method ``get_WF`` to return the desidered waveform. Orbital parameters must be specified. It accepts N data as ``(N,D) np.array``. The D features must have one of the following layout:
        ::
        
        	D = 3	[q, spin1_z, spin2_z]
        	D = 4	[m1, m2, spin1_z, spin2_z]
        	D = 5	[m1, m2, spin1_z , spin2_z, D_L]
        	D = 6	[m1, m2, spin1_z , spin2_z, D_L, inclination]
        	D = 7	[m1, m2, spin1_z , spin2_z, D_L, inclination, phi_0]
        	D = 14	[m1, m2, spin1 (3,), spin2 (3,), D_L, inclination, phi_0, long_asc_nodes, eccentricity, mean_per_ano]
        
        Method ``__call__`` can only be given the last line.
        
        The ML model generates the waves in reduced grid ``t' = t/M_tot`` with a fixed number of grid points. With argument ``t_grid``, the user can specify a grid which they want to evaluate the wave at.
        Any custom grid must meet the convention that the origin of time is at merger and that the inspiral takes place at negative times.
        An additional boolean argument ``red_grid`` must state whether the grid is in reduced time domain or true time domain.
        Furthermore, the ``out_type`` option allows the user to choose the desidered output representation of the wave. Currently, the code implements the output of plus cross polarizations, amplitude and phase and real and imaginary part of the 22 mode.
        
        Method ``get_grads`` computes the gradients of the waveform with respect to orbital parameters.
        
        Installation & documentation
        ============================
        To install the package: ::
        
        	pip install mlgw
        
        It requires ``numpy``, ``scipy`` and ``lalsuite``, all available to PyPI.
        	
        This page is intented to present the use of the code only for generating a wave. For more advanced use or for more information, please refer to the code documentation: ::
        
        	import mlgw
        	help(mlgw)
        	help(mlgw.<module_name>)
        
        For full source code (and much more) see: https://github.com/stefanoschmidt1995/MLGW
        
        In the thesis, the model is explained in every details as well as the underlying theory and the validation results. The document is available `here <https://raw.githubusercontent.com/stefanoschmidt1995/MLGW/master/MLGW_package/docs/thesis.pdf>`_.
        
        
        
        
Platform: UNKNOWN
Description-Content-Type: text/x-rst
