Binsparse fixes for SuiteSparse

CMakeLists.txt

@@ -120,6 +120,8 @@ install(FILES
     DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/binsparse)
 
 if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
+  enable_testing()
+
   if (ENABLE_SANITIZERS)
       set(SANITIZER_FLAGS "-fsanitize=address,undefined")
       target_compile_options(binsparse INTERFACE ${SANITIZER_FLAGS} -g -O1 -fno-omit-frame-pointer)

bindings/matlab/Contents.m

@@ -6,28 +6,26 @@
 %   binsparse_from_ssmc             - convert SSMC A+Zeros to a Binsparse matrix struct
 %   binsparse_minimize_types        - minimize value/index types in a Binsparse struct
 %   binsparse_write_string_dataset  - write an HDF5 UTF-8 string dataset
-%   write_binsparse_from_matlab     - write an SSMC Problem struct (delegates to generate_bsp_from_ssmc)
 %
 % MATLAB helpers:
-%   generate_bsp_from_ssmc          - write an SSMC Problem to a Binsparse file
-%   convert_to_problem_struct       - convert a Binsparse problem to an SSMC Problem
-%   bsp_matrix_create               - create a Binsparse matrix struct
-%   bsp_matrix_info                 - display information about a Binsparse matrix struct
+%   binsparse_write_ssmc_problem    - write an SSMC Problem to a Binsparse file
+%   binsparse_to_ssmc_problem       - convert a Binsparse problem to an SSMC Problem
+%   binsparse_create_struct         - create a Binsparse vector or matrix struct
+%   binsparse_info                  - display information about a Binsparse struct
 %
 % Build scripts:
-%   build_matlab_bindings           - build all MEX functions with MATLAB's mex
-%   build_octave_bindings           - build all MEX functions with Octave's mkoctfile
+%   binsparse_build_matlab_bindings - build all MEX functions with MATLAB's mex
+%   binsparse_build_octave_bindings - build all MEX functions with Octave's mkoctfile
 %   compile_octave.sh               - build the Octave MEX functions from the shell
 %
 % Tests:
 %   test_binsparse_read             - error-handling tests for binsparse_read
 %   test_binsparse_write            - write and round-trip tests for binsparse_write
 %   test_binsparse_from_ssmc        - basic test for binsparse_from_ssmc
 %   test_binsparse_minimize_roundtrip - SSMC conversion + type minimization test
-%   test_bsp_matrix_struct          - tests for the Binsparse matrix struct helpers
-%   test_convert_to_problem_struct  - tests for Binsparse Problem conversion
-%   test_generate_bsp_from_ssmc     - end-to-end test for generate_bsp_from_ssmc
-%   test_write_binsparse_from_matlab - end-to-end test for the SSMC writer MEX
+%   test_binsparse_struct           - tests for the Binsparse struct helpers
+%   test_binsparse_to_ssmc_problem  - tests for Binsparse Problem conversion
+%   test_binsparse_write_ssmc_problem - end-to-end SSMC writer test
 %   test_binsparse_roundtrip_dir    - round-trip every .h5 file in a directory
 
 % SPDX-FileCopyrightText: 2024 Binsparse Developers

bindings/matlab/README.md

@@ -50,14 +50,14 @@ mkoctfile --version
 
 2. Build the MEX functions:
    ```matlab
-   build_matlab_bindings()
+   binsparse_build_matlab_bindings()
    ```
 
 3. Test the installation:
    ```matlab
    test_binsparse_read()
    test_binsparse_write()
-   test_write_binsparse_from_matlab()
+   test_binsparse_write_ssmc_problem()
    ```
 
 #### Option 2: Octave (from within Octave)
@@ -69,14 +69,14 @@ mkoctfile --version
 
 2. Build the MEX functions:
    ```octave
-   build_octave_bindings()
+   binsparse_build_octave_bindings()
    ```
 
 3. Test the installation:
    ```octave
    test_binsparse_read()
    test_binsparse_write()
-   test_write_binsparse_from_matlab()
+   test_binsparse_write_ssmc_problem()
    ```
 
 #### Option 3: Octave (from command line)
@@ -95,7 +95,7 @@ mkoctfile --version
    ```bash
    octave --eval "test_binsparse_read()"
    octave --eval "test_binsparse_write()"
-   octave --eval "test_write_binsparse_from_matlab()"
+   octave --eval "test_binsparse_write_ssmc_problem()"
    ```
 
 ## Usage Examples
@@ -157,13 +157,13 @@ Problem.title = 'Test Matrix';
 Problem.kind = 'artificial/test';
 
 % Write directly from SuiteSparse format to Binsparse
-write_binsparse_from_matlab(Problem, 'output.bsp.h5');
+binsparse_write_ssmc_problem(Problem, 'output.bsp.h5');
 
 % Write with an explicit sparse format ('COO', 'COOR', 'CSC', or 'CSR')
-write_binsparse_from_matlab(Problem, 'output.bsp.h5', 'CSC');
+binsparse_write_ssmc_problem(Problem, 'output.bsp.h5', 'CSC');
 
 % Write with a format and gzip compression level (0-9)
-write_binsparse_from_matlab(Problem, 'output.bsp.h5', 'COO', [], 6);
+binsparse_write_ssmc_problem(Problem, 'output.bsp.h5', 'COO', 6);
 ```
 
 ### Error Handling
@@ -187,23 +187,21 @@ end
 | `binsparse_from_ssmc.c` | MEX function converting SuiteSparse A+Zeros to a Binsparse struct |
 | `binsparse_minimize_types.c` | MEX function minimizing value/index types in a Binsparse struct |
 | `binsparse_write_string_dataset.c` | MEX function writing HDF5 UTF-8 string datasets |
-| `write_binsparse_from_matlab.c` | MEX entry point for writing an SSMC Problem (delegates to `generate_bsp_from_ssmc.m`) |
 | `matlab_bsp_helpers.h` | Shared MATLAB/Binsparse conversion helpers for the MEX sources |
-| `generate_bsp_from_ssmc.m` | Write a full SSMC Problem struct to one Binsparse file |
-| `convert_to_problem_struct.m` | Convert Binsparse data back to an SSMC Problem struct |
-| `bsp_matrix_create.m` | Utility function for creating matrix structs |
-| `bsp_matrix_info.m` | Utility function for displaying matrix information |
-| `build_matlab_bindings.m` | Build script for all MATLAB MEX functions |
-| `build_octave_bindings.m` | Build script for all Octave MEX functions |
+| `binsparse_write_ssmc_problem.m` | Write a full SSMC Problem struct to one Binsparse file |
+| `binsparse_to_ssmc_problem.m` | Convert Binsparse data back to an SSMC Problem struct |
+| `binsparse_create_struct.m` | Utility function for creating Binsparse structs |
+| `binsparse_info.m` | Utility function for displaying Binsparse information |
+| `binsparse_build_matlab_bindings.m` | Build script for all MATLAB MEX functions |
+| `binsparse_build_octave_bindings.m` | Build script for all Octave MEX functions |
 | `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_binsparse_from_ssmc.m` | Test script for SSMC conversion |
 | `test_binsparse_minimize_roundtrip.m` | Test script for type minimization |
-| `test_bsp_matrix_struct.m` | Test script for the matrix struct helpers |
-| `test_convert_to_problem_struct.m` | Test script for Problem conversion |
-| `test_generate_bsp_from_ssmc.m` | End-to-end test for the SSMC writer |
-| `test_write_binsparse_from_matlab.m` | Test script for the SSMC writer MEX |
+| `test_binsparse_struct.m` | Test script for the struct helpers |
+| `test_binsparse_to_ssmc_problem.m` | Test script for Problem conversion |
+| `test_binsparse_write_ssmc_problem.m` | End-to-end test for the SSMC writer |
 | `test_binsparse_roundtrip_dir.m` | Round-trip every .h5 file in a directory |
 | `Contents.m` | Directory listing for MATLAB's `help` |
 | `README.md` | This documentation file |
@@ -242,7 +240,7 @@ To add new Binsparse functionality:
 
 1. Create a new `.c` file with MEX function structure
 2. Include `<binsparse/binsparse.h>` and relevant headers
-3. Add the filename to `mex_files` list in `build_matlab_bindings.m`
+3. Add the filename to `mex_files` list in `binsparse_build_matlab_bindings.m`
 4. Create corresponding test functions
 
 ### Example MEX Function Template
@@ -284,8 +282,8 @@ void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[]) {
    - Check that `../../include/binsparse/binsparse.h` exists
 
 3. **Compilation errors**
-   - **MATLAB**: Try building with verbose output: `build_matlab_bindings('verbose')`
-   - **Octave**: Try building with verbose output: `build_octave_bindings('verbose')` or `./compile_octave.sh --verbose`
+   - **MATLAB**: Try building with verbose output: `binsparse_build_matlab_bindings('verbose')`
+   - **Octave**: Try building with verbose output: `binsparse_build_octave_bindings('verbose')` or `./compile_octave.sh --verbose`
    - Check compiler compatibility with your MATLAB/Octave version
 
 ### Platform-Specific Notes

bindings/matlab/build_matlab_bindings.m → bindings/matlab/binsparse_build_matlab_bindings.m

@@ -1,14 +1,14 @@
-function build_matlab_bindings(varargin)
-% BUILD_MATLAB_BINDINGS - Build Binsparse MATLAB MEX functions
+function binsparse_build_matlab_bindings(varargin)
+% BINSPARSE_BUILD_MATLAB_BINDINGS - Build Binsparse MATLAB MEX functions
 %
 % This script provides a simple interface to build MATLAB bindings
 % for the Binsparse library. It automatically detects include paths
 % and sets up the compilation environment.
 %
 % Usage:
-%   build_matlab_bindings()           % Build all available MEX functions
-%   build_matlab_bindings('verbose')  % Build with verbose output
-%   build_matlab_bindings('clean')    % Clean compiled MEX files
+%   binsparse_build_matlab_bindings()           % Build all available MEX functions
+%   binsparse_build_matlab_bindings('verbose')  % Build with verbose output
+%   binsparse_build_matlab_bindings('clean')    % Clean compiled MEX files
 %
 % Prerequisites:
 % - MATLAB with working MEX compiler (run 'mex -setup' if needed)
@@ -56,7 +56,7 @@ function build_matlab_bindings(varargin)
 fprintf('Run the test functions to verify the installation:\n');
 fprintf('  test_binsparse_read()\n');
 fprintf('  test_binsparse_write()\n');
-fprintf('  test_write_binsparse_from_matlab()\n\n');
+fprintf('  test_binsparse_write_ssmc_problem()\n\n');
 
 end
 
@@ -107,7 +107,6 @@ function compile_mex_functions(paths, verbose)
     % List of MEX functions to compile
     mex_files = {'binsparse_read.c', 'binsparse_write.c', ...
         'binsparse_from_ssmc.c', 'binsparse_minimize_types.c', ...
-        'write_binsparse_from_matlab.c', ...
         'binsparse_write_string_dataset.c'};
 
     fprintf('Compiling MEX functions...\n');

bindings/matlab/build_octave_bindings.m → bindings/matlab/binsparse_build_octave_bindings.m

@@ -1,14 +1,14 @@
-function build_octave_bindings(varargin)
-% BUILD_OCTAVE_BINDINGS - Build Binsparse Octave MEX functions
+function binsparse_build_octave_bindings(varargin)
+% BINSPARSE_BUILD_OCTAVE_BINDINGS - Build Binsparse Octave MEX functions
 %
 % This script provides a simple interface to build Octave bindings
 % for the Binsparse library using mkoctfile. It automatically detects
 % include paths and sets up the compilation environment.
 %
 % Usage:
-%   build_octave_bindings()           % Build all available MEX functions
-%   build_octave_bindings('verbose')  % Build with verbose output
-%   build_octave_bindings('clean')    % Clean compiled MEX files
+%   binsparse_build_octave_bindings()           % Build all available MEX functions
+%   binsparse_build_octave_bindings('verbose')  % Build with verbose output
+%   binsparse_build_octave_bindings('clean')    % Clean compiled MEX files
 %
 % Prerequisites:
 % - GNU Octave with mkoctfile (usually included with Octave)
@@ -36,7 +36,8 @@ function build_octave_bindings(varargin)
 
 % Check if we're running in Octave
 if ~is_octave()
-    warning('This script is designed for Octave. For MATLAB, use build_matlab_bindings.m');
+    warning(['This script is designed for Octave. For MATLAB, use ' ...
+             'binsparse_build_matlab_bindings.m']);
 end
 
 % Check mkoctfile availability
@@ -64,7 +65,7 @@ function build_octave_bindings(varargin)
 fprintf('Run the test functions to verify the installation:\n');
 fprintf('  test_binsparse_read()\n');
 fprintf('  test_binsparse_write()\n');
-fprintf('  test_write_binsparse_from_matlab()\n\n');
+fprintf('  test_binsparse_write_ssmc_problem()\n\n');
 
 end
 
@@ -119,7 +120,6 @@ function compile_octave_functions(paths, verbose)
     % List of MEX functions to compile
     mex_files = {'binsparse_read.c', 'binsparse_write.c', ...
         'binsparse_from_ssmc.c', 'binsparse_minimize_types.c', ...
-        'write_binsparse_from_matlab.c', ...
         'binsparse_write_string_dataset.c'};
 
     fprintf('Compiling MEX functions with mkoctfile...\n');

bindings/matlab/bsp_matrix_create.m → bindings/matlab/binsparse_create_struct.m

@@ -1,12 +1,12 @@
-function matrix = bsp_matrix_create(varargin)
-% BSP_MATRIX_CREATE - Create a Binsparse matrix struct
+function matrix = binsparse_create_struct(varargin)
+% BINSPARSE_CREATE_STRUCT - Create a Binsparse vector or matrix struct
 %
 % Creates a MATLAB struct analogous to the C bsp_matrix_t structure.
 % The struct contains four native MATLAB arrays and metadata fields.
 %
 % Usage:
-%   matrix = bsp_matrix_create()                    % Empty matrix
-%   matrix = bsp_matrix_create(values, indices_0, indices_1, pointers_to_1, ...
+%   matrix = binsparse_create_struct()              % Empty struct
+%   matrix = binsparse_create_struct(values, indices_0, indices_1, pointers_to_1, ...
 %                              nrows, ncols, nnz, is_iso, format, structure)
 %
 % Fields:
@@ -23,13 +23,14 @@
 %
 % Example:
 %   % Create empty matrix
-%   matrix = bsp_matrix_create();
+%   matrix = binsparse_create_struct();
 %
 %   % Create COO matrix
 %   values = [1.0, 2.0, 3.0];
 %   rows = [1, 2, 3];
 %   cols = [1, 2, 3];
-%   matrix = bsp_matrix_create(values, rows, cols, [], 3, 3, 3, false, 'COO', 'general');
+%   matrix = binsparse_create_struct(values, rows, cols, [], ...
+%       3, 3, 3, false, 'COO', 'general');
 
 % SPDX-FileCopyrightText: 2024 Binsparse Developers
 %
@@ -64,7 +65,7 @@
         'structure', char(varargin{10}));
 
 else
-    error('bsp_matrix_create:InvalidArgs', ...
+    error('binsparse_create_struct:InvalidArgs', ...
           'Expected 0 or 10 arguments, got %d', nargin);
 end
 

bindings/matlab/binsparse_from_ssmc.m

@@ -20,7 +20,8 @@
 %   Zeros = sparse (2, 3, 1, 3, 3) ;
 %   matrix = binsparse_from_ssmc (A, Zeros, 'CSC') ;
 %
-% See also binsparse_write, binsparse_minimize_types, generate_bsp_from_ssmc.
+% See also binsparse_write, binsparse_minimize_types,
+% binsparse_write_ssmc_problem.
 
 % SPDX-FileCopyrightText: 2024 Binsparse Developers
 %
@@ -29,4 +30,5 @@
 % This .m file provides the help text for the binsparse_from_ssmc MEX
 % function.
 
-error('binsparse_from_ssmc mexFunction not found; compile with build_matlab_bindings first');
+error(['binsparse_from_ssmc mexFunction not found; compile with ' ...
+       'binsparse_build_matlab_bindings first']);

bindings/matlab/bsp_matrix_info.m → bindings/matlab/binsparse_info.m

@@ -1,8 +1,8 @@
-function bsp_matrix_info(matrix)
-% BSP_MATRIX_INFO - Display information about a Binsparse matrix struct
+function binsparse_info(matrix)
+% BINSPARSE_INFO - Display information about a Binsparse vector or matrix struct
 %
 % Usage:
-%   bsp_matrix_info(matrix)
+%   binsparse_info(matrix)
 %
 % Displays:
 %   - Matrix dimensions and number of non-zeros
@@ -14,7 +14,7 @@ function bsp_matrix_info(matrix)
 % SPDX-License-Identifier: BSD-3-Clause
 
 if ~isstruct(matrix)
-    error('bsp_matrix_info:InvalidInput', 'Input must be a struct');
+    error('binsparse_info:InvalidInput', 'Input must be a struct');
 end
 
 % Display basic matrix information

bindings/matlab/binsparse_read.c

@@ -8,7 +8,7 @@
  * binsparse_read.c - Read Binsparse matrices into MATLAB
  *
  * This MEX function reads Binsparse format matrices and returns them
- * as MATLAB structs compatible with bsp_matrix_create.
+ * as MATLAB structs compatible with binsparse_create_struct.
  *
  * Usage in MATLAB/Octave:
  *   matrix = binsparse_read(filename)

bindings/matlab/binsparse_read.m

@@ -9,21 +9,22 @@
 % group optionally names an HDF5 group within the file that holds a
 % Binsparse matrix.  The result is a raw Binsparse matrix struct with the
 % fields values, indices_0, indices_1, pointers_to_1, nrows, ncols, nnz,
-% is_iso, format, and structure, as documented in bsp_matrix_create.
+% is_iso, format, and structure, as documented in binsparse_create_struct.
 % Value and index arrays keep the types stored in the file; indices are
-% 0-based.  Use convert_to_problem_struct to build a MATLAB-native
+% 0-based.  Use binsparse_to_ssmc_problem to build a MATLAB-native
 % SuiteSparse Problem struct from Binsparse data.
 %
 % Example:
 %   matrix = binsparse_read ('west0067.bsp.h5') ;
 %   b = binsparse_read ('west0067.bsp.h5', 'b') ;
 %
-% See also binsparse_write, bsp_matrix_create, convert_to_problem_struct.
+% See also binsparse_write, binsparse_create_struct, binsparse_to_ssmc_problem.
 
 % SPDX-FileCopyrightText: 2024 Binsparse Developers
 %
 % SPDX-License-Identifier: BSD-3-Clause
 
 % This .m file provides the help text for the binsparse_read MEX function.
 
-error ('binsparse_read mexFunction not found; compile with build_matlab_bindings first') ;
+error (['binsparse_read mexFunction not found; compile with ' ...
+    'binsparse_build_matlab_bindings first']) ;

bindings/matlab/convert_to_problem_struct.m → bindings/matlab/binsparse_to_ssmc_problem.m

@@ -1,7 +1,7 @@
-function Problem = convert_to_problem_struct(bsp_problem)
-%CONVERT_TO_PROBLEM_STRUCT convert a Binsparse problem to an SSMC Problem
+function Problem = binsparse_to_ssmc_problem(bsp_problem)
+%BINSPARSE_TO_SSMC_PROBLEM convert a Binsparse problem to an SSMC Problem
 %
-% Problem = convert_to_problem_struct(bsp_problem)
+% Problem = binsparse_to_ssmc_problem(bsp_problem)
 %
 % bsp_problem is an in-memory representation of one SuiteSparse Matrix
 % Collection problem.  Its A, b, x, and aux numeric entries are raw structs

bindings/matlab/binsparse_write.c

@@ -7,7 +7,8 @@
 /**
  * binsparse_write.c - Write MATLAB structs to Binsparse format
  *
- * This MEX function writes MATLAB structs (compatible with bsp_matrix_create)
+ * This MEX function writes MATLAB structs (compatible with
+ * binsparse_create_struct)
  * to Binsparse format files.
  *
  * Usage in MATLAB/Octave: