Improving documentation and fixing little things.

Author: eduardo-rodrigues

docs/Makefile

@@ -4,7 +4,7 @@
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = python -msphinx
-SPHINXPROJ    = HydraPython
+SPHINXPROJ    = Hydra.Python
 SOURCEDIR     = .
 BUILDDIR      = _build
 
@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/Vector.rst

@@ -3,18 +3,18 @@
 Vector Classes
 ##############
 
-There are two Vector classes available that are ``Vector4R`` and ``Vector3R``.
+There are two vector classes available in Hydra, namely ``Vector4R`` and ``Vector3R``.
 
 Vector4R
 ========
 
-The Vector4R class is the wrapper of C++ Vector4R class. This class basically
-deals with the vector of 4 particles. We have three types of constructors
-to instantiate the Vector4R class:
+The ``Vector4R`` class available in Python wraps the C++ ``Vector4R`` class representing
+four-dimensional relativistic vectors.
+Three types of constructors allow to instantiate the ``Vector4R`` class:
 
-- Default empty constructor
-- Copy constructor
-- Constructor with 4 real (``float``) numbers
+- Default empty constructor.
+- Copy constructor.
+- Constructor from 4 real (``float``) numbers.
 
 .. code-block:: python
 
@@ -28,19 +28,18 @@ to instantiate the Vector4R class:
     print (vec2)  # (0.8385,0.1242,0.9821,1.2424)
     print (vec3)  # (0.8385,0.1242,0.9821,1.2424)
 
-The Vector4R class also provides a pretty convenient method to create an
-object from python list.
+The ``Vector4R`` class also provides a pretty convenient method to create an instance from a python list.
 
 .. code-block:: python
 
     list_ = [0.9241, 0.13223, 0.13121, 1.1141]
     vec4 = hp.Vector4R(list_)
 
-This will construct a new Vector4R object with the values passed within
+This will construct a new ``Vector4R`` object with the values passed within
 a list. The list should contain exactly 4 elements otherwise a ``TypeError``
 will be raised.
 The ``set`` methods can be used to set all 4 values or a particular value
-in a Vector4R object, while the ``get`` method can be used with Vector4R
+in a ``Vector4R`` object, while the ``get`` method can be used with ``Vector4R``
 to get the value of a particular index. The ``__getitem__`` and
 ``__setitem`` methods can also be used to get or set the value which comes
 very handy and maintain more pythonic way to access and set the values.
@@ -61,9 +60,9 @@ very handy and maintain more pythonic way to access and set the values.
     vec5[1] = 0.5678
     print (vec5)  # (0.1234,0.5678,0.9101,0.1121)
 
-The Vector4R object can be multiplied or divided by a real value while it
-can be added or subtracted with another Vector4R object. One Vector4R
-object can be multiplied by another Vector4R object.
+The ``Vector4R`` object can be multiplied or divided by a real value while it
+can be added or subtracted with another ``Vector4R`` object. One Vector4R
+object can be multiplied by another ``Vector4R`` object.
 
 .. code-block:: python
 
@@ -80,17 +79,17 @@ object can be multiplied by another Vector4R object.
     vec6 -= vec7
     print (vec6)  # (1.50608,1.69418,0.01925,2.1989)
 
-Two Vector4R objects can be easily added, subtracted or multiplied so:
+Two ``Vector4R`` objects can easily be added, subtracted or multiplied:
 
  - ``v = v1 + v2`` # Returns a Vector4R object
  - ``v = v1 - v2`` # Returns a Vector4R object
  - ``v = v1 * v2`` # Returns a real number
 
-All above three are valid for any Vector4R object. There are various
-other methods available in Vector4R. The list of Vector4R
+All above three are valid for any ``Vector4R`` object. There are various
+other methods available in ``Vector4R``. The list of ``Vector4R``
 methods can be found on [#f1]_.
 
-The Vector4R provides an ``assign`` method to assign or copy the Vector4R
+The ``Vector4R`` provides an ``assign`` method to assign or copy the Vector4R
 object. This is a very useful method to avoid the nasty bugs for example:
 
 .. code-block:: python
@@ -111,13 +110,13 @@ object. This is a very useful method to avoid the nasty bugs for example:
 Vector3R
 ========
 
-The Vector3R class is the wrapper of C++ Vector3R class. This class basically
-deals with the vector of 3 particles. We have three types of constructors
-to instantiate the Vector3R class:
+The ``Vector43`` class available in Python wraps the C++ ``Vector3R`` class representing
+three-dimensional Euclidian vectors.
+Three types of constructors allow to instantiate the ``Vector3R`` class:
 
-- Default empty constructor
-- Copy constructor
-- Constructor with 3 real (``float``) numbers
+- Default empty constructor.
+- Copy constructor.
+- Constructor from 3 real (``float``) numbers.
 
 .. code-block:: python
 
@@ -131,19 +130,19 @@ to instantiate the Vector3R class:
     print (vec2)  # (0.8385,0.1242,0.9821)
     print (vec3)  # (0.8385,0.1242,0.9821)
 
-The Vector3R class also provides a pretty convenient method to create an
+The ``Vector3R`` class also provides a pretty convenient method to create an
 object from python list.
 
 .. code-block:: python
 
     list_ = [0.9241, 0.13223, 0.13121]
     vec4 = hp.Vector3R(list_)
 
-This will construct a new Vector3R object with the values passed within
+This will construct a new ``Vector3R`` object with the values passed within
 a list. The list should contain exactly 3 elements otherwise a ``TypeError``
 will be raised.
 The ``set`` methods can be used to set all 3 values or a particular value
-in a Vector3R object, while the ``get`` method can be used with Vector3R
+in a ``Vector3R`` object, while the ``get`` method can be used with ``Vector3R``
 to get the value of a particular index. The ``__getitem__`` and
 ``__setitem`` methods can also be used to get or set the value which comes
 very handy and maintain more pythonic way to access and set the values.
@@ -164,9 +163,9 @@ very handy and maintain more pythonic way to access and set the values.
     vec5[1] = 0.5678
     print (vec5)  # (0.1234,0.5678,0.9101)
 
-The Vector3R object can be multiplied or divided by a real value while it
-can be added or subtracted with another Vector3R object. One Vector3R
-object can be multiplied by another Vector3R object.
+The ``Vector3R`` object can be multiplied or divided by a real value while it
+can be added or subtracted with another ``Vector3R`` object. One ``Vector3R``
+object can be multiplied by another ``Vector3R`` object.
 
 .. code-block:: python
 
@@ -183,17 +182,17 @@ object can be multiplied by another Vector3R object.
     vec6 -= vec7
     print (vec6)  # (1.50608,1.69418,0.01925)
 
-Two Vector3R objects can be easily added, subtracted or multiplied so:
+Two ``Vector3R`` objects can easily be added, subtracted or multiplied:
 
  - ``v = v1 + v2`` # Returns a Vector3R object
  - ``v = v1 - v2`` # Returns a Vector3R object
  - ``v = v1 * v2`` # Returns a real number
 
-All above three are valid for any Vector3R object. There are various
-other methods available in Vector3R. The list of Vector3R
+All above three are valid for any ``Vector3R`` object. There are various
+other methods available in ``Vector3R``. The list of ``Vector3R``
 methods can be found on [#f2]_.
 
-The Vector3R provides an ``assign`` method to assign or copy the Vector3R
+The ``Vector3R`` provides an ``assign`` method to assign or copy the Vector3R
 object. This is a very useful method to avoid the nasty bugs for example:
 
 .. code-block:: python

docs/conf.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
-# Hydra Python documentation build configuration file, created by
+# Hydra.Python documentation build configuration file, created by
 # sphinx-quickstart on Fri Aug 11 18:15:40 2017.
 #
 # This file is execfile()d with the current directory set to its
@@ -48,8 +48,8 @@
 master_doc = 'index'
 
 # General information about the project.
-project = 'Hydra Python'
-copyright = '2017, Deepanshu Thakur'
+project = 'Hydra.Python'
+copyright = '2017, Antonio Augusto Alves Junior'
 author = 'Deepanshu Thakur'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -144,7 +144,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'HydraPython.tex', 'Hydra Python Documentation',
+    (master_doc, 'HydraPython.tex', 'Hydra.Python Documentation',
      'Deepanshu Thakur', 'manual'),
 ]
 
@@ -154,7 +154,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'hydrapython', 'Hydra Python Documentation',
+    (master_doc, 'hydrapython', 'Hydra.Python Documentation',
      [author], 1)
 ]
 
@@ -165,10 +165,7 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'HydraPython', 'Hydra Python Documentation',
-     author, 'HydraPython', 'One line description of project.',
+    (master_doc, 'HydraPython', 'Hydra.Python Documentation',
+     author, 'HydraPython', 'Python bindings for the Hydra C++ header-only library.',
      'Miscellaneous'),
 ]
-
-
-

docs/index.rst

@@ -2,8 +2,8 @@
 
     .. image:: hydra_mini_logo.png
 
-Hydra Python --- The Python wrapper of Hydra C++
-================================================
+Hydra.Python --- Python bindings for the Hydra C++ library
+==========================================================
 
 .. only: not latex
 
@@ -15,7 +15,7 @@ Hydra Python --- The Python wrapper of Hydra C++
    intro
 
 .. toctree::
-   :caption: The Basics
+   :caption: The basics
    :maxdepth: 2
 
    basics
@@ -25,7 +25,7 @@ Hydra Python --- The Python wrapper of Hydra C++
    Random
 
 .. toctree::
-   :caption: PhaseSpace example
+   :caption: Examples
    :maxdepth: 2
 
    PhaseSpaceExample

docs/intro.rst

@@ -1,22 +1,27 @@
 .. image:: hydra_logo.png
-
+   :scale: 25 %
+	   
 About this project
 ==================
-**HydraPython** is a wrapper around the header-only C++ `Hydra`_ library that provides
-the abstraction over the C++ method. This library is an abstraction over the
-C++ library, so that you can work with much simpler Python language, concentrate
-more on the logic and leave all the memory management stuff up to the library. This
-library is written keeping ``Linux`` systems in mind, but you might apply some
-hacks to make compatible with other platforms.
+The **Hydra.Python** package provides the Python bindings for the header-only C++ `Hydra`_ library.
+This library is an abstraction over the C++ library, so that daily work can be code and run with the much simpler Python language,
+concentrating on the logic and leaving all the complex memory management and optimisations to the C++ library.
+
+The bindings are produced with [pybind11](http://pybind11.readthedocs.io/). The project makes use of [CMAKE](https://cmake.org/).
+
+The  library is written with ``Linux`` systems in mind, but compatibility with other platforms may be achieved with "hacks".
+Python 2.7, and 3.x are supported.
+
 
 .. _Hydra: https://github.com/MultithreadCorner/Hydra
 
 
 Core features
 *************
-The following core C++ features can be mapped to Python
+The core functionality of Hydra has been exposed to Python.
+
+The following core C++ features of Hydra can be mapped to Python:
 
-- Python 2.7, and 3.x are supported.
 - The continuous expansion of the original Hydra library.
 - Support for ``particles`` with ``Vector4R`` class.
 - Support for containers like ``Events`` or ``Decay``.
@@ -25,5 +30,12 @@ The following core C++ features can be mapped to Python
 Supported compilers
 *******************
 
-1. Clang/LLVM (any non-ancient version with C++11 support)
-2. GCC 4.8 or newer
+1. Clang/LLVM (any non-ancient version with C++11 support).
+2. GCC 4.8 or newer.
+
+
+History
+*******
+The development of **Hydra.Python** started as a
+[2017 Google Summer of Code project](https://summerofcode.withgoogle.com/projects/#6669304945704960)
+with student Deepanshu Thakur.

src/PyBindings.cpp

@@ -1,4 +1,3 @@
-
 /*----------------------------------------------------------------------------
  *
  *   Copyright (C) 2017 Antonio Augusto Alves Junior
@@ -24,8 +23,8 @@
 /*
  * PyBindings.cpp
  *
- *  Created on: 30 de jul de 2017
- *      Author: augalves
+ *  Created on: July 30, 2017
+ *      Author: Antonio Augusto Alves Junior
  */
 
 /*
@@ -39,33 +38,35 @@
  *
  */
 
-//pybind11
+// pybind11
 #include <pybind11/pybind11.h>
 #include <pybind11/stl.h>
-//Hydra.Python
+
+//Hydra.Python helpers
 #include <add_object.h>
 #include <bind_container.h>
 #include <casters.h>
 #include <typedefs.h>
 #include <make_opaque.h>
-//Hydra.Python hydra classes
+// Hydra.Python binded Hydra classes
 #include <PyRandom.h>
 #include <PyEvents.h>
 #include <PyVector3R.h>
 #include <PyVector4R.h>
 #include <PyPhaseSpace.h>
 
+
 namespace py = pybind11;
 namespace hypy = hydra_python;
 
 
 
 PYBIND11_MODULE(HydraPython, m) {
 
-hypy::add_object< hydra::Random<thrust::random::default_random_engine> >(m);
-hypy::add_object< hydra::Events<4, hydra::host::sys_t> >(m);
 hypy::add_object< hydra::Vector3R >(m);
 hypy::add_object< hydra::Vector4R >(m);
+hypy::add_object< hydra::Random<thrust::random::default_random_engine> >(m);
+hypy::add_object< hydra::Events<4, hydra::host::sys_t> >(m);
 hypy::add_object< hydra::PhaseSpace<4, thrust::random::default_random_engine> >(m);
 
 //decay container host
@@ -115,4 +116,4 @@ hypy::bind_vector< hypy::device_vector_float9 >(m,"device_vector_float9");
 hypy::bind_vector< hypy::device_vector_float10>(m,"device_vector_float10");
 
 
-}
+}