moonbit-lbm
A D2Q9 lattice Boltzmann fluid simulation core for MoonBit.
lbm
fluid
simulation
d2q9
cfd
moon add zhsyutt/moonbit-lbm@0.2.1
Download zipAuthor
Version
0.2.1
License
Apache-2.0
Repository
Last updated
3 hours ago
Downloads
4
README#moonbit-lbm
moonbit-lbm is a reusable two-dimensional lattice Boltzmann method (LBM) core for MoonBit. It provides a dependency-light D2Q9 solver, explicit scalar transport, geometry and mask tools, numerical diagnostics, deterministic benchmark cases, and export formats for downstream applications and notebooks.
The package is designed for small-to-medium incompressible-flow experiments where a compact, inspectable numerical core is more useful than a large external runtime. The solver is intentionally explicit about collision models, boundary behavior, stability checks, and serialized state.
#Core capabilities
- D2Q9 BGK, regularized, and MRT-style collision operators.
- Periodic, open, bounce-back, velocity-inlet, pressure-outlet, and labeled boundary workflows.
- Reusable Simulation and ScalarSolver APIs for fluid and scalar fields.
- Rectangular masks, circles, boxes, morphology, connected components, boundary layers, and geometric moments.
- Field and vector-field calculus: interpolation, gradients, divergence, curl, convolution, resampling, and statistics.
- Checkpoint round trips with a versioned MLBM/1 text format.
- CSV, PPM, VTK, JSON-lines, and compact ASCII exports.
- Poiseuille, lid-driven cavity, and cylinder-wake benchmark cases with numerical gates.
- Pure MoonBit implementation with no runtime service or native library dependency.
#Quick start
Install MoonBit, clone the repository, and run the complete local gate:
git clone https://github.com/zhsyutt/moonbit-lbm.git
cd moonbit-lbm
moon update
moon fmt --check
moon check --target all --deny-warn
moon test --target all --deny-warn
moon run cmd/mainThe library package is available as:
///|
import {
"zhsyutt/moonbit-lbm" @lbm,
}#CLI and examples
The example executable runs the deterministic benchmark suite and a reusable periodic simulation:
moon run cmd/mainThe CLI prints CSV benchmark records, the number of stable cases, a compact simulation state summary, and the serialized checkpoint size. The library remains the primary API; applications can construct a simulation directly:
let simulation = @lbm.Simulation::new(
size=@lbm.Size::new(width=128, height=48),
options=@lbm.SimulationOptions::new(
model=@lbm.CollisionModel::bgk(omega=1.0),
boundary=@lbm.BoundaryMode::BounceBack,
force_x=0.000001,
),
)
simulation.set_box_walls()
simulation.set_uniform(rho=1.0, ux=0.0, uy=0.0)
simulation.run(500)
let report = simulation.report(name="channel")#Architecture
The root package is organized by numerical responsibility:
| Area | Main modules |
|---|---|
| Lattice and solver | constants.mbt, lattice.mbt, solver.mbt, advanced_solver.mbt, collision_models.mbt |
| Geometry and boundaries | geometry.mbt, geometry_boundaries.mbt, boundary_schemes.mbt, boundary_map.mbt |
| Fields and analysis | grid.mbt, field_calculus.mbt, flow_derivatives.mbt, analysis_advanced.mbt |
| Scalar transport | scalar_transport.mbt, scalar_analysis.mbt, scalar_pipeline.mbt |
| Persistence and export | checkpoint.mbt, export_*.mbt, reporting.mbt |
| Verification and studies | benchmarks.mbt, benchmark_*.mbt, numerical_checks.mbt, scheduler.mbt, sweep.mbt |
| Runnable entry point | cmd/main |
The main data path is Simulation -> collision -> streaming -> boundary application -> diagnostics. Field objects expose copies for safe analysis and provide explicit export methods. Checkpoints retain dimensions, options, solid geometry, time-step count, and distribution populations so a run can be resumed or audited without an external database.
#Benchmarks
The built-in suite measures Poiseuille flow, a lid-driven cavity, and a cylinder wake. Each report records grid size, steps, L2 and Linf profile error, mass drift, mean speed, and a stability flag. Run it locally with:
moon run cmd/mainThe benchmark implementation is deterministic and the output is intended to be captured in docs/BENCHMARKS.md. Threshold checks are available through BenchmarkGate, while run_resolution_study supports comparing grid sizes without changing the solver API.
#Tests and numerical safeguards
The test suite covers equilibrium and collision behavior, streaming and boundary edge cases, degenerate geometries, morphology, scalar transport, checkpoint corruption, field transforms, exports, benchmark gates, and reusable API round trips. Warning-free checks are part of the normal gate:
moon fmt --check
moon check --target all --deny-warn
moon test --target all --deny-warn
moon info
git diff --exit-codeUse validate_options, validate_size, Simulation::health, validate_checkpoint, and BenchmarkGate when integrating the package into a larger application. Stability diagnostics report density bounds, maximum speed, Mach-limit compliance, NaN detection, mass, and density variation.
The Ubuntu CI job also runs native coverage instrumentation and prints a summary so newly added numerical branches remain observable.
#Continuous integration
GitHub Actions runs the warning-free format, interface, check, test, and CLI gates on Ubuntu, macOS, and Windows. The workflow installs the latest stable MoonBit CLI at job start and checks both native and wasm-gc targets. A manually triggered publish workflow validates the package again before publishing the version declared in moon.mod to Mooncakes.
#Package and license
Package: zhsyutt/moonbit-lbm
Repository: github.com/zhsyutt/moonbit-lbm
This project is distributed under the Apache License 2.0.
#CheckpointError
pub(all) suberror CheckpointError {
InvalidHeader
InvalidRecord(String)
InvalidSize
InvalidPayload
}Errors raised when a simulation checkpoint cannot be trusted.
#Aabb
#Axis
Axis used by line-integral and flow-rate helpers.
#BenchmarkComparison
pub(all) struct BenchmarkComparison {
l2_delta : Double
relative_l2 : Double
linf_delta : Double
mass_delta : Double
} derive(Debug)Comparison between two measured benchmark results.
#BenchmarkGate
pub(all) struct BenchmarkGate {
max_l2 : Double
max_linf : Double
max_mass_drift : Double
} derive(Debug)Thresholds for a numerical benchmark gate.
#BenchmarkGate::accepts
Check a benchmark result against configured thresholds.
#BenchmarkGate::new
fn BenchmarkGate::new(max_l2~ : Double, max_linf~ : Double, max_mass_drift~ : Double) -> BenchmarkGateConstruct a benchmark gate.
#BenchmarkReport
pub(all) struct BenchmarkReport {
name : String
cells : Int
steps : Int
l2_error : Double
linf_error : Double
mass_drift : Double
mean_speed : Double
stable : Bool
} derive(Debug)A deterministic numerical benchmark result.
#BenchmarkReport::to_csv
Format a benchmark result as one CSV record.
#BenchmarkReport::to_markdown
Format a benchmark result for a human-readable report.
#BenchmarkStatistics
pub(all) struct BenchmarkStatistics {
count : Int
stable_count : Int
mean_l2 : Double
mean_linf : Double
min_speed : Double
max_speed : Double
quality_score : Double
} derive(Debug)Aggregate quality statistics across benchmark results.
#BenchmarkStatistics::passes
Return whether an aggregate meets a minimum quality score.
#BenchmarkStatistics::to_csv
Export aggregate benchmark statistics.
#BoundaryDiagnostics
pub(all) struct BoundaryDiagnostics {
solid_cells : Int
fluid_cells : Int
exposed_faces : Int
corner_cells : Int
periodic_safe : Bool
} derive(Debug)Diagnostics for a solid/fluid interface.
#BoundaryKind
Common local boundary schemes.
#BoundaryLabel
Semantic labels for boundary patches.
#BoundaryMap
Row-major boundary label map.
#BoundaryMap::boundary_count
Count all non-interior labels.
#BoundaryMap::boundary_only
Return a map with only labels that are not interior.
#BoundaryMap::count
Count one label.
#BoundaryMap::get
Get a label, treating out-of-domain coordinates as walls.
#BoundaryMap::new
Allocate an interior-filled boundary map.
#BoundaryMap::open_boundary_count
Return the number of inlet/outlet labels combined.
#BoundaryMap::set
Set a boundary label within the map.
#BoundaryMap::set_inlet_row
Mark a horizontal row as an inlet.
#BoundaryMap::set_outer_walls
Set the outer frame to wall labels.
#BoundaryMap::set_outlet_row
Mark a horizontal row as an outlet.
#BoundaryMap::set_periodic_column
Mark a vertical column as periodic.
#BoundaryMap::solid_mask
Convert an obstacle label map into a solid mask.
#BoundaryMap::to_ascii
Export a label map as ASCII initials.
#BoundaryMode
Outer-boundary behavior for the advanced solver.
#BoundarySpec
pub(all) struct BoundarySpec {
kind : BoundaryKind
value_x : Double
value_y : Double
density : Double
} derive(Debug)Parameters for one boundary patch.
#BoundarySpec::pressure
Construct a Zou/He pressure patch.
#BoundarySpec::velocity
Construct a Zou/He velocity patch.
#Cell
#Circle
#CollisionModel
Collision operators supported by the reusable solver.
#CollisionModel::bgk
Construct a BGK collision model.
#CollisionModel::mrt
Construct a two-relaxation-time MRT model.
#CollisionModel::omega
Read the shear relaxation parameter from a collision model.
#CollisionModel::regularized
Construct a regularized collision model.
#Config
#ConfigAudit
pub(all) struct ConfigAudit {
valid : Bool
model_name : String
viscosity : Double
recommended_dt : Double
relaxation_margin : Double
max_mach : Double
} derive(Debug)Explain the numerical implications of a simulation configuration.
#ConfigAudit::to_string
Return a human-readable configuration audit.
#ConnectedComponent
A connected solid region in a domain mask.
#ConvergenceHistory
pub(all) struct ConvergenceHistory {
capacity : Int
samples : Array[ConvergenceSample]
} derive(Debug)Bounded convergence history for iterative solvers.
#ConvergenceHistory::get
Read a sample safely.
#ConvergenceHistory::is_converging
True when the most recent residual does not increase.
#ConvergenceHistory::latest_residual
Return the latest residual, or zero for an empty history.
#ConvergenceHistory::length
Number of observations stored.
#ConvergenceHistory::new
Allocate a convergence history.
#ConvergenceHistory::push
fn ConvergenceHistory::push(self : ConvergenceHistory, step~ : Int, residual~ : Double, mass~ : Double) -> UnitAppend an observation and discard the oldest one after reaching capacity.
#ConvergenceHistory::residual_ratio
Ratio between the latest and earliest residual.
#ConvergenceHistory::to_csv
Export a convergence history as CSV.
#ConvergenceHistory::to_json
Export convergence history as a compact JSON-like record.
#ConvergenceSample
One residual/mass observation.
#DomainMask
A row-major solid-cell mask used by advanced simulations.
#DomainMask::add_box
Rasterize normalized rectangular bounds.
#DomainMask::add_circle
Rasterize a circle using cell-center coordinates.
#DomainMask::boundary_layer
Return solid cells that touch at least one fluid neighbor.
#DomainMask::bounding_box
Return an axis-aligned solid bounding box.
#DomainMask::centroid
Compute the centroid of solid cells.
#DomainMask::column_counts
Compute the number of solid cells in each column.
#DomainMask::connected_components
Find four-neighbor connected solid regions.
#DomainMask::copy
Return a copy of the mask.
#DomainMask::dilate
Grow solid cells by a four-neighbor stencil.
#DomainMask::erode
Erode solid cells by a four-neighbor stencil.
#DomainMask::first_solid
Return the first solid coordinate, if one exists.
#DomainMask::fluid_boundary
Return fluid cells adjacent to a solid cell.
#DomainMask::fluid_count
Count fluid cells inside the mask.
#DomainMask::geometric_moments
Compute area, centroid, and second moments of solid cells.
#DomainMask::invert
Return a mask with all cells inverted within its finite domain.
#DomainMask::is_solid
Read a solid flag; outside cells are treated as solid.
#DomainMask::perimeter
Count fluid-solid interface faces.
#DomainMask::radius
Return the Euclidean radius of the farthest solid cell from the centroid.
#DomainMask::report
Return a compact summary of a mask.
#DomainMask::row_counts
Compute the number of solid cells in each row.
#DomainMask::set
Set a solid flag when coordinates are inside the mask.
#DomainMask::solid_count
Count solid cells.
#DomainMask::to_ascii
Render a mask as a compact text image.
#DomainMask::to_csv
Export a mask as integer CSV.
#Field2D
A row-major scalar field with clamped interpolation support.
#Field2D::absolute_integral
Integrate absolute values over unit lattice cells.
#Field2D::add_constant
Add a constant to every field value.
#Field2D::boundary_mean
Return the mean value of the outermost one-cell ring.
#Field2D::box_blur
Apply a normalized box blur.
#Field2D::clamp
Apply a bounded pointwise transform.
#Field2D::contains
Return whether integer coordinates are inside the field.
#Field2D::convolve
Apply a finite convolution kernel centered at each cell.
#Field2D::count_above
Count values above a threshold.
#Field2D::crop
Extract a clipped scalar subfield.
#Field2D::dimensions
Return the dimensions of a scalar field.
#Field2D::edge_mask
Return a mask for high-gradient edge cells.
#Field2D::fill
Fill all cells with one value.
#Field2D::flip_horizontal
Flip a field horizontally.
#Field2D::flip_vertical
Flip a field vertically.
#Field2D::get
Read a value, returning zero outside the domain.
#Field2D::gradient_energy
Return the squared gradient energy.
#Field2D::gradient_magnitude
Return the magnitude of the centered gradient at a cell.
#Field2D::gradient_x
Return the x component of the centered gradient.
#Field2D::gradient_y
Return the y component of the centered gradient.
#Field2D::index
Convert a coordinate to a row-major index.
#Field2D::integral
Integrate a scalar field over unit lattice cells.
#Field2D::laplacian
Apply a five-point discrete Laplacian.
#Field2D::map
Apply a pointwise transformation and return a new field.
#Field2D::maximum_location
Return the coordinate of a maximum value, using row-major tie breaking.
#Field2D::mean_on_mask
Compute the mean of values at solid cells.
#Field2D::minimum_location
Return the coordinate of a minimum value.
#Field2D::new
Allocate a scalar field.
#Field2D::nonzero_count
Count values that are not numerically zero.
#Field2D::normalize
Normalize a field into a requested range.
#Field2D::pad
Pad a field with a constant border.
#Field2D::radial_average
Compute a radial average profile around a point.
#Field2D::region_count
Count values in a half-open region that pass a predicate.
#Field2D::region_mean
Average a half-open integer region.
#Field2D::region_sum
Sum a half-open integer region after clipping to the field.
#Field2D::resample
Resample a field with nearest-neighbor interpolation.
#Field2D::rotate90
Rotate a field clockwise by ninety degrees.
#Field2D::sample
Bilinearly sample at floating-point coordinates with edge clamping.
#Field2D::scale_values
Scale every field value.
#Field2D::set
Write a value when the coordinate is inside the domain.
#Field2D::smooth
Average each cell with a square neighborhood.
#Field2D::square
Return a pointwise square of a scalar field.
#Field2D::statistics
Compute unmasked descriptive statistics.
#Field2D::statistics_masked
fn Field2D::statistics_masked(self : Field2D, mask~ : DomainMask, include_solid? : Bool) -> FieldStatisticsCompute statistics while optionally excluding solid mask cells.
#Field2D::target_residual
Compute a scalar field residual against a constant target.
#Field2D::threshold
Return a threshold mask with high values marked solid.
#Field2D::to_ascii
Export a scalar field as a compact ASCII heatmap.
#Field2D::to_csv
Export a scalar field as row-major CSV.
#Field2D::to_json_lines
Export a field as newline-delimited JSON-like points.
#Field2D::to_ppm
Export a scalar field as an ASCII PPM image.
#Field2D::to_vtk
Export a scalar field in a simple VTK legacy structured-points format.
#Field2D::values
Copy the underlying data in row-major order.
#FieldStatistics
pub(all) struct FieldStatistics {
count : Int
sum : Double
mean : Double
minimum : Double
maximum : Double
variance : Double
l2_norm : Double
} derive(Debug)Summary statistics for a scalar field.
#GeometricMoments
Integer geometric moments of a solid mask.
#GridPoint
Integer coordinate used by connected-component reports.
#Lattice
D2Q9 lattice Boltzmann state. Distribution arrays are stored in
cell-major order: (y * width + x) * 9 + direction.
#Lattice::add_cylinder
Place a solid circular obstacle.
#Lattice::apply_mask
Apply a reusable mask to legacy solid flags.
#Lattice::cell
Reconstruct density and velocity at a cell from distribution values.
#Lattice::cell_index
Convert coordinates to a cell index.
#Lattice::cells
Return all macroscopic cells in row-major order.
#Lattice::compressibility_error
Return mean absolute divergence for a legacy lattice.
#Lattice::contains
True when the coordinate is inside the domain.
#Lattice::density_field
Convert a legacy lattice density field to a reusable scalar type.
#Lattice::dimensions
Return the legacy lattice dimensions.
#Lattice::dist_index
Convert coordinates and direction to a distribution index.
#Lattice::divergence_field
Return the centered divergence of a legacy velocity field.
#Lattice::domain_mask
Copy the legacy solid mask into a reusable domain mask.
#Lattice::field_statistics
Return a compact field quality summary.
#Lattice::horizontal_profile
Sample ux along one horizontal row.
#Lattice::is_solid
Read whether a cell is solid.
#Lattice::kinetic_energy
Compute legacy kinetic energy.
#Lattice::mass_drift
Compute the absolute mass drift after a run.
#Lattice::maximum_pressure
Return the maximum legacy pressure.
#Lattice::maximum_speed_location
Return the location of the largest legacy speed.
#Lattice::maximum_strain_rate
Return the maximum legacy strain rate.
#Lattice::mean_pressure
Return the mean legacy pressure.
#Lattice::mean_ux
Mean horizontal velocity over non-solid cells.
#Lattice::new
Create an equilibrium lattice with density 1 and zero velocity.
#Lattice::pressure_field
Return the legacy isothermal pressure field.
#Lattice::pressure_range
Return the legacy pressure range.
#Lattice::reset_fluid
Set every legacy fluid cell to equilibrium zero velocity.
#Lattice::rho_field
Extract density values in row-major order.
#Lattice::set_box_walls
Mark the outer box as no-slip walls.
#Lattice::set_cavity_walls
Mark bottom, left, and right walls while leaving the top row for a moving lid.
#Lattice::set_cell
Reset one fluid cell to a chosen macroscopic state.
#Lattice::set_channel_walls
Mark only the top and bottom rows as channel walls.
#Lattice::set_moving_lid
Initialize the upper row as a moving lid.
#Lattice::set_poiseuille_profile
Initialize a parabolic channel profile between the solid top and bottom rows.
#Lattice::set_solid
Mark or clear a solid bounce-back cell.
#Lattice::set_uniform_inlet
Initialize a vertical inlet stripe with a uniform horizontal velocity.
#Lattice::speed_ascii
Render a compact text heatmap of velocity magnitude.
#Lattice::speed_field
Extract velocity magnitude values in row-major order.
#Lattice::speed_scalar_field
Return a scalar field of legacy speed magnitudes.
#Lattice::stability
Compute simple stability diagnostics for regression checks and demos.
#Lattice::step
Advance the lattice by one collide-stream step.
#Lattice::strain_rate_field
Return the legacy strain-rate magnitude field.
#Lattice::summary
Human-readable one-block simulation summary.
#Lattice::to_csv
Export rho/ux/uy/speed/solid fields as CSV text.
#Lattice::to_png
Encode velocity magnitude as a small RGB PNG image.
#Lattice::ux_field
Extract horizontal velocity values in row-major order.
#Lattice::uy_field
Extract vertical velocity values in row-major order.
#Lattice::velocity_field
Convert a legacy lattice velocity field to the reusable vector type.
#Lattice::vertical_profile
Sample ux along one vertical column.
#Lattice::vorticity_at
Estimate scalar vorticity at one cell, duy/dx - dux/dy.
#Lattice::vorticity_csv
Export vorticity as CSV for quick plotting.
#Lattice::vorticity_field
Estimate scalar vorticity with centered differences where possible.
#MaskReport
pub(all) struct MaskReport {
total_cells : Int
solid_cells : Int
fluid_cells : Int
solid_fraction : Double
} derive(Debug)A report about the solid mask.
#MemoryEstimate
pub(all) struct MemoryEstimate {
cells : Int
distribution_bytes : Int
next_bytes : Int
mask_bytes : Int
scalar_field_bytes : Int
vector_field_bytes : Int
total_bytes : Int
} derive(Debug)Estimated memory footprint of row-major simulation arrays.
#MemoryEstimate::to_string
Format a memory estimate in a readable form.
#NumericalHealth
pub(all) struct NumericalHealth {
finite : Bool
positive_density : Bool
mass_residual : Double
max_mach : Double
min_density : Double
max_density : Double
pass : Bool
} derive(Debug)Numerical health signals used by reports and quality gates.
#ParameterSweep
pub(all) struct ParameterSweep {
omegas : Array[Double]
steps : Int
boundary : BoundaryMode
} derive(Debug)A one-dimensional relaxation parameter sweep.
#ParameterSweep::new
fn ParameterSweep::new(omegas~ : Array[Double], steps~ : Int, boundary? : BoundaryMode) -> ParameterSweepBuild a sweep over supplied relaxation values.
#Point
A two-dimensional point or vector.
#Point::distance
Distance between two points.
#Preset
Reusable scenario presets for examples and parameter sweeps.
#Probe
#RunPlan
pub(all) struct RunPlan {
steps : Int
sample_every : Int
record_initial : Bool
stop_on_unstable : Bool
} derive(Debug)#RunSummary
pub(all) struct RunSummary {
steps : Int
samples : Int
final_mass : Double
final_max_speed : Double
converged : Bool
stopped_early : Bool
} derive(Debug)Summary returned by a planned run.
#RunSummary::mass_change
Return the absolute mass change represented by a run summary.
#RunSummary::to_csv
Serialize a run summary as CSV.
#ScalarBoundary
Boundary behavior for a passive scalar.
#ScalarReport
A compact scalar report.
#ScalarReport::to_csv
Export a scalar report as CSV.
#ScalarReport::to_markdown
Export a scalar report as a Markdown row.
#ScalarSolver
Explicit finite-difference advection-diffusion solver for one scalar.
#ScalarSolver::absolute_mass
Return the sum of absolute scalar values.
#ScalarSolver::add_uniform_source
Apply a source to every cell.
#ScalarSolver::clamped_field
Return a bounded scalar field with a new lower and upper range.
#ScalarSolver::clear_sources
Clear all source terms.
#ScalarSolver::count_above
Count cells above a scalar threshold.
#ScalarSolver::courant_number
Estimate a scalar Courant number for a uniform velocity.
#ScalarSolver::diffusion_number
Estimate the explicit diffusion stability number.
#ScalarSolver::domain
Return the field size.
#ScalarSolver::explicitly_stable
Return true when an explicit scalar step is within the five-point limit.
#ScalarSolver::field
Convert the scalar values to a reusable field object.
#ScalarSolver::fill
Fill the scalar field.
#ScalarSolver::get
Read one scalar value with boundary-aware extension.
#ScalarSolver::gradient_energy
Return the L2 energy of scalar gradients.
#ScalarSolver::gradient_magnitude
Return the current scalar gradient field magnitude.
#ScalarSolver::is_above
True when no scalar is below a supplied lower bound.
#ScalarSolver::is_finite
True when every stored scalar is finite.
#ScalarSolver::laplacian
Return the current scalar Laplacian.
#ScalarSolver::mass
Total scalar quantity in the domain.
#ScalarSolver::mass_ratio
Return the fraction of the initial mass remaining.
#ScalarSolver::maximum
Return the maximum scalar value.
#ScalarSolver::maximum_location
Return the position of the first maximum scalar cell.
#ScalarSolver::maximum_source
Return the maximum source magnitude.
#ScalarSolver::mean
Return the mean scalar value.
#ScalarSolver::mean_source
Return the mean source contribution.
#ScalarSolver::minimum
Return the minimum scalar value.
#ScalarSolver::minimum_location
Return the position of the first minimum scalar cell.
#ScalarSolver::new
fn ScalarSolver::new(size~ : Size, diffusivity~ : Double, dt~ : Double, boundary? : ScalarBoundary) -> ScalarSolverAllocate a scalar transport field.
#ScalarSolver::normalized_field
Return the scalar state as normalized output.
#ScalarSolver::report
Build a scalar report.
#ScalarSolver::set
Set one scalar value.
#ScalarSolver::set_source
Set a per-cell source term.
#ScalarSolver::source_mass
Total absolute source strength currently configured.
#ScalarSolver::stability_number
Return the dimensionless diffusion stability number.
#ScalarSolver::statistics
Return descriptive scalar statistics.
#ScalarSolver::steady_state_error
Absolute error between the current mean and a target state.
#ScalarSolver::step
Advance with a zero velocity field.
#ScalarSolver::step_many
Advance a scalar solver several times.
#ScalarSolver::step_with_velocity
Set a uniform velocity and advance one advection-diffusion step.
#ScalarSolver::variance
Scalar variance over all cells.
#Scenario
High level demo scenario.
#Shape
A shape that can be rasterized into a lattice mask.
#Shape::circle
Build a circle shape.
#Shape::contains
Test a shape using lattice-cell-center coordinates.
#Simulation
A reusable D2Q9 simulation with selectable collision and outer boundaries.
#Simulation::add_box
Add a rectangular obstacle.
#Simulation::add_circle
Add a circular obstacle.
#Simulation::apply_boundary_map
Apply semantic wall and obstacle labels to a simulation.
#Simulation::apply_mask
Apply a reusable geometry mask.
#Simulation::boundary_map
Build a label map from a simulation's solid geometry.
#Simulation::boundary_report
Return a boundary diagnostic report for the current simulation mask.
#Simulation::cell
Read the macroscopic state at a cell.
#Simulation::cells
Return all fluid cells in row-major order.
#Simulation::checkpoint_size
Return the serialized checkpoint size in bytes.
#Simulation::compressibility_error
Return the mean absolute divergence.
#Simulation::contains
Return whether integer coordinates are inside the simulation.
#Simulation::current_mask
Copy the current solid geometry.
#Simulation::density_csv
Export density as a CSV grid.
#Simulation::density_field
Build a density field from the simulation state.
#Simulation::density_variation
Return the normalized density variation.
#Simulation::distribution_count
Return the number of stored distribution populations.
#Simulation::distribution_index
Convert coordinates and direction to a distribution index.
#Simulation::distribution_values
Copy the distribution payload for diagnostics or persistence adapters.
#Simulation::divergence_at
Centered divergence of a velocity field.
#Simulation::divergence_field
Return the divergence field.
#Simulation::flow_rate
Sum horizontal or vertical velocity along one lattice line.
#Simulation::fluid_count
Count fluid cells in an advanced simulation.
#Simulation::force_on_mask
Estimate the net force on solid cells from local interface momentum exchange.
#Simulation::forced_copy
Add a uniform body force to the current velocity state through options.
#Simulation::from_checkpoint
Restore a simulation from Simulation::to_checkpoint output.
#Simulation::health
Compute health metrics for a reusable simulation.
#Simulation::horizontal_profile
Return a horizontal velocity profile.
#Simulation::is_equilibrium
Return whether the distribution is within tolerance of local equilibrium.
#Simulation::is_solid
Read a solid flag; outside coordinates are solid.
#Simulation::kinetic_energy
Total kinetic energy over fluid cells.
#Simulation::kinetic_energy_field
Construct a field of local kinetic energy densities.
#Simulation::mass_drift
Absolute mass drift from a reference mass.
#Simulation::max_mach
Return the maximum absolute speed in a simulation.
#Simulation::maximum_density
Find the maximum fluid density.
#Simulation::maximum_strain_rate
Return the maximum strain-rate magnitude.
#Simulation::mean_density
Return the mean density over fluid cells.
#Simulation::mean_velocity
Compute the mean velocity over fluid cells.
#Simulation::minimum_density
Find the minimum fluid density.
#Simulation::momentum_x_field
Construct the x component of local momentum density.
#Simulation::momentum_y_field
Construct the y component of local momentum density.
#Simulation::new
Allocate an equilibrium advanced simulation.
#Simulation::payload_bytes
Estimate the payload bytes without allocating a checkpoint string.
#Simulation::pressure_at
Local pressure under the isothermal D2Q9 equation of state.
#Simulation::pressure_field
Return the pressure field.
#Simulation::report
Build a report from a reusable simulation.
#Simulation::run
Advance several steps.
#Simulation::run_plan
Execute a run plan and record deterministic observation count.
#Simulation::same_geometry
Return whether two simulations share dimensions and solid geometry.
#Simulation::sample_component
fn Simulation::sample_component(self : Simulation, axis~ : Axis, index~ : Int, component~ : String) -> Array[Double]Sample a line of one scalar component.
#Simulation::sample_line
Sample a complete line of macroscopic cells.
#Simulation::sample_line_csv
fn Simulation::sample_line_csv(self : Simulation, axis~ : Axis, index~ : Int, component~ : String) -> StringExport a line profile with a component name.
#Simulation::sample_probe
Sample one probe using nearest-cell or bilinear interpolation.
#Simulation::set_box_walls
Mark the four domain walls as solid.
#Simulation::set_cell
fn Simulation::set_cell(self : Simulation, x~ : Int, y~ : Int, rho~ : Double, ux~ : Double, uy~ : Double) -> UnitReset a cell to an equilibrium state.
#Simulation::set_poiseuille_profile
Apply a parabolic channel profile to an advanced simulation.
#Simulation::set_pressure_outlet
fn Simulation::set_pressure_outlet(self : Simulation, x~ : Int, density~ : Double, ux? : Double, uy? : Double) -> UnitInitialize a vertical density outlet stripe.
#Simulation::set_solid
Set a solid flag inside the simulation.
#Simulation::set_uniform
Initialize all fluid cells to the same macroscopic state.
#Simulation::set_velocity_inlet
fn Simulation::set_velocity_inlet(self : Simulation, x~ : Int, ux~ : Double, uy~ : Double, rho? : Double) -> UnitInitialize a vertical velocity inlet stripe.
#Simulation::solid_count
Count solid cells in an advanced simulation.
#Simulation::solid_values
Copy the solid-cell mask in row-major order.
#Simulation::speed_csv
Export velocity magnitude as a CSV grid.
#Simulation::speed_field
Return a scalar field of advanced speed magnitude.
#Simulation::stability
Compute stability metrics for an advanced simulation.
#Simulation::state_checksum
Compute a deterministic checksum over geometry and populations.
#Simulation::state_delta
Compare two states using a normalized distribution L2 error.
#Simulation::state_fingerprint
Produce a compact, deterministic identity for a simulation state.
#Simulation::state_summary
Return a human-readable state summary for logs and notebooks.
#Simulation::step
Advance one collision/stream/boundary step.
#Simulation::steps
Return the number of completed time steps.
#Simulation::strain_rate_at
Centered strain-rate tensor magnitude.
#Simulation::strain_rate_field
Return the strain-rate magnitude field.
#Simulation::to_checkpoint
Serialize a simulation into a versioned, dependency-free text checkpoint.
#Simulation::velocity_csv
Export velocity components as a CSV point table.
#Simulation::velocity_field
Build a velocity field from the simulation state.
#Simulation::vertical_profile
Return a vertical velocity profile.
#Simulation::vorticity_at
Estimate scalar vorticity with centered differences.
#Simulation::vorticity_field
Return a row-major vorticity field.
#SimulationOptions
pub(all) struct SimulationOptions {
model : CollisionModel
boundary : BoundaryMode
force_x : Double
force_y : Double
density_floor : Double
max_mach : Double
} derive(Debug)Configuration shared by collision, streaming, and stability checks.
#SimulationOptions::new
fn SimulationOptions::new(model~ : CollisionModel, boundary? : BoundaryMode, force_x? : Double, force_y? : Double, density_floor? : Double, max_mach? : Double) -> SimulationOptionsBuild conservative solver options.
#SimulationReport
Human-facing simulation report.
#SimulationReport::to_csv
Format a report as CSV.
#SimulationReport::to_json
Format a report as a small JSON object.
#SimulationReport::to_markdown
Format a report as a Markdown table row.
#Size
#Stability
pub(all) struct Stability {
min_rho : Double
max_rho : Double
max_speed : Double
mass : Double
has_nan : Bool
recommended : Bool
} derive(Debug)Runtime stability summary for a lattice.
#StatisticsAccumulator
pub(all) struct StatisticsAccumulator {
count : Int
sum : Double
sum_squares : Double
minimum : Double
maximum : Double
} derive(Debug)A small online accumulator for streaming diagnostics.
#StatisticsAccumulator::finish
Convert a streaming accumulator into descriptive statistics.
#StatisticsAccumulator::new
Create an empty streaming accumulator.
#StatisticsAccumulator::push
Add one value to a streaming accumulator.
#SweepResult
pub(all) struct SweepResult {
omega : Double
steps : Int
mass : Double
max_speed : Double
stable : Bool
health_pass : Bool
} derive(Debug)One parameter sweep result.
#ValidationError
Configuration errors are explicit so callers can reject unsafe runs.
#VectorField2D
A two-component velocity field aligned with a scalar grid.
#VectorField2D::add
Add two vector fields over their overlapping rectangle.
#VectorField2D::blend
fn VectorField2D::blend(self : VectorField2D, other : VectorField2D, weight~ : Double) -> VectorField2DBlend two vector fields using a clamped weight.
#VectorField2D::clamp_speed
Limit vector magnitude while preserving direction.
#VectorField2D::component_sum
Sum one named component, with speed as a useful derived option.
#VectorField2D::curl_field
Compute the scalar curl (vorticity) field.
#VectorField2D::curl_l1
L1 norm of a derived curl field.
#VectorField2D::difference
Subtract another vector field from this one.
#VectorField2D::dimensions
Return the dimensions carried by a vector field.
#VectorField2D::divergence_field
Compute a centered finite-difference divergence field.
#VectorField2D::divergence_l1
L1 norm of a derived divergence field.
#VectorField2D::dot
Compute the pointwise vector dot product.
#VectorField2D::fill
Fill a velocity field with a uniform vector.
#VectorField2D::get
Read a velocity with zero extension outside the grid.
#VectorField2D::gradient_energy
Compute the total squared gradient of vector components.
#VectorField2D::height
Return the height of a vector field.
#VectorField2D::horizontal_field
Copy the horizontal component into a scalar field.
#VectorField2D::is_finite
Return whether every stored component is finite.
#VectorField2D::kinetic_energy
Return the integrated kinetic energy density.
#VectorField2D::magnitude_field
Convert a vector field to a scalar magnitude field.
#VectorField2D::max_component
Find the largest absolute component in a vector field.
#VectorField2D::mean_square_speed
Compute the mean squared magnitude of a vector field.
#VectorField2D::momentum
Integrate vector components over the grid.
#VectorField2D::negate
Return the negative of every vector.
#VectorField2D::new
Allocate a zero velocity field.
#VectorField2D::normalized
Normalize each nonzero vector independently.
#VectorField2D::sample
Sample both velocity components bilinearly.
#VectorField2D::scale
Scale every vector by one factor.
#VectorField2D::set
Set a velocity at one cell.
#VectorField2D::size
Return the number of stored cells in a vector field.
#VectorField2D::speed_statistics
Compute descriptive statistics for vector speed.
#VectorField2D::to_csv
Export a vector field as CSV.
#VectorField2D::ux_field
Copy the x component of a vector field.
#VectorField2D::uy_field
Copy the y component of a vector field.
#VectorField2D::vertical_field
Copy the vertical component into a scalar field.
#VectorField2D::width
Return the width of a vector field.
#abs_double
fn abs_double(value : Double) -> DoubleReturn the absolute value without relying on a target-specific helper.
#analyze_boundary_mask
Count interface faces and corner cells.
#apply_boundary
Apply a local boundary specification.
#apply_pressure_boundary
Reconstruct a pressure boundary and preserve its supplied tangential velocity.
#apply_velocity_boundary
Reconstruct a velocity boundary from its requested equilibrium moments.
#argmax
Return the index of the first finite maximum.
#audit_options
Audit options before a long numerical run.
#benchmark_statistics
Compute aggregate benchmark statistics.
#benchmark_suite_csv
Export a suite as CSV with a stable header.
#benchmark_suite_is_usable
Return true when every report is stable and finite.
#benchmark_suite_markdown
Export a suite as a Markdown table.
#best_benchmark
Return the report with the smallest L2 error.
#best_sweep_result
Return the stable sweep result with the smallest maximum speed.
#better_report
Return the better of two stable reports by L2 error.
#bounce_direction
fn bounce_direction(direction : Int) -> IntReturn the opposite direction used by a bounce-back link.
#boundary_label_name
Convert a label to a stable string.
#bundle_memory_bytes
Return an upper bound on bytes for a scalar/vector/checkpoint bundle.
#central_difference
Central difference at an index, with one-sided edge handling.
#clamp_double
fn clamp_double(value : Double, low~ : Double, high~ : Double) -> DoubleClamp a floating-point value to a closed interval.
#clamp_int
fn clamp_int(value : Int, low~ : Int, high~ : Int) -> IntClamp an integer to a closed interval.
#collide_distribution
fn collide_distribution(distribution : ArrayView[Double], rho~ : Double, ux~ : Double, uy~ : Double, model~ : CollisionModel) -> Array[Double]Apply BGK, regularized, or MRT collision while preserving mass and momentum.
#collision_model_name
Return a stable model name.
#compare_reports
Compare the error and conservation fields of two reports.
#cosine_similarity
Compute a normalized cosine similarity.
#cumulative_distribution
Compute a normalized cumulative distribution.
#cylinder_wake
fn cylinder_wake(width~ : Int, height~ : Int, radius? : Int, omega? : Double, inlet_velocity? : Double) -> LatticeBuild a channel with a circular obstacle for wake experiments.
#distance_to_solid
Return a scalar field of solid-cell distance in four-neighbor steps.
#distribution_cell
Reconstruct macroscopic quantities from one distribution vector.
#distribution_is_physical
Check a distribution vector for finite and nonnegative populations.
#distribution_length
Return the number of distribution values in a domain.
#distribution_mass
Return the zeroth moment of a distribution vector.
#distribution_momentum_x
Return the x momentum of a distribution vector.
#distribution_momentum_y
Return the y momentum of a distribution vector.
#dot_product
Dot product of two numeric vectors.
#equilibrium
fn equilibrium(d : Int, rho : Double, ux : Double, uy : Double) -> DoubleD2Q9 equilibrium distribution for a direction.
#equilibrium_distribution
Build a D2Q9 equilibrium vector.
#equilibrium_error
fn equilibrium_error(distribution : ArrayView[Double], rho~ : Double, ux~ : Double, uy~ : Double) -> DoubleMaximum absolute deviation from equilibrium moments.
#error_improved
Return true when a later report has lower L2 error.
#error_trend
Return an error trend between two reports.
#field_blend
Blend two fields with a scalar weight.
#field_difference
Compute a field difference.
#field_dot
Compute the covariance-like dot product of two equal-sized fields.
#field_is_nonnegative
Check that a field has no negative values below a tolerance.
#field_residual
Compute a finite residual between two scalar fields.
#fields_are_finite
Check density/velocity fields for finite values.
#finite_fraction
Return the fraction of finite values in a scalar field.
#finite_or
fn finite_or(value : Double, fallback~ : Double) -> DoubleReturn a fallback when a value is NaN or infinite.
#fluid_neighbor_count
Count the number of fluid neighbors of a lattice cell.
#force_limit_from_density
fn force_limit_from_density(density~ : Double, max_mach~ : Double) -> DoubleReturn a stable force magnitude bound.
#forward_differences
Return a forward difference vector.
#gradient_at
Compute a central-difference gradient at one scalar cell.
#histogram
Return a normalized histogram with a fixed number of bins.
#kinematic_viscosity
Estimate the kinematic viscosity of a D2Q9 shear mode.
#l2_error
Absolute L2 error normalized by the number of samples.
#laplacian_at
Compute the scalar Laplacian at one cell.
#legacy_preset
Build the matching high-level legacy scenario.
#lerp
fn lerp(a : Double, b : Double, t : Double) -> DoubleLinear interpolation between two values.
#lid_driven_cavity
Build a square cavity with a moving lid encoded as initial velocity near the top.
#linf_error
Maximum absolute error over the overlapping samples.
#mach_number
fn mach_number(ux~ : Double, uy~ : Double) -> DoubleCompute the lattice Mach number of a velocity vector.
#mask_intersection
Intersect two masks over their shared domain.
#mask_union
Union two masks over their shared domain.
#max_speed
Return the maximum speed in a vector field.
#maximum_mass_drift
Return the largest mass drift in a report set.
#mean_value
Arithmetic mean, returning zero for an empty vector.
#memory_estimate
Estimate payload memory without hiding allocation overhead.
#min_max
Return the smallest and largest finite values in a vector.
#momentum_exchange
Compute the local momentum exchange of a reflected population.
#nearly_zero
fn nearly_zero(value : Double, tolerance? : Double) -> BoolTrue when a value is close to zero under an absolute tolerance.
#omega_grid
Create a regular relaxation grid, inclusive of its endpoints.
#periodic_coordinate
fn periodic_coordinate(value : Int, extent : Int) -> IntReturn a periodic coordinate for a lattice extent.
#poiseuille
Build a pressure-driven channel with no-slip top and bottom walls.
#poiseuille_reference_profile
Build the analytical channel profile used by the Poiseuille comparison.
#prefix_sums
Return cumulative sums.
#preset_description
Return a compact preset description.
#preset_name
Return a stable human-readable preset name.
#preset_options
Return conservative collision settings for a preset.
#preset_output_kind
Return the expected output family for a preset.
#preset_size
Return default lattice dimensions for a preset.
#preset_velocity
Return the estimated characteristic velocity of a preset.
#rasterize_shape
Rasterize a shape into a new mask.
#recommended_steps
Return a demonstration step count.
#regularized_stress
A second-order regularized non-equilibrium stress estimate.
#relative_l2_error
Relative L2 error with a stable zero-reference convention.
#relaxation_from_viscosity
fn relaxation_from_viscosity(viscosity : Double) -> DoubleEstimate a relaxation parameter from a target viscosity.
#relaxation_is_stable
fn relaxation_is_stable(omega : Double) -> BoolReturn whether a relaxation value is in the open stable interval.
#reports_are_healthy
Return true when every report passes its numerical health gate.
#reports_to_markdown
Combine several reports into a Markdown table.
#resize_vector
Return a vector with a fixed length and a fill value.
#run_benchmark_suite
Run the three reference cases used by the CLI and documentation.
#run_cavity_benchmark
Run a cavity benchmark against a zero-velocity interior reference.
#run_completed
Return true when a run summary reached its planned length.
#run_cylinder_benchmark
Run an obstacle-wake benchmark and report a vorticity magnitude summary.
#run_parameter_sweep
Execute every point in a relaxation sweep.
#run_poiseuille_benchmark
Run a measured Poiseuille profile comparison.
#run_resolution_study
Run a small resolution study for Poiseuille flow.
#run_summary_distance
Compare two run summaries by final mass and speed.
#safe_divide
fn safe_divide(numerator : Double, denominator : Double, fallback~ : Double) -> DoubleA division that returns a caller-selected value for a zero denominator.
#safest_report
Return the most stable report by maximum speed.
#sample_polyline
Sample a scalar field along a polyline.
#scalar_diffusion_time
fn scalar_diffusion_time(length~ : Double, diffusivity~ : Double) -> DoubleCompute the scalar diffusion time for a characteristic length.
#scalar_finite_or
fn scalar_finite_or(value : Double, fallback~ : Double) -> DoubleReturn a finite scalar value or a fallback for diagnostics.
#scalar_mass_change
Return the sum of scalar changes between two solver states.
#scalar_peclet_number
fn scalar_peclet_number(velocity~ : Double, length~ : Double, diffusivity~ : Double) -> DoubleCompute the scalar Péclet number for a characteristic length.
#scalar_state_error
Difference between two scalar solver states.
#scenario
Build a named demo scenario with conservative default dimensions.
#schedule_intervals
Plan a geometrically increasing sequence of sample intervals.
#size_is_allocatable
Return true when a domain has a safe positive allocation size.
#smoothstep
fn smoothstep(edge0~ : Double, edge1~ : Double, value~ : Double) -> DoubleCubic smoothstep interpolation on an unclamped parameter.
#speed_limit_from_mach
fn speed_limit_from_mach(max_mach~ : Double) -> DoubleReturn a conservative inlet speed bound for a Mach limit.
#square_memory_estimate
Return an upper bound on a square simulation footprint.
#stable_benchmark_count
Return the number of stable reports in a suite.
#stable_relaxation_range
fn stable_relaxation_range() -> (Double, Double)Return the relaxation range that passes the ordinary BGK stability criterion.
#sum_values
Sum a vector without changing its order.
#sweep_results_csv
Serialize sweep results as CSV.
#sweep_stability_fraction
Return the stable fraction of a sweep.
#trace_streamline
fn trace_streamline(velocity : VectorField2D, start~ : Point, step_size~ : Double, max_steps~ : Int) -> Array[Point]Trace a streamline with first-order Euler integration.
#validate_checkpoint
Validate a checkpoint without retaining the restored simulation.
#validate_options
Validate solver options before allocating a simulation.
#validate_size
Validate a rectangular domain size.
#variance_value
Population variance, returning zero for fewer than two values.
#viscosity_from_relaxation
fn viscosity_from_relaxation(omega : Double) -> DoubleEstimate the BGK viscosity for an omega value.
#weighted_mean
Compute a weighted mean with a zero-weight fallback.
Source Files
- advanced_math.mbt
- advanced_solver.mbt
- analysis_advanced.mbt
- benchmark_extra.mbt
- benchmark_statistics.mbt
- benchmarks.mbt
- boundary.mbt
- boundary_application.mbt
- boundary_diagnostics.mbt
- boundary_map.mbt
- boundary_schemes.mbt
- checkpoint.mbt
- collision_models.mbt
- config_audit.mbt
- config_validation.mbt
- constants.mbt
- diagnostics.mbt
- export_advanced.mbt
- export_csv.mbt
- export_png.mbt
- export_summary.mbt
- field_api_extension.mbt
- field_calculus.mbt
- field_exports_extra.mbt
- fields.mbt
- flow_derivatives.mbt
- geometry.mbt
- geometry_boundaries.mbt
- grid.mbt
- lattice.mbt
- lattice_advanced.mbt
- lattice_flow_reports.mbt
- math_utils.mbt
- memory_layout.mbt
- mesh_tools.mbt
- numerical_checks.mbt
- presets.mbt
- probes.mbt
- reporting.mbt
- sampling.mbt
- scalar_analysis.mbt
- scalar_pipeline.mbt
- scalar_transport.mbt
- scenarios.mbt
- scheduler.mbt
- simulation_controls.mbt
- simulation_state_api.mbt
- solver.mbt
- sweep.mbt
- time_series.mbt
- types.mbt
- vector_api_extension.mbt
A D2Q9 lattice Boltzmann fluid simulation core for MoonBit.
lbmfluidsimulationd2q9cfd
0.2.1
Apache-2.0
Updated 3 hours ago
4 downloads