Merge pull request #20 from krober10nd/revisions

Changing license of SeismicMesh to GPLv3, more extensive readme, more info on docs.

CMakeLists.txt

@@ -31,6 +31,9 @@ set (GEOMETRY_SRCE "SeismicMesh/geometry/cpp")
 
 include_directories (${MIGRATION_SRCE} ${GENERATION_SRCE} ${SIZING_SRC} ${GEOMETRY_SRCE})
 
+find_package(pybind11)
+message(STATUS "Found pybind11 v${pybind11_VERSION}: ${pybind11_INCLUDE_DIRS}")
+
 add_subdirectory(pybind11)
 pybind11_add_module(cpputils ${SOURCES}  "${MIGRATION_SRCE}/cpputils.cpp")
 pybind11_add_module(FastHJ ${SOURCES} "${SIZING_SRCE}/FastHJ.cpp")

MANIFEST.in

@@ -0,0 +1,9 @@
+include SeismicMesh/generation/cpp/*.cpp
+include SeismicMesh/geometry/cpp/*.cpp
+include SeismicMesh/migration/cpp/*.cpp
+include SeismicMesh/sizing/cpp/*.cpp
+
+include README.rst LICENSE 
+global-include CMakeLists.txt 
+recursive-include pybind11/include *.h
+

README.rst

@@ -14,41 +14,141 @@
 .. image:: https://readthedocs.org/projects/seismicmesh/badge/?version=par3d
         :target: https://seismicmesh.readthedocs.io/en/par3d/?badge=par3d
 
-.. image:: https://img.shields.io/badge/License-BSD%202--Clause-orange.svg
-	:target: https://opensource.org/licenses/BSD-2-Clause
+.. image:: https://img.shields.io/badge/License-GPLv3-blue.svg
+	:target: https://www.gnu.org/licenses/gpl-3.0
 
 .. image:: https://zenodo.org/badge/216707188.svg
    :target: https://zenodo.org/badge/latestdoi/216707188
 
 
 
 SeismicMesh_: Mesh generation for Seismology in Python
-==============================================
-2D/3D triangular meshing for a slab of Earth based on modifications to the DistMesh_ algorithm. SeismicMesh is distributed under the BSD 2-Clause.
+=========================================================
+2D/3D triangular meshing for a slab of Earth based on modifications to the DistMesh_ algorithm. SeismicMesh is distributed under GPL3.
 
 .. _SeismicMesh: https://github.com/krober10nd/SeismicMesh
 .. _DistMesh: http://persson.berkeley.edu/distmesh/
 .. _`GNU-GPL`: http://www.gnu.org/copyleft/gpl.html
 
 
-Getting Started
-===============
+Installation
+=====================
+
+For installation, SeismicMesh needs CGAL (https://www.cgal.org/)::
+
+    sudo apt install libcgal-dev
+
+and pybind11 (https://github.com/pybind/pybind11):: 
+
+    sudo apt-get install python-pybind11
 
-All information is available at: https://seismicmesh.readthedocs.io
+After that, SeismicMesh can be installed from the Python Package
+Index (https://pypi.org/project/SeismicMesh/), so with::
+
+    pip install -U SeismicMesh
+
+For more detailed information about installation and requirements see: 
 
 `Install <https://seismicmesh.readthedocs.io/en/par3d/install.html>`_
 - How to install SeismicMesh. 
 
+
+Example 
+===========
+
+The user can quickly build quality 2D/3D meshes from seismic velocity models in serial/parallel like so. 
+First we take care of our imports::
+
+    import numpy as np
+    import zipfile
+    
+    from mpi4py import MPI
+    import meshio
+
+    import SeismicMesh
+    
+    comm = MPI.COMM_WORLD
+    size = comm.Get_size()
+    rank = comm.Get_rank()
+
+Here we download a benchmark 3D velocity model and turn it into a Numpy array::
+
+    # https://s3.amazonaws.com/open.source.geoscience/open_data/seg_eage_models_cd/Salt_Model_3D.tar.gz
+
+    if rank == 0: 
+        # Dimensions of model (number of grid points in z, x, and y)
+        nx, ny, nz = 676, 676, 210
+
+        path = "velocity_models/Salt_Model_3D/3-D_Salt_Model/VEL_GRIDS/"
+        # Extract Saltf@@ from SALTF.ZIP
+        zipfile.ZipFile(path + "SALTF.ZIP", "r").extract("Saltf@@", path=path)
+
+        # Load data into a numpy array
+        with open(path + "Saltf@@", "r") as file:
+            vp = np.fromfile(file, dtype=np.dtype("float32").newbyteorder(">"))
+            vp = vp.reshape(nx, ny, nz, order="F")
+            vp = np.flipud(vp.transpose((2, 0, 1)))  # z, x and then y
+
+The domain is defined (in this case) as a cube and domain extents are provided in meters::
+
+    # Bounding box describing domain extents (corner coordinates)
+    bbox = (-4200, 0, 0, 13520, 0, 13520)
+
+A graded sizing function is created from the velocity model along with a signed distance function by passing
+the velocity grid that we created above::
+
+    ef = SeismicMesh.MeshSizeFunction(
+        bbox=bbox,
+        velocity_grid=vp,
+        dt=0.001,
+        freq=2,
+        wl=5,
+        grade=0.25,
+        hmin=150,
+        hmax=5e3,
+        domain_ext=250,
+        padstyle="linear_ramp",
+    )
+
+    ef = ef.build()
+
+The user then calls the mesh generator::
+
+    # Construct a mesh generator object
+    mshgen = SeismicMesh.MeshGenerator(ef)
+
+    # Build the mesh
+    points, cells = mshgen.build(max_iter=75, axis=1)
+
+For 3D mesh generation, we provide an implementation to bound the minimum dihedral angle::
+
+    points, cells = mshgen.build(
+        points=points, mesh_improvement=True, max_iter=50, min_dh_bound=5,
+    )
+
+Meshes can be written quickly to disk using meshio and visualized with Paraview::
+
+    if rank == 0:
+        meshio.write_points_cells(
+            "EAGE_Salt.vtk", points / 1000.0, [("tetra", cells)],
+        )
+
+ 
+More information
+==================
+
+All other information is available at: https://seismicmesh.readthedocs.io
+
 `Getting started <https://seismicmesh.readthedocs.io/en/par3d/overview.html>`_
 - Learn the basics about the program and the application domain. 
 
 `Tutorials <https://seismicmesh.readthedocs.io/en/par3d/tutorial.html>`_
 - Tutorials that will guide you through the main features.
 
 
-
 Gallery:
 ==============================================
-.. image:: imgs/seismic_example3.png
-.. image:: imgs/seismic_example.png
+
+.. image:: https://github.com/krober10nd/SeismicMesh/raw/par3d/imgs/seismic_example3.png
+.. image:: https://github.com/krober10nd/SeismicMesh/raw/par3d/imgs/seismic_example.png
 

SeismicMesh/generation/mesh_generator.py

@@ -1,19 +1,17 @@
-# -----------------------------------------------------------------------------
-# Copyright 2020 Keith Jared Roberts
+#   Copyright (C) 2020 Keith Roberts
 #
-# Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+#   This program is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
 #
-# 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
 #
-# 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.
-#
-# 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 should have received a copy of the GNU General Public License
+#   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 import math
 import time

SeismicMesh/sizing/mesh_size_function.py

@@ -1,19 +1,17 @@
-# -----------------------------------------------------------------------------
-# Copyright 2020 Keith Jared Roberts
+#   Copyright (C) 2020 Keith Roberts
 #
-# Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+#   This program is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
 #
-# 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+#   This program is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU General Public License for more details.
 #
-# 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.
-#
-# 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 should have received a copy of the GNU General Public License
+#   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 import warnings
 

docs/source/usrman/install.rst

@@ -12,6 +12,8 @@ build *SeismicMesh*:
     The file ``requirements.txt`` in the main directory indicates all the Python dependencies and their respective version numbers. These packages should be installed at compile time by setuptools
 .. note ::
     Some users have experienced  problems with the `skfmm-fmm` Python package not being found. If this occurs, try uninstalling and then reinstalling this package after attempting installation of SeismicMesh.
+.. note :: 
+    On some Linux systems, users may have to resort to `apt install python3-segyio` to installing segyio on their systems.
 
 * Pybind11 >= 2.5
 .. note ::
@@ -53,8 +55,8 @@ If installing on a cluster with a local installation of ``CGAL`` and ``Boost``,
   -DMPFR_INCLUDE_DIR=+/PATH/TO/MPFR/include
 
 
-Compilation
--------------
+Compilation by source
+----------------------
 
 After installing all dependencies, perform the two steps in the main directory in the order that they appear below::
 
@@ -63,6 +65,8 @@ $  pip install -e .
 
 .. note ::
     If you do not have administrative rights on your system, add the flag ``--user`` to end of the second command
+.. note :: 
+    It's highly recommended to just use pip to install (after installing CGAL): pip install SeismicMesh
 
 Testing
 -------

requirements.txt

@@ -7,3 +7,4 @@ meshio==4.0.10
 h5py==2.3.1
 pybind11==2.5.0
 scikit-fmm
+scikit-build

setup.py

@@ -17,9 +17,6 @@
     sys.exit(1)
 
 
-files = ["*.so*"]
-
-
 class CMakeExtension(Extension):
     def __init__(self, name, sourcedir=""):
         Extension.__init__(self, name, sources=[])
@@ -81,13 +78,18 @@ def build_extension(self, ext):
         )
 
 
+with open("README.rst", "r") as fh:
+    long_description = fh.read()
+
 setup(
     name="SeismicMesh",
-    version="1.0.0",
+    url="https://github.com/krober10nd/SeismicMesh",
+    version="1.2.41",
     author="Keith Roberts",
-    author_email="keithrbt0gmail.com",
+    author_email="keithrbt0@gmail.com",
     description="2D/3D serial and parallel triangular mesh generation and mesh improvement for seismology",
-    long_description="",
+    long_description=long_description,
+    long_description_content_type="text/x-rst",
     setup_requires=["pybind11"],
     install_requires=[
         "numpy",
@@ -101,7 +103,7 @@ def build_extension(self, ext):
         "scikit-fmm",
     ],
     packages=find_packages(),
-    package_data={"SeismicMesh": files},
+    package_data={"SeismicMesh": ["*.so", "*.txt"]},
     include_package_data=True,
     ext_modules=[
         CMakeExtension("SeismicMesh/sizing/cpp/FastHJ"),
@@ -113,4 +115,14 @@ def build_extension(self, ext):
     ],
     cmdclass=dict(build_ext=CMakeBuild),
     zip_safe=False,
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Topic :: Scientific/Engineering",
+        "Topic :: Scientific/Engineering :: Mathematics",
+        "Topic :: Scientific/Engineering :: Physics",
+        "Topic :: Scientific/Engineering :: Visualization"],
+    python_requires='>=3.0',
 )