Crate bridgestan 

BridgeStan from Rust

View the BridgeStan documentation on Github Pages.

This is a Rust wrapper for BridgeStan. It allows users to evaluate the log likelihood and related functions for Stan models natively from Rust.

Internally, it relies on bindgen and libloading.

Compiling the model

The Rust wrapper has the ability to compile Stan models by invoking the make command through the compile_model function.

This requires a C++ toolchain and a copy of the BridgeStan source code. The source code can be downloaded automatically by enabling the download-bridgestan-src feature and calling download_bridgestan_src. Alternatively, the path to the BridgeStan source code can be provided manually.

For safety reasons all Stan models need to be built with STAN_THREADS=true. This is the default behavior in the compile_model function, but may need to be set manually when compiling the model in other contexts.

If STAN_THREADS was not specified while building the model, the Rust wrapper will throw an error when loading the model.

Usage

Run this example with cargo run --example=example.

use std::ffi::CString;
use std::path::{Path, PathBuf};
use bridgestan::{BridgeStanError, Model, open_library, compile_model};

// The path to the Stan model
let path = Path::new(env!["CARGO_MANIFEST_DIR"])
    .parent()
    .unwrap()
    .join("test_models/simple/simple.stan");

// You can manually set the BridgeStan src path or
// automatically download it (but remember to
// enable the download-bridgestan-src feature first)
let bs_path: PathBuf = "..".into();
// let bs_path = bridgestan::download_bridgestan_src().unwrap();

// The path to the compiled model
let path = compile_model(&bs_path, &path, &[], &[]).expect("Could not compile Stan model.");
println!("Compiled model: {:?}", path);

let lib = open_library(path).expect("Could not load compiled Stan model.");

// The dataset as json
let data = r#"{"N": 7}"#;
let data = CString::new(data.to_string().into_bytes()).unwrap();

// The seed is used in case the model contains a transformed data section
// that uses rng functions.
let seed = 42;

let model = match Model::new(&lib, Some(data), seed) {
    Ok(model) => model,
    Err(BridgeStanError::ConstructFailed(msg)) => {
        panic!("Model initialization failed. Error message from Stan was {msg}")
    }
    Err(e) => {
        panic!("Unexpected error:\n{e}")
    }
};

let n_dim = model.param_unc_num();
assert_eq!(n_dim, 7);
let point = vec![1f64; n_dim];
let mut gradient_out = vec![0f64; n_dim];
let logp = model.log_density_gradient(&point[..], true, true, &mut gradient_out[..])
    .expect("Stan failed to evaluate the logp function.");
// gradient_out contains the gradient of the logp density

Structs

Model

A Stan model instance with data

Rng

A random number generator for Stan models. This is only used in the Model::param_constrain() method of the model when requesting values from the generated quantities block. Different threads should use different instances.

StanLibrary

A loaded shared library for a Stan model

Enums

BridgeStanError

Error type for bridgestan interface

Constants

VERSION

Functions

compile_model

Compile a Stan Model. Requires a path to the BridgeStan sources (can be downloaded with download_bridgestan_src if that feature is enabled), a path to the .stan file, and additional arguments for the Stan compiler and the make command.

download_bridgestan_src

Download and unzip the BridgeStan source distribution for this version to ~/.bridgestan/bridgestan-$VERSION. Requires feature download-bridgestan-src.

open_library

Open a compiled Stan library.