Phase Space Example
====================
This page is basically to demonstrate, how the PhaseSpace class with N
particles can be used to generate the Events.

.. code-block:: python

    import HydraPython as hp

Above line will bring the classes in HydraPython in the scope of interpreter with
the alias hp.

I will be using the Generate method of PhaseSpace here.

.. code-block:: python

    ps = hp.PhaseSpace4([3.096916, 0.493677, 0.13957018, 0.0195018])

Above will create a PhaseSpace class object with ``N=4`` number of particles in
the final state. Since the number HydraPython currently supports particles up-to
N=10 in the final state each PhaseSpace class have a suffix number from 1 to 10 is
associated with it. The argument to the PhaseSpace class constructor is
the list of ``daughter masses``. The size of this list
should be equal to the number of particles in the final state.

Now that we have defined a PhaseSpace object, let's create an ``Event`` container
to contain or save the states of the particle generated by the ``Generate`` method.

.. code-block:: python

    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
    mother_particle = hp.Vector4R(5.2795, 0.83859, 0.77825, 0.98876)
    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.

Iterating over ``e_host`` will produce the output like this.

.. code-block:: python

    iterator = e_host.Events()
    for state in iterator:
        print(state)

The output is similar to this.

.. code-block:: bash

    (0.0005371556105645586, (3.26523953659142, 0.8636638960657156, 0.0039751958746361005, -0.5700608675519644), (0.5205929150762441, 0.1361899815237809, 0.005650876525868165, -0.09338286473236444), (0.20194244730558714, -0.1422365383415909, 0.02243309740186762, 0.023800003783548303), (1.0705417836594209, -0.8576173392479055, -0.03205916980237188, 0.6396437285007806))

    (0.05958088064572496, (3.165087693874953, -0.03009443713313225, 0.6184073639056892, 0.2087056683071267), (0.5809611490129989, -0.016410682480807473, -0.054177669092790454, -0.30098894665035486), (0.7999891064682725, 0.08709929588193556, -0.6686502155923885, -0.40721411710277927), (0.5122787332764478, -0.04059417626799582, 0.10442052077948974, 0.4994973954460073))

    (0.03738710351970522, (3.376147992537914, -0.4901521345374072, 1.085407051180553, 0.6238020316717038), (1.0297008095722722, 0.22021896692371404, -0.8251558826920553, -0.29527640063259364), (0.49365860519565796, 0.27558785182792184, -0.33498661390711465, -0.18987966654280578), (0.15880927532682793, -0.005654684214228855, 0.07473544541861718, -0.13864596449630434))

So what is this? It is the tuple of output in which the first element of tuple
represent the ``weight`` and the remaining number of elements are the Vector4R of
each particle for N particle. (In this case 4)

If you will closely follow the result, you will see that the each particle in
every event has the mass specified by the list of daughter masses at the time
of the creation of PhaseSpace.

.. code-block:: python

    state1 = e_host[0]  # first state particle
    d_particle0, d_particle1, d_particle2, d_particle3 = state1[1], state1[2], state1[3], state1[4]

    d_particle0 = hp.Vector4R(d_particle0)
    d_particle1 = hp.Vector4R(d_particle1)
    d_particle2 = hp.Vector4R(d_particle2)
    d_particle3 = hp.Vector4R(d_particle3)

    print(d_particle0.mass(), d_particle1.mass(), d_particle2.mass(), d_particle3.mass(), sep=', ')

    # Output is
    # 3.096916, 0.493677, 0.13957017999999996, 0.01950179999999231
    # This is exactly the weight given for each daughter while creation of PhaseSpace
    # Same thing is true for rest of the states.

So this is a simple PhaseSpace example of 4 particles in the final state.
For the sake of completeness, all the code showed in the doc is below.

.. code-block:: python

    import HydraPython as hp

    mother_particle = hp.Vector4R(5.2795, 0.83859, 0.77825, 0.98876)
    daughter_masses = [3.096916, 0.493677, 0.13957018, 0.0195018]
    print("Daughter masses at the time of creation of PhaseSpace:", daughter_masses)
    print()

    ps = hp.PhaseSpace4(daughter_masses)
    e_host = hp.host_events_4(3)
    ps.Generatehost(mother_particle, e_host)

    iterator = e_host.Events()
    for idx, state in enumerate(iterator):
        print("State", idx, ": ", state)

    state1 = e_host[0]  # first state particle
    d_particle0, d_particle1, d_particle2, d_particle3 = state1[1], state1[2], state1[3], state1[4]

    d_particle0 = hp.Vector4R(d_particle0)
    d_particle1 = hp.Vector4R(d_particle1)
    d_particle2 = hp.Vector4R(d_particle2)
    d_particle3 = hp.Vector4R(d_particle3)

    print('\nDaughter masses:', d_particle0.mass(), d_particle1.mass(), d_particle2.mass(), d_particle3.mass(), sep=', ')