Contributor Guide

TL;DR: To contribute via pull requests you can check issues that have labels "wanted feature" or "good first issue" in the GitHub repositories of the subpackages of DynamicalSystems.jl

The ultimate goal for DynamicalSystems.jl is to be a useful library for scientists working on nonlinear dynamics and to make nonlinear dynamics accessible and reproducible.

Of course, for such an ambitious goal to be achieved, many of us should try to work together to improve the library! If you want to help the cause, there are many ways to contribute to the DynamicalSystems.jl library:

  1. Just use it. If you encountered unexpected behavior simply report it either on our gitter chatroom or using the DynamicalSystems.jl Issues page.
  2. Suggest methods that you think should be included in our library. This should be done by opening a new issue that describes the method, gives references to papers using the method and also justifies why the method should be included.
  3. Contribute code by solving issues. The easiest issues to tackle are the ones with label "good first issue".
  4. Contribute code by implementing new methods! That is the most awesome way to contribute! The individual packages that compose DynamicalSystems.jl have plenty of issues with the tag "wanted feature", which can get you started on a big contribution!
  5. Contribute code by defining a new pre-defined dynamical system that you found useful.

Contributing Code

When contributing code, you should keep these things in mind:

  • In general, the speed of the implementation is important, but not as important as the clarity of the implementation. One of cornerstones of all of DynamicalSystems.jl is to have clear and readable source code. Fortunately, Julia allows you to have perfectly readable code but also super fast ;) If necessary add comments to the code, so that somebody that knows the method, can also understand the code immediately.
  • Try to design general, extendable functions instead of unnecessarily specialized to the case at hand.
  • For the documentation strings of new methods and systems please follow the convention of the documentation strings of DynamicalSystems.jl. Specifically, the first section should describe the function in a couple of sentences, its positional arguments and its return value. The next section ## Keyword Arguments describes the keywords. The next section ## Description describes the algorithm in detail if need be. Lastly, papers that are relevant to the method must be cited. Have a look at the documentation strings of lyapunov and lyapunovspectrum to get an idea.

Documentation string style

Documentation strings are the most important thing in your pull request/code. The number 1 priority of DynamicalSystems.jl is highest possible quality of documentation and utmost transparency, and the best way to achieve this is with good documentation strings. In DynamicalSystems.jl we recommend that documentation strings are structured in the following way (and this is also the recommendation we give in the Good Scientific Code Workshop).

  1. Clear call signature in code syntax, including expected input types if necessary. The call signature should ONLY include only the most important information, not list out in detail every keyword!
  2. Brief summary of the function
  3. [Optional] Return value and type if not obvious
  4. [Optional] References to related functions if sensible
  5. [Optional] Keyword arguments list if the function has some
  6. [Optional] Detailed discussion of functionality if function behavior is scientifically involved
  7. [Optional] Citations to relevant scientific papers!

The syntax of the documentation strings follows Documenter.jl protocol. Please see the documentation string of the lyapunov function and use the same structure.