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,15 +240,26 @@ 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
+        wget https://julialang-s3.julialang.org/bin/linux/x64/1.6/julia-1.6.7-linux-x86_64.tar.gz
+        sudo tar -xz -C /usr/local -f julia-1.6.7-linux-x86_64.tar.gz
+        rm julia-1.6.7-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.6.7/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
         ctest --test-dir build --output-on-failure

.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: 10.15}
       # 10.14+ due to std::visit
@@ -35,10 +41,11 @@ 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
         ctest --test-dir build --verbose

.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,20 @@ 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)
+    set(CMAKE_INSTALL_RPATH "${CMAKE_INSTALL_PREFIX}/lib;${JlCxx_location}")
+    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)
@@ -593,6 +612,37 @@ 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)
+endif()
+
 # python bindings
 if(openPMD_HAVE_PYTHON)
     add_library(openPMD.py MODULE
@@ -1053,6 +1103,10 @@ 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)

NEWS.rst

@@ -13,6 +13,9 @@ 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.
+
 
 0.15.0
 ------

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.10.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

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

src/binding/julia/Access.cpp

@@ -0,0 +1,13 @@
+// IO/Access
+
+#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,24 @@
+// Attributable
+
+#include "defs.hpp"
+
+void define_julia_Attributable(jlcxx::Module &mod)
+{
+    auto type = mod.add_type<Attributable>("CXX_Attributable");
+
+#define USE_TYPE(NAME, ENUM, TYPE)                                             \
+    type.method(                                                               \
+        "cxx_set_attribute_" NAME "!", &Attributable::setAttribute<TYPE>);
+    {FORALL_OPENPMD_TYPES(USE_TYPE)}
+#undef USE_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,17 @@
+// Attribute
+
+#include "defs.hpp"
+
+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; });
+
+#define USE_TYPE(NAME, ENUM, TYPE)                                             \
+    type.method("cxx_get_" NAME, &Attribute::get<TYPE>);
+    {
+        FORALL_OPENPMD_TYPES(USE_TYPE)
+    }
+#undef USE_TYPE
+}

src/binding/julia/BaseRecordComponent.cpp

@@ -0,0 +1,25 @@
+// BaseRecordComponent
+
+#include "defs.hpp"
+
+// Define supertype relationships
+namespace jlcxx
+{
+template <>
+struct SuperType<BaseRecordComponent>
+{
+    typedef Attributable type;
+};
+} // 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);
+}

src/binding/julia/ChunkInfo.cpp

@@ -0,0 +1,31 @@
+// ChunkInfo
+
+#include "defs.hpp"
+
+// Define supertype relationships
+namespace jlcxx
+{
+template <>
+struct SuperType<WrittenChunkInfo>
+{
+    typedef ChunkInfo type;
+};
+} // namespace jlcxx
+
+void define_julia_ChunkInfo(jlcxx::Module &mod)
+{
+    auto chunkInfo = mod.add_type<ChunkInfo>("CXX_ChunkInfo");
+    chunkInfo.constructor<>();
+    chunkInfo.constructor<Offset, Extent>();
+    chunkInfo.method("cxx_offset", [](const ChunkInfo &chunkInfo_) {
+        return chunkInfo_.offset;
+    });
+    chunkInfo.method("cxx_extent", [](const ChunkInfo &chunkInfo_) {
+        return chunkInfo_.extent;
+    });
+
+    auto writtenChunkInfo = mod.add_type<WrittenChunkInfo>(
+        "CXX_WrittenChunkInfo", jlcxx::julia_base_type<ChunkInfo>());
+    writtenChunkInfo.constructor<>();
+    writtenChunkInfo.constructor<Offset, Extent>();
+}

src/binding/julia/Container.cpp

@@ -0,0 +1,3 @@
+#include "Container.hpp"
+
+std::unique_ptr<julia_Container_type_t> julia_Container_type;