autosim.experimental.simulations.lattice_boltzmann

autosim.experimental.simulations.lattice_boltzmann#

Lattice Boltzmann Method (LBM) Simulator for 2D Fluid Flow.

This module implements a differentiable D2Q9 LBM solver for incompressible Navier-Stokes equations. It supports complex boundary conditions (like obstacles) and inflow/outflow profiles, making it suitable for benchmarks like Flow Past Cylinder.

class LatticeBoltzmann(parameters_range=None, output_names=None, return_timeseries=False, log_level='progress_bar', width=128, height=64, T=4.0, dt=0.004, use_cylinder=True, oscillatory_inlet=None, n_saved_frames=None, skip_nt=0, warmup_steps=200)[source]#

Bases: SpatioTemporalSimulator

Lattice Boltzmann (D2Q9) simulator for channel flow with obstacles.

Simulates 2D flow past a cylinder using the BGK collision model. The simulation domain is a rectangular channel controlled by width and height.

The D2Q9 update evolves particle populations \(f_i\) as:

\[f_i(\mathbf{x} + \mathbf{c}_i\Delta t, t + \Delta t) = f_i(\mathbf{x}, t) - \frac{1}{\tau} \left(f_i(\mathbf{x}, t) - f_i^{\mathrm{eq}}(\mathbf{x}, t)\right).\]

Macroscopic density and velocity are recovered from:

\[\rho = \sum_i f_i, \qquad \mathbf{u} = \frac{1}{\rho}\sum_i \mathbf{c}_i f_i.\]
Parameters:

  • parameters_range (dict[str, tuple[float, float]] | None) –

    Bounds on sampled parameters:

    • viscosity: Kinematic viscosity (0.01-0.05 typically).

    • u_in: Maximum inflow velocity (keep < 0.15 for stability).

    • oscillation_frequency: Inlet oscillation frequency in cycles per unit simulation time.

  • output_names (list[str] | None) – Names for output channels. Defaults to ["vorticity", "velocity_x", "velocity_y", "rho"].

  • return_timeseries (bool) – If True, returns full trajectory; otherwise final frame only.

  • use_cylinder (bool) – If True, include the circular obstacle. If False, run a plain channel.

  • oscillatory_inlet (bool | None) – If True, apply time-dependent inlet modulation (useful for rich dynamics in no-cylinder channels). If None, defaults to not use_cylinder.

  • width (int) – Grid width (Nx).

  • height (int) – Grid height (Ny).

  • T (float) – Total simulation time (in seconds, approximate).

  • dt (float) – Temporal step size in simulation-time units. Smaller values increase internal step count and reduce jumpiness in returned trajectories.

  • n_saved_frames (int | None) – Number of saved frames for returned timeseries. If None, save every post-warmup LBM step (temporal resolution scales with T). If set, the simulator samples exactly that many frames when possible (capped at available post-warmup steps).

  • skip_nt (int) – Number of initial saved trajectory frames to drop from returned timeseries outputs.

  • warmup_steps (int) – Number of initial LBM steps to run without recording to let the inlet flow establish and the simulation stabilize.

  • log_level (str)

forward_samples_spatiotemporal(n, random_seed=None, ensure_exact_n=False)[source]#

Run sampled trajectories and return spatiotemporal tensors.

Parameters:

  • n (int)

  • random_seed (int | None)

  • ensure_exact_n (bool)

Return type:

dict

curl_2d(u, v)[source]#

Compute vorticity = dv/dx - du/dy using central differences.

Parameters:
Return type:

Tensor

simulate_lbm_cylinder(params, return_timeseries, width, height, duration, dt=0.004, use_cylinder=True, oscillatory_inlet=False, n_saved_frames=None, warmup_steps=200)[source]#

Simulate flow past a cylinder using D2Q9 Lattice Boltzmann.

Parameters:

  • params (Tensor) – Physical parameters for viscosity, inlet speed, and inlet oscillation.

  • return_timeseries (bool) – Whether to return the saved flow trajectory or only the final frame.

  • width (int) – Number of lattice nodes in the horizontal direction.

  • height (int) – Number of lattice nodes in the vertical direction.

  • duration (float) – Physical duration to simulate after warmup.

  • dt (float) – Time represented by each LBM step.

  • use_cylinder (bool) – Whether to include a circular obstacle in the flow.

  • oscillatory_inlet (bool) – Whether to use the sampled inlet oscillation frequency.

  • n_saved_frames (int | None) – Number of trajectory frames to save when returning a timeseries.

  • warmup_steps (int) – Number of initial steps to run before collecting outputs.

Return type:

Tensor

Coordinate system: