I’ve created a prototype that’s meant to be easier to use than CmdStan. If you’re a CmdStan user, I’d appreciate some feedback on what works and what doesn’t. Please comment here, on discourse, on twitter, or however you can find me.

The license for the prototype is 3-clause BSD (just like CmdStan).

### Quick example: setting delta and max_depth

Here’s how to set delta to 0.9 and max_depth to 14.

Prototype:

> examples/bernoulli/bernoulli sample --delta 0.9 --max_depth 14 \
--data_file examples/bernoulli/bernoulli.data.R


Compare this to CmdStan v2.24.0:

> examples/bernoulli/bernoulli sample adapt delta=0.9 \
algorithm=hmc engine=nuts max_depth=14 \
data file=examples/bernoulli/bernoulli.data.R


What really makes the prototype easier to use is that the order of the options doesn’t matter. “--max_depth 14” could come first or last. In CmdStan, in order to set max_depth, you must keep these things together: “algorithm=hmc engine=nuts max_depth=14”.

## Installation

The prototype is currently on a branch of CmdStan, feature/cli11. Since this is on a branch of CmdStan, there isn’t a single tarball that includes everything. (If there’s enough demand for it, I can package one up.)

These are instructions to get the source code using Git.

> git clone https://github.com/stan-dev/cmdstan cmdstan-cli11
> cd cmdstan-cli11
> git checkout feature/cli11
> git submodule update --init --recursive  # this gets the Stan and Stan Math submodules


That’s it. That will get the prototype and grab all the related dependencies.

### Build

Building the first Stan program will set up everything for you.

> make examples/bernoulli/bernoulli


### Installation Complete

You can now build other executables with the prototype command line interface.

## Usage

The usage of the protoype is similar to CmdStan v2.24.0. There are a few notable differences:

1. The first keyword after the executable name is the subcommand, with the exception of --help and --version flags.
2. Options are specified using dashes: -- for the long form and - for the short form.
3. Option order does not matter.
4. Values can come after the option name with a space or an equal sign.

The output files look exactly as if it were generated by CmdStan.

### Synopsis

The executable is generated in the same way as with the existing CmdStan. To compile the examples/bernoulli/bernoulli.stan Stan program, we’d start with:

> make examples/bernoulli/bernoulli


Once that’s compiled, to run the program, it’d look like:

> examples/beroulli/bernoulli <subcommand> [<options>]


The subcommands are:

1. sample. Bayesian inference with Markov Chain Monte Carlo (aliases: s, mcmc)
2. optimize. Point estimation (aliases: o, optimise)
3. variational. Variational inference (aliases: v, advi)
4. diagnose. Model diagnostics (aliases: d, test)
5. generate_quantities. Generate quantities of interest (aliases: g, gq)

To get more information about any of the subcommands, add the --help flag after the subcommand.

### Examples

Here are just some examples that show the usage of the prototype compared with CmdStan.

#### Sampling

Prototype (each line accomplishes the same thing):

> examples/bernoulli/bernoulli sample --data_file examples/bernoulli/bernoulli.data.R
> examples/bernoulli/bernoulli sample --data_file=examples/bernoulli/bernoulli.data.R
> examples/bernoulli/bernoulli sample -d examples/bernoulli/bernoulli.data.R
> examples/bernoulli/bernoulli mcmc -d examples/bernoulli/bernoulli.data.R
> examples/bernoulli/bernoulli s -d examples/bernoulli/bernoulli.data.R


CmdStan v2.24.0:

> examples/bernoulli/bernoulli sample data file=examples/bernoulli/bernoulli.data.R


#### Sampling with fixed seed and diagnostic file

Prototype:

> examples/bernoulli/bernoulli sample --data_file examples/bernoulli/bernoulli.data.R \
--seed 20200827 --diagnostic_file=diagnostic.csv


CmdStan v2.24.0:

> examples/bernoulli/bernoulli sample data file=examples/bernoulli/bernoulli.data.R \
random seed=20200827 output diagnostic_file=diagnostic.csv


In the prototype, there’s no order dependence of the options (after the subcommand), so you can move the order around. In CmdStan, keywords are often nested. For example, this would fail:

> examples/bernoulli/bernoulli sample data file=examples/bernoulli/bernoulli.data.R \
random seed=20200827 diagnostic_file=diagnostic.csv output


## Motivation

CmdStan has been part of Stan since before v1.0; it was the first interface that turned a Stan program into something that could generate MCMC draws, predating RStan and PyStan. It was designed to be easy to use from the command line, easy to maintain, and easy to extend.

With CmdStan v2.0, these goals weren’t prioritized. This prototype gets closer to those original goals. It intentionally does not stray too far from the existing CmdStan arguments.

As a user, this it’s a lot easier for me to use. If you do find it easier, please let me know. If it’s still too clunky, that’s good to know too.

From a developer perspective, the prototype is soooo much simpler than CmdStan. It makes it easy to extend and add features that we just couldn’t introduce.

Note: this was a one-person effort (from design to implementation). There is definitely room for improvement.

## Next Steps

The immediate next step is to get feedback. If you try it out and end up using it, please let me know! It’ll determine what happens next.

Long term, we (including you) need to determine what to do with the prototype. Logistically, it’ll be hard to replace CmdStan with this because of backwards compatibility. That leads to a few options:

1. If no one else uses it, then I’ll just maintain the branch on CmdStan.
2. If people really like it, then we can name it and either find a place for it in the stan-dev organization (if there’s a lot of community support) or I can maintain it.