jainothniel/ludwig_multiple_particle

Purpose and entry points

Ludwig is an ANSI C, distributed-memory simulation engine for complex fluids. It combines lattice-Boltzmann hydrodynamics with free-energy/order-parameter models for mixtures, colloids, gels, liquid crystals, and electrokinetics. The executable starts at src/main.c; top-level orchestration and time stepping are centered in src/ludwig.c and src/control.c. Builds are driven by Makefile and src/Makefile.

Runtime, parallelism, and execution model

MPI provides domain-decomposed distributed-memory execution through the parallel-environment and coordinate layers (src/pe.c, src/coords.c). A serial MPI compatibility implementation exists in mpi_s/mpi_serial.c. Compute kernels use TargetDP abstractions, selecting x86/OpenMP, CUDA, or HIP implementations via target/target.h, target/target_cuda.c, and target/target_hip.c. This is an HPC batch executable, not a service-oriented application.

Initialization and configuration boundary

Runtime input is parsed and transformed into model options and initialized state through src/runtime.c, src/physics_rt.c, and src/build.c. This separates textual run configuration from allocated simulation objects. Spatial decomposition, lattice geometry, and boundary topology are established before physics modules; runtime-specific *_rt.c files configure optional models without embedding input parsing in core numerical kernels.

Hydrodynamic lattice-Boltzmann core

The fluid solver owns lattice distributions, collision/propagation, and macroscopic hydrodynamic fields. Key components are src/lb_model.c, src/collision.c, and src/propagation.c; supported velocity lattices include src/lb_d2q9.c, src/lb_d3q19.c, and src/lb_d3q27.c. Hydrodynamics is exposed through src/hydro.c, while inflow/outflow and moving/sheared-domain conditions are implemented at the solver boundary, e.g. src/lb_bc_inflow_rhou.c and src/leesedwards.c.

Free-energy fields and coupled physics

A shared field/gradient layer (src/field.c, src/field_grad.c, src/free_energy.h) lets selected free-energy models produce chemical potentials, stresses, and forces for the fluid. Major model families include symmetric and ternary mixtures (src/symmetric.c, src/fe_ternary.c), Cahn–Hilliard transport (src/cahn_hilliard.c, src/phi_cahn_hilliard.c), liquid crystals/blue phases (src/blue_phase.c, src/blue_phase_beris_edwards.c), and electrokinetics (src/psi.c, src/nernst_planck.c). Couplers such as src/phi_lb_coupler.c transfer field-derived forcing into LB evolution.

Particles, solid boundaries, and interactions

Colloid state, links to the lattice, halo exchange, and motion are handled by src/colloid.c, src/colloids.c, and src/colloids_halo.c. Bounce-back coupling (src/bbl.c) forms the principal fluid–solid/particle boundary. Pair potentials, bonds, lubrication, walls, and map-defined solids provide optional mechanical interactions: src/interaction.c, src/lubrication.c, and src/map.c. These modules consume hydrodynamic/field forces and feed particle and boundary effects back into the time step.

I/O, observability, and external dependencies

Parallel output is abstracted behind src/io_impl.c with MPI-IO support in src/io_impl_mpio.c; aggregation, subfiles, metadata, and event scheduling are in src/io_aggregator.c, src/io_subfile.c, and src/io_event.c. Statistics modules emit derived physical measures alongside snapshots. MPI is fundamental; PETSc is an optional electrostatic solver integration (src/psi_petsc.c, src/util_petsc.c); bundled cJSON support is exposed through src/util_cJSON.c.

Validation and deployment surfaces

Regression inputs exercise full executable configurations under tests/regression/; unit coverage targets core C modules under tests/unit/. Platform/compiler configurations cover GCC, MPI, CUDA/NVCC, HIP, Cray, and Intel environments in config/, including config/unix-mpicc-default.mk and config/unix-hipcc-nvcc.mk. CI workflows execute regression and analysis in .github/workflows/regression.yml and .github/workflows/codeql-analysis.yml.