probl

Compile and run Probl programs from Rust.

Probl is a language for probabilities, simulations and forecasts. Write models with variables, functions and loops, then inspect their possible outcomes. This crate is the supported embedding API used by the command-line tool and browser playground.

API reference · Library guide · Try the playground

To run .probl files from a terminal, install probl-cli, which provides the probl command.

Get started

Requires Rust 1.99 or later; the latest stable release is recommended. Add the library to your project:

cargo add probl

Compile a model, run it, and read its reports without parsing output text:

use probl::{Options, compile};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let source = r#"
        let total ~ 2d6
        report total >= 10 as "ten or more"
    "#;
    let program = compile("dice.probl", source)?;
    let outcome = program.run(&Options::new())?;
    print!("{}", outcome.text());

    if let Some(chance) = outcome.report("ten or more")
        .and_then(|report| report.groups().first())
        .and_then(|group| group.probability())
    {
        println!("point: {:?}, complete: {}", chance.point(), chance.is_complete());
    }
    Ok(())
}

The model enumerates two six-sided dice and reports a probability of 6/36, displayed as 16.67%. Compilation returns a reusable Program; it does not run the model or open data files.

Execution and results

• Modes: the program's mode applies unless overridden. The default enumerates; it does not automatically fall back to sampling. For sampling, pass options such as Options::new().runs(100_000).seed(42).
• Structured results: Outcome exposes reports, evidence, unresolved weight, sampling metadata and execution statistics, as well as formatted text.
• Data: models using read load their inputs through Program::load and a host-chosen Files provider. Use MemoryFiles for supplied bytes or LocalFiles for native filesystem access.
• Host controls: options configure resource limits, cancellation, progress callbacks and fixed Date/DateTime snapshots through Options::today and Options::now.
• Errors: compilation, loading and execution return diagnostics. In partial failure mode, execution still returns an error; Error::partial() exposes the available results explicitly.

Interpret a probability's point() together with is_complete(), bounds() and its sampling uncertainty. An available point does not guarantee a complete answer. Enumeration uses floating-point weights, and sampling carries Monte Carlo error.

The library guide explains data loading, errors and result interpretation. The language guide and examples introduce model writing.

Compatibility

The Rust minimum may advance in future releases. Each release declares its requirement in Cargo metadata; see the toolchain policy.

Probl is early-stage software; the language and Rust API are evolving. Use this crate to embed Probl. probl-number, probl-syntax, probl-sema and probl-engine are internal components with no stable API; the hidden probl::__internal adapter is also outside the supported API.

License

Licensed under either the MIT license or Apache License, Version 2.0, at your option.