[gnuastro-commits] master ed301e20 1/2: Library (python.c): Added module for helping build Python package

[Mohammad Akhlaghi]

branch: master
commit ed301e20c831a276da77dd1b8f138695f672359e
Author: Jash Shah <jash28582@gmail.com>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Library (python.c): Added module for helping build Python package
    
    Until now, Gnuastro library facilitated C/C++ programs, but with this
    commit we start working towards setting up the Gnuastro Python package.
    The Python package will provide a high-level abstraction of the current
    library functions alongwith using NumPy as the default container for any
    data arrays.
    
    With this commit, we add an extra option to the configure script to toggle
    Python library module. We also add checks to conditionally build the python
    library module, only if the user has Python 3 and NumPy installed.
    
    Currently, the new module added, only provides two conversion functions
    between Gnuastro and NumPy's data types. However, the aim is to collect all
    utility functions that might be needed for writing the Python extensions
    modules (source of the Python package) in this one place.
    
    Also, added description of the module and its functions in the book under
    the Library section.
    
    Also, fixed a typo found in the lib/fits.c file.
---
 configure.ac          |  43 +++++++++++++++++++
 doc/gnuastro.texi     |  24 +++++++++++
 lib/Makefile.am       |  19 ++++++++-
 lib/fits.c            |   2 +-
 lib/gnuastro/python.h |  68 ++++++++++++++++++++++++++++++
 lib/python.c          | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++
 6 files changed, 267 insertions(+), 3 deletions(-)

diff --git a/configure.ac b/configure.ac
index 58c648ec..c097aca4 100644
--- a/configure.ac
+++ b/configure.ac
@@ -755,6 +755,49 @@ AS_IF([test "x$has_topcat" = "xno"], [anywarnings=yes])
 
 
 
+# Check Python3 and NumPy:
+# checks if Python3 and NumPy are installed, in that order
+# and gets their include path if true. This is done using two
+# python scripts:
+## py_check_cmd: Uses the sysconfig package's get_paths method
+##               to get the include path for Python.h header.
+## np_check_cmd: Uses numpy's get_include method to get the
+##               include path for NumPy's core C-API.
+AC_ARG_WITH([python],
+            [AS_HELP_STRING([--without-python],
+                            [disable support for python])],
+            [], [with_python=yes])
+py_check_cmd='from sysconfig import get_paths; \
+              print(get_paths().get("include"))'
+np_check_cmd='from numpy import get_include; \
+              print(get_include())'
+AS_IF([test "x$with_python" != xno],
+      [
+        AC_CHECK_PROG(has_python3, python3, [yes], [no])
+        AM_PATH_PYTHON(3.0,,[:])
+        AS_IF([test $has_python3 = yes],
+        [
+          AC_DEFINE(HAVE_PYTHON, [1],
+                    [Define to 1 if you have Python3.])
+          AC_MSG_CHECKING(if numpy is available in the python3 installation)
+          AS_IF([$PYTHON -c "$py_check_cmd" &> /dev/null],
+                [python_includedir="$($PYTHON -c "$py_check_cmd")"
+                 AS_IF([$PYTHON -c "$np_check_cmd" &> /dev/null],
+                       [numpy_includedir="$($PYTHON -c "$np_check_cmd")"])
+                ])
+        ])
+        AC_SUBST(NUMPY_INCLUDE_DIR, [$numpy_includedir])
+        AC_SUBST(PYTHON_INCLUDE_DIR, [$python_includedir])
+      ])
+AS_IF([test "x$numpy_includedir" = x],
+      [AC_MSG_RESULT([no])],
+      [AC_MSG_RESULT([yes])])
+AM_CONDITIONAL([COND_NUMPY], [test "x$numpy_includedir" != x])
+
+
+
+
+
 # If any necessary dependency is missing inform the user and abort.
 AS_IF([test "x$missing_mandatory" = "xyes"],
       [
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 34b47272..deb193cb 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -781,6 +781,7 @@ Gnuastro library
 * Spectral lines library::      Functions for operating on Spectral lines.
 * Cosmology library::           Cosmological calculations.
 * SAO DS9 library::             Take inputs from files generated by SAO DS9.
+* Python library::              Utility functions for the Gnuastro Python 
Package.
 
 Multithreaded programming (@file{threads.h})
 
@@ -28693,6 +28694,7 @@ If you use the Info version of this manual (see 
@ref{Info}), you do not have to
 * Spectral lines library::      Functions for operating on Spectral lines.
 * Cosmology library::           Cosmological calculations.
 * SAO DS9 library::             Take inputs from files generated by SAO DS9.
+* Python library::              Utility functions for the Gnuastro Python 
Package.
 @end menu
 
 @node Configuration information, Multithreaded programming, Gnuastro library, 
Gnuastro library
@@ -36236,6 +36238,28 @@ polygon(53.187414,-27.779152,53.159507,-27.759633,...)
 @end example
 @end deftypefun
 
+
+
+
+
+@node Python library, , SAO DS9 library, Gnuastro library
+@subsection Python Library (@file{python.h})
+
+This library provides the utility functions required for building the Gnuastro 
Python package. The Gnuastro Python Package is built using CPython. This 
entails using Python wrappers around currently existing Gnuastro library 
functions to build @url{https://docs.python.org/3/extending/extending.html#, 
Python Extension Modules}. It also makes use of the 
@url{https://numpy.org/doc/stable/reference/c-api/index.html, NumPy C-API} for 
dealing with data arrays.
+The interfacing between all these tools requires a set of utility functions. 
Since many of these functions depend on the Gnuastro Library itself, it is more 
convenient to package them with the Library instead of the Python package.
+
+@deftypefun int gal_py_galtype_to_npytype(uint8_t @code{type})
+Returns the NumPy datatype corresponding the Gnuastro @code{type}.
+@end deftypefun
+
+@deftypefun int gal_py_npytype_to_galtype(uint_8 @code{type})
+Returns the Gnuastro's type identifier that correspondes to the NumPy 
@code{type} passed.
+@end deftypefun
+
+
+
+
+
 @node Library demo programs,  , Gnuastro library, Library
 @section Library demo programs
 
diff --git a/lib/Makefile.am b/lib/Makefile.am
index b8597d1a..e0ebd1f6 100644
--- a/lib/Makefile.am
+++ b/lib/Makefile.am
@@ -22,6 +22,8 @@
 
 
 # Conditional compilation
+headersdir=$(top_srcdir)/lib/gnuastro
+
 if COND_HASWCSDIS_H
   MAYBE_WCSDISTORTION = wcsdistortion.c
 endif
@@ -29,6 +31,14 @@ if COND_HASGNUMAKE_H
   MAYBE_GNUMAKE = libgnuastro_make.la
 endif
 
+# Build the python utilities file,
+# only if Python and NumPy are present.
+if COND_NUMPY
+  MAYBE_NUMPY_C = python.c
+  MAYBE_NUMPY_H = $(headersdir)/python.h
+  MAYBE_NUMPY_INCLUDE = -I$(NUMPY_INCLUDE_DIR) -I$(PYTHON_INCLUDE_DIR)
+endif
+
 
 
 
@@ -43,9 +53,13 @@ endif
 ##
 ##   SYSCONFIG_DIR: only necessary in 'options.c' to get the system
 ##       installation directory.
+##
+##   MAYBE_NUMPY_INCLUDE: only necessary in 'python.c' to link the
+##                        numpy C-API.
 AM_CPPFLAGS = -I\$(top_builddir)/bootstrapped/lib \
               -I\$(top_srcdir)/bootstrapped/lib \
-              -DSYSCONFIG_DIR=\"$(sysconfdir)\"
+              -DSYSCONFIG_DIR=\"$(sysconfdir)\" \
+              $(MAYBE_NUMPY_INCLUDE)
 
 
 
@@ -73,6 +87,7 @@ libgnuastro_make_la_LDFLAGS = -version-info $(GAL_LT_VERSION)
 # Specify the library .c files
 libgnuastro_make_la_SOURCES = makeplugin.c
 libgnuastro_la_SOURCES = \
+  $(MAYBE_NUMPY_C) \
   $(MAYBE_WCSDISTORTION) \
   arithmetic.c \
   arithmetic-and.c \
@@ -141,8 +156,8 @@ libgnuastro_la_SOURCES = \
 # Installed headers, note that we are not blindly including all '.h' files
 # in the $(headersdir) directory. Some of the header files don't need to be
 # installed.
-headersdir=$(top_srcdir)/lib/gnuastro
 pkginclude_HEADERS = gnuastro/config.h \
+  $(MAYBE_NUMPY_H) \
   $(headersdir)/arithmetic.h \
   $(headersdir)/array.h \
   $(headersdir)/binary.h \
diff --git a/lib/fits.c b/lib/fits.c
index bab69df4..b0a0e4a1 100644
--- a/lib/fits.c
+++ b/lib/fits.c
@@ -124,7 +124,7 @@ gal_fits_name_is_fits(char *name)
 
 
 
-/* IMPORTANT NOTE: if other compression suffixes are add to this function,
+/* IMPORTANT NOTE: if other compression suffixes are added to this function,
    include them in 'gal_checkset_automatic_output', so the compression
    suffix can be skipped when the user doesn't specify an output
    filename.*/
diff --git a/lib/gnuastro/python.h b/lib/gnuastro/python.h
new file mode 100644
index 00000000..af171600
--- /dev/null
+++ b/lib/gnuastro/python.h
@@ -0,0 +1,68 @@
+/*********************************************************************
+python -- Functions to assist the python wrappers.
+This is part of GNU Astronomy Utilities (Gnuastro) package.
+Original author:
+     Mohammad Akhlaghi <mohammad@akhlaghi.org>
+Contributing author(s):
+     Sachin Kumar Singh <sachinkumarsingh092@gmail.com>
+Copyright (C) 2017-2022 Free Software Foundation, Inc.
+Gnuastro 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.
+Gnuastro 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.
+You should have received a copy of the GNU General Public License
+along with Gnuastro. If not, see <http://www.gnu.org/licenses/>.
+**********************************************************************/
+#ifndef __GAL_PYTHON_H__
+#define __GAL_PYTHON_H__
+
+/* Include other headers if necessary here. Note that other header files
+   must be included before the C++ preparations below */
+#include <gnuastro/data.h>
+
+
+/* C++ Preparations */
+#undef __BEGIN_C_DECLS
+#undef __END_C_DECLS
+#ifdef __cplusplus
+# define __BEGIN_C_DECLS extern "C" {
+# define __END_C_DECLS }
+#else
+# define __BEGIN_C_DECLS                /* empty */
+# define __END_C_DECLS                  /* empty */
+#endif
+/* End of C++ preparations */
+
+
+
+
+
+/* Actual header contants (the above were for the Pre-processor). */
+__BEGIN_C_DECLS  /* From C++ preparations */
+
+
+
+
+
+/*************************************************************
+ **************           Type codes           ***************
+ *************************************************************/
+/* Convert Gnuastro type to NumPy datatype. */
+int
+gal_py_galtype_to_npytype(uint8_t type);
+
+/* Convert Numpy datatype to Gnuastro type. */
+int
+gal_py_npytype_to_galtype(uint8_t type);
+
+
+
+
+
+__END_C_DECLS    /* From C++ preparations */
+
+#endif           /* __GAL_TABLE_H__ */
diff --git a/lib/python.c b/lib/python.c
new file mode 100644
index 00000000..5230956e
--- /dev/null
+++ b/lib/python.c
@@ -0,0 +1,114 @@
+/*********************************************************************
+python -- Functions to assist the python wrappers.
+This is part of GNU Astronomy Utilities (Gnuastro) package.
+Original author:
+     Mohammad Akhlaghi <mohammad@akhlaghi.org>
+Contributing author(s):
+     Sachin Kumar Singh <sachinkumarsingh092@gmail.com>
+Copyright (C) 2017-2022 Free Software Foundation, Inc.
+Gnuastro 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.
+Gnuastro 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.
+You should have received a copy of the GNU General Public License
+along with Gnuastro. If not, see <http://www.gnu.org/licenses/>.
+**********************************************************************/
+#include <config.h>
+
+#include <errno.h>
+#include <error.h>
+
+#ifdef HAVE_PYTHON
+  // This macro needs to be defined before including any NumPy headers
+  // to avoid the compiler from raising a warning message.
+  #define NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION
+  #include <numpy/arrayobject.h>
+#endif
+
+#include <gnuastro/python.h>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+/*************************************************************
+ **************           Type codes           ***************
+ *************************************************************/
+#ifdef HAVE_PYTHON
+/* Convert Gnuastro type to NumPy datatype. */
+int
+gal_py_galtype_to_npytype(uint8_t type)
+{
+  switch (type)
+  {
+  /* Types directly convertible between Gnuastro and NumPy. */
+  case GAL_TYPE_INT8:      return NPY_INT8;
+  case GAL_TYPE_INT16:     return NPY_INT16;
+  case GAL_TYPE_INT32:     return NPY_INT32;
+  case GAL_TYPE_INT64:     return NPY_LONG;
+  case GAL_TYPE_UINT8:     return NPY_UINT8;
+  case GAL_TYPE_UINT16:    return NPY_UINT16;
+  case GAL_TYPE_UINT32:    return NPY_UINT32;
+  case GAL_TYPE_UINT64:    return NPY_UINT64;
+  case GAL_TYPE_FLOAT32:   return NPY_FLOAT32;
+  case GAL_TYPE_FLOAT64:   return NPY_FLOAT64;
+  case GAL_TYPE_STRING:    return NPY_STRING;
+  default:
+    error(EXIT_FAILURE, 0, "%s: type code %d is not convertible"
+            "to NumPy.", __func__, type);
+  }
+
+  return GAL_TYPE_INVALID;
+}
+
+
+
+
+
+/* Convert Numpy datatype to Gnuastro type. */
+int
+gal_py_npytype_to_galtype(uint8_t type)
+{
+  /* Types directly convertible between NumPy and Gnuastro. */
+  switch (type)
+  {
+  // Currently only converting types directly compatible
+  // between the two.
+  case NPY_INT8:           return GAL_TYPE_INT8;
+  case NPY_INT16:          return GAL_TYPE_INT16;
+  case NPY_INT32:          return GAL_TYPE_INT32;
+  case NPY_LONG:           return GAL_TYPE_INT64;
+  case NPY_UINT8:          return GAL_TYPE_UINT8;
+  case NPY_UINT16:         return GAL_TYPE_UINT16;
+  case NPY_UINT32:         return GAL_TYPE_UINT32;
+  case NPY_UINT64:         return GAL_TYPE_UINT64;
+  case NPY_FLOAT32:        return GAL_TYPE_FLOAT32;
+  case NPY_FLOAT64:        return GAL_TYPE_FLOAT64;
+  case GAL_TYPE_COMPLEX64: return NPY_COMPLEX64;
+  case GAL_TYPE_STRING:    return NPY_STRING;
+  default:
+    error(EXIT_FAILURE, 0, "%s: type code %d is not convertible"
+            "to Gnuastro.", __func__, type);
+  }
+  return GAL_TYPE_INVALID;
+}
+#endif