feat: C API for the DeGroot iteration

seldon_degroot_settle is the same sweep as DeGrootModel::iteration
so a seat crate can call it without linking the whole engine.

Author: HaoZeke

include/seldon_capi.h

@@ -0,0 +1,20 @@
+#pragma once
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* One DeGroot sweep of x <- W x until ||dx||_inf < tol or max_iter.
+ * For each agent i, n_in[i] incoming edges start at off = sum_{k<i} n_in[k].
+ * neigh[off+j] and weight[off+j] are the neighbour and the incoming weight.
+ * opinions is length n, overwritten in place.
+ * Returns 0 on success, -1 on a bad argument.
+ * This is the same iteration as Seldon::DeGrootModel::iteration. */
+int seldon_degroot_settle( size_t n, const size_t * n_in, const size_t * neigh,
+                           const double * weight, double * opinions, double tol,
+                           int max_iter, int * rounds_out );
+
+#ifdef __cplusplus
+}
+#endif

meson.build

@@ -28,6 +28,7 @@ sources_seldon = [
   'src/models/DeffuantModelVector.cpp',
   'src/models/InertialModel.cpp',
   'src/util/tomlplusplus.cpp',
+  'src/capi.cpp',
 ]
 
 # both static and shared library for bindings
@@ -39,6 +40,8 @@ if get_option('default_library') == 'static'
   symbol_visibility = 'inlineshidden'
 endif
 
+install_headers('include/seldon_capi.h')
+
 seldon_lib = both_libraries('seldon',
   sources_seldon,
   install:true,
@@ -79,6 +82,7 @@ if get_option('build_tests')
     ['Test_IO', 'test/test_io.cpp'],
     ['Test_Util', 'test/test_util.cpp'],
     ['Test_Prob', 'test/test_probability_distributions.cpp'],
+    ['Test_CAPI', 'test/test_capi.cpp'],
   ]
 
   Catch2 = dependency('Catch2', method : 'cmake', modules : ['Catch2::Catch2WithMain', 'Catch2::Catch2'])

src/capi.cpp

@@ -0,0 +1,60 @@
+#include "seldon_capi.h"
+#include <cmath>
+#include <vector>
+
+int seldon_degroot_settle( size_t n, const size_t * n_in, const size_t * neigh,
+                           const double * weight, double * opinions, double tol,
+                           int max_iter, int * rounds_out )
+{
+    if( n == 0 || n_in == nullptr || opinions == nullptr || max_iter < 1 )
+    {
+        return -1;
+    }
+    size_t edges = 0;
+    for( size_t i = 0; i < n; i++ )
+    {
+        edges += n_in[i];
+    }
+    if( edges > 0 && ( neigh == nullptr || weight == nullptr ) )
+    {
+        return -1;
+    }
+
+    std::vector<double> nxt( n, 0.0 );
+    int rounds = 0;
+    for( int r = 1; r <= max_iter; r++ )
+    {
+        size_t off = 0;
+        for( size_t i = 0; i < n; i++ )
+        {
+            double acc = 0.0;
+            for( size_t j = 0; j < n_in[i]; j++ )
+            {
+                size_t k = neigh[off + j];
+                if( k >= n )
+                {
+                    return -1;
+                }
+                acc += weight[off + j] * opinions[k];
+            }
+            nxt[i] = acc;
+            off += n_in[i];
+        }
+        double err = 0.0;
+        for( size_t i = 0; i < n; i++ )
+        {
+            err = std::max( err, std::abs( nxt[i] - opinions[i] ) );
+            opinions[i] = nxt[i];
+        }
+        rounds = r;
+        if( err < tol )
+        {
+            break;
+        }
+    }
+    if( rounds_out != nullptr )
+    {
+        *rounds_out = rounds;
+    }
+    return 0;
+}

test/test_capi.cpp

@@ -0,0 +1,17 @@
+#include "seldon_capi.h"
+#include <catch2/catch_test_macros.hpp>
+#include <catch2/matchers/catch_matchers_floating_point.hpp>
+
+TEST_CASE( "C API DeGroot matches the two-agent symmetric case", "[capi]" )
+{
+    using namespace Catch::Matchers;
+    size_t n_in[2]   = { 2, 2 };
+    size_t neigh[4]  = { 1, 0, 0, 1 };
+    double weight[4] = { 0.2, 0.8, 0.2, 0.8 };
+    double x[2]      = { 0.0, 1.0 };
+    int rounds       = 0;
+    REQUIRE( seldon_degroot_settle( 2, n_in, neigh, weight, x, 1e-6, 100, &rounds ) == 0 );
+    REQUIRE( rounds > 0 );
+    REQUIRE_THAT( x[0], WithinAbs( 0.5, 1e-5 ) );
+    REQUIRE_THAT( x[1], WithinAbs( 0.5, 1e-5 ) );
+}