use std::{
collections::{
BTreeMap,
BTreeSet,
HashMap,
HashSet,
},
fmt,
sync::Arc,
};
use burn::tensor::TensorData;
use crate::errors::{
BunsenError,
BunsenResult,
};
#[derive(Clone)]
pub struct Rekey {
rules: Vec<Rule>,
transforms: Vec<(String, TensorTransform)>,
unclaimed: Unclaimed,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Unclaimed {
Keep,
Drop,
Pass,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Indices {
AsIs,
From(usize),
Module,
}
pub type Claim = Option<Option<String>>;
pub type TensorTransform = Arc<dyn Fn(TensorData) -> TensorData + Send + Sync>;
#[derive(Clone)]
pub struct Target {
pub path: String,
pub transform: Option<TensorTransform>,
}
impl fmt::Debug for Target {
fn fmt(
&self,
f: &mut fmt::Formatter<'_>,
) -> fmt::Result {
f.debug_struct("Target")
.field("path", &self.path)
.field("transform", &self.transform.is_some())
.finish()
}
}
#[derive(Debug)]
pub struct RekeyPlan {
pub targets: Vec<(String, Option<Target>)>,
pub collisions: Vec<(String, Vec<String>)>,
pub orphan_transforms: Vec<String>,
pub unused_rules: Vec<String>,
pub index_conflicts: Vec<String>,
pub unknown_paths: Vec<(String, String)>,
}
impl RekeyPlan {
pub fn check(&self) -> BunsenResult<()> {
if self.collisions.is_empty()
&& self.orphan_transforms.is_empty()
&& self.index_conflicts.is_empty()
{
return Ok(());
}
let mut details: Vec<String> = self
.collisions
.iter()
.map(|(path, names)| format!("{path} <- {}", names.join(", ")))
.collect();
details.extend(
self.orphan_transforms
.iter()
.map(|path| format!("transform for {path}: no name loads there")),
);
details.extend(
self.index_conflicts
.iter()
.map(|conflict| format!("indices: {conflict}")),
);
Err(BunsenError::invalid_resource(format!(
"the key map loads {} paths from more than one name, has {} transforms no name \
reaches, and {} stacks whose indices do not match the module's",
self.collisions.len(),
self.orphan_transforms.len(),
self.index_conflicts.len()
))
.with_details(details.join("\n")))
}
}
fn compose(
first: Option<TensorTransform>,
then: Option<TensorTransform>,
) -> Option<TensorTransform> {
match (first, then) {
(Some(a), Some(b)) => Some(Arc::new(move |data| b(a(data)))),
(a, b) => a.or(b),
}
}
fn prefixed(
prefix: &str,
target: Target,
) -> Target {
Target {
path: format!("{prefix}{}", target.path),
transform: target.transform,
}
}
fn plain(path: String) -> Target {
Target {
path,
transform: None,
}
}
#[derive(Clone)]
enum Rule {
DropSuffix(String),
Exact(String, String),
Rename(String, String),
Mount(String, String, Rekey),
MountIndexed(String, String, Indices, Rekey),
Custom(Arc<dyn Fn(&str) -> Claim + Send + Sync>),
}
#[derive(Default)]
struct Trace {
rules: HashSet<usize>,
transforms: HashSet<usize>,
}
type StackKey = (usize, String);
#[derive(Default)]
struct Cx<'a> {
trace: Trace,
module: Option<&'a BTreeSet<String>>,
seen: BTreeMap<StackKey, BTreeSet<usize>>,
resolving: bool,
index_maps: HashMap<StackKey, Option<BTreeMap<usize, usize>>>,
index_conflicts: BTreeSet<String>,
}
impl Cx<'_> {
fn module_index(
&mut self,
key: &StackKey,
to: &str,
index: usize,
) -> Option<usize> {
let (Some(module), true) = (self.module, self.resolving) else {
return Some(index);
};
if !self.index_maps.contains_key(key) {
let seen = self.seen.get(key).cloned().unwrap_or_default();
let theirs: BTreeSet<usize> = module
.range(to.to_string()..)
.take_while(|path| path.starts_with(to))
.filter_map(|path| path[to.len()..].split_once('.')?.0.parse().ok())
.collect();
let map = if seen.is_subset(&theirs) {
Some(seen.iter().map(|&i| (i, i)).collect())
} else if seen.len() == theirs.len() {
Some(seen.iter().copied().zip(theirs.iter().copied()).collect())
} else {
self.index_conflicts.insert(format!(
"{}N.: the checkpoint has {seen:?}, the module ({to}N.) {theirs:?}",
key.1
));
None
};
self.index_maps.insert(key.clone(), map);
}
self.index_maps[key].as_ref()?.get(&index).copied()
}
}
fn rule_addr(rule: &Rule) -> usize {
std::ptr::from_ref(rule) as usize
}
fn transform_addr(f: &TensorTransform) -> usize {
Arc::as_ptr(f).cast::<()>() as usize
}
impl Rule {
fn describe(&self) -> String {
match self {
Rule::DropSuffix(suffix) => format!("drop_suffix({suffix:?})"),
Rule::Exact(from, to) => format!("exact({from:?} -> {to:?})"),
Rule::Rename(from, to) => format!("rename({from:?} -> {to:?})"),
Rule::Mount(from, to, _) => format!("mount({from:?} -> {to:?})"),
Rule::MountIndexed(from, to, Indices::AsIs, _) => {
format!("mount_indexed({from:?} -> {to:?})")
}
Rule::MountIndexed(from, to, indices, _) => {
format!("mount_indexed({from:?} -> {to:?}, {indices:?})")
}
Rule::Custom(_) => "custom".to_string(),
}
}
fn claim(
&self,
name: &str,
from_prefix: &str,
to_prefix: &str,
cx: &mut Cx,
) -> Option<Option<Target>> {
match self {
Rule::DropSuffix(suffix) => name.ends_with(suffix.as_str()).then_some(None),
Rule::Exact(from, to) => (name == from).then(|| Some(plain(to.clone()))),
Rule::Rename(from, to) => name
.strip_prefix(from.as_str())
.map(|rest| Some(plain(format!("{to}{rest}")))),
Rule::Mount(from, to, sub) => sub
.claim(
name.strip_prefix(from.as_str())?,
&format!("{from_prefix}{from}"),
&format!("{to_prefix}{to}"),
cx,
)
.map(|t| t.map(|t| prefixed(to, t))),
Rule::MountIndexed(from, to, indices, sub) => {
let (digits, rest) = name.strip_prefix(from.as_str())?.split_once('.')?;
if digits.is_empty() || !digits.bytes().all(|b| b.is_ascii_digit()) {
return None;
}
let index: usize = digits.parse().ok()?;
let key = (rule_addr(self), format!("{from_prefix}{from}"));
cx.seen.entry(key.clone()).or_default().insert(index);
let mapped = match indices {
Indices::AsIs => Some(index),
Indices::From(first) => index.checked_sub(*first),
Indices::Module => cx.module_index(&key, &format!("{to_prefix}{to}"), index),
};
let Some(mapped) = mapped else {
return Some(None);
};
let to = format!("{to}{mapped}.");
sub.claim(
rest,
&format!("{from_prefix}{from}{digits}."),
&format!("{to_prefix}{to}"),
cx,
)
.map(|t| t.map(|t| prefixed(&to, t)))
}
Rule::Custom(f) => f(name).map(|path| path.map(plain)),
}
}
}
impl Rekey {
pub fn keep_rest() -> Self {
Self {
rules: Vec::new(),
transforms: Vec::new(),
unclaimed: Unclaimed::Keep,
}
}
pub fn drop_rest() -> Self {
Self {
rules: Vec::new(),
transforms: Vec::new(),
unclaimed: Unclaimed::Drop,
}
}
pub fn pass_rest() -> Self {
Self {
rules: Vec::new(),
transforms: Vec::new(),
unclaimed: Unclaimed::Pass,
}
}
fn with(
mut self,
rule: Rule,
) -> Self {
self.rules.push(rule);
self
}
pub fn drop_suffix(
self,
suffix: impl Into<String>,
) -> Self {
self.with(Rule::DropSuffix(suffix.into()))
}
pub fn exact(
self,
from: impl Into<String>,
to: impl Into<String>,
) -> Self {
self.with(Rule::Exact(from.into(), to.into()))
}
pub fn rename(
self,
from: impl Into<String>,
to: impl Into<String>,
) -> Self {
self.with(Rule::Rename(from.into(), to.into()))
}
pub fn mount(
self,
from: impl Into<String>,
to: impl Into<String>,
sub: Rekey,
) -> Self {
self.with(Rule::Mount(from.into(), to.into(), sub))
}
pub fn mount_indexed(
self,
from: impl Into<String>,
to: impl Into<String>,
sub: Rekey,
) -> Self {
self.mount_indexed_with(from, to, Indices::AsIs, sub)
}
pub fn mount_indexed_with(
self,
from: impl Into<String>,
to: impl Into<String>,
indices: Indices,
sub: Rekey,
) -> Self {
self.with(Rule::MountIndexed(from.into(), to.into(), indices, sub))
}
pub fn custom(
self,
f: impl Fn(&str) -> Claim + Send + Sync + 'static,
) -> Self {
self.with(Rule::Custom(Arc::new(f)))
}
pub fn transform(
mut self,
path: impl Into<String>,
f: impl Fn(TensorData) -> TensorData + Send + Sync + 'static,
) -> Self {
self.transforms.push((path.into(), Arc::new(f)));
self
}
pub fn target(
&self,
name: &str,
) -> Option<Target> {
self.claim(name, "", "", &mut Cx::default()).flatten()
}
fn claim(
&self,
name: &str,
from_prefix: &str,
to_prefix: &str,
cx: &mut Cx,
) -> Option<Option<Target>> {
let claimed = self
.rules
.iter()
.find_map(|rule| {
let claim = rule.claim(name, from_prefix, to_prefix, cx)?;
cx.trace.rules.insert(rule_addr(rule));
Some(claim)
})
.or_else(|| match self.unclaimed {
Unclaimed::Keep => Some(Some(plain(name.to_string()))),
Unclaimed::Drop => Some(None),
Unclaimed::Pass => None,
})?;
Some(claimed.map(|target| self.with_own_transform(target, &mut cx.trace)))
}
fn with_own_transform(
&self,
target: Target,
trace: &mut Trace,
) -> Target {
let own = self
.transforms
.iter()
.find(|(path, _)| *path == target.path)
.map(|(_, f)| {
trace.transforms.insert(transform_addr(f));
f.clone()
});
Target {
transform: compose(target.transform, own),
path: target.path,
}
}
pub fn apply(
&self,
name: &str,
) -> Option<String> {
self.target(name).map(|t| t.path)
}
pub fn plan<S: AsRef<str>>(
&self,
names: impl IntoIterator<Item = S>,
) -> RekeyPlan {
self.plan_in(names, None)
}
pub fn plan_for<S: AsRef<str>>(
&self,
names: impl IntoIterator<Item = S>,
module_paths: &BTreeSet<String>,
) -> RekeyPlan {
self.plan_in(names, Some(module_paths))
}
fn plan_in<S: AsRef<str>>(
&self,
names: impl IntoIterator<Item = S>,
module: Option<&BTreeSet<String>>,
) -> RekeyPlan {
let names: Vec<String> = names.into_iter().map(|n| n.as_ref().to_string()).collect();
let mut cx = Cx {
module,
..Cx::default()
};
if module.is_some() {
for name in &names {
self.claim(name, "", "", &mut cx);
}
cx.trace = Trace::default();
cx.resolving = true;
}
let targets: Vec<(String, Option<Target>)> = names
.into_iter()
.map(|name| {
let target = self.claim(&name, "", "", &mut cx).flatten();
(name, target)
})
.collect();
let trace = std::mem::take(&mut cx.trace);
let index_conflicts = cx.index_conflicts.into_iter().collect();
let unknown_paths = match module {
None => Vec::new(),
Some(module) => {
let parents: BTreeSet<&str> = module
.iter()
.flat_map(|path| path.match_indices('.').map(move |(i, _)| &path[..i]))
.collect();
targets
.iter()
.filter_map(|(name, target)| {
let path = &target.as_ref()?.path;
let parent = path.rsplit_once('.').map_or("", |(p, _)| p);
(!parents.contains(parent)).then(|| (name.clone(), path.clone()))
})
.collect()
}
};
let mut by_path: BTreeMap<&str, Vec<String>> = BTreeMap::new();
for (name, target) in &targets {
if let Some(target) = target {
by_path.entry(&target.path).or_default().push(name.clone());
}
}
let collisions = by_path
.into_iter()
.filter(|(_, names)| names.len() > 1)
.map(|(path, names)| (path.to_string(), names))
.collect();
let mut unused_rules = Vec::new();
let mut orphan_transforms = Vec::new();
self.unused(&trace, "", "", &mut unused_rules, &mut orphan_transforms);
RekeyPlan {
targets,
collisions,
orphan_transforms,
unused_rules,
index_conflicts,
unknown_paths,
}
}
fn unused(
&self,
trace: &Trace,
from_prefix: &str,
to_prefix: &str,
rules: &mut Vec<String>,
transforms: &mut Vec<String>,
) {
for (path, f) in &self.transforms {
if !trace.transforms.contains(&transform_addr(f)) {
transforms.push(format!("{to_prefix}{path}"));
}
}
for rule in &self.rules {
if !trace.rules.contains(&rule_addr(rule)) {
let context = if from_prefix.is_empty() {
String::new()
} else {
format!("under {from_prefix:?}: ")
};
rules.push(format!("{context}{}", rule.describe()));
continue;
}
match rule {
Rule::Mount(from, to, sub) => sub.unused(
trace,
&format!("{from_prefix}{from}"),
&format!("{to_prefix}{to}"),
rules,
transforms,
),
Rule::MountIndexed(from, to, _, sub) => sub.unused(
trace,
&format!("{from_prefix}{from}N."),
&format!("{to_prefix}{to}N."),
rules,
transforms,
),
_ => {}
}
}
}
pub fn as_fn(&self) -> impl Fn(&str) -> Option<String> + '_ {
move |name| self.apply(name)
}
}
impl fmt::Debug for Rekey {
fn fmt(
&self,
f: &mut fmt::Formatter<'_>,
) -> fmt::Result {
f.debug_struct("Rekey")
.field("rules", &self.rules.len())
.field("transforms", &self.transforms.len())
.field("unclaimed", &self.unclaimed)
.finish()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_first_claim_decides() {
let keep = Rekey::keep_rest()
.drop_suffix(".num_batches_tracked")
.rename("a.", "x.")
.rename("a.b.", "never.");
assert_eq!(keep.apply("a.b.weight").as_deref(), Some("x.b.weight"));
assert_eq!(keep.apply("a.num_batches_tracked"), None);
assert_eq!(keep.apply("other.bias").as_deref(), Some("other.bias"));
let drop = Rekey::drop_rest().exact("silence_embeds", "silence");
assert_eq!(drop.apply("silence_embeds").as_deref(), Some("silence"));
assert_eq!(drop.apply("silence_embeds.x"), None);
assert_eq!(drop.apply("other.bias"), None);
}
#[test]
fn test_mounts() {
let block = Rekey::drop_rest().rename("fc1.", "mlp.linear1.");
let model = Rekey::keep_rest()
.mount("tower.block.", "encoder.block.", block.clone())
.mount_indexed("tower.layers.", "encoder.transformer.layers.", block);
assert_eq!(
model.apply("tower.block.fc1.weight").as_deref(),
Some("encoder.block.mlp.linear1.weight")
);
assert_eq!(model.apply("tower.block.other.weight"), None);
assert_eq!(
model.apply("tower.layers.11.fc1.bias").as_deref(),
Some("encoder.transformer.layers.11.mlp.linear1.bias")
);
assert_eq!(model.apply("tower.layers.11.other.bias"), None);
assert_eq!(model.apply("head.weight").as_deref(), Some("head.weight"));
}
#[test]
fn test_mount_indexed_claims_only_indices() {
let rekey = Rekey::keep_rest()
.mount_indexed("layers.", "blocks.", Rekey::keep_rest())
.rename("layers.", "stack.");
assert_eq!(rekey.apply("layers.12.w").as_deref(), Some("blocks.12.w"));
assert_eq!(
rekey.apply("layers.norm.weight").as_deref(),
Some("stack.norm.weight")
);
assert_eq!(rekey.apply("layers..w").as_deref(), Some("stack..w"));
assert_eq!(rekey.apply("layers.3").as_deref(), Some("stack.3"));
}
#[test]
fn test_pass_rest() {
let numbered = Rekey::pass_rest()
.custom(|name| {
let (n, rest) = name.split_once('.')?;
let n: usize = n.parse().ok()?;
Some((n > 0).then(|| format!("blocks.{}.{rest}", n - 1)))
})
.transform("blocks.0.weight", |data| data);
let model = Rekey::keep_rest().mount("conv", "head.", numbered.clone());
assert_eq!(
model.apply("conv1.weight").as_deref(),
Some("head.blocks.0.weight")
);
assert!(model.target("conv1.weight").unwrap().transform.is_some());
assert_eq!(model.apply("conv0.weight"), None);
assert_eq!(
model.apply("conv_out.weight").as_deref(),
Some("conv_out.weight")
);
assert_eq!(numbered.apply("x.weight"), None);
}
#[test]
fn test_plan_reports() {
let block = Rekey::keep_rest()
.rename("fc1.", "mlp.linear1.")
.rename("fc2.", "mlp.linear2.")
.transform("mlp.linear1.weight", |data| data)
.transform("mlp.nothing.weight", |data| data);
let model = Rekey::drop_rest()
.mount_indexed("layers.", "blocks.", block)
.exact("head", "out.weight")
.exact("tied_head", "out.weight")
.mount("unused.", "never.", Rekey::keep_rest().rename("a.", "b."));
let plan = model.plan(["layers.0.fc1.weight", "head", "tied_head", "other"]);
assert_eq!(
plan.targets
.iter()
.map(|(n, t)| (n.as_str(), t.as_ref().map(|t| t.path.as_str())))
.collect::<Vec<_>>(),
[
("layers.0.fc1.weight", Some("blocks.0.mlp.linear1.weight")),
("head", Some("out.weight")),
("tied_head", Some("out.weight")),
("other", None),
]
);
assert_eq!(
plan.collisions,
[(
"out.weight".to_string(),
vec!["head".to_string(), "tied_head".to_string()]
)]
);
assert_eq!(plan.orphan_transforms, ["blocks.N.mlp.nothing.weight"]);
assert_eq!(
plan.unused_rules,
[
"under \"layers.N.\": rename(\"fc2.\" -> \"mlp.linear2.\")",
"mount(\"unused.\" -> \"never.\")",
]
);
assert!(plan.check().is_err());
let clean = Rekey::keep_rest().rename("a.", "b.").plan(["a.w", "c.w"]);
assert!(clean.collisions.is_empty() && clean.unused_rules.is_empty());
clean.check().unwrap();
}
#[test]
fn test_module_indices() {
let inner = Rekey::keep_rest().mount_indexed_with(
"seq.",
"seq.",
Indices::Module,
Rekey::keep_rest(),
);
let rekey =
Rekey::keep_rest().mount_indexed_with("stage", "stages.", Indices::From(1), inner);
let module: BTreeSet<String> = [
"stages.0.seq.0.w",
"stages.0.seq.1.w",
"stages.1.seq.0.w",
"stages.1.seq.1.w",
"stages.2.seq.0.w",
"head.w",
]
.map(String::from)
.into();
let names = [
"stage1.seq.0.w",
"stage1.seq.2.w",
"stage2.seq.0.w",
"stage2.seq.1.w",
"stage3.seq.0.w",
"stage3.seq.3.w",
"tail.w",
];
let plan = rekey.plan_for(names, &module);
let paths: Vec<Option<&str>> = plan
.targets
.iter()
.map(|(_, t)| t.as_ref().map(|t| t.path.as_str()))
.collect();
assert_eq!(
paths,
[
Some("stages.0.seq.0.w"),
Some("stages.0.seq.1.w"),
Some("stages.1.seq.0.w"),
Some("stages.1.seq.1.w"),
None,
None,
Some("tail.w"),
]
);
assert_eq!(
plan.index_conflicts,
["stage3.seq.N.: the checkpoint has {0, 3}, the module (stages.2.seq.N.) {0}"]
);
assert_eq!(
plan.unknown_paths,
[("tail.w".to_string(), "tail.w".to_string())]
);
assert!(plan.check().is_err());
assert_eq!(
rekey.apply("stage1.seq.2.w").as_deref(),
Some("stages.0.seq.2.w")
);
assert_eq!(rekey.plan(names).index_conflicts, Vec::<String>::new());
}
#[test]
fn test_custom() {
let rekey = Rekey::drop_rest()
.custom(|name| {
let k: usize = name
.strip_prefix("conv.")?
.split_once('.')?
.0
.parse()
.ok()?;
Some(
k.is_multiple_of(2)
.then(|| format!("stages.{}.conv", k / 2)),
)
})
.rename("conv.", "kept.");
assert_eq!(
rekey.apply("conv.4.weight").as_deref(),
Some("stages.2.conv")
);
assert_eq!(rekey.apply("conv.3.weight"), None);
assert_eq!(
rekey.apply("conv.x.weight").as_deref(),
Some("kept.x.weight")
);
}
#[test]
fn test_transforms_compose_through_mounts() {
use burn::tensor::TensorData;
let scale = |k: f32| {
move |data: TensorData| {
let v: Vec<f32> = data.try_to_vec::<f32>().unwrap();
TensorData::new(v.into_iter().map(|x| x * k).collect::<Vec<_>>(), [2])
}
};
let block = Rekey::keep_rest()
.rename("fc1.", "mlp.linear1.")
.transform("mlp.linear1.weight", scale(2.0));
let model = Rekey::drop_rest()
.mount("tower.", "encoder.", block)
.transform("encoder.mlp.linear1.weight", |data| {
let v: Vec<f32> = data.try_to_vec::<f32>().unwrap();
TensorData::new(v.into_iter().map(|x| x + 1.0).collect::<Vec<_>>(), [2])
});
let target = model.target("tower.fc1.weight").unwrap();
assert_eq!(target.path, "encoder.mlp.linear1.weight");
let out = (target.transform.unwrap())(TensorData::new(vec![1.0f32, 3.0], [2]));
assert_eq!(out.try_to_vec::<f32>().unwrap(), vec![3.0, 7.0]);
let plain = model.target("tower.fc1.bias").unwrap();
assert_eq!(plain.path, "encoder.mlp.linear1.bias");
assert!(plain.transform.is_none());
assert_eq!(
model.apply("tower.fc1.weight").as_deref(),
Some("encoder.mlp.linear1.weight")
);
}
}