Added the documentation of PhaseSpace

Signed-off-by: Deepanshu <deepanshu2017@gmail.com>

Author: Deepanshu2017

docs/Events.rst

@@ -230,6 +230,10 @@ device object of particle 7 you will do something like this,
       - iterator = event.Daughters(i)  # event can be of the host or device type and then can be used to iterator over the values.
         For example ``for daughter in iterator: print(daughter)`` Will print out the ith particle state in all the events.
 
+  - ``getDaughters``  This method returns the daughter particles at given index.
+
+      - vector_float4 = event.getDaughters(i)
+
   - ``Events``  This method returns the iterator of events. Syntax:
 
       - iterator = event.Events()  # event can be of the host or device type and then can be used to iterator over the values.

docs/PhaseSpace.rst

@@ -16,10 +16,10 @@ to instantiate the PhaseSpace class:
 
 .. code-block:: python
 
-    import HydraPython as hp
+    import HydraPython as hypy
 
-    vec4 = hp.Vector4R(5.2795, 0.0, 0.0, 0.0)
-    p = hp.PhaseSpace4(vec4.mass(), [3.096916, 0.493677, 0.13957018, 0.0195018])
+    vec4 = hypy.Vector4R(5.2795, 0.0, 0.0, 0.0)
+    p = hypy.PhaseSpace4(vec4.mass(), [3.096916, 0.493677, 0.13957018, 0.0195018])
     # This will construct the PhaseSpace object with the mass provided by the vector4R
     # class and the exactly 4 daughter masses in the list.
 
@@ -29,23 +29,45 @@ or a phase-space given a range of mother particles and an output range.
 
 .. code-block:: python
 
-    vec4 = hp.Vector4R(5.2795, 0.0, 0.0, 0.0)
-    ps = hp.PhaseSpace4(vec4.mass(), [3.096916, 0.493677, 0.13957018, 0.0195018])
-    e_host = hp.hostEvents4(3)
-    e_device = hp.deviceEvents4(3)
-    ps.Generatehost(vec4, e_host)  # Generate particle on host
-    ps.Generatedevice(vec, e_device)  # Generate particle on device
+    # The below example generates and fills 3 states of 4 particle host events
+    vec4 = hypy.Vector4R(5.2795, 0.0, 0.0, 0.0)
+    ps = hypy.PhaseSpace4(vec4.mass(), [3.096916, 0.493677, 0.13957018, 0.0195018])
+    e_host = hypy.host_events_4(3)
+    e_device = hypy.device_events_4(3)
+    ps.GenerateOnhost(vec4, e_host)  # Generate particle on host
+    ps.GenerateOndevice(vec, e_device)  # Generate particle on device
 
-    ####### ADD EXAMPLE OF given a range of mother particles and an output range
 
+We can also generate the decay from list of mother particles instead of one mother particle.
 
-The ``AverageOn`` method by PhaseSpace classes calculate the ``mean`` and ``sqrt(variance)``
-of a functor over the phase-space with n-samples or of a functor over the phase-space given a
-list of mother particles.
+.. code-block:: python
+
+
+    B0_mass = 5.27955
+    B0 = hypy.Vector4R(B0_mass, 0.0, 0.0, 0.0)
+
+    mothers = hypy.host_vector_float4(5)
+    # Fill mother with some particles
+    mothers[0] = (3.326536152819228, -0.7376241292510032, 0.9527533342879685, 0.15239715864543849)
+    mothers[1] = (3.3327060111834546, -0.44741166640978447, 1.012640505284964, -0.5390007001803998)
+    mothers[2] = (3.4673036097962844, 0.6781637974979919, -1.4020213115136253, -0.0763859825560801)
+    mothers[3] = (3.5042443315560945, 1.5383404921780213, -0.1442073504412384, -0.5492280905481964)
+    mothers[4] = (3.4406218104833015, -0.16339927010014546, 1.363729549941791, 0.6005257912194031)
+
+    phsp2 = hypy.PhaseSpace2(3.0969, [0.1056583745, 0.1056583745])
+    container = hypy.host_events_2(5)
+    phsp2.GenerateOnhost(mothers, grand_daughter)
+
+    for i in grand_daughter: print(i)
+
+
+The ``AverageOnhost`` and ``AverageOndevice`` method by PhaseSpace classes calculate the
+``mean`` and ``sqrt(variance)`` of a functor over the phase-space with n-samples or
+of a functor over the phase-space given a list of mother particles.
 
 .. code-block:: python
 
-    import HydraPython as hp
+    import HydraPython as hypy
     import math
     def foo(*data):
         p1, p2, p3 = data[0], data[1], data[2]
@@ -59,86 +81,103 @@ list of mother particles.
         md2 = p2.mass2()
         return (pd * mq2 - pq * qd) / math.sqrt((pq * pq - mq2 * mp2) * (qd * qd - mq2 * md2))
 
-    vec4 = hp.Vector4R(5.2795, 0.0, 0.0, 0.0)
-    p = hp.PhaseSpace4(vec4.mass(), [3.096916, 0.493677, 0.13957018, 0.0195018])
-    tup1 = p.AverageONhost(vec4, foo, 10)  # Average of host, currently passing functor to device will fail
+    vec4 = hypy.Vector4R(5.2795, 0.0, 0.0, 0.0)
+    p = hypy.PhaseSpace4(vec4.mass(), [3.096916, 0.493677, 0.13957018, 0.0195018])
+    tup1 = p.AverageOnhost(vec4, foo, 10)  # Average of host, currently passing functor to device will fail
     print (tup[0])  # Mean
     print (tup[1])  # sqrt of variance
 
-    ####### ADD EXAMPLE of a functor over the phase-space given a list of mother particles.
 
+Like generators, the Average on method also can accept the list of mother particle instead of one mother particle
+and calculate the ``mean`` and ``sqrt(variance)``.
 
-#### TODO ####
-Add example and documentation of ``Evaluate`` methods.
+The ``EvaluateOnhost`` and ``EvaluateOndevice`` evaluates a functor over the passed one mother particle or the list
+of mother particles.
 
-The complete method list supported by PhaseSpace Events classes can be found
-on [#f1]_.
 
-The complete list of the classes in the PhaseSpace can be found on [#f2]_.
+The complete list of the classes in the PhaseSpace can be found on [#f1]_ and complete method list supported
+by PhaseSpace Events classes can be found on [#f2]_.
 
-.. [#f1] The method list for PhaseSpace classes
 
-  - ``GetSeed``  Get the seed. Syntax:
+.. [#f1] The list of PhaseSpace classes
 
-      - p.GetSeed()
+  - ``PhaseSpace2``  Generate the phase-space with 2 particles. Syntax:
 
-  - ``SetSeed``  Set seed. Syntax:
+      - p = hypy.PhaseSpace2(mass, [2 daughter masses])
 
-      - p.SetSeed(seed)
+  - ``PhaseSpace3``  Generate the phase-space with 3 particles. Syntax:
 
-  - ``generate``  Generate the phase-space. Syntax:
+      - p = hypy.PhaseSpace3(mass, [3 daughter masses])
 
-      - p.generate(vector4R, event)  # event1's content will be assigned to event2.
-      - ### SECOND EXAMPLE
+  - ``PhaseSpace4``  Generate the phase-space with 4 particles. Syntax:
 
-  - ``AverageON`` Get the mean and sqrt of variance. Syntax:
+      - p = hypy.PhaseSpace4(mass, [4 daughter masses])
 
-      - p.AverageON(vector4R, functor, entires)
-      - ### SECOND EXAMPLE
+  - ``PhaseSpace5``  Generate the phase-space with 5 particles. Syntax:
 
-  - ``Evaluate`` dummy Syntax:
+      - p = hypy.PhaseSpace5(mass, [5 daughter masses])
 
-      - dummy
+  - ``PhaseSpace6``  Generate the phase-space with 6 particles. Syntax:
 
+      - p = hypy.PhaseSpace6(mass, [6 daughter masses])
 
-.. [#f2] The list of PhaseSpace classes
+  - ``PhaseSpace7``  Generate the phase-space with 7 particles. Syntax:
 
-  - ``PhaseSpace1``  Generate the phase-space with 1 particles. Syntax:
+      - p = hypy.PhaseSpace7(mass, [7 daughter masses])
 
-      - p = hp.PhaseSpace1(mass, [1 daughter mass])
+  - ``PhaseSpace8``  Generate the phase-space with 8 particles. Syntax:
 
-  - ``PhaseSpace2``  Generate the phase-space with 2 particles. Syntax:
+      - p = hypy.PhaseSpace8(mass, [8 daughter masses])
 
-      - p = hp.PhaseSpace2(mass, [2 daughter masses])
+  - ``PhaseSpace9``  Generate the phase-space with 9 particles. Syntax:
 
-  - ``PhaseSpace3``  Generate the phase-space with 3 particles. Syntax:
+      - p = hypy.PhaseSpace9(mass, [9 daughter masses])
 
-      - p = hp.PhaseSpace3(mass, [3 daughter masses])
+  - ``PhaseSpace10``  Generate the phase-space with 10 particles. Syntax:
 
-  - ``PhaseSpace4``  Generate the phase-space with 4 particles. Syntax:
+      - p = hypy.PhaseSpace10(mass, [10 daughter masses])
 
-      - p = hp.PhaseSpace4(mass, [4 daughter masses])
 
-  - ``PhaseSpace5``  Generate the phase-space with 5 particles. Syntax:
+.. [#f2] The method list for PhaseSpace classes
 
-      - p = hp.PhaseSpace5(mass, [5 daughter masses])
+  - ``GetSeed``  Get the seed. Syntax:
 
-  - ``PhaseSpace6``  Generate the phase-space with 6 particles. Syntax:
+      - p.GetSeed()
 
-      - p = hp.PhaseSpace6(mass, [6 daughter masses])
+  - ``SetSeed``  Set seed. Syntax:
 
-  - ``PhaseSpace7``  Generate the phase-space with 7 particles. Syntax:
+      - p.SetSeed(seed)
 
-      - p = hp.PhaseSpace7(mass, [7 daughter masses])
+  - ``GenerateOnhost``  Generate the phase-space. Syntax:
 
-  - ``PhaseSpace8``  Generate the phase-space with 8 particles. Syntax:
+      - p.GenerateOnhost(vector4R, event)
+      - p.GenerateOnhost(hypy.host_vector_float4& mothers, event)
+      - p.GenerateOnhost(vector4R, decays)
+      - p.GenerateOnhost(hypy.host_vector_float4& mothers, decays)
 
-      - p = hp.PhaseSpace8(mass, [8 daughter masses])
+  - ``GenerateOndevice``  Generate the phase-space. Syntax:
 
-  - ``PhaseSpace9``  Generate the phase-space with 9 particles. Syntax:
+      - p.GenerateOndevice(vector4R, event)
+      - p.GenerateOndevice(hypy.device_vector_float4& mothers, event)
+      - p.GenerateOndevice(vector4R, decays)
+      - p.GenerateOndevice(hypy.device_vector_float4& mothers, decays)
 
-      - p = hp.PhaseSpace9(mass, [9 daughter masses])
+  - ``AverageOnhost`` Get the mean and sqrt of variance. Syntax:
 
-  - ``PhaseSpace10``  Generate the phase-space with 10 particles. Syntax:
+      - p.AverageOnhost(vector4R, functor, number_of_entires)
+      - p.AverageOnhost(hypy.host_vector_float4& mothers, functor)
+
+  - ``AverageOndevice`` Get the mean and sqrt of variance. Syntax:
+
+      - p.AverageOndevice(vector4R, functor, number_of_entires)
+      - p.AverageOndevice(hypy.device_vector_float4& mothers, functor)
+
+  - ``EvaluateOnhost`` Evaluate a function over the given particle or list of particles:
+
+      - p.EvaluateOnhost(vector4R, hypy.host_vector_float2& result, functor)
+      - p.EvaluateOnhost(hypy.host_vector_float4& mothers, hypy.host_vector_float2& result, functor)
+
+  - ``EvaluateOndevice`` Evaluate a function over the given particle or list of particles:
 
-      - p = hp.PhaseSpace10(mass, [10 daughter masses])
+      - p.EvaluateOndevice(vector4R, hypy.device_vector_float2& result, functor)
+      - p.EvaluateOndevice(hypy.device_vector_float4& mothers, hypy.device_vector_float2& result, functor)

docs/PhaseSpaceExample.rst

@@ -43,15 +43,15 @@ to contain or save the states of the particle generated by the ``Generate`` meth
 
 .. code-block:: python
 
-    e_host = hp.hostEvents4(3)
+    e_host = hp.host_events_4(3)
 
 Above I have defined a host Event container with N=4 particle and number of
 states as 3. So this container will contain the 3 states of 4 particles each
 generated by the PhaseSpace.
 
 .. code-block:: python
 
-    ps.Generatehost(mother_particle, e_host)
+    ps.GenerateOnhost(mother_particle, e_host)
 
 Above will generate the events or states of N particles using host and save the
 result in the passed ``e_host`` container.
@@ -112,7 +112,7 @@ For the sake of completeness, all the code showed in the doc is below.
     print()
 
     ps = hp.PhaseSpace4(mother_particle.mass(), daughter_masses)
-    e_host = hp.hostEvents4(3)
+    e_host = hp.host_events_4(3)
     ps.Generatehost(mother_particle, e_host)
 
     iterator = e_host.Events()