feat: 📦️ MEX-accelerated upscale function

Introduce `CodeMexGen` class
that can compile the `upscale` function
into MEX-file to accelerate the toolkit.

How to use:
```matlab
% 1. compile MEX functions
codegen_mex = CodeGenMex().config().build();

% 2. use strata_trapper normally
...

% 3. recompile MEX functions when the source code changes
codegen_mex.build();

% 4. delete MEX functions to use the original
codegen_mex.clear();
```

Author: djmaxus

.cspell.json

@@ -21,6 +21,7 @@
     "ignoreWords": [
         "buildfile",
         "buildplan",
-        "localfunctions"
+        "localfunctions",
+        "codegen_mex"
     ]
 }

.github/workflows/matlab.yml

@@ -18,3 +18,6 @@ jobs:
             Statistics_and_Machine_Learning_Toolbox
             Parallel_Computing_Toolbox
       - uses: matlab-actions/run-build@v2
+        with:
+          #NOTE: test_codegen requires batch licensing
+          tasks: check test

README.md

@@ -11,6 +11,7 @@ Repository: [github.com/ImperialCollegeLondon/StrataTrapper](https://github.com/
 * [The StrataTrapper codes](#the-stratatrapper-codes)
 * [Structure](#structure)
 * [Running](#running)
+* [MEX acceleration](#mex-acceleration)
 * [Versions](#versions)
 * [Contributing](#contributing)
 * [References](#references)
@@ -63,6 +64,27 @@ if they are in a startup folder.
 So, using several parallel workers usually results
 in a proportional performance boost.
 
+## MEX acceleration
+
+We provide the `CodeGenMex` class to automatically build
+a MEX-accelerated version of the `upscale` function.
+
+```matlab
+% 1. compile MEX functions
+codegen_mex = CodeGenMex().config().build();
+
+% 2. use strata_trapper normally
+...
+
+% 3. recompile MEX functions when the source code changes
+codegen_mex.build();
+
+% 4. delete MEX functions to use the original
+codegen_mex.clear();
+```
+
+Requires [MATLAB Coder](https://uk.mathworks.com/products/matlab-coder.html).
+
 ## Versions
 
 The original version of the toolkit is [v0.1.0](https://github.com/ImperialCollegeLondon/StrataTrapper/tree/v0.1.0).\

buildfile.m

@@ -1,25 +1,30 @@
 function plan = buildfile()
-
+startup;
 plan = buildplan(localfunctions);
-plan.DefaultTasks = ["check", "test"];
+plan.DefaultTasks = ["check", "test", "test_codegen"];
 
-test_options = {"IncludeSubfolders",true};
+test_options = {"IncludeSubfolders",false};
+test_codegen_options = {"test/CodeGenMexTest.m"};
 
 if isMATLABReleaseOlderThan("R2023b")
     plan("test") = matlab.buildtool.Task( ...
     Description="Run tests", ...
     Actions=@(~) assert(runtests(test_options{:}).Failed == 0));
 
+    plan("test_codegen") = matlab.buildtool.Task( ...
+    Description="Run tests", ...
+    Actions=@(~) assert(runtests(test_codegen_options{:}).Failed == 0));
+
     plan("check") = matlab.buildtool.Task(...
     Description="Identify code issues", ...
     Actions=@(~) assert(code_issues()) );
-    
+
     return;
 end
 
 plan("check") = matlab.buildtool.tasks.CodeIssuesTask(WarningThreshold=0);
 plan("test") = matlab.buildtool.tasks.TestTask(test_options{:});
-
+plan("test_codegen") = matlab.buildtool.tasks.TestTask(test_codegen_options{:});
 end
 
 function issue_free = code_issues()

src/CodeGenMex.m

@@ -0,0 +1,48 @@
+classdef CodeGenMex < handle
+    properties
+        cfg
+        built_func
+    end
+
+    methods
+        function self = CodeGenMex()
+            mex -setup C++
+        end
+
+        function self = config(self)
+            self.cfg = coder.config("mex");
+
+            self.cfg.Name = "strata_trapper-mex";
+            self.cfg.Description = "MEX-compiled StrataTrapper functions";
+
+            self.cfg.TargetLang = "C++";
+            self.cfg.CppNamespace = "strata_trapper";
+
+            self.cfg.InlineBetweenUserFunctions = "Speed";
+            self.cfg.InlineBetweenUserAndMathWorksFunctions = "Speed";
+            self.cfg.InlineBetweenMathWorksFunctions = "Speed";
+
+            self.cfg.NumberOfCpuThreads = 32;
+            self.cfg.SIMDAcceleration = "Full";
+            self.cfg.OptimizeReductions = true;
+            self.cfg.EnableAutoParallelization = false;
+            self.cfg.EnableOpenMP = false;
+        end
+
+        
+        function self = build_with(self,options,func)
+            codegen("-config",self.cfg,options{:},func);
+            self.built_func = func;
+        end
+
+        function self = build(self)
+            self = self.build_with({"-o","upscale"},'upscale');
+        end
+
+        function self = clear(self)
+            clear mex; %#ok<CLMEX>
+            delete([self.built_func,'.mex*']);
+            self.built_func = [];
+        end
+    end
+end

test/CodeGenMexTest.m

@@ -0,0 +1,43 @@
+% This test file was generated by Copilot. Validate the generated output before use.
+classdef CodeGenMexTest < matlab.unittest.TestCase
+    properties
+        codeGen
+    end
+
+    methods(TestMethodSetup)
+        function createCodeGen(testCase)
+            testCase.codeGen = CodeGenMex();
+        end
+    end
+
+    methods(Test)
+        function testConfig(testCase)
+            testCase.codeGen.config();
+            testCase.verifyEqual(testCase.codeGen.cfg.Name, 'strata_trapper-mex');
+            testCase.verifyEqual(testCase.codeGen.cfg.Description, ...
+                'MEX-compiled StrataTrapper functions');
+            testCase.verifyEqual(testCase.codeGen.cfg.TargetLang, 'C++');
+            testCase.verifyEqual(testCase.codeGen.cfg.NumberOfCpuThreads, int32(32));
+        end
+
+        function testBuild(testCase)
+            testCase.codeGen.config();
+            a = int32(2);
+            b = int32(2);
+            sum = add_mex_test(a,b);
+            testCase.codeGen.build_with({"-o","add_mex_test","-v"},'add_mex_test');
+            % Check if the MEX file was created
+            testCase.verifyTrue(exist('add_mex_test', 'file') == 3);
+            sum_mex = add_mex_test(a,b);
+            testCase.verifyTrue(sum_mex == sum); % test compiled MEX function
+        end
+
+        function testClear(testCase)
+            testCase.codeGen.config();
+            testCase.codeGen.build_with({"-o","add_mex_test"},'add_mex_test');
+            testCase.codeGen.clear();
+            % Check if the MEX file was deleted
+            testCase.verifyTrue(exist('add_mex_test', 'file') == 2);
+        end
+    end
+end

test/add_mex_test.m

@@ -0,0 +1,11 @@
+function sum= add_mex_test(a,b)
+arguments (Input)
+    a (1,1) int32
+    b (1,1) int32
+end
+
+arguments (Output)
+    sum (1,1) int32
+end
+sum = a+b;
+end