use crate::matrix::Matrix;
use crate::network::NetworkError;
use rand::{Rng, SeedableRng, rngs::StdRng};
pub trait Denoiser {
fn denoise(&mut self, latents: &Matrix, sigma: f32) -> Result<Matrix, NetworkError>;
fn denoise_unconditional(
&mut self,
_latents: &Matrix,
_sigma: f32,
) -> Result<Option<Matrix>, NetworkError> {
Ok(None)
}
}
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum Scheduler {
FlowMatch { shift: f32 },
Ddim {
beta_start: f32,
beta_end: f32,
train_steps: usize,
},
}
impl Scheduler {
pub fn flow_match(shift: f32) -> Self {
Self::FlowMatch { shift }
}
pub fn ddim() -> Self {
Self::Ddim {
beta_start: 0.00085,
beta_end: 0.012,
train_steps: 1000,
}
}
pub fn sigmas(&self, steps: usize) -> Result<Vec<f32>, NetworkError> {
if steps == 0 {
return Err(NetworkError::InvalidConfig(
"a sampling run of no steps produces noise".into(),
));
}
Ok(match *self {
Self::FlowMatch { shift } => (0..=steps)
.map(|step| {
let level = 1.0 - step as f32 / steps as f32;
shift * level / (1.0 + (shift - 1.0) * level)
})
.collect(),
Self::Ddim {
beta_start,
beta_end,
train_steps,
} => {
let alphas = alphas_cumprod(beta_start, beta_end, train_steps);
let mut sigmas: Vec<f32> = (0..steps)
.map(|step| {
let index = train_steps - 1 - step * train_steps / steps;
let alpha = alphas[index];
((1.0 - alpha) / alpha).sqrt()
})
.collect();
sigmas.push(0.0);
sigmas
}
})
}
pub fn karras_sigmas(&self, steps: usize) -> Result<Vec<f32>, NetworkError> {
let Self::Ddim {
beta_start,
beta_end,
train_steps,
} = *self
else {
return Err(NetworkError::InvalidConfig(
"Karras spacing is for a DDIM schedule; flow matching spaces its levels with `shift`"
.into(),
));
};
self.sigmas(steps)?;
const RHO: f32 = 7.0;
let alphas = alphas_cumprod(beta_start, beta_end, train_steps);
let root = |alpha: f32| ((1.0 - alpha) / alpha).sqrt().powf(1.0 / RHO);
let (high, low) = (root(alphas[train_steps - 1]), root(alphas[0]));
let mut sigmas: Vec<f32> = (0..steps)
.map(|step| {
let fraction = step as f32 / (steps - 1).max(1) as f32;
(high + fraction * (low - high)).powf(RHO)
})
.collect();
sigmas.push(0.0);
Ok(sigmas)
}
pub fn lcm_sigmas(&self, steps: usize) -> Result<Vec<f32>, NetworkError> {
const ORIGINAL_STEPS: usize = 50;
let Self::Ddim {
beta_start,
beta_end,
train_steps,
} = *self
else {
return Err(NetworkError::InvalidConfig(
"LCM timesteps are for a DDIM schedule".into(),
));
};
self.sigmas(steps)?;
let stride = train_steps / ORIGINAL_STEPS;
if steps > ORIGINAL_STEPS || stride == 0 {
return Err(NetworkError::InvalidConfig(format!(
"an LCM runs at most {ORIGINAL_STEPS} steps over a schedule of at least {ORIGINAL_STEPS} timesteps"
)));
}
let alphas = alphas_cumprod(beta_start, beta_end, train_steps);
let mut sigmas: Vec<f32> = (0..steps)
.map(|step| {
let index = step * ORIGINAL_STEPS / steps;
let alpha = alphas[(ORIGINAL_STEPS - index) * stride - 1];
((1.0 - alpha) / alpha).sqrt()
})
.collect();
sigmas.push(0.0);
Ok(sigmas)
}
pub fn step(
&self,
latents: &mut Matrix,
prediction: &Matrix,
sigma: f32,
next_sigma: f32,
) -> Result<(), NetworkError> {
if latents.data.len() != prediction.data.len() {
return Err(NetworkError::InvalidTarget {
expected: latents.data.len(),
actual: prediction.data.len(),
});
}
match self {
Self::FlowMatch { .. } => {
let delta = next_sigma - sigma;
for (latent, velocity) in latents.data.iter_mut().zip(&prediction.data) {
*latent += delta * velocity;
}
}
Self::Ddim { .. } => {
for (latent, noise) in latents.data.iter_mut().zip(&prediction.data) {
let clean = *latent - sigma * noise;
*latent = clean + next_sigma * noise;
}
}
}
Ok(())
}
pub fn add_noise(
&self,
latents: &mut Matrix,
noise: &Matrix,
sigma: f32,
) -> Result<(), NetworkError> {
if latents.data.len() != noise.data.len() {
return Err(NetworkError::InvalidTarget {
expected: latents.data.len(),
actual: noise.data.len(),
});
}
for (latent, noise) in latents.data.iter_mut().zip(&noise.data) {
*latent = match self {
Self::FlowMatch { .. } => (1.0 - sigma) * *latent + sigma * noise,
Self::Ddim { .. } => *latent + sigma * noise,
};
}
Ok(())
}
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum Solver {
#[default]
Euler,
EulerAncestral,
DpmPlusPlus2m,
}
pub(crate) fn alphas_cumprod(beta_start: f32, beta_end: f32, steps: usize) -> Vec<f32> {
let (start, end) = (beta_start.sqrt(), beta_end.sqrt());
let mut product = 1.0;
(0..steps)
.map(|step| {
let fraction = step as f32 / (steps - 1).max(1) as f32;
let beta = (start + fraction * (end - start)).powi(2);
product *= 1.0 - beta;
product
})
.collect()
}
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct SamplingConfig {
pub steps: usize,
pub solver: Solver,
pub guidance: f32,
pub seed: Option<u64>,
}
impl Default for SamplingConfig {
fn default() -> Self {
Self {
steps: 28,
solver: Solver::default(),
guidance: 1.0,
seed: None,
}
}
}
pub fn noise(rows: usize, cols: usize, seed: Option<u64>) -> Matrix {
let mut rng = match seed {
Some(seed) => StdRng::seed_from_u64(seed),
None => StdRng::from_entropy(),
};
let data = (0..rows * cols).map(|_| gaussian(&mut rng)).collect();
Matrix::from_vec(rows, cols, data)
}
pub fn gaussian<R: Rng>(rng: &mut R) -> f32 {
let first: f32 = rng.gen_range(f32::MIN_POSITIVE..1.0);
let second: f32 = rng.gen_range(0.0..1.0);
(-2.0 * first.ln()).sqrt() * (std::f32::consts::TAU * second).cos()
}
pub fn sample<D: Denoiser>(
denoiser: &mut D,
scheduler: Scheduler,
latents: Matrix,
config: &SamplingConfig,
on_step: impl FnMut(usize, &Matrix) -> bool,
) -> Result<Matrix, NetworkError> {
sample_from(denoiser, scheduler, latents, config, 0, on_step)
}
pub fn sample_from<D: Denoiser>(
denoiser: &mut D,
scheduler: Scheduler,
latents: Matrix,
config: &SamplingConfig,
first: usize,
on_step: impl FnMut(usize, &Matrix) -> bool,
) -> Result<Matrix, NetworkError> {
let sigmas = scheduler.sigmas(config.steps)?;
sample_with_sigmas(
denoiser, scheduler, latents, &sigmas, config, first, on_step,
)
}
pub fn sample_with_sigmas<D: Denoiser>(
denoiser: &mut D,
scheduler: Scheduler,
mut latents: Matrix,
sigmas: &[f32],
config: &SamplingConfig,
first: usize,
mut on_step: impl FnMut(usize, &Matrix) -> bool,
) -> Result<Matrix, NetworkError> {
let Some(steps) = sigmas.len().checked_sub(1).filter(|&steps| steps > 0) else {
return Err(NetworkError::InvalidConfig(
"a sampling run needs at least two noise levels".into(),
));
};
let mut previous: Option<(Vec<f32>, f32)> = None;
for step in first.min(steps)..steps {
let (sigma, next) = (sigmas[step], sigmas[step + 1]);
let prediction = predict(denoiser, &latents, sigma, config.guidance)?;
match config.solver {
Solver::Euler => scheduler.step(&mut latents, &prediction, sigma, next)?,
Solver::EulerAncestral => {
let up = (next * next * (sigma * sigma - next * next) / (sigma * sigma))
.max(0.0)
.sqrt()
.min(next);
let down = (next * next - up * up).max(0.0).sqrt();
scheduler.step(&mut latents, &prediction, sigma, down)?;
if up > 0.0 {
let seed = config
.seed
.map(|seed| seed ^ (step as u64 + 1).wrapping_mul(0x9E37_79B9_7F4A_7C15));
let extra = noise(latents.rows, latents.cols, seed);
for (latent, value) in latents.data.iter_mut().zip(&extra.data) {
*latent += up * value;
}
}
}
Solver::DpmPlusPlus2m => {
let denoised: Vec<f32> = latents
.data
.iter()
.zip(&prediction.data)
.map(|(latent, prediction)| latent - sigma * prediction)
.collect();
let height = (sigma / next).ln();
let ratio = next / sigma;
let mut target = denoised.clone();
if let Some((before, last)) = &previous
&& next > 0.0
{
let slope = 0.5 * height / last;
for (target, before) in target.iter_mut().zip(before) {
*target += slope * (*target - before);
}
}
for (latent, target) in latents.data.iter_mut().zip(&target) {
*latent = ratio * *latent + (1.0 - ratio) * target;
}
previous = Some((denoised, height));
}
}
if !on_step(step, &latents) {
break;
}
}
Ok(latents)
}
fn predict<D: Denoiser>(
denoiser: &mut D,
latents: &Matrix,
sigma: f32,
guidance: f32,
) -> Result<Matrix, NetworkError> {
let mut prediction = denoiser.denoise(latents, sigma)?;
if guidance != 1.0
&& let Some(unconditional) = denoiser.denoise_unconditional(latents, sigma)?
{
if unconditional.data.len() != prediction.data.len() {
return Err(NetworkError::InvalidTarget {
expected: prediction.data.len(),
actual: unconditional.data.len(),
});
}
for (conditional, unconditional) in prediction.data.iter_mut().zip(&unconditional.data) {
*conditional = unconditional + guidance * (*conditional - unconditional);
}
}
Ok(prediction)
}
pub struct Inpaint<'a, D> {
pub denoiser: &'a mut D,
pub image: &'a Matrix,
pub keep: &'a [f32],
}
impl<D: Denoiser> Inpaint<'_, D> {
fn blend(
&self,
latents: &Matrix,
sigma: f32,
mut prediction: Matrix,
) -> Result<Matrix, NetworkError> {
if self.image.data.len() != latents.data.len() || self.keep.len() != latents.rows {
return Err(NetworkError::InvalidConfig(format!(
"inpainting a {}x{} latent needs an image of that shape and {} weights, \
not {}x{} and {}",
latents.rows,
latents.cols,
latents.rows,
self.image.rows,
self.image.cols,
self.keep.len()
)));
}
let cols = latents.cols;
for (i, value) in prediction.data.iter_mut().enumerate() {
let keep = self.keep[i / cols];
let known = (latents.data[i] - self.image.data[i]) / sigma.max(1e-6);
*value = keep * known + (1.0 - keep) * *value;
}
Ok(prediction)
}
}
impl<D: Denoiser> Denoiser for Inpaint<'_, D> {
fn denoise(&mut self, latents: &Matrix, sigma: f32) -> Result<Matrix, NetworkError> {
let prediction = self.denoiser.denoise(latents, sigma)?;
self.blend(latents, sigma, prediction)
}
fn denoise_unconditional(
&mut self,
latents: &Matrix,
sigma: f32,
) -> Result<Option<Matrix>, NetworkError> {
match self.denoiser.denoise_unconditional(latents, sigma)? {
Some(prediction) => self.blend(latents, sigma, prediction).map(Some),
None => Ok(None),
}
}
}
pub fn sample_consistency<D: Denoiser>(
denoiser: &mut D,
scheduler: Scheduler,
mut latents: Matrix,
sigmas: &[f32],
config: &SamplingConfig,
mut on_step: impl FnMut(usize, &Matrix) -> bool,
) -> Result<Matrix, NetworkError> {
let Some(steps) = sigmas.len().checked_sub(1).filter(|&steps| steps > 0) else {
return Err(NetworkError::InvalidConfig(
"a sampling run needs at least two noise levels".into(),
));
};
for step in 0..steps {
let (sigma, next) = (sigmas[step], sigmas[step + 1]);
let prediction = predict(denoiser, &latents, sigma, config.guidance)?;
scheduler.step(&mut latents, &prediction, sigma, 0.0)?;
if next > 0.0 {
let seed = config
.seed
.map(|seed| seed ^ (step as u64 + 1).wrapping_mul(0x9E37_79B9_7F4A_7C15));
let fresh = noise(latents.rows, latents.cols, seed);
scheduler.add_noise(&mut latents, &fresh, next)?;
}
if !on_step(step, &latents) {
break;
}
}
Ok(latents)
}
pub fn sample_unipc<D: Denoiser>(
denoiser: &mut D,
scheduler: Scheduler,
mut latents: Matrix,
sigmas: &[f32],
config: &SamplingConfig,
mut on_step: impl FnMut(usize, &Matrix) -> bool,
) -> Result<Matrix, NetworkError> {
let Some(steps) = sigmas.len().checked_sub(1).filter(|&steps| steps > 0) else {
return Err(NetworkError::InvalidConfig(
"a sampling run needs at least two noise levels".into(),
));
};
let mut answers: Vec<Vec<f32>> = Vec::with_capacity(2);
let mut last: Option<(Vec<f32>, usize)> = None;
for step in 0..steps {
let (sigma, next) = (sigmas[step], sigmas[step + 1]);
let prediction = predict(denoiser, &latents, sigma, config.guidance)?;
let mut answer = latents.clone();
scheduler.step(&mut answer, &prediction, sigma, 0.0)?;
if let Some((before, order)) = &last {
let earlier = (*order == 2).then(|| (&answers[0][..], sigmas[step - 2]));
latents.data = unipc_update(
scheduler,
before,
(sigmas[step - 1], sigma),
&answers[answers.len() - 1],
earlier,
Some(&answer.data),
);
}
if answers.len() == 2 {
answers.remove(0);
}
answers.push(answer.data);
let order = if step == 0 || step + 1 == steps { 1 } else { 2 };
let earlier = (order == 2).then(|| (&answers[0][..], sigmas[step - 1]));
let predicted = unipc_update(
scheduler,
&latents.data,
(sigma, next),
&answers[answers.len() - 1],
earlier,
None,
);
last = Some((std::mem::replace(&mut latents.data, predicted), order));
if !on_step(step, &latents) {
break;
}
}
Ok(latents)
}
fn signal_and_noise(scheduler: Scheduler, sigma: f32) -> (f64, f64) {
let sigma = f64::from(sigma);
match scheduler {
Scheduler::FlowMatch { .. } => (1.0 - sigma, sigma),
Scheduler::Ddim { .. } => (1.0, sigma),
}
}
fn unipc_update(
scheduler: Scheduler,
x: &[f32],
(from, to): (f32, f32),
newest: &[f32],
earlier: Option<(&[f32], f32)>,
answer_at_to: Option<&[f32]>,
) -> Vec<f32> {
let log_snr = |sigma| {
let (signal, noise) = signal_and_noise(scheduler, sigma);
signal.ln() - noise.ln()
};
let (signal_to, noise_to) = signal_and_noise(scheduler, to);
let (_, noise_from) = signal_and_noise(scheduler, from);
let h = log_snr(to) - log_snr(from);
let phi = (-h).exp_m1();
let phi_2 = phi / -h - 1.0;
let first = phi_2 / phi;
let second = 2.0 * (phi_2 / -h - 0.5) / phi;
let ratio = earlier.map(|(_, sigma)| (log_snr(sigma) - log_snr(from)) / h);
let (weight_earlier, weight_new) = match (answer_at_to, ratio) {
(None, _) => (0.5, 0.0),
(Some(_), None) => (0.0, 0.5),
(Some(_), Some(ratio)) => {
let weight = (first - second) / (1.0 - ratio);
(weight, first - weight)
}
};
let keep = noise_to / noise_from;
(0..x.len())
.map(|i| {
let newest = f64::from(newest[i]);
let mut correction = 0.0;
if let (Some((answers, _)), Some(ratio)) = (earlier, ratio) {
correction += weight_earlier * (f64::from(answers[i]) - newest) / ratio;
}
if let Some(at_to) = answer_at_to {
correction += weight_new * (f64::from(at_to[i]) - newest);
}
let value = keep * f64::from(x[i]) - signal_to * phi * (newest + correction);
value as f32
})
.collect()
}
#[cfg(test)]
mod tests {
use super::*;
struct Straight {
target: Vec<f32>,
calls: usize,
}
impl Denoiser for Straight {
fn denoise(&mut self, latents: &Matrix, sigma: f32) -> Result<Matrix, NetworkError> {
self.calls += 1;
let data = latents
.data
.iter()
.zip(&self.target)
.map(|(value, target)| (value - target) / sigma.max(1e-6))
.collect();
Ok(Matrix::from_vec(latents.rows, latents.cols, data))
}
}
#[test]
fn flow_matching_walks_a_straight_path_to_the_image() {
let target = vec![0.5, -0.25, 1.0, 0.0];
let mut model = Straight {
target: target.clone(),
calls: 0,
};
let start = Matrix::from_vec(1, 4, vec![2.0, -3.0, 0.5, 1.5]);
let config = SamplingConfig {
steps: 30,
..SamplingConfig::default()
};
let image = sample(
&mut model,
Scheduler::flow_match(1.0),
start,
&config,
|_, _| true,
)
.unwrap();
assert_eq!(model.calls, 30);
for (value, target) in image.data.iter().zip(&target) {
assert!((value - target).abs() < 0.05, "{value} vs {target}");
}
}
#[test]
fn lcm_sigmas_sit_on_the_timesteps_diffusers_picks() {
let alphas = alphas_cumprod(0.00085, 0.012, 1000);
let level = |t: usize| ((1.0 - alphas[t]) / alphas[t]).sqrt();
let sigmas = Scheduler::ddim().lcm_sigmas(4).unwrap();
let expected: Vec<f32> = [999, 759, 499, 259]
.map(level)
.into_iter()
.chain([0.0])
.collect();
assert_eq!(sigmas, expected);
assert_eq!(
Scheduler::ddim().lcm_sigmas(1).unwrap(),
vec![level(999), 0.0]
);
assert_eq!(Scheduler::ddim().lcm_sigmas(50).unwrap()[49], level(19));
assert!(Scheduler::ddim().lcm_sigmas(51).is_err());
assert!(Scheduler::ddim().lcm_sigmas(0).is_err());
assert!(Scheduler::flow_match(1.0).lcm_sigmas(4).is_err());
}
struct Halving {
inputs: Vec<Vec<f32>>,
}
impl Denoiser for Halving {
fn denoise(&mut self, latents: &Matrix, sigma: f32) -> Result<Matrix, NetworkError> {
self.inputs.push(latents.data.clone());
let data = latents.data.iter().map(|x| 0.5 * x / sigma).collect();
Ok(Matrix::from_vec(latents.rows, latents.cols, data))
}
}
#[test]
fn consistency_sampling_renoises_each_answer_to_the_next_level() {
let sigmas = Scheduler::ddim().lcm_sigmas(4).unwrap();
let config = SamplingConfig {
seed: Some(3),
..SamplingConfig::default()
};
let run = |seed| {
let mut model = Halving { inputs: Vec::new() };
let start = noise(64, 64, Some(1));
let config = SamplingConfig { seed, ..config };
let image = sample_consistency(
&mut model,
Scheduler::ddim(),
start,
&sigmas,
&config,
|_, _| true,
)
.unwrap();
(image, model.inputs)
};
let (image, inputs) = run(Some(3));
assert_eq!(inputs.len(), 4);
for step in 1..4 {
let residual: Vec<f32> = inputs[step]
.iter()
.zip(&inputs[step - 1])
.map(|(x, before)| x - 0.5 * before)
.collect();
let spread =
(residual.iter().map(|r| r * r).sum::<f32>() / residual.len() as f32).sqrt();
assert!(
(spread / sigmas[step] - 1.0).abs() < 0.05,
"step {step}: noise {spread} vs level {}",
sigmas[step]
);
}
for (value, input) in image.data.iter().zip(&inputs[3]) {
assert!((value - 0.5 * input).abs() < 1e-4);
}
assert_eq!(run(Some(3)).0, image);
assert_ne!(run(Some(4)).0, image);
let target = vec![0.5, -0.25, 1.0, 0.0];
let mut model = Straight {
target: target.clone(),
calls: 0,
};
let start = Matrix::from_vec(1, 4, vec![2.0, -3.0, 0.5, 1.5]);
let image = sample_consistency(
&mut model,
Scheduler::flow_match(1.0),
start,
&[1.0, 0.6, 0.3, 0.0],
&config,
|_, _| true,
)
.unwrap();
assert_eq!(model.calls, 3);
for (value, target) in image.data.iter().zip(&target) {
assert!((value - target).abs() < 1e-5, "{value} vs {target}");
}
}
struct Wavy;
impl Denoiser for Wavy {
fn denoise(&mut self, latents: &Matrix, sigma: f32) -> Result<Matrix, NetworkError> {
let data = latents
.data
.iter()
.map(|x| sigma * x / (1.0 + sigma * sigma) + 0.1 * x.sin())
.collect();
Ok(Matrix::from_vec(latents.rows, latents.cols, data))
}
}
#[test]
fn unipc_matches_the_diffusers_scheduler() {
let alphas = alphas_cumprod(0.00085, 0.012, 1000);
let cases: [(&[usize], [f32; 4]); 3] = [
(
&[999, 500],
[1.393_945_2, -1.558_015_2, -0.032_679_02, 0.594_333_2],
),
(
&[999, 874, 749, 624, 500, 375, 250, 125],
[1.819_281_8, -2.845_583, 0.296_030_2, 1.358_274],
),
(
&[
999, 949, 899, 849, 799, 749, 699, 649, 599, 549, 500, 450, 400, 350, 300, 250,
200, 150, 100, 50,
],
[1.961_916_3, -2.946_663, 0.386_013, 1.407_398_7],
),
];
for (timesteps, expected) in cases {
let mut sigmas: Vec<f32> = timesteps
.iter()
.map(|&t| ((1.0 - alphas[t]) / alphas[t]).sqrt())
.collect();
sigmas.push(0.0);
let scale = alphas[999].sqrt();
let start = Matrix::from_vec(1, 4, [2.0, -3.0, 0.5, 1.5].map(|x| x / scale).to_vec());
let image = sample_unipc(
&mut Wavy,
Scheduler::ddim(),
start,
&sigmas,
&SamplingConfig::default(),
|_, _| true,
)
.unwrap();
for (value, expected) in image.data.iter().zip(expected) {
assert!(
(value - expected).abs() < 1e-4,
"{} steps: {value} vs diffusers {expected}",
timesteps.len()
);
}
}
let target = vec![0.5, -0.25, 1.0, 0.0];
let mut model = Straight {
target: target.clone(),
calls: 0,
};
let start = Matrix::from_vec(1, 4, vec![2.0, -3.0, 0.5, 1.5]);
let sigmas = Scheduler::flow_match(3.0).sigmas(6).unwrap();
let image = sample_unipc(
&mut model,
Scheduler::flow_match(3.0),
start,
&sigmas,
&SamplingConfig::default(),
|_, _| true,
)
.unwrap();
assert_eq!(model.calls, 6);
for (value, target) in image.data.iter().zip(&target) {
assert!((value - target).abs() < 1e-4, "{value} vs {target}");
}
}
#[test]
fn karras_sigmas_span_the_stable_diffusion_range() {
let sigmas = Scheduler::ddim().karras_sigmas(10).unwrap();
assert_eq!(sigmas.len(), 11);
assert!((sigmas[0] - 14.6146).abs() < 1e-2, "{}", sigmas[0]);
assert!((sigmas[9] - 0.0292).abs() < 1e-4, "{}", sigmas[9]);
assert_eq!(sigmas[10], 0.0);
assert!(sigmas.windows(2).all(|pair| pair[0] > pair[1]));
let ddim = Scheduler::ddim().sigmas(10).unwrap();
assert!(sigmas[5] < ddim[5]);
assert!(Scheduler::flow_match(1.0).karras_sigmas(10).is_err());
let target = vec![0.5, -0.25, 1.0, 0.0];
let mut model = Straight {
target: target.clone(),
calls: 0,
};
let start = Matrix::from_vec(1, 4, vec![2.0, -3.0, 0.5, 1.5]);
let config = SamplingConfig {
solver: Solver::DpmPlusPlus2m,
..SamplingConfig::default()
};
let image = sample_with_sigmas(
&mut model,
Scheduler::ddim(),
start,
&sigmas,
&config,
0,
|_, _| true,
)
.unwrap();
assert_eq!(model.calls, 10);
for (value, target) in image.data.iter().zip(&target) {
assert!((value - target).abs() < 1e-4, "{value} vs {target}");
}
}
struct Curved {
target: Vec<f32>,
calls: usize,
}
impl Denoiser for Curved {
fn denoise(&mut self, latents: &Matrix, sigma: f32) -> Result<Matrix, NetworkError> {
self.calls += 1;
let data = latents
.data
.iter()
.zip(&self.target)
.map(|(value, target)| {
let clean = target + 0.5 * sigma * (value - target);
(value - clean) / sigma.max(1e-6)
})
.collect();
Ok(Matrix::from_vec(latents.rows, latents.cols, data))
}
}
#[test]
fn the_higher_order_solver_lands_on_the_image_in_fewer_steps() {
let target = vec![0.5, -0.25, 1.0, 0.0];
let start = Matrix::from_vec(1, 4, vec![2.0, -3.0, 0.5, 1.5]);
let run = |solver: Solver, steps: usize| {
let mut model = Curved {
target: target.clone(),
calls: 0,
};
let config = SamplingConfig {
steps,
solver,
..SamplingConfig::default()
};
let image = sample(
&mut model,
Scheduler::flow_match(1.0),
start.clone(),
&config,
|_, _| true,
)
.unwrap();
assert_eq!(model.calls, steps);
image
};
let settled = run(Solver::Euler, 500);
let error = |solver: Solver, steps: usize| {
run(solver, steps)
.data
.iter()
.zip(&settled.data)
.map(|(value, settled)| (value - settled).abs())
.fold(0.0f32, f32::max)
};
assert!(error(Solver::DpmPlusPlus2m, 4) < error(Solver::Euler, 4));
assert!(error(Solver::DpmPlusPlus2m, 8) < error(Solver::Euler, 8));
assert!(error(Solver::DpmPlusPlus2m, 30) < 0.01);
}
#[test]
fn the_ancestral_solver_repeats_on_a_seed_and_wanders_without_one() {
let target = vec![0.5, -0.25, 1.0, 0.0];
let start = Matrix::from_vec(1, 4, vec![2.0, -3.0, 0.5, 1.5]);
let run = |seed: Option<u64>| {
let mut model = Straight {
target: target.clone(),
calls: 0,
};
let config = SamplingConfig {
steps: 12,
solver: Solver::EulerAncestral,
seed,
..SamplingConfig::default()
};
let mut route = Vec::new();
let landed = sample(
&mut model,
Scheduler::ddim(),
start.clone(),
&config,
|_, latents| {
route.extend_from_slice(&latents.data);
true
},
)
.unwrap();
(route, landed)
};
assert_eq!(run(Some(7)).0, run(Some(7)).0);
assert_ne!(run(Some(7)).0, run(Some(8)).0);
for (value, target) in run(Some(7)).1.data.iter().zip(&target) {
assert!((value - target).abs() < 0.05, "{value} vs {target}");
}
}
#[test]
fn the_levels_fall_to_zero_and_the_shift_slows_the_noisy_end() {
for scheduler in [Scheduler::flow_match(1.0), Scheduler::flow_match(3.0)] {
let sigmas = scheduler.sigmas(20).unwrap();
assert_eq!(sigmas.len(), 21);
assert!((sigmas[0] - 1.0).abs() < 1e-6);
assert_eq!(*sigmas.last().unwrap(), 0.0);
for pair in sigmas.windows(2) {
assert!(pair[0] > pair[1], "{pair:?}");
}
}
let even = Scheduler::flow_match(1.0).sigmas(20).unwrap();
let shifted = Scheduler::flow_match(3.0).sigmas(20).unwrap();
assert!(
even.iter()
.zip(&shifted)
.skip(1)
.take(19)
.all(|(even, shifted)| shifted > even)
);
let ddim = Scheduler::ddim().sigmas(20).unwrap();
assert_eq!(ddim.len(), 21);
assert_eq!(*ddim.last().unwrap(), 0.0);
for pair in ddim.windows(2) {
assert!(pair[0] > pair[1], "{pair:?}");
}
assert!(Scheduler::ddim().sigmas(0).is_err());
}
#[test]
fn a_noise_predicting_model_lands_on_the_same_image() {
struct Noisy {
target: Vec<f32>,
}
impl Denoiser for Noisy {
fn denoise(&mut self, latents: &Matrix, sigma: f32) -> Result<Matrix, NetworkError> {
let data = latents
.data
.iter()
.zip(&self.target)
.map(|(value, target)| (value - target) / sigma.max(1e-6))
.collect();
Ok(Matrix::from_vec(latents.rows, latents.cols, data))
}
}
let target = vec![0.25, -0.75, 0.0];
let image = sample(
&mut Noisy {
target: target.clone(),
},
Scheduler::ddim(),
Matrix::from_vec(1, 3, vec![3.0, 1.0, -2.0]),
&SamplingConfig {
steps: 12,
..SamplingConfig::default()
},
|_, _| true,
)
.unwrap();
for (value, target) in image.data.iter().zip(&target) {
assert!((value - target).abs() < 1e-3, "{value} vs {target}");
}
}
#[test]
fn inpainting_keeps_the_picture_and_repaints_the_rest() {
let image = Matrix::from_vec(3, 2, vec![1.0, -1.0, 2.0, -2.0, 0.0, 0.0]);
let keep = [1.0, 0.0, 0.5];
for (scheduler, solver) in [
(Scheduler::flow_match(1.0), Solver::Euler),
(Scheduler::flow_match(3.0), Solver::DpmPlusPlus2m),
(Scheduler::ddim(), Solver::EulerAncestral),
] {
let mut model = Straight {
target: vec![0.5; 6],
calls: 0,
};
let start = noise(3, 2, Some(7));
let mut inpaint = Inpaint {
denoiser: &mut model,
image: &image,
keep: &keep,
};
let config = SamplingConfig {
steps: 20,
solver,
seed: Some(3),
..SamplingConfig::default()
};
let out = sample(&mut inpaint, scheduler, start, &config, |_, _| true).unwrap();
let expected = [1.0, -1.0, 0.5, 0.5, 0.25, 0.25];
for (value, expected) in out.data.iter().zip(expected) {
assert!(
(value - expected).abs() < 1e-3,
"{scheduler:?} {solver:?}: {:?}",
out.data
);
}
}
let mut model = Straight {
target: vec![0.5; 6],
calls: 0,
};
let mut wrong = Inpaint {
denoiser: &mut model,
image: &image,
keep: &keep[..2],
};
assert!(wrong.denoise(&image, 0.5).is_err());
}
#[test]
fn guidance_pushes_away_from_the_unconditional_prediction() {
struct Guided;
impl Denoiser for Guided {
fn denoise(&mut self, latents: &Matrix, _: f32) -> Result<Matrix, NetworkError> {
Ok(Matrix::from_vec(
latents.rows,
latents.cols,
vec![2.0; latents.data.len()],
))
}
fn denoise_unconditional(
&mut self,
latents: &Matrix,
_: f32,
) -> Result<Option<Matrix>, NetworkError> {
Ok(Some(Matrix::from_vec(
latents.rows,
latents.cols,
vec![1.0; latents.data.len()],
)))
}
}
let start = Matrix::from_vec(1, 2, vec![0.0, 0.0]);
let config = SamplingConfig {
steps: 1,
guidance: 3.0,
..SamplingConfig::default()
};
let guided = sample(
&mut Guided,
Scheduler::flow_match(1.0),
start.clone(),
&config,
|_, _| true,
)
.unwrap();
assert_eq!(guided.data, vec![-4.0, -4.0]);
struct Distilled;
impl Denoiser for Distilled {
fn denoise(&mut self, latents: &Matrix, _: f32) -> Result<Matrix, NetworkError> {
Ok(Matrix::from_vec(
latents.rows,
latents.cols,
vec![2.0; latents.data.len()],
))
}
}
let plain = sample(
&mut Distilled,
Scheduler::flow_match(1.0),
start,
&config,
|_, _| true,
)
.unwrap();
assert_eq!(plain.data, vec![-2.0, -2.0]);
}
#[test]
fn the_callback_can_stop_a_run_early() {
let mut model = Straight {
target: vec![0.0; 4],
calls: 0,
};
sample(
&mut model,
Scheduler::flow_match(1.0),
Matrix::new(1, 4),
&SamplingConfig {
steps: 20,
..SamplingConfig::default()
},
|step, _| step < 4,
)
.unwrap();
assert_eq!(model.calls, 5);
}
#[test]
fn seeded_noise_repeats_and_looks_normal() {
let first = noise(8, 16, Some(9));
assert_eq!(first.data, noise(8, 16, Some(9)).data);
assert_ne!(first.data, noise(8, 16, Some(10)).data);
let mean = first.data.iter().sum::<f32>() / first.data.len() as f32;
let variance = first
.data
.iter()
.map(|value| (value - mean).powi(2))
.sum::<f32>()
/ first.data.len() as f32;
assert!(mean.abs() < 0.2, "{mean}");
assert!((variance - 1.0).abs() < 0.3, "{variance}");
}
}