Development (original) (raw)

Guidelines

Developers without write access to the adcomp repository can contribute with code or documentation by forking the project and sending a pull request once the code has been changed.

Recommended workflow (fork and pull request)

• Let your own master branch be an exact copy of the official master branch:
  git remote add official https://github.com/kaskr/adcomp.git
  Synchronize frequently:

git checkout master  
git pull official master  

• Never commit directly to your master. Work on a local branch and send pull requests only for the local branch:
  git checkout -b local_branch
  Do work, commit and push to you github account:
  git push origin local_branch
  Send pull request for 'local_branch'.
• Once your pull request is accepted, synchronize the master branch:

git checkout master  
git pull official master  

And delete you local branch
git branch -d local_branch
Remember to delete it on github:
git push origin --delete local_branch

For developers with write access to the adcomp repository:

• The master branch should be stable and never get into a broken state. Therefore: Never push changes directly to the master branch. Development must be performed on a separate branch (named by e.g. developers name or the topic of change) which is pushed to the adcomp repository.
• When code is ready, send request to review and merge into the master branch.
• The following tests must be performed before changes can be merged (to ensure nothing is broken on any platforms):
  • cd tmb_examples;make clean;make must pass.
  • The file REPORT.md must be inspected for inaccuracies and performance regressions.
  • runExample(all=TRUE) must pass.
  • Above should be tested with both gcc and clang on linux.
  • Tests should also be run on Windows and OSX.

Conventions

• Text files should have Unix line endings. Check with file command from command line that output looks like e.g. sdv_multi.cpp: ASCII C program text without CR+LF.
• Text files should not be executable.

Code formatting

Automated code formatting is recommended for new files

• For internal C++ use
  clang-format-3.6 -i -style="{BasedOnStyle: Google, Standard: Cpp03}" file.cpp
• For C++ model templates use
  clang-format-3.6 -i -style="{BasedOnStyle: Google, Standard: Cpp03, BreakBeforeBraces: Linux}" file.cpp
• For R code use
  library(formatR)
  tidy_source("file.R", arrow=TRUE)

Distributing code

Probably the easiest way to distribute TMB code is to use R's package functionality. You can get a test package working following these steps (with mypkg replaced by the name of your package):

• package.skeleton("mypkg")
• Copy model.cpp to mypkg/src
• Add Depends: TMB LinkingTo: TMB, RcppEigen to the file mypkg/DESCRIPTION to ensure that TMB is loaded when mypkg is loaded, and that the TMB source code is found when compiling mypkg.
• Add useDynLib(mypkg) to the file mypkg/NAMESPACE to ensure that the compiled code is loaded when you load the package.
• Pass DLL="mypkg" to all MakeADFun calls.

TMB uses some features that are against the CRAN polices (e.g. calling abort() to step into the debugger). In order to pass CRAN checks a few workarounds may be required:

• Edit model.cpp to avoid CRAN warning Found no calls to: ‘R_registerRoutines’, ‘R_useDynamicSymbols’:

#define TMB_LIB_INIT R_init_mypkg  
#include <TMB.hpp>  

In addition this enables 'C-callables' tmb_forward and tmb_reverse required by tmbstan.

• To avoid notes such as Found ‘_ZSt4cout’, possibly from ‘std::cout’ (C++) use the CRAN version of TMB when checking the package.
• To avoid the warning Found ‘_abort’, possibly from ‘abort’ make sure the preprocessor flag -DTMB_SAFEBOUNDS does not appear during compilation (if you use your own Makefile pass safebounds=FALSE to compile).
• To avoid the warning Found non-API call to R: ‘R_RunExitFinalizers’ make sure the preprocessor flag -DTMB_SAFEUNLOAD does not appear during compilation (if you use your own Makefile pass safeunload=FALSE to compile).

Other notes:

• While developing you can add a file mypkg/src/Makevars with compiler and preprocessor flags - see the relevant section in the R Extensions manual ; PKG_CXXFLAGS="-O0 -g" can be used for debugging.

Locating regressions and bugs

Suppose you update TMB and suddenly your model runs slow or has other issues. To find the commit that caused the problem, we can apply 'git bisect'.

1. Clone a fresh adcomp folder and cd adcomp.
2. Copy a selfcontained test example e.g. 'mymodel.R' and 'mymodel.cpp' to this folder.
3. Make R-script 'bisect.R' containing:

Re-install TMB and re-compile model:

system("make install")
library(TMB)
system("rm -f *.o *.so")
compile("mymodel.cpp")

Run model under restricted permissions

status <- system("ulimit -t 20; R --vanilla < mymodel.R")
if(status != 0) stop("Fail")
Here 'ulimit -t 20' interrupts the model run if it takes more than 20 sec. Alternatively 'ulimit -v 100000' would trigger interruption if the model uses more than 100Mb. 4. Make an executable shell script 'bisect.sh' containing:
#/bin/bash
R --vanilla < bisect.R 5. Verify that the script fails now and that it worked e.g. 40 commits ago:
git checkout master
./bisect.sh
git checkout HEAD40
./bisect.sh 6. Now we can start bisecting:
git checkout master
git bisect start
git bisect bad HEAD
git bisect good HEAD40
git bisect run ./bisect.sh
The first bad commit will be displayed.