.. currentmodule:: pNbody.config.extensions.gear


.. _units_comovingnoncomoving-label: 

How to deal with comoving to proper units conversion ? 
******************************************************

One common problem is the correct conversion of quantities coming from simulations ran in a cosmological context
to proper units.
In some evolution code, the units stored are in comoving coordinates, implicitly including the scale factor.
Some code even use units including the Hubble parameter :math:`h`.

.. note::

  To run the examples proposed hereafter, you need first to follow the instructions given in 
  the section :ref:`generate_examples-label` .



We describe hereafter the methods used by **pNbody** to properly convert any quantities to proper units.



.. list-table:: Main convertion methods 
   :widths: 40 25 
   :header-rows: 1

   * - method name
     - comments
   * - :meth:`nb.doHubbleFactorCorrection()<_NbodyMyGear.doHubbleFactorCorrection>`
     - 
   * - :meth:`nb.HubbleFactorCorrectionOn()<_NbodyMyGear.HubbleFactorCorrectionOn>`
     -    
   * - :meth:`nb.HubbleFactorCorrectionOff()<_NbodyMyGear.HubbleFactorCorrectionOff>`
     -    
   * - :meth:`nb.doComovingToProperConversion()<_NbodyMyGear.doComovingToProperConversion>`
     -    
   * - :meth:`nb.ComovingToProperConversionOn()<_NbodyMyGear.ComovingToProperConversionOn>`
     -    
   * - :meth:`nb.ComovingToProperConversionOff()<_NbodyMyGear.ComovingToProperConversionOff>`
     -    
   * - :meth:`nb.UnitsConversionFactor()<_NbodyMyGear.UnitsConversionFactor>`
     -    
   * - :meth:`nb.ScaleFactorConversionFactor()<_NbodyMyGear.ScaleFactorConversionFactor>`
     -    
   * - :meth:`nb.HubbleConversionFactor()<_NbodyMyGear.HubbleConversionFactor>`
     -    
   * - :meth:`nb.ConversionFactor()<_NbodyMyGear.ConversionFactor>`
     -    
   * - :meth:`nb.isComovingIntegrationOn()<_NbodyMyGear.isComovingIntegrationOn>`
     - should no longer be used               
   * - :meth:`nb.setComovingIntegrationOn()<_NbodyMyGear.setComovingIntegrationOn>`
     - should no longer be used             
   * - :meth:`nb.setComovingIntegrationOff()<_NbodyMyGear.setComovingIntegrationOff>`
     - should no longer be used           
   * - :meth:`nb.ComovingIntegrationInfo()<_NbodyMyGear.ComovingIntegrationInfo>`            
     - should no longer be used









The conversion factor computed from ``ConversionFactor()`` includes three conversions (units, scale factor, Hubble parameter)::

  # do the unit conversion        
  funit = self.UnitsConversionFactor(units,mode=mode)
  
  
  # compute the comoving to proper conversion factor
  funit = funit * self.ScaleFactorConversionFactor(a=a,mode=mode)
  
  
  # compute the Hubble parameter factor
  funit = funit * self.HubbleConversionFactor(h=h,mode=mode)


Comoving to proper conversion factor
....................................

To decide if a quantity must be corrected from the scale factor, the method ``doComovingToProperConversion()``
which return a boolean is called. This boolean is the variable ``comovingtoproperconversion`` which is set
by the methods ``ComovingToProperConversionOn()`` or ``ComovingToProperConversionOff()`` when reading the file.
It is thus defined in the specific format file.

.. warning::

  In case we need to convert, the convertion factor may depends on the format. Something that should be include
  in the definition of the format in the future. 


Example from a cosmological run in the swift format::

  >>> from pNbody import Nbody
  >>> nb = Nbody("cosmo_zoom.hdf5")
  >>> nb.doComovingToProperConversion()
  True

Example from a non-cosmological run in the swift format::


  >>> from pNbody import Nbody
  >>> nb = Nbody("MW_galaxy.hdf5")
  >>> nb.doComovingToProperConversion()
  False


Hubble parameter correction
...........................

To decide if a quantity must be corrected from the Hubble parameter, the method ``doHubbleFactorCorrection()``
which return a boolean is called. This boolean is the variable ``hubblefactorcorrection`` which is set
by the methods ``HubbleFactorCorrectionOn()`` or ``HubbleFactorCorrectionOff()`` when reading the file.
It is thus defined in the specific format file.


Example from a cosmological run in the swift format::

  >>> from pNbody import Nbody
  >>> nb = Nbody("cosmo_zoom.hdf5")
  >>> nb.doHubbleFactorCorrection()
  False

Example from a non-cosmological run in the swift format::


  >>> from pNbody import Nbody
  >>> nb = Nbody("MW_galaxy.hdf5")
  >>> nb.doHubbleFactorCorrection()
  False

As the swift format does not include the Hubble parameter in its units system, in both cases the answer is ``False``.
  

However, for a gadget cosmological run, we get::

  >>> from pNbody import Nbody
  >>> nb = Nbody("gadget_z40.dat")
  >>> nb.doHubbleFactorCorrection()
  True
  >>> nb.doComovingToProperConversion()
  True







  
Methods description
===================


.. automethod:: _NbodyMyGear.doHubbleFactorCorrection
.. automethod:: _NbodyMyGear.HubbleFactorCorrectionOn
.. automethod:: _NbodyMyGear.HubbleFactorCorrectionOff
.. automethod:: _NbodyMyGear.doComovingToProperConversion
.. automethod:: _NbodyMyGear.ComovingToProperConversionOn
.. automethod:: _NbodyMyGear.ComovingToProperConversionOff
.. automethod:: _NbodyMyGear.UnitsConversionFactor
.. automethod:: _NbodyMyGear.ScaleFactorConversionFactor
.. automethod:: _NbodyMyGear.HubbleConversionFactor
.. automethod:: _NbodyMyGear.ConversionFactor
.. automethod:: _NbodyMyGear.isComovingIntegrationOn      
.. automethod:: _NbodyMyGear.setComovingIntegrationOn     
.. automethod:: _NbodyMyGear.setComovingIntegrationOff    
.. automethod:: _NbodyMyGear.ComovingIntegrationInfo