Skip to content

Getting Started

Jump to bottom
Metodi Latinov edited this page Sep 18, 2026 · 1 revision

Getting Started

This page takes you from nothing installed to a sampled model. There are two routes. The terminal route uses the laplace command-line tool directly. The R route uses cmdlaplacer, a small R package that wraps laplace and cmdstanr so you never have to leave R. Both produce exactly the same .stan file.

Commands are shown for macOS and Linux.

1. What you need

To... You need
Install laplace git and a Rust toolchain (Cargo 1.78 or newer, from rustup)
Compile .laplace files to .stan Only laplace. Stan is not required.
Sample a model CmdStan, most easily through cmdstanr

If you install Rust through your Linux distribution's package manager, check cargo --version first. Distribution packages are often too old to read Laplace's Cargo.lock. The rustup toolchain is always recent enough.

2. Install laplace

From the terminal

git clone https://github.com/mlatinov/laplace
cd laplace
cargo install --path . --root ~/.local

Add the install directory's bin/ to your PATH if it isn't already there (put this line in your ~/.bashrc or ~/.zshrc to make it permanent):

export PATH="$HOME/.local/bin:$PATH"

Then check that it works:

laplace --help

To update later, run git pull in the cloned repository and repeat the install command with --force added.

From R

If git and cargo are already on your PATH, cmdlaplacer can do all of the above for you:

# install.packages("remotes")
remotes::install_github("mlatinov/cmdlaplacer")
 
library(cmdlaplacer)
laplace_install()

laplace_install() clones the Laplace repository, runs the same cargo install command shown above, and adds ~/.local/bin to PATH for the current R session. It is a convenience wrapper, not a separate build: the binary is identical to the one you get from the terminal.

To sample models from R you also need cmdstanr and CmdStan:

install.packages("cmdstanr", repos = c("https://stan-dev.r-universe.dev", getOption("repos")))
cmdstanr::install_cmdstan()

3. Create a project and add a library

A Laplace project is just a directory containing your .laplace model. Create one, then add a library. This example uses transformations, a small library of data-scaling functions:

mkdir my-first-model
cd my-first-model
 
laplace add transformations \
  --git https://github.com/mlatinov/laplace-transform --tag 0.1.0 --subdir laplace

This creates two files next to your model:

  • laplace.toml records what you asked for: the transformations library, from that repository, at tag 0.1.0. You can edit it by hand.
  • laplace.lock records exactly what was resolved, with a checksum. It is written by Laplace; you never edit it. Commit both files to git.

4. Write your first model

Save this as model.laplace. It is an ordinary Stan linear regression with one addition: a library { } block that imports transformations, whose standardize() function is then called as transformations::standardize().

library {
  import transformations
}
 
data {
  int<lower=1> N;
  vector[N] x;
  vector[N] y;
}
 
transformed data {
  vector[N] x_std = transformations::standardize(x);
}
 
parameters {
  real alpha;
  real beta;
  real<lower=0> sigma;
}
 
model {
  alpha ~ normal(0, 2.5);
  beta  ~ normal(0, 2.5);
  sigma ~ exponential(1);
 
  y ~ normal(alpha + beta * x_std, sigma);
}

To see what any library function does before you use it, look it up:

laplace doc transformations::standardize

5. Build it

Run the build from the project directory, where laplace.lock lives:

laplace build model.laplace

This writes build/model.stan. Open it. You will find:

  • The library { } block is gone, because it means nothing to Stan.
  • A functions { } block now contains the full source of standardize, renamed transformations__standardize, including its documentation comment.
  • The call site now reads transformations__standardize(x).
  • Every other line is exactly what you wrote. That file is plain Stan. It runs without Laplace installed, and it is meant to be committed alongside your source.

If you have stanc available, laplace build model.laplace --validate also type-checks the generated file. Set the LAPLACE_STANC environment variable if stanc is not on your PATH.

6. Sample it

With cmdstanr

Because the output is plain Stan, cmdstanr uses it like any other model:

library(cmdstanr)
 
set.seed(1)
N <- 100
x <- rnorm(N, mean = 50, sd = 10)
y <- 2 + 0.5 * (x - mean(x)) / sd(x) + rnorm(N, sd = 0.3)
 
mod <- cmdstan_model("build/model.stan")
fit <- mod$sample(data = list(N = N, x = x, y = y))
fit$summary()

With cmdlaplacer

laplace_model() runs the build step and hands the result to cmdstanr in one call. It returns an ordinary cmdstanr model object, so everything after that is standard cmdstanr:

library(cmdlaplacer)
 
mod <- laplace_model("model.laplace")
fit <- mod$sample(data = list(N = N, x = x, y = y))

Pass stan_only = TRUE to get the path to the generated .stan file instead of a model object, if you want to inspect it or drive cmdstanr yourself.

Libraries hosted on git can also be added from R. laplace_install_git() wraps laplace add --git:

laplace_install_git(
  "transformations",
  "https://github.com/mlatinov/laplace-transform",
  tag = "0.1.0",
  subdir = "laplace"
)

7. Opening the project on another machine

Clone the project, then run:

laplace install
laplace build model.laplace

laplace install reads only laplace.lock, so it installs exactly the library versions you used, byte for byte. Nothing is re-resolved.

Where to go next

Built on

Laplace and cmdlaplacer rely on Stan for all modeling and inference, and cmdlaplacer uses cmdstanr, developed by Jonah Gabry, Rok Češnovar, Andrew Johnson and contributors, to compile and run models from R. If you publish results from a model built with Laplace, please cite Stan and cmdstanr. In R, citation("cmdstanr") gives the current reference, and the Stan project lists how to cite Stan at https://mc-stan.org/users/citations/.

Clone this wiki locally