From 7d650c6d4febac6c4319d313ac89a3b89d78abe9 Mon Sep 17 00:00:00 2001 From: Mitzi Morris Date: Tue, 24 Jan 2023 09:08:00 -0500 Subject: [PATCH 1/2] first draft --- designs/0034-stancli-api.md | 93 +++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 designs/0034-stancli-api.md diff --git a/designs/0034-stancli-api.md b/designs/0034-stancli-api.md new file mode 100644 index 0000000..bc91a93 --- /dev/null +++ b/designs/0034-stancli-api.md @@ -0,0 +1,93 @@ +# StanCLI - C++ interface to Stan inference algorithms + +## Overview + +StanCLI provides command-line argument handling +for the transpiled Stan model C++ code, +allowing the user to run the resulting C++ executable +from the Unix shell or Windows terminal. +StanCLI will also anticipate the proposal for new +[Stan output formats](https://github.com/stan-dev/design-docs/blob/master/designs/0032-stan-output-formats.md), +allowing the end-user to configure which information to output and in what format. + +Stan's inference engines are highly configurable. +The command line interface must allow the end user to specify +or override default behavoirs for the following: + +* Inputs + + + Model data - one or more input files which fully specify the values for all Stan program data variables. + + + Initial parameter values, either a combination of exact parameter initializations + plus random initialization according to a uniform distribution of range [-x, x], or setting all parameters to 0. + It should be possible to specify the value of each parameter either exactly or allow random initialization within a range. + +* Outputs - per new Stan output format spec + +* Runtime configuration - random seed plus stride, inference or diagnostic algorithm, and attendant agorithm-specific arguments + + + +Argument parsing is handled by [CLI11](https://github.com/CLIUtils/CLI11), +a header-only C++ library (BSD license). +CLI11 supports common shell idioms, making it easy for the end-user to use, +and the CLI11 API is well structured, documented, and tested, +making it easy for the developer to code against. +Better command-line argument handling will simplify the +wrapper interfaces CmdStanPy, CmdStanR, et al., +which interact with the Stan inference algorithms programmatically. + +## Functional Specification + +The StanCLI interface is compiled together with the transpiled Stan model C++ code +to create a model executable. +Command line arguments consist of either a flag or a keyword-value pair. + +The command line argument structure is completely flat; arguments and flags can be +specified in any order, i.e., commands are not nested into subcommands. +Nested subcommands impose a partial ordering on the command line arguments. +The model development process often requires repeated runs with different configurations. +Adding order constraints to the configuration process adds overhead to an already +complicated task. +Nonetheless, in the following spec, we discuss options by grouping inputs, outputs, and config. + +### Inputs + +* data\_values + +* param\_init\_values + +* param\_init\_range + +### Outputs + +* output\_dir + +* output\_format + +* output\_types + +### Runtime config + +* algo + +* random\_seed, random\_offset + +#### Algorithm-specific config + + + + + + + + + + + + + + + + + From 4cc25ef78a1adcb3678bdb4fbfbcafc52372e687 Mon Sep 17 00:00:00 2001 From: Mitzi Morris Date: Tue, 24 Jan 2023 09:59:23 -0500 Subject: [PATCH 2/2] hmc config --- designs/0034-stancli-api.md | 31 +++++++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/designs/0034-stancli-api.md b/designs/0034-stancli-api.md index bc91a93..2578c3f 100644 --- a/designs/0034-stancli-api.md +++ b/designs/0034-stancli-api.md @@ -55,9 +55,10 @@ Nonetheless, in the following spec, we discuss options by grouping inputs, outpu * data\_values -* param\_init\_values +* param\_init\_values - list of parameter names, values for some or all model parameters - overrides random inits + +* param\_init\_ranges - list of parameter names, upper bound x of range which is distributed uniform [-x, x] - used when no init values are supplied. -* param\_init\_range ### Outputs @@ -69,14 +70,36 @@ Nonetheless, in the following spec, we discuss options by grouping inputs, outpu ### Runtime config -* algo +* a, algo, algorithm: one of "hmc", "optimize", "laplace", "variational", "eval-log-prob" * random\_seed, random\_offset -#### Algorithm-specific config +* verbosity - what to report to stdout / stderr ("refresh") + +#### HMC config + +* chains - exec must be compiled for multi-threading + +* hmc_params + + stepsize\_init\_value + + metric\_type - one of unit, diag, or dense + + metric\_init\_values - if specified, must match metric type + +* warmup\_schedule - 3-stage adapt, pathfinder adapt + +* num\_draws - draws post-warmup + +* hmc\_output config + + save\_adaptation - boolean + + post\_draws - number of post-adaptation draws to report + + report\_gradiants ("diagnostics-file") +* hmc\_nuts\_config + + max\_treedepth + + adapt\_delta (metropolis accept rate?) +Note: eliminate notion of thinning - use binary formats instead