Python API (#96)

This revision includes the new Python API and minor updates on the C++ API.

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "external/googletest"]
 	path = external/googletest
 	url = https://github.com/google/googletest
+[submodule "external/pybind11"]
+	path = external/pybind11
+	url = https://github.com/pybind/pybind11.git

.travis.yml

@@ -2,24 +2,11 @@ language: cpp
 
 matrix:
   include:
-    # Test Ubuntu 14.04 + clang
-    - os: linux
-      dist: trusty
-      sudo: required
-      compiler: clang
     # Test Ubuntu 14.04 + gcc
     - os: linux
       dist: trusty
       sudo: required
       compiler: gcc
-    # Test OS X 10.10 + Xcode 6.4 + clang
-    - os: osx
-      osx_image: xcode6.4
-      compiler: clang
-    # Test OS X 10.10 + Xcode 6.4 + gcc
-    - os: osx
-      osx_image: xcode6.4
-      compiler: gcc
     # Test OS X 10.11 + Xcode 7.3 + clang
     - os: osx
       osx_image: xcode7.3
@@ -28,10 +15,20 @@ matrix:
     - os: osx
       osx_image: xcode7.3
       compiler: gcc
+    # Test OS X 10.12 + Xcode 8.3 + clang
+    - os: osx
+      osx_image: xcode8.3
+      compiler: clang
+    # Test OS X 10.12 + Xcode 8.3 + gcc
+    - os: osx
+      osx_image: xcode8.3
+      compiler: gcc
 
 script:
   - mkdir build
   - cd build
   - cmake ..
   - make
   - bin/unit_tests
+  - pip install --user ..
+  - python ../src/tests/python_tests/main.py

3RD_PARTY.md

@@ -401,3 +401,85 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 
 Jet uses portion of Fluid3D by Christopher Batty.
 Original code from: https://github.com/christopherbatty/Fluid3D
+
+---
+
+Jet uses pybind11 for Python binding.
+
+Copyright (c) 2016 Wenzel Jakob <[email protected]>, 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.
+
+You are under no obligation whatsoever to provide any bug fixes, patches, or
+upgrades to the features, functionality or performance of the source code
+("Enhancements") to anyone; however, if you choose to make your Enhancements
+available either publicly, or directly to the author of this software, without
+imposing a separate written license agreement for such Enhancements, then you
+hereby grant the following license: a non-exclusive, royalty-free perpetual
+license to install, use, modify, prepare derivative works, incorporate into
+other computer software, distribute, and sublicense such enhancements or
+derivative works thereof, in binary and source code form.
+
+---
+
+Jet uses portion of pybind/cmake_example for Python binding.
+
+Copyright (c) 2016 The Pybind Development Team, 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.
+
+You are under no obligation whatsoever to provide any bug fixes, patches, or
+upgrades to the features, functionality or performance of the source code
+("Enhancements") to anyone; however, if you choose to make your Enhancements
+available either publicly, or directly to the author of this software, without
+imposing a separate written license agreement for such Enhancements, then you
+hereby grant the following license: a non-exclusive, royalty-free perpetual
+license to install, use, modify, prepare derivative works, incorporate into
+other computer software, distribute, and sublicense such enhancements or
+derivative works thereof, in binary and source code form.

CMakeLists.txt

@@ -7,7 +7,7 @@
 #
 
 # CMake version
-cmake_minimum_required(VERSION 2.8 FATAL_ERROR)
+cmake_minimum_required(VERSION 2.8.12 FATAL_ERROR)
 
 # Include cmake modules
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
@@ -16,13 +16,15 @@ list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 project(jet)
 
 # Set output directories
+set(DEFAULT_CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_LIBRARY_OUTPUT_DIRECTORY})
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/bin)
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/lib)
 set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/lib)
 
 # Includes
 include_directories(include)
 include_directories(external)
+include_directories(external/pybind11/include)
 include_directories(external/googletest/googletest/include)
 if (CMAKE_CXX_COMPILER_ID MATCHES "MSVC")
     include_directories(src/winix)
@@ -55,9 +57,14 @@ add_custom_target(unzip_py ALL
         DEPENDS ${RESOURCES_OBJS})
 
 # Project modules
-add_subdirectory(external/cnpy)
 set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
 add_subdirectory(external/googletest EXCLUDE_FROM_ALL)
+if ((CMAKE_VERSION VERSION_EQUAL 3.3) OR (CMAKE_VERSION VERSION_GREATER 3.3))
+    cmake_policy(SET CMP0063 NEW)
+endif()
+set(CMAKE_CXX_VISIBILITY_PRESET hidden)
+set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)
+add_subdirectory(external/cnpy)
 add_subdirectory(external/pystring)
 add_subdirectory(src/jet)
 add_subdirectory(src/tests/manual_tests)
@@ -74,3 +81,9 @@ add_subdirectory(src/examples/particles2obj)
 add_subdirectory(src/examples/particles2xml)
 add_subdirectory(src/examples/smoke_sim)
 add_subdirectory(src/examples/sph_sim)
+
+add_subdirectory(external/pybind11)
+if (BUILD_FROM_PIP)
+    set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${DEFAULT_CMAKE_LIBRARY_OUTPUT_DIRECTORY})
+endif()
+add_subdirectory(src/python)

INSTALL.md

@@ -18,9 +18,11 @@ To build the code, a compiler that supports C++11 is required. Platform-specific
 Jet supports OS X 10.10 Yosemite or higher. Also, Xcode 6.4 or higher and the command line tools are required for building Jet. Once ready, install [Homebrew](http://brew.sh) and run the following command line to setup [CMake](https://cmake.org/):
 
 ```
-brew install cmake
+brew install cmake python
 ```
 
+> Note that we want `brew` version of Python which is recommended. You can still use macOS's default Python.
+
 Once CMake is installed, build the code by running
 
 ```
@@ -30,18 +32,22 @@ cmake ..
 make
 ```
 
+> Of course, use `make -j<num_threads>` flag to boost up the build performance by using multithreads.
+
 This will build entire codebase. To run the unit test, execute
 
 ```
 bin/unit_tests
 ```
 
+It should show all the tests are passing.
+
 ### Building from Ubuntu
 
 Jet supports Ubuntu 14.04 or higher. Using `apt-get`, install required tools and libraries by running,
 
 ```
-sudo apt-get install build-essential python cmake
+sudo apt-get install build-essential python-dev python-pip cmake
 ```
 
 This will install GNU compilers, python, and CMake. Once installed, build the code by running
@@ -53,15 +59,19 @@ cmake ..
 make
 ```
 
+> Again, use `make -j<num_threads>` flag to boost up the build performance by using multithreads.
+
 This will build entire codebase. To run the unit test, execute
 
 ```
 bin/unit_tests
 ```
 
+It should show all the tests are passing.
+
 ### Building from Windows
 
-To build the code on Windows, [CMake](https://cmake.org/) and Visual Studio 2015 is required. Windows' version of CMake is available from [this website](https://cmake.org/), and free version of VS 2015 also can be downloaded from [Visual Studio Community 2015](https://www.Visualstudio.com/en-us/products/Visual-studio-community-vs.aspx). In addition to Visual Studio, install [Python](https://www.python.org/) (2.7.9 or higher recommended) to run post-build events.
+To build the code on Windows, CMake, Python, and Visual Studio 2015 (or higher) is required. Windows' version of CMake is available from [this website](https://cmake.org/), Python installer can be downloaded from [here](https://python.org/). For Python, version 2.7.9 or later is recommended. To install Visual Studio, the community edition of the tool can be downloaded from [Visual Studio Community 2015](https://www.Visualstudio.com/en-us/products/Visual-studio-community-vs.aspx). You can also use Visual Studio 2017.
 
 Once everything is installed, run the following commands:
 
@@ -87,9 +97,9 @@ bin\Release\unit_tests.exe
 
 ### Running Tests
 
-There are three different tests in the codebase including the unit test, manual test, and performance test. For the detailed instruction on how to run those tests, please checkout the documentation page from [the project website](http://doyubkim.github.io/fluid-engine-dev/documentation/).
+There are four different tests in the codebase including the unit test, manual test, performance test, and Python API test. For the detailed instruction on how to run those tests, please checkout the documentation page from [the project website](http://doyubkim.github.io/fluid-engine-dev/documentation/).
 
-### Installing SDK
+### Installing C++ SDK
 
 For macOS and Ubuntu platforms, the library can be installed by running
 
@@ -109,6 +119,22 @@ cmake .. -G"Visual Studio 14 2015 Win64" -DCMAKE_INSTALL_PREFIX=_INSTALL_PATH_
 
 Then, build `INSTALL` project under `jet.sln`. This will install the header files and the static library `jet.lib` under `_INSTALL_PATH_`.
 
+### Installing Python SDK
+
+To install the Python SDK, `pyjet`, run the following command from the project root directory (where `setup.py` lives):
+
+```
+pip install .
+```
+
+Once installed, try running the unit test to see if the module is installed correctly:
+
+```
+python src/tests/python_tests/main.py
+```
+
+The tests should pass.
+
 ### Coding Style
 
 Jet uses clang-format. Checkout [`.clang-format`](https://github.com/doyubkim/fluid-engine-dev/blob/master/.clang-format) file for the style guideline.

README.md

@@ -1,8 +1,8 @@
 # Fluid Engine Dev - Jet
 
-[![License](http://img.shields.io/:license-mit-blue.svg)](LICENSE.md) [![Build Status](https://travis-ci.org/doyubkim/fluid-engine-dev.svg?branch=master)](https://travis-ci.org/doyubkim/fluid-engine-dev) [![Build status](https://ci.appveyor.com/api/projects/status/kulihlhy43vbwou6/branch/master?svg=true)](https://ci.appveyor.com/project/doyubkim/fluid-engine-dev/branch/master)
+[![License](http://img.shields.io/:license-mit-blue.svg)](LICENSE.md) [![Build Status](https://travis-ci.org/doyubkim/fluid-engine-dev.svg?branch=python)](https://travis-ci.org/doyubkim/fluid-engine-dev) [![Build status](https://ci.appveyor.com/api/projects/status/kulihlhy43vbwou6/branch/python?svg=true)](https://ci.appveyor.com/project/doyubkim/fluid-engine-dev/branch/python)
 
-Jet framework is a fluid simulation engine SDK for computer graphics applications that was created by Doyub Kim as part of the book, ["Fluid Engine Development"](https://www.crcpress.com/Fluid-Engine-Development/Kim/p/book/9781498719926). The code is built on C++11 and can be compiled with most of the commonly available compilers such as g++, clang++, or Microsoft Visual Studio. Jet currently supports macOS (10.10 or later), Ubuntu (14.04 or later), and Windows (Visual Studio 2015 or later). Other untested platforms that support C++11 also should be able to build Jet.
+Jet framework is a fluid simulation engine SDK for computer graphics applications that was created by Doyub Kim as part of the book, ["Fluid Engine Development"](https://www.crcpress.com/Fluid-Engine-Development/Kim/p/book/9781498719926). The code is built on C++11 and can be compiled with most of the commonly available compilers such as g++, clang++, or Microsoft Visual Studio. Jet currently supports macOS (10.10 or later), Ubuntu (14.04 or later), and Windows (Visual Studio 2015 or later). Other untested platforms that support C++11 also should be able to build Jet. The framework also provides Python API for faster prototyping.
 
 The latest code is always available from the [`master`](https://github.com/doyubkim/fluid-engine-dev/tree/master) branch. Since the code evolves over time, the latest from the master could be somewhat different from the code in the book. To find the version that is consistent with the book, check out the branch [`book-1st-edition`](https://github.com/doyubkim/fluid-engine-dev/tree/book-1st-edition).
 
@@ -15,6 +15,7 @@ The latest code is always available from the [`master`](https://github.com/doyub
 * PIC, FLIP, and APIC fluid simulators
 * Upwind, ENO, and FMM level set solvers
 * Converters between signed distance function and triangular mesh
+* C++ and Python API
 
 Every simulator has both 2-D and 3-D implementations.
 

appveyor.yml

@@ -1,23 +1,36 @@
-version: 1.0.6 ({build})
+# Adopted from https://github.com/pybind/pybind11/blob/master/.appveyor.yml
+
+version: 1.1.0-rc1 ({build})
 
 os:
+  - Visual Studio 2017
   - Visual Studio 2015
 
 platform:
   - x64
 
+matrix:
+  fast_finish: true  # Stop remaining jobs after a job failure
+
 configuration:
   - Release
 
 clone_folder: c:\jet
 
 install:
   - git submodule update --init
+  - ps: |
+      if ($env:PLATFORM -eq "x64") { $env:CMAKE_ARCH = "x64" }
+      if ($env:APPVEYOR_JOB_NAME -like "*Visual Studio 2017*") { $env:CMAKE_GENERATOR = "Visual Studio 15 2017" }
+      else { $env:CMAKE_GENERATOR = "Visual Studio 14 2015" }
+      $env:PYTHON = "27"
+      if ($env:PLATFORM -eq "x64") { $env:PYTHON = "$env:PYTHON-x64" }
+      $env:PATH = "C:\Python$env:PYTHON\;C:\Python$env:PYTHON\Scripts\;$env:PATH"
 
 before_build:
   - md c:\jet\build
   - cd c:\jet\build
-  - cmake .. -G"Visual Studio 14 2015 Win64"
+  - cmake .. -G "%CMAKE_GENERATOR%" -A "%CMAKE_ARCH%"
 
 build:
   project: c:\jet\build\jet.sln
@@ -26,3 +39,5 @@ build:
 
 after_build:
   - c:\jet\build\bin\Release\unit_tests.exe
+  - pip install --user c:\jet
+  - python c:\jet\src\tests\python_tests\main.py

doc/doxygen/Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = Jet
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = v1.0.6
+PROJECT_NUMBER         = v1.1.0-rc1
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

doc/doxygen/main.md

@@ -1,4 +1,4 @@
-Jet framework is a fluid simulation engine SDK for computer graphics applications that was created by Doyub Kim as part of the book, ["Fluid Engine Development"](https://www.crcpress.com/Fluid-Engine-Development/Kim/p/book/9781498719926). The code is built on C++11 and can be compiled with most of the commonly available compilers such as g++, clang++, or Microsoft Visual Studio. Jet currently supports macOS (10.10 or later), Ubuntu (14.04 or later), and Windows (Visual Studio 2015 or later). Other untested platforms that support C++11 also should be able to build Jet.
+Jet framework is a fluid simulation engine SDK for computer graphics applications that was created by Doyub Kim as part of the book, ["Fluid Engine Development"](https://www.crcpress.com/Fluid-Engine-Development/Kim/p/book/9781498719926). The code is built on C++11 and can be compiled with most of the commonly available compilers such as g++, clang++, or Microsoft Visual Studio. Jet currently supports macOS (10.10 or later), Ubuntu (14.04 or later), and Windows (Visual Studio 2015 or later). Other untested platforms that support C++11 also should be able to build Jet. The framework also provides Python API for faster prototyping.
 
 ### Key Features
 * Basic math and geometry operations and data structures
@@ -9,5 +9,6 @@ Jet framework is a fluid simulation engine SDK for computer graphics application
 * PIC, FLIP, and APIC fluid simulators
 * Upwind, ENO, and FMM level set solvers
 * Converters between signed distance function and triangular mesh
+* C++ and Python API
 
 Every simulator has both 2-D and 3-D implementations.

include/jet/bounding_box3.h

@@ -110,7 +110,7 @@ class BoundingBox<T, 3> {
     Vector3<T> corner(size_t idx) const;
 
     //! Returns the clamped point.
-    Vector3<T> clamp(const Vector3<T>& pt) const;
+    Vector3<T> clamp(const Vector3<T>& point) const;
 };
 
 //! Type alias for 3-D BoundingBox.

include/jet/cell_centered_vector_grid2.h

@@ -76,10 +76,12 @@ class CellCenteredVectorGrid2 final : public CollocatedVectorGrid2 {
     CellCenteredVectorGrid2& operator=(const CellCenteredVectorGrid2& other);
 
     //! Fills the grid with given value.
-    void fill(const Vector2D& value) override;
+    void fill(const Vector2D& value,
+              ExecutionPolicy policy = ExecutionPolicy::kParallel) override;
 
     //! Fills the grid with given function.
-    void fill(const std::function<Vector2D(const Vector2D&)>& func) override;
+    void fill(const std::function<Vector2D(const Vector2D&)>& func,
+              ExecutionPolicy policy = ExecutionPolicy::kParallel) override;
 
     //! Returns the copy of the grid instance.
     std::shared_ptr<VectorGrid2> clone() const override;