Merge pull request #22 from datasig-ac-uk/release/v0.0.5

Release/v0.0.5

.github/workflows/manage_version.yml

@@ -4,7 +4,7 @@ name: Manage version file
 on:
   pull_request:
     branches:
-      - release/v[0-9]+.[0-9]+.[0-9]+**
+      - main
     types:
       - opened
 
@@ -13,7 +13,7 @@ on:
 jobs:
   update_version:
     runs-on: ubuntu-latest
-    if: github.base_ref == 'refs/heads/main'
+    if: startsWith(github.ref_name, 'refs/heads/main')
     steps:
       - uses: actions/checkout@v3
       - name: Write version file

CHANGELOG

@@ -1,3 +1,13 @@
+Version 0.0.5:
+  - Added free functions for performing free-tensor, shuffle, half-shuffle
+  multiplication between pairs of tensors (of either kind).
+  - Added free function for applying the adjoint of left free tensor
+  multiplication to arbitrary tensors.
+  - Improved exception usage, messages now include filename, lineno, and
+  function name to help locate c++ exceptions passed through to Python.
+  - Basis objects in Python are now iterable.
+  - Added `split_n` and `to_index` methods to Tensor key.
+
 Version 0.0.4:
   - Overhauled the RPY_CHECK macro so it now gives much better contextual
   information.

CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 3.21)
+cmake_minimum_required(VERSION 3.22)
 
 message(STATUS "Toolchain file: ${CMAKE_TOOLCHAIN_FILE}")
 list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_LIST_DIR}/cmake/Modules)
@@ -15,62 +15,87 @@ endif ()
 
 project(RoughPy VERSION ${_rpy_version})
 
-set_property(GLOBAL PROPERTY USE_FOLDERS ON)
-
-set(CMAKE_INSTALL_LIBDIR "roughpy" CACHE STRING "install library dir")
-set(CMAKE_INSTALL_BINDIR "roughpy" CACHE STRING "install binary dir")
-
-set(CMAKE_CXX_STANDARD 17)
-set(CMAKE_CXX_STANDARD_REQUIRED ON)
-if (LINUX)
-    set(CMAKE_INSTALL_RPATH "$ORIGIN")
-elseif (APPLE)
-    execute_process(COMMAND "brew" "--prefix"
-            RESULT_VARIABLE _brew_prefix_found
-            OUTPUT_VARIABLE _brew_prefix
-            OUTPUT_STRIP_TRAILING_WHITESPACE
-            )
-    message(STATUS "Adding brew prefix: ${_brew_prefix}")
-    if (_brew_prefix_found)
-        list(APPEND CMAKE_PREFIX_PATH "${_brew_prefix}")
-    endif ()
-
-
-    #    set(CMAKE_BUILD_WITH_INSTALL_RPATH ON)
-    set(CMAKE_MACOSX_RPATH ON)
-    #    set(CMAKE_INSTALL_RPATH_USE_LINK_PATH ON)
-    #    set(CMAKE_INSTALL_RPATH @loader_path)
-    #    set(CMAKE_INSTALL_NAME_DIR @rpath)
-endif ()
+include(CMakeDependentOption)
 
 option(ROUGHPY_BUILD_LA_CONTEXTS "Build the collection of libalgebra contexts" OFF)
 option(ROUGHPY_BUILD_TESTS "Build C++ tests for RoughPy" ON)
 option(ROUGHPY_BUILD_PYMODULE_INPLACE "Buildg the pymodule in the project roughpy directory" OFF)
+option(ROUGHPY_LINK_NUMPY "Link with Numpy library for array handling" ON)
+option(ROUGHPY_GENERATE_DEVICE_CODE "Generate code for objects on devices" OFF)
+cmake_dependent_option(ROUGHPY_PREFER_ACCELERATE
+        "Prefer Accelerate framework on MacOS always" OFF APPLE OFF)
 
-if (MSVC)
-    #    add_compile_options(/permissive-)
-endif ()
-
-find_package(GTest CONFIG QUIET)
-if (ROUGHPY_BUILD_TESTS AND GTest_FOUND)
+# If testing is enabled, find GTest to make sure the tests can be
+# successfully built.
+if (ROUGHPY_BUILD_TESTS)
     find_package(GTest CONFIG REQUIRED)
 
     if (NOT TARGET GTest::gtest)
         message(FATAL_ERROR "GTest::gtest target not defined")
     endif ()
 
     enable_testing()
-else ()
-    set(ROUGHPY_BUILD_TESTS OFF CACHE INTERNAL "")
-endif ()
-
-include(cmake/roughpy_helpers.cmake)
 
+    # If we are building roughpy tests and gtest is available then we also
+    # to build the libalgebra_lite tests.
+    set(LIBALGEBRA_LITE_BUILD_TESTS ON CACHE INTERNAL "")
+endif ()
 
-option(ROUGHPY_LINK_NUMPY "Link with Numpy library for array handling" ON)
-option(ROUGHPY_GENERATE_DEVICE_CODE "Generate code for objects on devices" OFF)
+# If we're building with SKBUILD, we need to define install locations for
+# all the components using their special directory variables. Otherwise,
+# use the GNUInstall dirs
+if (SKBUILD)
+
+    # This is all the variables set by GNUInstallDirs, minus LIBDIR and BINDIR
+    set(_ignore_dirs
+            SBINDIR
+            LIBEXECDIR
+            SYSCONFIGDIR
+            SHAREDSTATEDIR
+            LOCALSTATEDIR
+            RUNSTATEDIR
+            INCLUDEDIR
+            OLDINCLUDEDIR
+            DATAROOTDIR
+            DATADIR
+            INFODIR
+            LOCALEDIR
+            MANDIR
+            DOCDIR
+            )
 
+    if (WIN32)
+        # On Windows, DLLs are put in BINDIR
+        list(APPEND _ignore_dirs LIBDIR)
+        set(CMAKE_INSTALL_BINDIR ${SKBUILD_PLATLIB_DIR}/roughpy CACHE STRING
+                "Overwritten install for BINDIR")
+    else()
+        # On not Windows, Shared Objects go in LIBDIR
+        list(APPEND _ignore_dirs BINDIR)
+        set(CMAKE_INSTALL_LIBDIR ${SKBUILD_PLATLIB_DIR}/roughpy CACHE STRING
+                "Overwritten install for LIBDIR")
+
+        list(APPEND _ignore_dirs BINDIR)
+    endif()
+
+    foreach(_dir ${_ignore_dirs})
+        set(CMAKE_INSTALL_${_dir} ${SKBUILD_NULL_DIR} CACHE STRING
+                "Overwritten install for ${_dir}")
+    endforeach()
+
+else()
+    include(GNUInstallDirs)
+endif()
+
+
+# Load the helper functions
+include(cmake/roughpy_helpers.cmake)
 
+# We need to provide some help to make sure we find the correct version of
+# Python. Ideally, if we're using Scikit-Build-Core to build the library (via
+# pip) and the Python executable is provided via the PYTHON_EXECUTABLE cache
+# variable. In this case, make sure that this is the version of Python that gets
+# found.
 set(PYBIND11_FINDPYTHON ON)
 if (NOT PYTHON_FOUND AND SKBUILD)
     cmake_path(GET PYTHON_EXECUTABLE PARENT_PATH _sk_env_dir)
@@ -85,44 +110,31 @@ if (NOT PYTHON_FOUND AND SKBUILD)
     # clean up temporary
     unset(_sk_env_dir)
 else ()
+    # If we're not using Scikit-Build-Core (i.e. a pure CMake build) then try
+    # looking for a Python virtual environment first.
     set(Python_FIND_VIRTUALENV FIRST)
-endif ()
 
-if (ROUGHPY_LINK_NUMPY)
-    find_package(Python 3.8 REQUIRED COMPONENTS Interpreter Development.Module NumPy)
-else ()
-    find_package(Python 3.8 REQUIRED COMPONENTS Interpreter Development.Module)
+    # In particular, if ENV{VIRTUAL_ENV} is set then add this to the cmake
+    # prefix path so FindPython is more likely to find this environemnt.
+    if (DEFINED ENV{VIRTUAL_ENV})
+        # Put venv/lib on the prefix path so we can find
+        # a pip installed MKL
+        message(STATUS "Adding python virtual environment to path")
+        list(PREPEND CMAKE_PREFIX_PATH "$ENV{VIRTUAL_ENV}")
+    endif ()
 endif ()
 
-if (DEFINED ENV{VIRTUAL_ENV})
-    # Put venv/lib on the prefix path so we can find
-    # a pip installed MKL
-    message(STATUS "Adding python virtual environment to path")
-    list(PREPEND CMAKE_PREFIX_PATH "$ENV{VIRTUAL_ENV}/lib")
-endif ()
 
-# Before we get too far, let's make use of Python's import
-# system to make sure MKL can be found if it was pip installed
-execute_process(COMMAND ${Python_EXECUTABLE}
-        "${CMAKE_CURRENT_LIST_DIR}/tools/python-get-binary-obj-path.py"
-        "--directory" "mkl-devel" "cmake/mkl/MKLConfig.cmake"
-        RESULT_VARIABLE _python_mkl_dir_found
-        OUTPUT_VARIABLE _python_mkl_dir
-        OUTPUT_STRIP_TRAILING_WHITESPACE
-        ERROR_QUIET
-        )
+# At minimum we need Interpreter and Development.Module in order to build a
+# Python extension module.
+set(PYTHON_COMPONENTS_NEEDED Interpreter Development.Module)
+if (ROUGHPY_LINK_NUMPY)
+    list(APPEND PYTHON_COMPONENTS_NEEDED NumPy)
+endif ()
 
-if (NOT _python_mkl_dir_found AND EXISTS "${_python_mkl_dir}")
-    cmake_path(GET _python_mkl_dir PARENT_PATH _python_mkl_dir)
-    message(STATUS "Adding MKL dir from pip-installed mkl: ${_python_mkl_dir}")
-    list(APPEND CMAKE_PREFIX_PATH "${_python_mkl_dir}")
-    if (NOT MKL_ROOT)
-        set(MKL_ROOT "${_python_mkl_dir}")
-    endif ()
-    set(MKL_DIR "${_python_mkl_dir}")
+find_package(Python 3.8 REQUIRED COMPONENTS ${PYTHON_COMPONENTS_NEEDED})
 
 
-endif ()
 
 if (NOT DEFINED pybind11_ROOT)
     execute_process(COMMAND
@@ -153,7 +165,35 @@ find_package(SndFile CONFIG REQUIRED)
 find_package(tomlplusplus CONFIG REQUIRED)
 
 message(STATUS "Target architecture ${RPY_ARCH}")
-if (RPY_ARCH MATCHES "[xX](86(_64)?|64)|[aA][mM][dD]64")
+if (RPY_ARCH MATCHES "[xX](86(_64)?|64)|[aA][mM][dD]64" AND NOT
+        ROUGHPY_PREFER_ACCELERATE)
+
+    # If we're looking for MKL then we might have installed it via pip.
+    # To make sure we can find this, let's use Python's importlib metadata to
+    # locate the directory containing MKLConfig.cmake and add the relevant
+    # directory to the prefix path.
+    execute_process(COMMAND ${Python_EXECUTABLE}
+            "${CMAKE_CURRENT_LIST_DIR}/tools/python-get-binary-obj-path.py"
+            "--directory" "mkl-devel" "cmake/mkl/MKLConfig.cmake"
+            RESULT_VARIABLE _python_mkl_dir_found
+            OUTPUT_VARIABLE _python_mkl_dir
+            OUTPUT_STRIP_TRAILING_WHITESPACE
+            ERROR_QUIET
+            )
+    if (NOT _python_mkl_dir_found AND EXISTS "${_python_mkl_dir}")
+        cmake_path(GET _python_mkl_dir PARENT_PATH _python_mkl_dir)
+        message(STATUS "Adding MKL dir from pip-installed mkl: ${_python_mkl_dir}")
+        list(APPEND CMAKE_PREFIX_PATH "${_python_mkl_dir}")
+        if (NOT MKL_ROOT)
+            set(MKL_ROOT "${_python_mkl_dir}")
+        endif ()
+        set(MKL_DIR "${_python_mkl_dir}")
+    endif ()
+
+    # Set the variables that determine the actual MKL library that we need to
+    # link. At the moment, we force 32-bit addressing on both 32- and 64-bit
+    # platforms, statically linked, and using the Intel OMP library (except on
+    # Windows).
     if (RPY_ARCH STREQUAL "x86")
         set(MKL_ARCH ia32)
     else ()
@@ -175,18 +215,13 @@ if (RPY_ARCH MATCHES "[xX](86(_64)?|64)|[aA][mM][dD]64")
         add_library(BLAS::BLAS ALIAS MKL::MKL)
         add_library(LAPACK::LAPACK ALIAS MKL::MKL)
 
-        #        if (DEFINED MKL_OMP_LIB AND MKL_OMP_LIB)
-        #            foreach (LANG IN ITEMS C CXX)
-        #                set(OpenMP_${LANG}_LIB_NAMES ${MKL_OMP_LIB} CACHE STRING "Intel OpenMP runtime library")
-        #            endforeach ()
-        #        endif ()
         if (DEFINED MKL_OMP_LIB AND MKL_OMP_LIB)
-            foreach (LANG IN ITEMS C CXX)
-                if (APPLE)
+            if (APPLE)
+                foreach (LANG IN ITEMS C CXX)
                     set(OpenMP_${LANG}_FLAGS "-XPreprocessor -fopenmp=${MKL_OMP_LIB}")
                     set(OpenMP_${LANG}_LIB_NAMES "${MKL_OMP_LIB}" CACHE STRING "libomp location for OpenMP")
-                endif ()
-            endforeach ()
+                endforeach ()
+            endif ()
             set(OpenMP_${MKL_OMP_LIB}_LIBRARY "${MKL_THREAD_LIB}")
         endif ()
     else ()
@@ -206,47 +241,33 @@ if (NOT TARGET LAPACK::LAPACK)
     find_package(LAPACK REQUIRED)
 endif ()
 
+if (APPLE AND NOT DEFINED MKL_OMP_LIB)
+    get_brew_prefix(_libomp_prefix libomp VERBOSE)
+
+    if (_libomp_prefix AND EXISTS ${_libomp_prefix})
+        list(APPEND CMAKE_PREFIX_PATH ${_libomp_prefix})
+    endif()
+endif()
+
 find_package(OpenMP REQUIRED COMPONENTS CXX)
 
 find_package(pybind11 REQUIRED)
 find_package(cereal REQUIRED)
 find_package(PCGRandom REQUIRED)
 
+# Now we get to adding our components. Let's do some global setup such as
+# setting the CXX standard and the shared library details.
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
-add_subdirectory(external/libalgebra_lite)
-#set_target_properties(Libalgebra_lite PROPERTIES NO_SONAME ON)
-
-#add_subdirectory(external/pybind11)
-
-
-# Make an imported target for PCG-CPP because it is a
-# makefile based project
-#if(NOT TARGET PCGRandom::pcg_random)
-#    add_library(PCGRandom::pcg_random IMPORTED INTERFACE)
-#    target_include_directories(PCGRandom::pcg_random INTERFACE
-#            external/pcg-cpp/include)
-#endif()
-
-
-#add_subdirectory(external/recombine)
-
-set(LIBALGEBRA_NO_SERIALIZATION ON CACHE INTERNAL "")
-add_subdirectory(external/libalgebra)
+if (LINUX)
+    set(CMAKE_INSTALL_RPATH "$ORIGIN")
+elseif (APPLE)
+    set(CMAKE_MACOSX_RPATH ON)
+endif ()
 
-#add_subdirectory(external/csv-parser)
-# The csv-parser CMakeLists.txt leaves much to be desired
-# Let's fix some of the problems now
-#if(NOT TARGET csv::csv)
-#    add_library(csv::csv ALIAS csv)
-#    target_include_directories(csv INTERFACE
-#            external/csv-parser/include)
-#    set_target_properties(csv PROPERTIES POSITION_INDEPENDENT_CODE ON)
-#endif()
+add_subdirectory(external/libalgebra_lite)
 
-#set(BUILD_DOC OFF CACHE INTERNAL "disable cereal docs")
-#set(BUILD_SANDBOX OFF CACHE INTERNAL "disable cereal sandbox examples")
-#set(SKIP_PERFORMANCE_COMPARISON ON CACHE INTERNAL "disable building cereal performance tests")
-#add_subdirectory(external/cereal)
 
 add_subdirectory(core)
 add_subdirectory(platform)
@@ -261,10 +282,17 @@ if (ROUGHPY_GENERATE_DEVICE_CODE)
 endif ()
 
 if (ROUGHPY_BUILD_LA_CONTEXTS)
+    set(LIBALGEBRA_NO_SERIALIZATION ON CACHE INTERNAL "")
+    add_subdirectory(external/libalgebra)
     add_subdirectory(la_context)
 endif ()
 
 
+# TODO: Maybe we should replace this with a custom install target rather than
+# messing with the install directories.
+#set(CMAKE_INSTALL_LIBDIR "roughpy" CACHE STRING "install library dir")
+#set(CMAKE_INSTALL_BINDIR "roughpy" CACHE STRING "install binary dir")
+
 install(TARGETS
         RoughPy_PyModule
         EXPORT RoughPy_EXPORTS
@@ -297,17 +325,3 @@ foreach (_rpy_lib IN LISTS ROUGHPY_LIBS)
     endif ()
 endforeach ()
 install(FILES ${_runtime_deps} DESTINATION roughpy)
-
-#
-#install(EXPORT RoughPy_EXPORTS
-#        DESTINATION roughpy
-#        NAMESPACE RoughPy
-#        FILE RoughPy.cmake
-#            COMPONENT Development
-#            EXCLUDE_FROM_ALL
-#        )
-#
-#
-#if (TARGET MKL::MKL AND DEFINED MKL_THREAD_LIB)
-#    install(FILES ${MKL_THREAD_LIB} DESTINATION roughpy)
-#endif ()