use crate::{CfdError, CollocatedGrid};
#[derive(Debug, Clone)]
pub struct ScalarTransport {
grid: CollocatedGrid,
diffusivity: f64,
}
impl ScalarTransport {
pub fn new(grid: CollocatedGrid, diffusivity: f64) -> Result<Self, CfdError> {
if !diffusivity.is_finite() || diffusivity < 0.0 {
return Err(CfdError::InvalidParameter(format!(
"diffusivity must be finite and >= 0, got {diffusivity}"
)));
}
Ok(Self { grid, diffusivity })
}
#[must_use]
pub fn max_stable_dt(&self, u: &[f64], v: &[f64]) -> f64 {
let umax = u.iter().fold(0.0_f64, |m, x| m.max(x.abs()));
let vmax = v.iter().fold(0.0_f64, |m, x| m.max(x.abs()));
let (dx, dy) = (self.grid.dx, self.grid.dy);
let advective = if umax / dx + vmax / dy > 0.0 {
1.0 / (umax / dx + vmax / dy)
} else {
f64::INFINITY
};
let diffusive = if self.diffusivity > 0.0 {
0.5 / (self.diffusivity * (1.0 / (dx * dx) + 1.0 / (dy * dy)))
} else {
f64::INFINITY
};
advective.min(diffusive)
}
pub fn step(
&self,
c: &mut [f64],
u: &[f64],
v: &[f64],
dt: f64,
source: &dyn Fn(usize, f64) -> f64,
) -> Result<(), CfdError> {
let n = self.grid.nx * self.grid.ny;
for field in [c.len(), u.len(), v.len()] {
if field != n {
return Err(CfdError::DimensionMismatch {
expected: n,
actual: field,
});
}
}
if dt.is_nan() || dt <= 0.0 {
return Err(CfdError::InvalidParameter(format!(
"dt must be > 0, got {dt}"
)));
}
let limit = self.max_stable_dt(u, v);
if dt > limit {
return Err(CfdError::InvalidParameter(format!(
"dt = {dt} exceeds the stable limit {limit}"
)));
}
let (nx, ny) = (self.grid.nx, self.grid.ny);
let (dx, dy) = (self.grid.dx, self.grid.dy);
let d = self.diffusivity;
let old = c.to_vec();
for j in 0..ny {
for i in 0..nx {
let k = self.grid.idx(i, j);
let here = old[k];
let west = if i > 0 {
old[self.grid.idx(i - 1, j)]
} else {
here
};
let east = if i + 1 < nx {
old[self.grid.idx(i + 1, j)]
} else {
here
};
let south = if j > 0 {
old[self.grid.idx(i, j - 1)]
} else {
here
};
let north = if j + 1 < ny {
old[self.grid.idx(i, j + 1)]
} else {
here
};
let dcdx = (if u[k] >= 0.0 {
here - west
} else {
east - here
}) / dx;
let dcdy = (if v[k] >= 0.0 {
here - south
} else {
north - here
}) / dy;
let advection = u[k] * dcdx + v[k] * dcdy;
let diffusion = d
* ((east - 2.0 * here + west) / (dx * dx)
+ (north - 2.0 * here + south) / (dy * dy));
c[k] = here + dt * (-advection + diffusion + source(k, here));
}
}
Ok(())
}
#[must_use]
pub fn total(&self, c: &[f64]) -> f64 {
c.iter().sum::<f64>() * self.grid.dx * self.grid.dy
}
}
#[cfg(test)]
mod tests {
use super::*;
fn grid() -> CollocatedGrid {
CollocatedGrid::new(16, 16, 1.0, 1.0).unwrap()
}
#[test]
fn pure_diffusion_conserves_total() {
let t = ScalarTransport::new(grid(), 0.01).unwrap();
let n = 16 * 16;
let zero = vec![0.0; n];
let mut c: Vec<f64> = (0..n)
.map(|k| if k % 17 == 0 { 1.0 } else { 0.0 })
.collect();
let before = t.total(&c);
let dt = 0.5 * t.max_stable_dt(&zero, &zero);
for _ in 0..200 {
t.step(&mut c, &zero, &zero, dt, &|_, _| 0.0).unwrap();
}
assert!((t.total(&c) - before).abs() < 1e-12 * before.max(1.0));
}
#[test]
fn uniform_flow_transports_a_blob_downstream() {
let g = grid();
let t = ScalarTransport::new(g.clone(), 0.0).unwrap();
let n = 16 * 16;
let u = vec![0.5; n];
let v = vec![0.0; n];
let mut c = vec![0.0; n];
c[g.idx(3, 8)] = 1.0;
let dt = 0.5 * t.max_stable_dt(&u, &v);
let steps = 10;
for _ in 0..steps {
t.step(&mut c, &u, &v, dt, &|_, _| 0.0).unwrap();
}
let centroid: f64 = (0..16)
.map(|i| i as f64 * (0..16).map(|j| c[g.idx(i, j)]).sum::<f64>())
.sum::<f64>()
/ c.iter().sum::<f64>();
assert!(
centroid > 3.0,
"the blob should move downstream, centroid {centroid}"
);
}
#[test]
fn source_term_consumes_the_scalar() {
let t = ScalarTransport::new(grid(), 0.0).unwrap();
let n = 16 * 16;
let zero = vec![0.0; n];
let mut c = vec![1.0; n];
let k = 0.5;
let dt = 0.01;
for _ in 0..100 {
t.step(&mut c, &zero, &zero, dt, &|_, ci| -k * ci).unwrap();
}
let expected = (1.0 - k * dt).powi(100);
assert!((c[0] - expected).abs() < 1e-12);
}
#[test]
fn unstable_steps_are_refused() {
let t = ScalarTransport::new(grid(), 0.1).unwrap();
let n = 16 * 16;
let zero = vec![0.0; n];
let mut c = vec![0.0; n];
let too_big = 10.0 * t.max_stable_dt(&zero, &zero);
assert!(t.step(&mut c, &zero, &zero, too_big, &|_, _| 0.0).is_err());
assert!(ScalarTransport::new(grid(), -1.0).is_err());
}
}