Overview

Find this tutorial at SYSTEMML_INSTALL_PATH/BRAHMS/support/example/995. It will run in Matlab (1258) or Python (1262), depending on the argument you pass to the script rabbitsandfoxes.m. This documentation is based on the Matlab version, but should apply equally well to the Python version.

Rabbits And Foxes illustrates designing your own BRAHMS processes and shows how to knit them together into a computable system. The script that executes this tutorial is rabbitsandfoxes.m, which should run out of the box. This page will take you through the process of developing this example. Here, we will cover the following.

  1. Understanding what happens inside a BRAHMS Process.
  2. Building your own BRAHMS Process.
  3. Constructing a system including that Process.

BRAHMS native language is C. However, a Matlab Component Binding (1258) is provided that lets us quickly develop (or prototype) Processes in Matlab, and run them under BRAHMS. We will use this binding in this tutorial.

The Dynamical System

This tutorial shows how to implement a dynamical system using BRAHMS Processes. The system is a simple model of population dynamics for the predator-prey relationship between a population of foxes and a population of rabbits (this is the famous Lotka-Volterra model). The two-dimensional system of ordinary differential equations (ODEs) is:


In words, this system describes the following. Both the change in number of rabbits over time (d/dt rabbits) and the change in number of foxes over time (d/dt foxes) are dependent on each other's population size. Rabbits reproduce quickly (2*rabbits) and independently of the number of foxes; but this is offset by deaths, which is partly dependent on the number of foxes (-1.2 * rabbits * foxes), because foxes eat rabbits. Foxes die at a rate unrelated to the number of rabbits (-foxes), as rabbits do not eat foxes; but foxes reproduce at a rate that is partly dependent on the availability of rabbits (0.9 * rabbits * foxes) because they eat rabbits to maintain energy (in this simple world).

Because these two ODEs are coupled, they cannot be solved exactly. Instead we need to solve them numerically, using some numerical method - to keep things simple we use the forward Euler method here: x(t+T) = x(t) + dx * T, using some small time-step T.

Implementation in Matlab (not BRAHMS)

Let's get a handle on how to implement this system in a Matlab script before we tackle a BRAHMS Process. The code that does this is included in rabbitsandfoxes.m, and runs before the script launches the BRAHMS implementation.

First we set up the initial size of the populations, the sample rate (fS), and the length of the execution. The time-step (T) is hence just (1/fS).

M Source Code
rabbits = 0.5; foxes = 0.5; fS = 100; executionStop = 10; N = fS * executionStop; T = 1/fS;

Implementing the Euler method to solve the equations over the execution length is as follows.

M Source Code
trace = zeros(N, 2); for n = 1:N d_rabbits = 2 * rabbits - 1.2 * rabbits * foxes; d_foxes = -foxes + 0.9 * rabbits * foxes'; rabbits = rabbits + T * d_rabbits; foxes = foxes + T * d_foxes; trace(n, :) = [rabbits foxes]; end

Finally, we plot the results.

M Source Code
subplot(2, 1, 1) plot(trace(:,1), 'b-') hold on plot(trace(:,2), 'r-') hold off

The plot shows the progression of the system, with rabbits in blue and foxes in red. It is shown below.

Implementation in BRAHMS

For the purposes of this tutorial, we shall construct the ODE system using two BRAHMS processes, one per equation. For such a computationally simple system, this incurs a big processing overhead, but that doesn't matter for our purposes here. You will notice that the BRAHMS version runs much slower than the Matlab version, for this reason. Both processes will be authored against the 1258 Matlab Component Bindings.

The example script, rabbitsandfoxes.m, includes the implementation of the system in Matlab described above, and then executes the implementation in BRAHMS, and plots their results alongside. The implementation in BRAHMS is pretty much a worst case scenario for BRAHMS performance, with two processes each doing a couple of operations per step. Thus, the vast majority of the run-time for this case is overhead, allowing you to directly measure the overhead after the run.

Open and examine the Matlab files that make up this example. Specifically, rabbitsandfoxes.m, and the two instances of brahms_process.m appearing under the installed Namespace (SYSTEMML_INSTALL_PATH/Namespace) at client/brahms/example/1258/rabbits and at client/brahms/example/1258/foxes.

Output

Matlab Console
Binding iteration time ---------------------- This is an estimate of the maximum total processing overhead, including all BRAHMS framework overheads and the overhead due to calling the language engine. Your workstation: 1.049ms My workstation: ~1.2ms

Acknowledgements

Mitch originally ripped this example off from this page. The documentation for this example is courtesy of Mark Humphries.