README.md

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