-
Notifications
You must be signed in to change notification settings - Fork 1
Torsten Development Process
This page contains a few tips to get started as a Torsten contributor. As much as possible, we try to follow the Stan development process, which is described on this page: https://github.com/stan-dev/stan/wiki/Developer-process-overview.
Users can report an issue or request a new feature by raising an issue on the appropriate GitHub repo. Torsten lives in three repos:
- Math Code: https://github.com/charlesm93/math
- Stan Code: https://github.com/charlesm93/stan
- Examples: https://github.com/charlesm93/example-models/PKPD/torsten
I encourage users to first raise issues on the example repo. We can then look for a fix. If we find there is indeed a bug with Torsten or a new desirable feature, you should raise an issue on the math repo.
The torsten-master branch directs you to the lastest release. The torsten-develop branch corresponds to the most recent functional branch (i.e. all unit tests pass). The branches may be out of synch. For example, a function may exist on math, but may not be exposed to Stan yet, nor reported in the user manual. Note the master and develop branches will not have torsten files, but will direct you to some version of the original Stan code.
To run the unit tests in math, from the math repo:
./runTests.py test/unit/math/torsten/
From the stan repo:
./runTests.py src/test/unit/lang/parser/torsten_functions_test.cpp
stan is not a stand-alone repo and depends on math. Under stan you should have the directory lib/stan_math_2.15.0 that contains the math repo (if it's not there, create it!). That is, build math inside \lib and rename it stan_math_2.15.0. The name of the repo depends on the version of Stan, which in turn depends on the version of Torsten. For instance, Torsten v0.82 is compatible with Stan 2.14.0, whereas the current development version of Torsten (v0.83-beta) works with Stan 2.15.0. This further implies there needs to be some compatibility between your stan and math repo. For instance, stan at torsten-develop may not work with math at torsten-master. If both repos are at torsten-develop, the unit tests should always compile.
We've had an issue in the past with the make file which gets called by ./runTests.py, and found it helpful to look at the compiler the makefile calls. Switching from g++ to clang++ did the trick for a colleague of mine.
There are currently no unit tests in the example repo. We may get to it later, but if the unit tests in the math and stan repo do their job, we shouldn't need more than that.
After raising an issue and coming up with a design, create a new branch from torsten-develop. Use a descriptive name. For example, for issue #29 Steady State Solution for General Compartment Model, I created a branch called issue-29-general-SS. You can create a new branch on the GitHub webpage or after cloning the repo on your local machine.
Open a terminal window.
To clone: git clone <url>.
View branch you're on: git branch
Change branch git checkout <branch_name>
Once you've made changes, you can monitor which files have been modified using git status. Before doing a commit, you need to specify which files you are going to stage for the commit:
git add <file_name>git add *
You can unstage a file using git rm <file_name>.
After staging the files you wish to add, use git commit -m '<descriptive title of the commit>'.
You can then push your local changes to the gitHub cloud: git push.
To get your local version of the repo up to date with what is online: git pull.
The repos torsten lives on are forked versions of Stan. Every so often, we want to get up to speed with Stan's core language. To do this, we update the develop branch on our forked repo using the parent repo: git pull parent develop. Git will then ask for a commit message. We can then create a pull request to merge to updated develop branch into torsten-develop.
Here are some helpful resources:
- https://github.com/stan-dev/stan/wiki/Contributing-New-Functions-to-Stan
- https://arxiv.org/abs/1509.07164
Half of the work is coding the unit tests. The torsten ones are located under test/unit/math/torsten/. There are some intermediate unit tests which I use during the development process. These are located in directories under torsten. Unit tests should make sure:
- functions produce the desired output given various inputs
- the gradients with respect to the parameters of interest get properly computed
- the function produces helpful error messages and throws exceptions when needed
(1.) is straightforward, though it's not easy to anticipate every use case. As a result, the unit tests usually grow with time, especially as bugs get fixed. (2.) can be done using the code in util_*.hpp, which compares automatic diff to finite diff. This is also a great way to test if the code can handle variables of the type stan::math::var. (3.) I have mostly not implemented it in torsten yet, but the stan math library has plenty of examples.
We can submit a pull request once:
- all the unit tests in torsten pass
- the
make cpplinttest passes (checks if coding standard have been met. Makes for more standardized and clearer code). - you have declared the author and a license for the code.
The unit tests in Stan are meant to make sure we can call a function in a Stan file. Usually, we'll write one model with all working signatures and make sure it parses, and then a few bad models meant to prompt error messages. We want to make sure the right error message are sent. Usually, we won't prompt signature errors (used an int instead of a real, etc.) rather, more "sophisticated" errors: for example if we pass a function argument for an ODE, we want to make sure it has the right signatures.
I haven't implemented the bad models yet.