Expand description
Compile and run Probl programs from Rust.
Probl is a small language for explicit random choices and weighted worlds:
a draw explores its outcomes, each in a world of its own, weighted by how
likely it is, and a report collects what the worlds say. This crate is
its supported API; the command line (probl-cli) and the playground are
built on it.
let source = "let a ~ d6\nlet b ~ d6\nreport a + b >= 10 as \"ten or more\"";
let program = probl::compile("dice.probl", source)?;
let outcome = program.run(&probl::Options::new())?;
let ten = outcome.report("ten or more").unwrap().groups()[0].probability().unwrap();
assert!((ten.point().unwrap() - 6.0 / 36.0).abs() < 1e-12);
assert!(ten.is_complete());
assert_eq!(outcome.text(), "enumerated\n\nten or more 16.67%\n");A run’s Outcome has its text, as probl run prints
it, and each report’s numbers, with what’s known about their accuracy:
whether unresolved weight affects them, their bounds, and when sampling,
their Monte Carlo error. A program that reads data has it loaded first,
with Program::load, from Files the host chooses.
The crates probl-syntax, probl-sema and probl-engine are internal:
their APIs change with every release.
Structs§
- Cancel
- Stops a run, or the loading of data, from another thread. Clones share the same switch.
- Confidence
Interval - Data
- A program’s data, read by
Program::load. It can be given to any number of runs of that program. - Data
Source - A file, or standard input, that was read: what results were computed from.
- Date
- A calendar date, from 0001-01-01 to 9999-12-31. It prints, and parses,
as
YYYY-MM-DD. - Diagnostic
- An error or a warning about a place in a program. It keeps the program’s source, so it can render itself.
- Error
- A problem compiling a program, loading its data or running it.
- Estimate
- One reported quantity, such as a probability or a mean, with what’s known about its accuracy.
- Evidence
- The evidence: the probability (or density) of what the program observed, as a natural logarithm, so that tiny likelihoods don’t underflow.
- Exact
Updates - How one variable’s draws were delayed and updated exactly, over all the runs.
- Failure
- The worlds of a partial run that failed at one place, with one kind of fault (docs/semantics.md, section 11).
- Group
- What a report saw for one key.
- Interval
- A range of numbers, both ends included.
- Limits
- Upper bounds on what a run, and the loading of its data, may do. A
program’s
@max_worldsand@max_iterationscan lower them, never raise them. The default is the command line’s; change a field to change one: - Local
Files - Local files, for someone running their own programs: the program is trusted, but not with anything but files.
- Memory
Files - Files given as bytes, by the path a program reads them with. There’s no standard input.
- Numeric
Summary - The summaries of real numbers, or of continuous values.
- Options
- How to run a program. Every setting is optional:
- Outcome
- What a run gives back.
- Parse
Date Error - A date that isn’t
YYYY-MM-DD, or is out of range. - Program
- A compiled program. Cloning it is cheap, and it can run any number of times, from any thread.
- Report
- One
report: what it saw, for each of its keys. - Sampling
- How a program was sampled.
- Sampling
Uncertainty - A sampled quantity’s Monte Carlo error.
- Snapshots
- Another
Files, keeping the bytes of everything it has read, so that reading it again gives the same data untilclear. The REPL keeps its data this way: it runs a session whose program changes with every input, and earlier bindings mustn’t change under it. - Stats
- How much work the engine did.
- Unresolved
- The weight that loops and limits cut off before it finished: an unnormalized bound, not a probability. When sampling, it’s per run.
Enums§
- Confidence
Method - Error
Kind - What kind of problem an
Erroris. - Evidence
Kind - What kind of number the evidence is.
- Failure
Mode - What a fault in one world, like a division by zero, does to the others (docs/semantics.md, section 11). The world that fails always stops there.
- Mode
- How a program runs: its
@mode, or whatOptionschoose instead. - Sampling
Status - What’s known about a sampled quantity’s Monte Carlo error.
- Severity
- How serious a
Diagnosticis. - Summary
Error - Why
NumericSummary::quantilegave no quantile.
Constants§
- VERSION
- This version of Probl.
Traits§
- Files
- Where
read("…")finds data. A program only names paths: what they refer to, and whether they may be read at all, is the host’s to decide, and a program can’t widen it.