getting-started.md

Getting Started

Install the crate, pick a feature set, and run your first learner and first WFST in a few lines. Deeper guides: learner-guide.md, wfst-guide.md, cookbook.md.

1. Install

[dependencies]
# Full crate: online learner + MSM-as-WFST embedding.
adaptive-msm = "0.1"

# Or, learner only (no lling-llang / WFST framework):
# adaptive-msm = { version = "0.1", default-features = false }

Bring the API into scope with the prelude:

use adaptive_msm::prelude::*;

2. Your first learner (30 seconds)

Adapt the MSM split/merge constant $c$ online from observed costs:

use adaptive_msm::{AdaptiveMsm, AdaptiveMsmConfig};

let mut learner = AdaptiveMsm::new(
    AdaptiveMsmConfig::new()
        .initial_c(1.0)
        .epsilon(1.0)
        .seed(42),          // reproducible
);

let query = [1.0, 2.0, 3.0];
let target = [2.0, 3.0, 4.0];

// One round: explore a perturbed c (predict), then report the observed cost.
let predicted = learner.predict(&query, &target);
learner.observe(predicted);          // any scalar cost signal works

println!("c is now {}", learner.current_c());

predict draws a perturbed $c$ and returns the MSM distance at it; observe attributes the cost back and updates $c$. See the mechanism in ../design/adaptive-learner.md and the theory in ../theory/online-learning-fptl.md.

3. Your first WFST (30 seconds)

Build the MSM-as-WFST lattice for a query against candidate series (requires the default wfst feature):

use adaptive_msm::wfst::{MsmWfst, MsmWfstBuilder};
use adaptive_msm::MsmConfig;
use lling_llang::prelude::{LazyWfst, Wfst};

let mut wfst: MsmWfst = MsmWfstBuilder::new()
    .query(&[1.0, 2.0, 3.0])
    .msm_config(MsmConfig::new(1.0))
    .max_cost(10.0)                       // prune paths above this cost
    .add_target(0, &[1.0, 2.0, 3.0])
    .add_target(1, &[2.0, 3.0, 4.0])
    .build()
    .expect("query and at least one target are set");

let start = Wfst::start(&wfst);
wfst.expand(start);                       // lazy: materialize on demand
assert!(wfst.num_states() >= 2);          // one initial state per candidate

The tropical shortest path over this lattice equals MsmConfig::distance (../design/msm-wfst-embedding.md); a full runnable shortest-distance is in cookbook.md and examples/cookbook.rs.

4. If you just want the number

For a plain MSM distance (no learning, no WFST), use MsmConfig directly — it is re-exported for convenience:

use adaptive_msm::MsmConfig;

let d = MsmConfig::new(1.0).distance(&[1.0, 2.0, 3.0], &[1.0, 2.5, 3.0]);
assert!(d >= 0.0);

5. Verify your setup

cargo test --all-features   # runs the runnable doc examples too
cargo run --release --example cookbook

Next steps

Goal	Guide
Full learner API, tuning, statistics	learner-guide.md
Full WFST API, composition, caching	wfst-guide.md
End-to-end recipes	cookbook.md
What is $c$ and why learn it	../theory/msm-metric.md