README.md

   1 # SDDEKit
   2
   3 ![Build Status](https://travis-ci.org/maedoc/sddekit.svg?branch=master)
   4 ![Coverage Status](https://coveralls.io/repos/github/maedoc/sddekit/badge.svg?branch=master)
   5
   6 ## What is SDDEKit?
   7
   8 A library for stochastic delay differential equations implementing published
   9 numerical schemes, utilities for constructing network models and handling
  10 simulation results, as well as bindings for MATLAB, Python.  Our intent is
  11 to make it possible to use and benchmark available schemes on your favorite
  12 model, not invent new numerical schemes, so we have attempted to follow
  13 [published results](#references), documenting caveats, assumptions etc. Care will be taken to
  14 handle calculation of partial erivatives, to enable higher order schemes,
  15 optimization and inversion techniques.
  16
  17 *The current focus is nailing down 'software carpentry' aspects of building a scientific library, and only preliminary sets of mathematical components are implemented, not for use pending v0.1 release, though I have stopped ruthless rebasing of master so it's safe to fork*.
  18
  19 ## Using
  20
  21 Currently the [documentation](https://maedoc.github.io/sddekit),
  22 [tests](tests) and [benchmark](bench/bench_net_exc.c) are the best places
  23 to look to understand what you can do with SDDEKit.
  24
  25 Python, MATLAB bindings and C++ header are in the works, on separate
  26 (`ctype`/`cython`/`py-c-api`, `matlab`, `cpp` respectively) branches of
  27 this repo.
  28
  29 You can build the tests and benchmark if you have GCC (or a C99 compiler) and Make:
  30
  31 ```bash
  32 $ make tests
  33 ...
  34 $ make bench_net_exc
  35 ...
  36 ```
  37
  38 Running the tests will generate some data files from [one of the tests](test/test_exc.c), which
  39 tests different integration schemes on the same system. These can be compared with
  40 the gnuplot script `fig/exc_em_emcolor_heun.gpi`
  41
  42 ```bash
  43 $ gnuplot fig/exc_em_emcolor_heun.gpi
  44 ```
  45
  46 which produces
  47
  48 ![this](fig/exc_em_emcolor_heun.png)
  49
  50 Running the benchmark will produce a trace `bench_net_exc.dat` which can be visualized
  51 with `fig/bench_net_exc.py`, producing
  52
  53 ![this](fig/bench_net_exc.png)
  54
  55 As stated, these are in place to help build up the library at this point. In the
  56 future extensive examples for different kinds of systems & networks will be provided.
  57
  58 ## js
  59
  60 Because SDDEKit is a C library, it's straighforward to build it as a JavaScript
  61 library and embed it in HTML with Emscripten. With the benchmark mentioned above
  62 as an example, compile it natively,
  63
  64 ```bash
  65 $ make BUILD=fast -B -j bench_net_exc
  66 ...
  67 $ ./bench_net_exc
  68 [bench_net_exc] nnz=1560
  69 [INFO] bench/bench_net_exc.c:71 (main) continuation required 23.766 s
  70 ```
  71
  72 A little slow on this 2009 Core 2 Duo laptop. Now, with
  73 the [Emscripten SDK installed](http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html),
  74 build an HTML page that runs the benchmark in your browser:
  75
  76 ```bash
  77 $ make CC=emcc BUILD=js OBJEXT=bc EXE=.html -B -j bench_net_exc.html
  78 ...
  79 ```
  80
  81 Open [`bench_net_exc.html`](http://rawgit.com/maedoc/sddekit/js-bench-html/bench_net_exc.html)
  82  with your browser. On this same machine, Safari
  83 runs the benchmark in 74 s, Firefox 55 s. On a win 10 workstation,
  84 GCC-compiled takes 12 s, Firefox takes 32 s & MS Edge 39 s.
  85
  86 Obviously for high-performance computing & science JS isn't ideal, but it could
  87 be useful for creating interactive graphics exploring dynamical systems.
  88
  89 ## Develop
  90
  91 Fork the code, try it out. See our documented [issues](issues) or
  92 add your own.
  93
  94 ### Contributing
  95
  96 Please follow the generic GitHub workflow:
  97
  98 - fork the repo
  99 - create a topic branch, e.g add-foo-implementation
 100 - make modifications
 101 - git commit -m 'useful comments'
 102 - push branch to your fork on GitHub
 103 - open pull request
 104
 105 [Here's way more detail w/ pictures](https://guides.github.com/introduction/flow/index.html)
 106
 107 ### Python wrapper
 108
 109 The current work on Python wrapper in the `ctype` branch follows the naming conventions
 110 of the C library for the moment, drastically reducing the code required to use it. Though
 111 if time permits, the API could be Python-ized.
 112
 113 ### C lib architecture
 114
 115 To keep things general, most high-level components are exposed as interfaces through
 116 structs whose fields are just function pointers.
 117
 118 Contributing an implementation of a particular interface therefore implies
 119
 120 - writing implementations for each of the members of the interface struct
 121 - writing a constructor function which
 122   - alloc with sd_malloc
 123   - fill out interface struct
 124   - return it
 125 - document & test
 126
 127 Keep in mind that if you 'subclass' an existing interface, some methods like
 128 `free` should be available (and correctly implemented) in both
 129
 130 ## References
 131
 132 - Kloeden & Platen 1999 *Numerical Solution of Stochastic Differential Equations*.
 133 - Fox et al 1998
 134 - Mannella 200?
 135 - Jimenez et al 2015
 136 - Kuechler & Platen 2000