STANC(1)

📦
version 2.40.0 · 2 versions
, in nixpkgs unstable

💅 STANC(1) — like, the Stanc Manual, bestie ✨

okay so real talk: this is the manual page for stanc, and I'm gonna walk you through it like we're texting at 1am 🫶 it's literally the Stan compiler (aka stanc or stanc3), and I promise it's not scary.

🌸 NAME 🌸

stanc — compile Stan programs to C++ 🔥

✨ SYNOPSIS ✨

stanc [OPTION]… [MODEL_FILE]

🦋 DESCRIPTION 🦋

So the Stan compiler — which honestly goes by stanc or stanc3, pick your fave 💅 — reads a Stan file and compiles it to C++. That's the main character job. But it ALSO does other Stan program manipulation, like formatting (--auto-format) and introspection (--info). Versatile queen 👑.

Wanna know more about Stan in general? https://mc-stan.org — go look, it's giving documentation.

More docs on the compiler, like, for users? https://mc-stan.org/docs/stan-users-guide/using-stanc.html 🌈

And for the devs, more compiler info lives at %%PKG_DOC%% 🧚

🎀 ARGUMENTS 🎀

  • MODEL_FILE — the Stan model file you want to compile. It should be a file ending in .stan or .stanfunctions (and ooooh, ending in .stanfunctions automatically sets --standalone-functions for you, slay ✨), or you can pass '-' to read from standard input 🍓

💖 OPTIONS 💖

okay this is the long part, stay with me, we're gonna get through it together 🫶

  • -? [=FMT] (default=auto) — literally just a synonym for --help. same vibe, different key 💅
  • --allow-undefined — don't fail if a function is declared but not defined. usually that means the definition is gonna show up later as a C++ function, so like, it's fine, it's handled 🙈
  • --auto-format — outputs a formatted version of the Stan program. you can tweak that output with --max-line-length and --canonicalize ✨
  • --canonicalize=OPTIONS — turn on specific canonicalizations in a comma separated list. the options are 'deprecations', 'parentheses', 'braces', 'includes', 'strip-comments' 🧚
  • --color=WHEN (absent=auto or STANC_COLORS env) — colorize the output. WHEN has to be one of auto, always or never. aesthetic decisions are valid 🌈
  • --filename-in-msg=FILENAME (absent=MODEL_FILE) — sets the filename used in compiler and runtime errors 👑
  • --help[=FMT] (default=auto) — shows this help in format FMT. FMT must be one of auto, pager, groff or plain. with auto, the format is pager or plain whenever the TERM env var is dumb or undefined 💀
  • -I DIRS, --include-paths=DIRS (absent="") — a comma-separated list of directories that get searched whenever an #include directive is parsed. like a little scavenger hunt for includes 🍓
  • --info — if set, print information about the model 👀
  • --max-line-length=LENGTH (absent=78) — sets the max line length for the formatter. 78 is the default, no cap 📏
  • --name=NAME (absent=MODEL_FILE_NAME_model) — takes a string and sets it as the model name. this controls the namespace in the generated C++ 🏷️
  • -o FILENAME, --output=FILENAME — output file for generated C++ code (default = "MODEL_FILE_NAME.hpp") or for auto-formatting output (default: no file/print to stdout) 💾
  • --O0 — (Default) do not apply optimizations to the Stan code. it's giving unbothered 😌
  • --O1 — only basic optimizations are applied. Recommended ⭐ also: the deprecated option --O is aliased to this starting in Stan 2.37, so heads up 🫶
  • --Oexperimental — (Experimental) apply ALL compiler optimizations. some of these are not thorougly tested and may not always improve a program's performance. it's giving risky behavior, don't say I didn't warn you 💀
  • --print-canonical — prints the canonicalized program. equivalent to --auto-format --canonicalize=deprecations,includes,parentheses,braces ✨
  • --print-cpp — if set, output the generated C++ Stan model class to stdout 🔥
  • --standalone-functions — if set, the generated C++ will only contain the code for the functions in the functions block, not the full Stan model class. minimalism, we love her 🎀
  • --use-opencl — if set, try to use matrix_cl signatures for supported Stan Math functions 🖥️
  • --version — show version information 🌸
  • --warn-pedantic — emit warnings about common mistakes in Stan programs. Note: this may produce false positive warnings, so like, don't spiral 🙈
  • --warn-uninitialized — (Experimental) emit warnings about uninitialized variables 👀

💜 COMMANDS 💜

these flags make the compiler exit right after printing info. no MODEL_FILE required, bestie, you can just run them 🫶

  • --dump-stan-math-distributions — dumps out the list of supported probability distributions and their supported suffix types for the Stan Math backend 📊
  • --dump-stan-math-signatures — dumps out the list of supported function signatures the for Stan Math backend 📋

🔧 EXTRA OPTIONS 🔧

these flags are provided primarily for development and debugging. their exact behavior should not be relied on. like, fr fr, don't build your whole thing on these 💀
  • --debug-ast — for debugging purposes: print the undecorated AST, before semantic checking 🌱
  • --debug-data-file=JSON_FILE — provide (possibly partially specified) data block values for use with --debug-generate-data or --debug-generate-inits 📁
  • --debug-decorated-ast — for debugging purposes: print the decorated AST, after semantic checking 🎄
  • --debug-generate-data — for debugging purposes: generate a mock dataset to run the model on 🎲
  • --debug-generate-inits — for debugging purposes: generate a mock initial value for each parameter 🎯
  • --debug-lex — for debugging purposes: print the lexer actions 🔍
  • --debug-lir — for debugging purposes: print the C++ LIR as a s-expression. mainly for comparison with --print-cpp 🧬
  • --debug-mem-patterns — for debugging purposes: print a list of matrix variables and their memory type, either AoS (array of structs) or the more efficient SoA (struct of arrays). only has an effect when optimizations are turned on 🧠
  • --debug-mir — for debugging purposes: print the MIR after lowering ⬇️
  • --debug-mir-pretty — for debugging purposes: pretty-print the MIR after lowering 💅
  • --debug-optimized-mir — for debugging purposes: print the MIR after it's been optimized. only has an effect when optimizations are turned on ⚡
  • --debug-optimized-mir-pretty — for debugging purposes: pretty-print the MIR after it's been optimized. only has an effect when optimizations are turned on ✨
  • --debug-parse — for debugging purposes: print the parser actions 🔎
  • --debug-print-factor-graph — for debugging purposes: print a conservative over-approximation of the factor graph for the model(s) implemented in the Stan program 🕸️
  • --debug-transformed-mir — for debugging purposes: print the MIR after the backend has transformed it 🔄
  • --debug-transformed-mir-pretty — for debugging purposes: pretty-print the MIR after the backend has transformed it 🎀
  • -f SETTING — debugging features. valid values: -fsoa to force on the Struct of Arrays optimization, -fno-soa to force it off 🔨

🌟 EXIT STATUS 🌟

  • 0 — on success. we love a happy ending 💖
  • 1 — on compilation failure 😭
  • 124 — on command line parsing errors 🫠
  • 125 — on internal compiler errors. Please file a bug! like genuinely, tell them, they wanna know 🐛

🌈 ENVIRONMENT 🌈

these environment variables affect how stanc runs:

  • STANC_COLORS — see option --color 🎨

🍓 BUGS 🍓

please report at %%PKG_ISSUES%% 🐞 don't suffer in silence, bestie 🫶

okay that's the whole thing! and for the cute sign-off: this page is from Stanc stanc3 v2.40.0 (Unix) — that's the source/version you're looking at, mwah 💋 go compile something iconic 👑✨

📦 where this page comes from