Merge pull request #20 from UM-Bridge/marlenaweidenauer-patch-2

Update README.md

.github/workflows/client-matlab.yml

@@ -4,14 +4,14 @@ on:
   push:
     branches:
       - 'main'
-
+      
 jobs:
   test:
     runs-on: ubuntu-latest
 
     services:
       model:
-        image: linusseelinger/benchmark-analytic-banana
+        image: linusseelinger/benchmark-analytic-funnel:latest
         ports:
         - 4243:4243
 
@@ -24,4 +24,4 @@ jobs:
       - name: Run all tests
         uses: matlab-actions/run-tests@v1
         with:
-          source-folder: matlab; clients/matlab
+          source-folder: matlab; clients/matlab

clients/README.md

@@ -181,6 +181,83 @@ if (supports_apply_jacobian(url, name)) {
 
 [Full example sources here.](https://github.com/UM-Bridge/umbridge/tree/main/clients/R)
 
+## Matlab client
+
+The Matlab integration can be found in the [git repository](https://github.com/UM-Bridge/umbridge/tree/main/matlab).
+
+We use the Matlab function `addpath()` to add the specified folder.
+
+```
+umbridge_supported_models('http://localhost:4243‘)
+model = HTTPModel('http://localhost:4243‘, 'posterior');
+```
+
+`umbridge_supported_models()` gives a list of models that are supported by the current server. We set up a model by connecting to the URL and selecting for example the „posterior“ model. We obtain its input and output dimensions using the functions
+
+
+```
+model.get_input_sizes()
+model.get_output_sizes()
+```
+
+A model that expects an input consisting of a single 2D vector can be evaluated as follows.
+
+```
+model.evaluate([0, 10.0])
+model.evaluate([0, 10.0], struct('a', 3.9))
+```
+
+If the model accepts configuartion parameters, we can add those to the model evaluation. The config options accepted by a particular model can be found in the model’s documentation.
+
+Furthermore a model indicates wheather it supports further features. The following example evaluates the Jacobian of model output zero with respect to model input zero at the same input parameter as before. It then applies it to the additional vector given.
+
+```
+model.apply_jacobian([1.0,4.0], [0, 10.0], 0, 0)
+```
+
+[Full example sources here.](https://github.com/UM-Bridge/umbridge/blob/main/clients/matlab/matlabClient.m)
+
+## Julia client
+
+The Julia integration can be installed using Julia's builtin package manager Pkg
+
+```
+Pkg.add("UMBridge")
+```
+
+It can be used as usual via
+
+```
+using UMBridge
+```
+
+We set up a model by connection to the URL and selecting the "forward" model
+
+```
+model = UMBridge.HTTPModel("forward", "http://localhost:4242")
+print(UMBridge.model_input_sizes(model))
+print(UMBridge.model_output_sizes(model))
+```
+
+The functions UMBridge.model_input_sizes() and UMBridge.model_output_sizes() give the input and output dimension of a model, respectively. A model that expects an input consisting of a single 2D vector can be evaluated as follows
+
+```
+print(UMBridge.evaluate(model, [[0, 10]], Dict()))
+
+config = Dict("vtk_output" => true, "level" => 1);
+print(UMBridge.evaluate(model, [[0, 10]], config))
+```
+
+If the model accepts configuartion parameters, we can add those to the model evaluation. The config options accepted by a particular model can be found in the model's documentation.
+
+Models indicate whether they support further features, e.g. Jacobian or Hessian actions. The following example evaluates the Jacobian of model output zero with respect to model input zero at the same input parameter as before. It then applies it to the additional vector given.
+
+```
+ UMBridge.apply_jacobian(model, 0, 0, [[0, 10]], [1, 4])
+```
+
+[Full example sources here.](https://github.com/UM-Bridge/umbridge/blob/main/clients/julia/juliaClient.jl)
+
 ## MUQ client
 
 Within the [MIT Uncertainty Quantification library (MUQ)](https://mituq.bitbucket.io), there is a ModPiece available that allows embedding an HTTP model in MUQ's model graph framework.

clients/julia/juliaClient.jl

@@ -0,0 +1,27 @@
+using UMBridge
+
+url = "http://localhost:4242"
+
+# Set up a model by connecting to URL and selecting the "forward" model
+model = UMBridge.HTTPModel("forward", url)
+
+# Print model input and output dimension
+print(UMBridge.model_input_sizes(model))
+print(UMBridge.model_output_sizes(model))
+
+param = [[0, 10]];
+
+# Simple model evaluation without config
+val = UMBridge.evaluate(model, param, Dict())
+print(val)
+
+# Model evaluation with configuration parameters
+config = Dict("vtk_output" => true, "level" => 1);
+print(UMBridge.evaluate(model, param, config))
+
+# If model supports Jacobian action,
+# apply Jacobian of output zero with respect to input zero to a vector
+if UMBridge.supports_apply_jacobian(model)
+    UMBridge.apply_jacobian(model, 0, 0, param, [1, 4])
+end
+

clients/matlab/matlabClient.m

@@ -1,5 +1,27 @@
+% use matlab function addpath('')
+
 uri = 'http://localhost:4243';
 
+% Print models supported by server
+umbridge_supported_models(uri)
+
+% Set up a model by connecting to URL and selecting the "posterior" model
 model = HTTPModel(uri,'posterior');
 
-httpValue = model.evaluate([1, 3])
+model.get_input_sizes()
+model.get_output_sizes()
+
+param=[0, 10.0];
+
+% Simple model evaluation without config
+model.evaluate(param)
+
+%Model evaluation with configuration parameters
+config = struct('a', 3.9);
+model.evaluate(param, config)
+
+% If model supports Jacobian action,
+% apply Jacobian of output zero with respect to input zero to a vector
+if model.supports_apply_jacobian()
+    model.apply_jacobian([1.0,4.0],param, 0, 0)
+end

testing/clients/TestMatlab.m

@@ -8,11 +8,22 @@ function testConnection(testCase)
             model = HTTPModel(uri,'posterior');
 
             httpValue = model.evaluate([1, 3])
-            exactValue = -11.194036030183454;
+            exactValue = -5.147502395904501;
             testCase.verifyEqual(httpValue, exactValue, 'RelTol', 1e-14)
 
         end
 
+        function testApplyJacobian(testCase)
+             uri = 'http://localhost:4243';
+
+            model = HTTPModel(uri,'posterior');
+
+            httpValue = model.apply_jacobian([1.0,4.0], [1,3], 0, 0)
+            exactValue = -3.370206919896928;
+            testCase.verifyEqual(httpValue, exactValue, 'RelTol', 1e-14)
+
+        end
+
         function testBasicExample(testCase)
           matlabClient;;
         end