.. _start:

***************
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``.

.. literalinclude:: _xcpp/sample.xcpp
    :linenos:
    :language: cpp

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)
