Getting Started — excentury 0.2 documentation

# Getting Started

Excentury aims to provide simple and intuitive tools which we can use to develop packages with easy. What we wish to provide is a file format where we can write C++ code and give accessibility from MATLAB and Python at the same time.

Consider the excentury file `sample.xcpp`.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    """Excentury Sample Package

    This package contains only one function. The comments written in this
    section should be used to give an overall description of the
    excentury package being written.

    """
    #include <excentury/excentury.h>
    #define VECTOR excentury::DynamicTensor<1, double>
    #define MATRIX excentury::DynamicTensor<2, double>
    #define MTRAND excentury::MTRand

    ----------------------------------------------------------------------
    @def{lotka_volterra}
        """Generate a trajectory from the Lokta-Volterra model using
        Gillespie's Stochastic Simulation Algorithm. The output is a
        vector `t` and a matrix `v` where the first column contains the
        size of the prey population and the second column the size of the
        predator population. """
        @param{double, A(1.0), "birth rate of prey"}
        @param{double, B(0.001), "death rate of prey"}
        @param{double, C(0.002), "birth rate of predator"}
        @param{double, D(1.0), "death rate of predator"}
        @param{int, x0(1000), "initial prey population size"}
        @param{int, y0(1000), "initial predator population size"}
        @param{int, num_points(50000), "total number of points"}
    @body[[
        // z(m,n) is the change to the m-th population
        // due to the n-th event.
        MATRIX z(2, 4);
        z(0,0) = 1; z(0,1) = -1; z(0,2) = 0; z(0,3) =  0;
        z(1,0) = 0; z(1,1) =  0; z(1,2) = 1; z(1,3) = -1;

        // Random number generator
        MTRAND rg;

        double x = x0;
        double y = y0;

        double a[4], a0, tau, prop_sum, rand_num;
        int event;

        VECTOR t(num_points);
        MATRIX v(2, num_points);
        t[0] = 0;
        v(0,0) = x0;
        v(1,0) = y0;

        for (int point = 1; point < num_points; ++point) {
            // Evaluating propensity functions
            a[0] = A*x;
            a[1] = B*x*y;
            a[2] = C*x*y;
            a[3] = D*y;
            // Sum of propensity functions
            a0 = 0;
            for (int i=0; i < 4; ++i) a0 += a[i];
            if (a0 == 0) {
                break;
            }
            // Time between events
            tau = log(1/rg.rand())/a0;
            // Next event computation
            event = -1;
            prop_sum = 0;
            rand_num = rg.rand()*a0;
            while (prop_sum < rand_num) {
                event = event + 1;
                prop_sum = prop_sum + a[event];
            }
            // Updating system
            x = x + z(0,event);
            y = y + z(1,event);
            // Storing point
            t[point] = t[point-1] + tau;
            v(0,point) = x;
            v(1,point) = y;
        }
    ]]
    @ret[[
        @ret{t, "t", t[0]}
        @ret{v, "v", v[0]}
    ]]
    ----------------------------------------------------------------------

The structure of this file goes as follows. Lines 1-7 provide a description of the package. A package in this context is a collection of functions. This section must start and end with three quotation marks `"""`. In lines 8-12 we include the excentury header file. This section follows immediately after the end of the package description and ends at the encounter of three or more consecutive dashes. In this section we have to provide all the includes as we would in C++. You may define function or anything in C++ that you want.

Lines 13-84 define a function. A function must be defined between two lines of three or more consecutive dashes. To define a function we must use the keyword `@def`. Here you provide the name of the function. This name must be valid in all scripting languages. Excentury will not complain if we name our function `my-awesome-function` but MATLAB will have something to say about the used dashes in the name.

After the declaration of the name we have to provide a documentation string. The documentation string can be found in lines 15-19. This string should give a full description of the function followed by a list of the input parameters. To provide a parameter we must provide the type , the name and a description.

The body of the function can be found in lines 27-79. This section is pure C++ code. Here we assume that the inputs declared previously are available. The scripting language will be providing those inputs.

Finally, in lines 80-83 we define the return statements. This is where we return our data back to the scripting language.

## CPP

To try to run this example in cpp we can try the following:

    excentury sample.xcpp to cpp

This will create a valid cpp file which will then be compiled into a binary which we can call.:

    $ sample-lotka_volterra.run -h
    usage: sample-lotka_volterra.run [-h] [-i] XC_CONTENT

    program: sample-lotka_volterra

    description:
        Generate a trajectory from the Lokta-Volterra model using
        Gillespie's Stochastic Simulation Algorithm. The output is a
        vector `t` and a matrix `v` where the first column contains the
        size of the prey population and the second column the size of the
        predator population.

    parameters:
        `A`: birth rate of prey
        `B`: death rate of prey
        `C`: birth rate of predator
        `D`: death rate of predator
        `x0`: initial prey population size
        `y0`: initial predator population size
        `num_points`: total number of points

    examples:

        generate an input file: sample-lotka_volterra.run -i > input_file.xc
        use the file: sample-lotka_volterra.run "`< input_file.xc`"

The help menu is important because it tells us how we can provide the inputs to the program. In this case we can generate an input file:

    sample-lotka_volterra.run -i > input_file.xc

Since the xcpp file declared default values we can leave the file as is and run it as follows:

    sample-lotka_volterra.run "`< input_file.xc`" > data.xc

Notice here that we redirected the output to the file data.xc. An Excentury CPP program by default will create an executable which takes input from the standard input and writes the output to the standard output. If you do not redirect the output from the command we presented above then expect to see a very long output. The output generated by this file can then be used by matlab or python.

## MATLAB

If we prefer to skip the middle guy we can compile the cpp file so that it may be called directly from MATLAB:

    excentury sample.xcpp to matlab

Then in the MATLAB prompt we can do:

    >> help sample.lotka_volterra
      sample.LOTKA_VOLTERRA generated on Sun Aug 17, 2014 11:57:01 PM by xcpp

          Generate a trajectory from the Lokta-Volterra model using
          Gillespie's Stochastic Simulation Algorithm. The output is a
          vector `t` and a matrix `v` where the first column contains the
          size of the prey population and the second column the size of the
          predator population.

          parameters:

            `A`: birth rate of prey
            `B`: death rate of prey
            `C`: birth rate of predator
            `D`: death rate of predator
            `x0`: initial prey population size
            `y0`: initial predator population size
            `num_points`: total number of points

    >> [t, v] = sample.lotka_volterra(1, 0.001, 0.002, 1, 1000, 100, 50000);
    >> plot(t, v)

## Python

Similarly, we can do the same in Python:

    excentury sample.xcpp to python

You can view the help on the package:

    import sample
    help(sample)