Julia bindings

.github/workflows/linux.yml

@@ -231,7 +231,7 @@ jobs:
         cmake --build build --parallel 2
         ctest --test-dir build --output-on-failure
 
-  gcc9_py38_pd_nompi_h5_ad2_libcpp:
+  gcc9_py38_pd_nompi_h5_ad2_libcpp_julia:
     runs-on: ubuntu-20.04
     if: github.event.pull_request.draft == false
     steps:
@@ -240,17 +240,31 @@ jobs:
       run: |
         sudo apt-get update
         sudo apt-get install g++ libopenmpi-dev libhdf5-openmpi-dev python3 python3-numpy python3-mpi4py python3-pandas
-#       TODO ADIOS2
+        # TODO ADIOS2
+        # Install Julia
+        # 1.6.7
+        wget https://julialang-s3.julialang.org/bin/linux/x64/1.7/julia-1.7.3-linux-x86_64.tar.gz
+        sudo tar -xz -C /usr/local -f julia-1.7.3-linux-x86_64.tar.gz
+        rm julia-1.7.3-linux-x86_64.tar.gz
+        # Install cmake-easyinstall
+        sudo curl -L -o /usr/local/bin/cmake-easyinstall https://git.io/JvLxY
+        sudo chmod a+x /usr/local/bin/cmake-easyinstall
+        export CEI_SUDO="sudo"
+        # Install libcxxwrap-julia
+        cmake-easyinstall git+https://github.com/JuliaInterop/[email protected] -DJulia_EXECUTABLE=/usr/local/julia-1.7.3/bin/julia
     - name: Build
       env: {CXXFLAGS: -Werror, PKG_CONFIG_PATH: /usr/lib/x86_64-linux-gnu/pkgconfig}
       run: |
         share/openPMD/download_samples.sh build
-        cmake -S . -B build \
-          -DopenPMD_USE_PYTHON=ON \
-          -DopenPMD_USE_MPI=ON    \
+        cmake -S . -B build       \
           -DopenPMD_USE_HDF5=ON   \
+          -DopenPMD_USE_JULIA=ON  \
+          -DopenPMD_USE_MPI=ON    \
+          -DopenPMD_USE_PYTHON=ON \
           -DopenPMD_USE_INVASIVE_TESTS=ON
         cmake --build build --parallel 2
+        # Install the Julia side of CxxWrap
+        julia --eval 'using Pkg; Pkg.add("CxxWrap")'
         ctest --test-dir build --output-on-failure
 
   musllinux_py10:

.github/workflows/macos.yml

@@ -24,9 +24,15 @@ jobs:
         brew update
         brew install adios2 || true
         brew install hdf5-mpi || true
+        brew install julia || true
         brew install python || true
         python3 -m pip install -U mpi4py numpy pandas
         set -e
+        # Install cmake-easyinstall
+        sudo curl -L -o /usr/local/bin/cmake-easyinstall https://git.io/JvLxY
+        sudo chmod a+x /usr/local/bin/cmake-easyinstall
+        # Install libcxxwrap-julia
+        cmake-easyinstall git+https://github.com/JuliaInterop/[email protected]
     - name: Build
       env: {CXXFLAGS: -Werror, MACOSX_DEPLOYMENT_TARGET: 11.0}
       # 10.14+ due to std::visit
@@ -36,12 +42,15 @@ jobs:
       run: |
         share/openPMD/download_samples.sh build
         cmake -S . -B build \
-          -DopenPMD_USE_PYTHON=ON \
-          -DopenPMD_USE_MPI=ON    \
-          -DopenPMD_USE_HDF5=ON   \
           -DopenPMD_USE_ADIOS2=ON \
+          -DopenPMD_USE_HDF5=ON   \
+          -DopenPMD_USE_JULIA=ON  \
+          -DopenPMD_USE_MPI=ON    \
+          -DopenPMD_USE_PYTHON=ON \
           -DopenPMD_USE_INVASIVE_TESTS=ON
         cmake --build build --parallel 3
+        # Install the Julia side of CxxWrap
+        julia --eval 'using Pkg; Pkg.add("CxxWrap")'
         ctest --test-dir build --verbose
 
   appleclang13_py:

.readthedocs.yml

@@ -14,4 +14,5 @@ build:
   tools:
     python: "3.11"
   apt_packages:
+    - graphviz
     - librsvg2-bin

CMakeLists.txt

@@ -2,6 +2,10 @@
 #
 cmake_minimum_required(VERSION 3.15.0)
 
+# macOS 10.15 is required for certain C++17 features.
+# (This variable needs to be set before calling `project`.)
+set(CMAKE_OSX_DEPLOYMENT_TARGET "10.15" CACHE STRING "Minimum OS X deployment version")
+
 project(openPMD VERSION 0.16.0) # LANGUAGES CXX
 
 # the openPMD "markup"/"schema" standard version
@@ -143,6 +147,7 @@ endfunction()
 openpmd_option(MPI            "Parallel, Multi-Node I/O for clusters"     AUTO)
 openpmd_option(HDF5           "HDF5 backend (.h5 files)"                  AUTO)
 openpmd_option(ADIOS2         "ADIOS2 backend (.bp files)"                AUTO)
+openpmd_option(JULIA          "Enable Julia bindings"                     OFF)
 openpmd_option(PYTHON         "Enable Python bindings"                    AUTO)
 
 option(openPMD_INSTALL               "Add installation targets"             ON)
@@ -388,6 +393,19 @@ endif()
 
 # TODO: Check if ADIOS2 is parallel when openPMD_HAVE_MPI is ON
 
+# External library: libcxxwrap-julia
+if(openPMD_USE_JULIA)
+    find_package(JlCxx 0.8.3 REQUIRED)
+    set(openPMD_HAVE_JULIA TRUE)
+else()
+    set(openPMD_HAVE_JULIA FALSE)
+endif()
+if(openPMD_HAVE_JULIA)
+    get_target_property(JlCxx_location JlCxx::cxxwrap_julia LOCATION)
+    get_filename_component(JlCxx_location ${JlCxx_location} DIRECTORY)
+    message(STATUS "Found JlCxx version ${JlCxx_VERSION} at ${JlCxx_location}")
+endif()
+
 # external library: pybind11 (optional)
 set(_PY_DEV_MODULE Development.Module)
 if(CMAKE_VERSION VERSION_LESS 3.18.0)
@@ -592,6 +610,57 @@ else()
     target_compile_definitions(openPMD PRIVATE openPMD_USE_VERIFY=0)
 endif()
 
+# Julia bindings
+if(openPMD_HAVE_JULIA)
+    add_library(openPMD.jl SHARED
+        src/binding/julia/Access.cpp
+        src/binding/julia/Attributable.cpp
+        src/binding/julia/Attribute.cpp
+        src/binding/julia/BaseRecordComponent.cpp
+        src/binding/julia/ChunkInfo.cpp
+        src/binding/julia/Container.cpp
+        src/binding/julia/Dataset.cpp
+        src/binding/julia/Datatype.cpp
+        src/binding/julia/Format.cpp
+        src/binding/julia/Iteration.cpp
+        src/binding/julia/Mesh.cpp
+        src/binding/julia/MeshRecordComponent.cpp
+        src/binding/julia/ReadIterations.cpp
+        src/binding/julia/RecordComponent.cpp
+        src/binding/julia/RecordComponent_load_chunk.cpp
+        src/binding/julia/RecordComponent_make_constant.cpp
+        src/binding/julia/RecordComponent_store_chunk.cpp
+        src/binding/julia/Series.cpp
+        src/binding/julia/UnitDimension.cpp
+        src/binding/julia/WriteIterations.cpp
+        src/binding/julia/openPMD.cpp
+        src/binding/julia/shared_ptr.cpp
+        src/binding/julia/version.cpp
+    )
+    openpmd_cxx_required(openPMD.jl)
+    target_link_libraries(openPMD.jl PRIVATE openPMD JlCxx::cxxwrap_julia JlCxx::cxxwrap_julia_stl)
+
+    set_target_properties(openPMD.jl PROPERTIES
+        COMPILE_PDB_NAME openPMD.jl
+        ARCHIVE_OUTPUT_DIRECTORY ${openPMD_ARCHIVE_OUTPUT_DIRECTORY}
+        LIBRARY_OUTPUT_DIRECTORY ${openPMD_LIBRARY_OUTPUT_DIRECTORY}
+        RUNTIME_OUTPUT_DIRECTORY ${openPMD_RUNTIME_OUTPUT_DIRECTORY}
+        PDB_OUTPUT_DIRECTORY ${openPMD_PDB_OUTPUT_DIRECTORY}
+        COMPILE_PDB_OUTPUT_DIRECTORY ${openPMD_COMPILE_PDB_OUTPUT_DIRECTORY}
+
+        POSITION_INDEPENDENT_CODE ON
+        WINDOWS_EXPORT_ALL_SYMBOLS ON
+    )
+
+    add_test(NAME CLI.julia_lowlevel
+        COMMAND julia
+            ${openPMD_SOURCE_DIR}/test/julia/lowlevel_test.jl
+            ${openPMD_LIBRARY_OUTPUT_DIRECTORY}/libopenPMD.jl.so
+        WORKING_DIRECTORY
+            ${openPMD_RUNTIME_OUTPUT_DIRECTORY}
+    )
+endif()
+
 # python bindings
 if(openPMD_HAVE_PYTHON)
     add_library(openPMD.py MODULE
@@ -1054,11 +1123,18 @@ if(openPMD_INSTALL)
         endforeach()
     endif()
 
+    if(openPMD_HAVE_JULIA)
+        list(APPEND openPMD_INSTALL_TARGET_NAMES openPMD.jl)
+    endif()
+
     if(openPMD_INSTALL_RPATH)
         set(openPMD_INSTALL_RPATH_TARGET_NAMES ${openPMD_INSTALL_TARGET_NAMES})
         if(openPMD_HAVE_PYTHON)
             list(APPEND openPMD_INSTALL_RPATH_TARGET_NAMES openPMD.py)
         endif()
+        if(openPMD_HAVE_JULIA)
+            list(APPEND openPMD_INSTALL_RPATH_TARGET_NAMES openPMD.jl)
+        endif()
         if(NOT DEFINED CMAKE_INSTALL_RPATH)
             if(APPLE)
                 set_target_properties(${openPMD_INSTALL_RPATH_TARGET_NAMES} PROPERTIES

NEWS.rst

@@ -13,6 +13,8 @@ Please transition to ADIOS2.
 For reading legacy ADIOS1 BP3 files, either use an older version of openPMD-api or the BP3 backend in ADIOS2.
 Note that ADIOS2 does not support compression in BP3 files.
 
+Julia 1.7 to 1.9 are supported. The development version of Julia
+(future 1.10) is supported as well. Julia 1.6 is too old.
 pybind11 2.11.1 is now the minimally supported version for Python support.
 
 

README.md

@@ -114,6 +114,12 @@ while those can be built either with or without:
 * MPI 2.1+, e.g. OpenMPI 1.6.5+ or MPICH2
 
 Optional language bindings:
+* Julia:
+  * Most Julia users will not build `openPMD_api` from source. The
+    Julia package `openPMD.jl` will automatically download a suitable
+    `openPMD_api` binary.
+  * Julia 1.7 - 1.10
+  * [libcxxwrap_julia](https://github.com/JuliaInterop/libcxxwrap-julia) 0.8.3 - 0.9.7
 * Python:
   * Python 3.7 - 3.11
   * pybind11 2.11.1+

docs/Doxyfile

@@ -36,3 +36,4 @@ PREDEFINED        = DOXYGEN_SHOULD_SKIP_THIS \
 WARN_IF_UNDOCUMENTED = NO
 WARN_NO_PARAMDOC = NO
 # the ideal CI enforcing world: WARN_AS_ERROR = YES
+WARN_AS_ERROR = YES

docs/source/install/install.rst

@@ -123,6 +123,18 @@ Additional CMake options can be passed via individual environment variables, whi
 
    .. image:: cmake.svg
 
+Using the Julia Package
+-----------------------
+
+A package for openPMD-api is available via the Julia Package Registry:
+
+.. code-block:: julia
+
+    # We need Julia 1.7 or newer
+    using("Pkg")
+    Pkg.add("openPMD")
+
+
 From Source with CMake
 ----------------------
 
@@ -147,7 +159,7 @@ Linux & OSX
    #   -DCMAKE_INSTALL_PREFIX=$HOME/somepath
    # for options append:
    #   -DopenPMD_USE_...=...
-   # e.g. for python support add:
+   # e.g. for Python support add:
    #   -DopenPMD_USE_PYTHON=ON -DPython_EXECUTABLE=$(which python3)
    cmake ../openPMD-api
 

include/openPMD/Series.hpp

@@ -55,7 +55,6 @@ namespace openPMD
 class ReadIterations;
 class SeriesIterator;
 class Series;
-class Series;
 
 namespace internal
 {

src/binding/julia/Access.cpp

@@ -0,0 +1,17 @@
+/* Bindings for IO/Access
+ *
+ * File authors: Erik Schnetter
+ * License: LGPL-3.0-or-later
+ */
+
+#include "defs.hpp"
+
+void define_julia_Access(jlcxx::Module &mod)
+{
+    mod.add_bits<Access>("Access", jlcxx::julia_type("CppEnum"));
+    jlcxx::stl::apply_stl<Access>(mod);
+
+    mod.set_const("ACCESS_READ_ONLY", Access::READ_ONLY);
+    mod.set_const("ACCESS_READ_WRITE", Access::READ_WRITE);
+    mod.set_const("ACCESS_CREATE", Access::CREATE);
+}

src/binding/julia/Attributable.cpp

@@ -0,0 +1,39 @@
+/* Bindings for Attributable
+ *
+ * File authors: Erik Schnetter
+ * License: LGPL-3.0-or-later
+ */
+
+#include "defs.hpp"
+
+namespace
+{
+struct UseType
+{
+    template <typename T>
+    static void call(jlcxx::TypeWrapper<Attributable> type)
+    {
+        type.method(
+            "cxx_set_attribute_" + datatypeToString(determineDatatype<T>()) +
+                "!",
+            &Attributable::setAttribute<T>);
+    }
+};
+} // namespace
+
+void define_julia_Attributable(jlcxx::Module &mod)
+{
+    auto type = mod.add_type<Attributable>("CXX_Attributable");
+
+    forallJuliaTypes<UseType>(type);
+
+    type.method("cxx_get_attribute", &Attributable::getAttribute);
+    type.method("cxx_delete_attribute!", &Attributable::deleteAttribute);
+    type.method("cxx_attributes", &Attributable::attributes);
+    type.method("cxx_num_attributes", &Attributable::numAttributes);
+    type.method("cxx_contains_attribute", &Attributable::containsAttribute);
+    type.method("cxx_comment", &Attributable::comment);
+    type.method("cxx_set_comment!", &Attributable::setComment);
+    type.method(
+        "cxx_series_flush", [](Attributable &attr) { attr.seriesFlush(); });
+}

src/binding/julia/Attribute.cpp

@@ -0,0 +1,30 @@
+/* Bindings for Attribute
+ *
+ * File authors: Erik Schnetter
+ * License: LGPL-3.0-or-later
+ */
+
+#include "defs.hpp"
+
+namespace
+{
+struct UseType
+{
+    template <typename T>
+    static void call(jlcxx::TypeWrapper<Attribute> type)
+    {
+        type.method(
+            "cxx_get_" + datatypeToString(determineDatatype<T>()),
+            &Attribute::get<T>);
+    }
+};
+} // namespace
+
+void define_julia_Attribute(jlcxx::Module &mod)
+{
+    auto type = mod.add_type<Attribute>("CXX_Attribute");
+
+    type.method("cxx_dtype", [](const Attribute &attr) { return attr.dtype; });
+
+    forallJuliaTypes<UseType>(type);
+}

src/binding/julia/BaseRecordComponent.cpp

@@ -0,0 +1,29 @@
+/* Bindings for BaseRecordComponent
+ *
+ * File authors: Erik Schnetter
+ * License: LGPL-3.0-or-later
+ */
+
+#include "defs.hpp"
+
+// Define supertype relationships
+namespace jlcxx
+{
+template <>
+struct SuperType<BaseRecordComponent>
+{
+    using type = Attributable;
+};
+} // namespace jlcxx
+
+void define_julia_BaseRecordComponent(jlcxx::Module &mod)
+{
+    auto type = mod.add_type<BaseRecordComponent>(
+        "CXX_BaseRecordComponent", jlcxx::julia_base_type<Attributable>());
+
+    type.method("cxx_unit_SI", &BaseRecordComponent::unitSI);
+    type.method("cxx_reset_datatype!", &BaseRecordComponent::resetDatatype);
+    type.method("cxx_get_datatype", &BaseRecordComponent::getDatatype);
+    type.method("cxx_isconstant", &BaseRecordComponent::constant);
+    type.method("cxx_available_chunks", &BaseRecordComponent::availableChunks);
+}