Merged in prabhuramachandran/pysph/add-license (pull request #165)

Add license, improve docs, add videos etc.

LICENSE.txt

@@ -0,0 +1,30 @@
+Unless otherwise specified by LICENSE.txt files in individual
+directories, all code is
+
+Copyright (c) 2009-2015, the PySPH developers
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+ 1. Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in
+    the documentation and/or other materials provided with the
+    distribution.
+ 3. Neither the name of the copyright holder nor the names of its contributors
+    may be used to endorse or promote products derived from this software
+    without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.rst

@@ -1,5 +1,5 @@
 PySPH: a Python-based SPH framework
------------------------------------
+------------------------------------
 
 |Shippable Status| |Drone Status| |Appveyor Status|
 
@@ -8,10 +8,10 @@ PySPH is an open source framework for Smoothed Particle Hydrodynamics
 `Python <http://www.python.org>`__ and the performance critical parts
 are implemented in `Cython <http://www.cython.org>`__.
 
-PySPH allows users to write their high-level code in pure Python.  This Python
-code is automatically converted to high-performance Cython which is compiled
-and executed.  PySPH can also work with OpenMP and MPI for larger scale
-computing.
+PySPH allows users to write their high-level code in pure Python.  This
+Python code is automatically converted to high-performance Cython which
+is compiled and executed.  PySPH can also be configured to work
+seamlessly with OpenMP and MPI.
 
 The latest documentation for PySPH is available at
 `pysph.readthedocs.org <http://pysph.readthedocs.org>`__.
@@ -23,23 +23,34 @@ The latest documentation for PySPH is available at
 .. |Appveyor Status| image:: https://ci.appveyor.com/api/projects/status/emqifa4xg2b837qj
    :target: https://ci.appveyor.com/project/prabhuramachandran/pysph
 
+Here are videos of some example problems solved using PySPH.
+
+.. raw:: html
+
+    <div align="left">
+    <iframe width="560" height="315"
+        src="https://www.youtube.com/embed/videoseries?list=PLH8Y2KepC2_VPLrcTiWGaYYh88gGVAuVr"
+        frameborder="0" allowfullscreen>
+    </iframe>
+    </div>
+
 Features
 --------
 
--  Solver framework to add arbitrary collection of particles.
--  Flexibility to define arbitrary SPH equations operating on particles
-   in pure Python.
--  Any kind of user-defined multi-step integrator.
--  Seamless parallel integration using
-   `Zoltan <http://www.cs.sandia.gov/zoltan/>`__.
--  High-performance: our performance is comparable to hand-written
-   solvers implemented in FORTRAN.
+- Flexibility to define arbitrary SPH equations operating on particles
+  in pure Python.
+- Define your own multi-step integrators in pure Python.
+- High-performance: our performance is comparable to hand-written
+  solvers implemented in FORTRAN.
+- Seamless multi-core support with OpenMP.
+- Seamless parallel support using
+  `Zoltan <http://www.cs.sandia.gov/zoltan/>`__.
 
-Solvers
--------
+SPH formulations
+-----------------
 
-Currently, PySPH has numerous examples to solve a variety of problems.  The
-features of the implementation are:
+PySPH ships with a variety of standard SPH formulations along with
+basic examples.  Some of the formulations available are:
 
 -  `Weakly Compressible SPH
    (WCSPH) <http://www.tandfonline.com/doi/abs/10.1080/00221686.2010.9641250>`__
@@ -55,7 +66,7 @@ features of the implementation are:
    (Puri et al. 2014, JCP, Vol. 256, pp 308--333)
 
 Installation
-============
+-------------
 
 Up-to-date details on how to install PySPH on Linux/OS X and Windows are
 available from
@@ -95,6 +106,7 @@ This runs the 3D dam-break problem which is also a SPHERIC benchmark
 `Test 2 <https://wiki.manchester.ac.uk/spheric/index.php/Test2>`__
 
 .. figure:: https://bitbucket.org/pysph/pysph/raw/master/docs/Images/db3d.png
+   :width: 550px
    :alt: Three-dimensional dam-break example
 
 PySPH is more than a tool for wave-body interactions:::
@@ -106,9 +118,10 @@ This runs the driven cavity problem using the transport velocity
 formulation of Adami et al. You can verify the results for this problem
 using the helper script
 ``examples/transport_velocity/ldcavity_results.py`` to plot, for example
-the streamlines:
+the streamlines look like the following image:
 
 .. figure:: https://bitbucket.org/pysph/pysph/raw/master/docs/Images/ldc-streamlines.png
+   :width: 550px
    :alt: Lid-driven-cavity example
 
 If you want to use PySPH for elastic dynamics, you can try some of the
@@ -120,9 +133,29 @@ examples from the directory ``examples/solid_mech``::
 Which runs the problem of the collision of two elastic rings:
 
 .. figure:: https://bitbucket.org/pysph/pysph/raw/master/docs/Images/rings-collision.png
+   :width: 550px
    :alt: Collision of two steel rings
 
 The auto-generated code for the example resides in the directory
 ``~/.pysph/source``. A note of caution however, it's not for the faint
 hearted.
 
+Credits
+--------
+
+PySPH is primarily developed at the `Department of Aerospace
+Engineering, IIT Bombay <http://www.aero.iitb.ac.in>`__. We are grateful
+to IIT Bombay for their support.  Our primary goal is to build a
+powerful SPH based tool for both application and research. We hope that
+this makes it easy to perform reproducible computational research.
+
+Lead developers:
+
+- `Prabhu Ramachandran <http://www.aero.iitb.ac.in/~prabhu>`__
+- Kunal Puri
+
+Earlier developers:
+
+- Pankaj Pandey (stress solver and improved load balancing, 2011)
+- Chandrashekhar Kaushik (original parallel and serial implementation in 2009)
+

docs/source/conf.py

@@ -11,7 +11,10 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys
+import os
+from os.path import join
+
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -41,16 +44,15 @@
 
 # General information about the project.
 project = u'PySPH'
-copyright = u'2014, PySPH developers'
+copyright = u'2013-2015, PySPH developers'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-# The short X.Y version.
-version = '1.0'
-# The full version, including alpha/beta/rc tags.
-release = '1.0'
+_d = {}
+execfile(join(os.pardir, os.pardir, 'pysph', '__init__.py'), _d)
+version = release = _d['__version__']
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -91,7 +93,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinxdoc'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/source/index.rst

@@ -6,14 +6,41 @@
 Welcome to the PySPH documentation!
 ====================================
 
+PySPH is an open source framework for Smoothed Particle Hydrodynamics (SPH)
+simulations.  Users can implement an SPH formulation in pure Python_ and still
+obtain excellent performance.  PySPH can make use of multiple cores via OpenMP
+or be run seamlessly in parallel using MPI.
+
+Here are some videos of simulations made with PySPH.
+
+.. raw:: html
+
+    <div align="center">
+    <iframe width="560" height="315"
+        src="https://www.youtube.com/embed/videoseries?list=PLH8Y2KepC2_VPLrcTiWGaYYh88gGVAuVr"
+        frameborder="0" allowfullscreen>
+    </iframe>
+    </div>
+
+.. _Python: http://www.python.org
+
+
+**********
+Overview
+**********
+
+.. toctree::
+   :maxdepth: 2
+
+   overview.rst
+
 *********************************
 Installation and getting started
 *********************************
 
 .. toctree::
    :maxdepth: 2
 
-   overview.rst
    installation.rst
    tutorial/circular_patch.rst
 

docs/source/overview.rst

@@ -8,9 +8,21 @@ are implemented in Cython_.
 
 PySPH is implemented in a way that allows a user to specify the entire SPH
 simulation in pure Python. High-performance code is generated from this
-high-level Python code, compiled on the fly and executed.  PySPH also features
-optional automatic parallelization using mpi4py_ and Zoltan_.  If you wish to
-use the parallel capabilities you will need to have these installed.
+high-level Python code, compiled on the fly and executed.  PySPH can use OpenMP
+to utilize multi-core CPUs effectively.  PySPH also features optional automatic
+parallelization (multi-CPU) using mpi4py_ and Zoltan_.  If you wish to use the
+parallel capabilities you will need to have these installed.
+
+Here are videos of simulations made with PySPH.
+
+.. raw:: html
+
+    <div align="center">
+    <iframe width="560" height="315"
+        src="https://www.youtube.com/embed/videoseries?list=PLH8Y2KepC2_VPLrcTiWGaYYh88gGVAuVr"
+        frameborder="0" allowfullscreen>
+    </iframe>
+    </div>
 
 
 .. _Python: http://www.python.org
@@ -24,13 +36,14 @@ Features
 
   - User scripts and equations are written in pure Python.
   - Flexibility to define arbitrary SPH equations operating on particles.
-  - Solver framework to add arbitrary collection of particles.
+  - Ability to define your own multi-step integrators in pure Python.
   - High-performance: our performance is comparable to hand-written solvers
     implemented in FORTRAN.
+  - Seamless multi-core support with OpenMP.
   - Seamless parallel integration using Zoltan_.
 
-Solvers
---------
+SPH formulations
+-----------------
 
 Currently, PySPH has numerous examples to solve the viscous, incompressible
 Navier-Stokes equations using the weakly compressible (WCSPH) approach. The
@@ -39,20 +52,23 @@ following formulations are currently implemented:
 - `Weakly Compressible SPH (WCSPH)`_ for free-surface flows (Gesteira et al. 2010, Journal of Hydraulic Research, 48, pp. 6--27)
 
 .. figure:: ../Images/db3d.png
+   :width: 500 px
    :align: center
 
    3D dam-break past an obstacle SPHERIC benchmark `Test 2`_
 
 - `Transport Velocity Formulation`_ for incompressilbe fluids (Adami et al. 2013, JCP, 241, pp. 292--307).
 
 .. figure:: ../Images/ldc-streamlines.png
+   :width: 500 px
    :align: center
 
    Streamlines for a driven cavity
 
 - `SPH for elastic dynamics`_ (Gray et al. 2001, CMAME, Vol. 190, pp 6641--6662)
 
 .. figure:: ../Images/rings-collision.png
+   :width: 500 px
    :align: center
 
    Collision of two elastic rings.
@@ -69,3 +85,59 @@ following formulations are currently implemented:
 .. _`Compressible SPH`: http://dx.doi.org/10.1016/j.jcp.2013.08.060
 
 .. _`Test 2`: https://wiki.manchester.ac.uk/spheric/index.php/Test2
+
+
+Credits
+--------
+
+PySPH is primarily developed at the `Department of Aerospace
+Engineering, IIT Bombay <http://www.aero.iitb.ac.in>`__. We are grateful
+to IIT Bombay for their support.  Our primary goal is to build a
+powerful SPH based tool for both application and research. We hope that
+this makes it easy to perform reproducible computational research.
+
+Lead developers:
+
+- `Prabhu Ramachandran <http://www.aero.iitb.ac.in/~prabhu>`__
+- Kunal Puri
+
+Earlier developers:
+
+- Pankaj Pandey (stress solver and improved load balancing, 2011)
+- Chandrashekhar Kaushik (original parallel and serial implementation in 2009)
+
+History
+--------
+
+- 2009: PySPH started with a simple Cython based 1D implementation written by
+  Prabhu.
+
+- 2009-2010: Chandrashekhar Kaushik worked on a full 3D SPH implementation with
+  a more general purpose design.  The implementation was in a mix of Cython and
+  Python.
+
+- 2010-2012: The previous implementation was a little too complex and was
+  largely overhauled by Kunal and Pankaj.  This became the PySPH 0.9beta
+  release.  The difficulty with this version was that it was almost entirely
+  written in Cython, making it hard to extend or add new formulations without
+  writing more Cython code.  Doing this was difficult and not too pleasant.  In
+  addition it was not as fast as we would have liked it. It ended up feeling
+  like we might as well have implemented it all in C++ and exposed a Python
+  interface to that.
+
+- 2011-2012: Kunal also implemented SPH2D_ and another internal version called
+  ZSPH in Cython which included Zoltan_ based parallelization using PyZoltan_.
+  This was specific to his PhD research and again required writing Cython
+  making it difficult for the average user to extend.
+
+- 2013-present In early 2013, Prabhu reimplemented the core of PySPH to be
+  almost entirely auto-generated from pure Python.  The resulting code was
+  faster than previous implementations and very easy to extend entirely from
+  pure Python.  Kunal and Prabhu integrated PyZoltan into PySPH and the current
+  version of PySPH was born.  Subsequently, OpenMP support was also added in
+  2015.
+
+
+.. _SPH2D: https://bitbucket.org/kunalp/sph2d
+.. _PyZoltan: https://bitbucket.org/pysph/pyzoltan
+.. _Zoltan: http://www.cs.sandia.gov/zoltan/

setup.py

@@ -312,7 +312,7 @@ def get_zoltan_directory(varname):
       author_email = 'pysph-dev@googlegroups.com',
       description = "A general purpose Smoothed Particle Hydrodynamics framework",
       long_description = open('README.rst').read(),
-      url = 'http://pysph.googlecode.com',
+      url = 'http://pysph.bitbucket.org',
       license = "BSD",
       keywords = "SPH simulation computational fluid dynamics",
       test_suite = "nose.collector",