Improve MATLAB bindings (SSMC pipeline, type minimization, allocator safety, tests)

.gitignore

@@ -4,7 +4,6 @@
 
 scripts
 venv
-build/
 build-*/
 compile_flags.txt
 ._*

CMakeLists.txt

@@ -9,13 +9,18 @@ cmake_policy(SET CMP0079 NEW)
 
 set(CMAKE_C_STANDARD 11)
 set(CMAKE_CXX_STANDARD 20)
-set(CMAKE_C_FLAGS "-O3 -march=native")
+
+# FIXME: -march=native is not portable
+# set(CMAKE_C_FLAGS "-O3 -march=native")
+set(CMAKE_C_FLAGS "-g ")
+set(CMAKE_CXX_FLAGS "-g ")
 
 option(ENABLE_SANITIZERS "Enable Clang sanitizers" OFF)
 
 include(GNUInstallDirs)
 
 add_library(binsparse STATIC)
+add_library(binsparse_dynamic SHARED)
 
 add_subdirectory(include)
 add_subdirectory(src)
@@ -26,6 +31,7 @@ add_subdirectory(src)
 
 find_package(HDF5 REQUIRED COMPONENTS C)
 target_link_libraries(binsparse PUBLIC ${HDF5_C_LIBRARIES})
+target_link_libraries(binsparse_dynamic PUBLIC ${HDF5_C_LIBRARIES})
 
 include(FetchContent)
 
@@ -46,7 +52,8 @@ FetchContent_MakeAvailable(cJSON)
 set(BUILD_SHARED_LIBS ${BUILD_SHARED_LIBS_BACKUP})
 
 configure_file(${cJSON_SOURCE_DIR}/cJSON.h ${CMAKE_BINARY_DIR}/include/cJSON/cJSON.h)
-target_link_libraries(${PROJECT_NAME} PRIVATE cjson)
+target_link_libraries(binsparse PRIVATE cjson)
+target_link_libraries(binsparse_dynamic PRIVATE cjson)
 
 # Set up include directories properly for both build and install
 target_include_directories(${PROJECT_NAME}
@@ -57,13 +64,27 @@ target_include_directories(${PROJECT_NAME}
         $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
         ${HDF5_INCLUDE_DIRS})
 
+target_include_directories(binsparse_dynamic
+    PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/include>
+        $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+        ${HDF5_INCLUDE_DIRS})
+
 # Installation rules - these are always needed when the library is built
 install(TARGETS binsparse
         EXPORT binsparse-targets
         LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
         ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
         RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
         INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+install(TARGETS binsparse_dynamic
+        EXPORT binsparse-targets_dynamic
+        LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+        ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+        RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+        INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
 
 # Install headers
 install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/binsparse
@@ -76,6 +97,10 @@ install(EXPORT binsparse-targets
         FILE binsparse-targets.cmake
         NAMESPACE binsparse::
         DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/binsparse)
+install(EXPORT binsparse-targets_dynamic
+        FILE binsparse-targets_dynamic.cmake
+        NAMESPACE binsparse::
+        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/binsparse)
 
 # Create and install package config files
 include(CMakePackageConfigHelpers)
@@ -99,6 +124,8 @@ if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
       set(SANITIZER_FLAGS "-fsanitize=address,undefined")
       target_compile_options(binsparse INTERFACE ${SANITIZER_FLAGS} -g -O1 -fno-omit-frame-pointer)
       target_link_options(binsparse INTERFACE ${SANITIZER_FLAGS})
+      target_compile_options(binsparse_dynamic INTERFACE ${SANITIZER_FLAGS} -g -O1 -fno-omit-frame-pointer)
+      target_link_options(binsparse_dynamic INTERFACE ${SANITIZER_FLAGS})
   endif()
 
   add_subdirectory(examples)

Makefile

@@ -0,0 +1,71 @@
+#-------------------------------------------------------------------------------
+# binsparse-reference-c/Makefile
+#-------------------------------------------------------------------------------
+
+# SPDX-FileCopyrightText: 2024 Binsparse Developers
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+#-------------------------------------------------------------------------------
+
+# simple Makefile for binsparse-reference-c, relies on cmake to do the actual
+# build.  Use the CMAKE_OPTIONS argument to this Makefile to pass options to
+# cmake.  For example, to compile with 40 threads, use:
+#
+#       make JOBS=40
+
+JOBS ?= 8
+
+default: library
+
+library:
+	( cd build && cmake $(F) $(CMAKE_OPTIONS) .. && cmake --build . --config Release -j${JOBS} )
+
+# install only in SuiteSparse/lib and SuiteSparse/include
+local:
+	( cd build && cmake $(F) $(CMAKE_OPTIONS) -USUITESPARSE_PKGFILEDIR -DSUITESPARSE_LOCAL_INSTALL=1 .. && cmake --build . --config Release -j${JOBS} )
+
+# install only in /usr/local (default)
+global:
+	( cd build && cmake $(F) $(CMAKE_OPTIONS) -USUITESPARSE_PKGFILEDIR -DSUITESPARSE_LOCAL_INSTALL=0 .. && cmake --build . --config Release -j${JOBS} )
+
+# compile with -g
+debug:
+	( cd build && cmake -DCMAKE_BUILD_TYPE=Debug $(F) $(CMAKE_OPTIONS) .. && cmake --build . --config Debug -j$(JOBS) )
+
+# run the demos
+demos: all
+	FIXME
+
+# just do 'make' in build; do not rerun the cmake script
+remake:
+	( cd build && cmake --build . -j$(JOBS) )
+
+# just run cmake; do not compile
+setup:
+	( cd build && cmake $(F) $(CMAKE_OPTIONS) .. )
+
+# build the static library
+static:
+	( cd build && cmake $(F) $(CMAKE_OPTIONS) -DBUILD_STATIC_LIBS=ON -DBUILD_SHARED_LIBS=OFF .. && cmake --build . --config Release -j$(JOBS) )
+
+# installs to the install location defined by cmake, usually
+# /usr/local/lib and /usr/local/include
+install:
+	( cd build && cmake --install . )
+
+# create the doc
+docs:
+	( cd Doc && $(MAKE) )
+
+# remove any installed libraries and #include files
+uninstall:
+	- xargs rm < build/install_manifest.txt
+
+clean: distclean
+
+purge: distclean
+
+# remove all files not in the distribution
+distclean:
+	- rm -rf build/*

bindings/matlab/Contents.m

@@ -0,0 +1,31 @@
+% SPDX-FileCopyrightText: 2024 Binsparse Developers
+%
+% SPDX-License-Identifier: BSD-3-Clause
+
+% binsparse
+%
+% Files
+%   binsparse_read                             - read a sparse matrix from a binsparse hd5 file
+%   binsparse_write                            - write a matrix to a file in binsparse hd5 format
+%   binsparse_from_ssmc                        - convert SSMC A+Zeros to a Binsparse matrix struct
+%   binsparse_minimize_types                   - minimize value/index types in a Binsparse struct
+%   generate_bsp_from_ssmc                     - write SSMC problem to a Binsparse file
+%
+%   bsp_matrix_create                          - SPDX-FileCopyrightText: 2024 Binsparse Developers
+%   bsp_matrix_info                            - SPDX-FileCopyrightText: 2024 Binsparse Developers
+%
+%   build_matlab_bindings                      - SPDX-FileCopyrightText: 2024 Binsparse Developers
+%   build_octave_bindings                      - SPDX-FileCopyrightText: 2024 Binsparse Developers
+%   compile_binsparse_read                     - SPDX-FileCopyrightText: 2024 Binsparse Developers
+%   compile_binsparse_read_octave              - SPDX-FileCopyrightText: 2024 Binsparse Developers
+%   compile_binsparse_write                    - SPDX-FileCopyrightText: 2024 Binsparse Developers
+%   compile_binsparse_write_octave             - SPDX-FileCopyrightText: 2024 Binsparse Developers
+%   compile_write_binsparse_from_matlab        - SPDX-FileCopyrightText: 2024 Binsparse Developers
+%   compile_write_binsparse_from_matlab_octave - SPDX-FileCopyrightText: 2024 Binsparse Developers
+%   test_binsparse_read                        - SPDX-FileCopyrightText: 2024 Binsparse Developers
+%   test_binsparse_write                       - SPDX-FileCopyrightText: 2024 Binsparse Developers
+%   test_bsp_matrix_struct                     - SPDX-FileCopyrightText: 2024 Binsparse Developers
+%   test_binsparse_from_ssmc                   - SPDX-FileCopyrightText: 2024 Binsparse Developers
+%   test_binsparse_minimize_roundtrip          - SPDX-FileCopyrightText: 2024 Binsparse Developers
+%   test_generate_bsp_from_ssmc                - SPDX-FileCopyrightText: 2024 Binsparse Developers
+%   test_write_binsparse_from_matlab           - SPDX-FileCopyrightText: 2024 Binsparse Developers

bindings/matlab/README.md

@@ -57,6 +57,7 @@ mkoctfile --version
    ```matlab
    test_binsparse_read()
    test_binsparse_write()
+   test_write_binsparse_from_matlab()
    ```
 
 #### Option 2: Octave (from within Octave)
@@ -75,6 +76,7 @@ mkoctfile --version
    ```octave
    test_binsparse_read()
    test_binsparse_write()
+   test_write_binsparse_from_matlab()
    ```
 
 #### Option 3: Octave (from command line)
@@ -93,6 +95,7 @@ mkoctfile --version
    ```bash
    octave --eval "test_binsparse_read()"
    octave --eval "test_binsparse_write()"
+   octave --eval "test_write_binsparse_from_matlab()"
    ```
 
 ## Usage Examples
@@ -143,6 +146,25 @@ binsparse_write('output.bsp.h5', matrix, 'my_group', '{"author": "me"}');
 binsparse_write('output.bsp.h5', matrix, 'my_group', '{"author": "me"}', 6);
 ```
 
+### Writing from SuiteSparse Matrix Collection Format
+
+```matlab
+% Create a SuiteSparse Matrix Collection problem struct
+Problem = struct();
+Problem.name = 'test_matrix';
+Problem.A = sparse([1 2 3], [1 2 3], [1.5 2.5 3.5], 4, 4);
+Problem.title = 'Test Matrix';
+Problem.kind = 'artificial/test';
+
+% Write directly from SuiteSparse format to Binsparse
+write_binsparse_from_matlab(Problem, 'output.bsp.h5');
+
+% Write with optional parameters
+write_binsparse_from_matlab(Problem, 'output.bsp.h5', 'my_group');
+write_binsparse_from_matlab(Problem, 'output.bsp.h5', 'my_group', '{"test": "metadata"}');
+write_binsparse_from_matlab(Problem, 'output.bsp.h5', 'my_group', '{"test": "metadata"}', 6);
+```
+
 ### Error Handling
 
 The MEX functions include proper error handling:
@@ -161,15 +183,19 @@ end
 |------|-------------|
 | `binsparse_read.c` | MEX function for reading Binsparse matrix files |
 | `binsparse_write.c` | MEX function for writing Binsparse matrix files |
+| `write_binsparse_from_matlab.c` | MEX function for writing from SuiteSparse Matrix Collection format |
 | `build_matlab_bindings.m` | Main build script for MATLAB MEX functions |
 | `build_octave_bindings.m` | Main build script for Octave MEX functions |
 | `compile_binsparse_read.m` | Simple compilation script for read function (MATLAB) |
 | `compile_binsparse_write.m` | Simple compilation script for write function (MATLAB) |
+| `compile_write_binsparse_from_matlab.m` | Simple compilation script for SuiteSparse write function (MATLAB) |
 | `compile_binsparse_read_octave.m` | Simple compilation script for read function (Octave) |
 | `compile_binsparse_write_octave.m` | Simple compilation script for write function (Octave) |
+| `compile_write_binsparse_from_matlab_octave.m` | Simple compilation script for SuiteSparse write function (Octave) |
 | `compile_octave.sh` | Shell script for building Octave MEX functions |
 | `test_binsparse_read.m` | Test script for read functionality |
 | `test_binsparse_write.m` | Test script for write functionality |
+| `test_write_binsparse_from_matlab.m` | Test script for SuiteSparse write functionality |
 | `bsp_matrix_create.m` | Utility function for creating matrix structs |
 | `bsp_matrix_info.m` | Utility function for displaying matrix information |
 | `README.md` | This documentation file |