Document Stan Math expressions requirements

[rok-cesnovar]

Stan Math functions that are meant to be exposed in the Stan language have 2 expressions requirements:

• they have to be able to accept Eigen expressions
• they have to work with the expressions efficiently (not evaluate them multiple times)

This is not really documented or expressed clearly for Stan Math developers I think. We need to mention this somewhere more prominently.

It should also mention that you can test expressions for a function not currently exposed in Stan by running:

python3 runTests.py test/expressions/ --only-function "foo(vector) => vector"

[spinkney]

A few notes. It is possible to run all the tests for a particular function if you have stanc3 built. Let's first build stanc3 (tested on a mac)

• Add make, git, curl, and m4 via apt, homebrew, or your system's package manager if you don't already have it
• Download the stanc3 repository (or your fork of it) from Github
• Install the necessary dependencies by running

   cd scripts; bash -x ./setup_dev_env.sh

• in the terminal at the stanc3 directory run eval $(opam env). Don't worry, there should be no output.
• Pin the version we need by opam pin -y core_kernel v0.14.2
• You can now build a stanc binary by running make. If this succeeds, you have the required software.

Next, we need to go into the stan-math directory. If you have run any expression tests prior to this you need to clean the test/expressions folder. There should only be two files in the test/expressions folder: expression_test_helpers.hpp and test_expression_testing_framework.py. If you have more, delete them.

In the main directory of stan-math cd into the make directory. You need to add a local file with the location of stanc by adding STANC3=/location/to/stanc3 in the local file.

Go back to the main stan-math directory and try running the expression test for the function

python3 runTests.py test/expressions/ --only-function "function"

If you get an error saying dune not found or something similar then run eval $(opam env) in the terminal to set the path to dune. Try again.