Susp3D: Lattice-Boltzmann simulation code for particle-fluid suspensions Copyright (C) 2003 Tony Ladd This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -------------------------------------------------------------------- INTRODUCTION Version 3 is the first public release of my efforts to develop a numerical simulation method for particle-fluid suspensions, based on the lattice-Boltzmann model of the fluid. In the past I have given out versions of the code in response to requests from colleagues. This version is far superior to those, both in reliability and functionality. It is now released under a GPL license. The basic ideas are those described in my papers in Journal of Fluid Mechanics [Ladd, J. Fluid Mech., 271:285, 311 (1994)]. Some subtle improvements to the lattice-Boltzmann model described recently [Ladd and Verberg, J. Stat. Phys., 104, 1191 (2001)], are also implemented. The boundary conditions are basically as described in the JFM papers, but modified to exclude internal fluid as suggested by Aidun and Lu, J. Fluid Mech., 373:287 (1998). Recent innovations, which can substantially reduce the fluctuations in force as the particle moves across the grid [Verberg and Ladd, Phys. Rev. Lett. 84:2148 (2000)] have not yet been implemented. An important improvement is an implicit update of the particle velocity, based on the work of Chris Lowe [Lowe et al. J. Chem. Phys., 103:1582 (1995)], but modified to take account of special cases when particles are close to contact. Lubrication forces are now included up to constant terms and patched smoothly onto the lattice-Boltzmann model. The resulting equations are stiff if the particles are near contact. Thus a cluster analysis is used to group closely spaced particles, in order to minimize the size of the matrices needed for implicit updates. These ideas are described fully in a recent paper [Nguyen and Ladd, Phys. Rev. 66:046708 (2002)]. Recently, Rolf Verberg and I made some modifications to the lubrication forces to allow for a physical lubrication cutoff, such as occurs in gas-solid suspensions. This package contains sources for the main program, configuration generation and data analysis. There are scripts for managing parallel jobs and several examples to try. I have tried to provide adequate documentation via a number of README.txt files in the appropriate places. Hope you find it useful. Let me know how it can be improved. If you publish results obtained with this code or a derivative, I would appreciate an acknowledgement. -------------------------------------------------------------------- -------------------------------------------------------------------- DISCLAIMER This program is distributed as is, and I take no responsibility for any errors or omissions in it. I will fix well documented problems as time permits. Please send input files (from init directory), LOG file and output files (from data directory) to me (ladd@che.ufl.edu), together with a detailed description of the problem. In the case of a problem with a parallel version, first determine if the problem is in the serial version as well. -------------------------------------------------------------------- -------------------------------------------------------------------- INSTALLATION The files are stored in a UNIX gzipped tar file. On a UNIX machine: tar xzf Susp3D-v3.xxx.tar.gz ln -s Susp3D-v3.xxx Susp3D On a Windows machine: Use WinZip to create the Susp3D directory. Ensure that the smart carriage return/line feed option is checked. The code has been developed for a Linux-Beowulf cluster of PC's, but the serial version at least should run under other operating systems, including MS Windows. I have run earlier incarnations of this program under Windows NT, using the Microsoft C compiler. The directory Susp3D then contains 5 subdirectories:- config_src/ configuration generation source files data_src/ data analysis source files src/ main source files utils/ scripts for running on a Unix cluster samples/ examples and documentation In addition to the directories created by the installation, you should create (in Susp3D) two more directories bin/ all executables config/ particle configurations; moved to init/ directory for running I recommend that you try some of the example problems first and read the README.txt files that accompany each example. The script QuickStart will compile the serial code, create all the directories necessary to run the calibration example, and then run this example (in ../Susp3D_Run). -------------------------------------------------------------------- -------------------------------------------------------------------- NOTES To run the code create a new directory (for example Susp3D_Run) outside Susp3D and create two directories in it init/ input files Contains: c_inp_file.*: initial particle configuration input_file.dat: input data file task_file.dat: task number identifying input and output files alloc_file.dat: allocation of data to processors (optional) data/ output data files Contains: chk_p.*: particle checkpoint for restarting a run chk_f.*: fluid checkpoint for restarting a run p_out.*: particle output (coordinates, velocities, forces) m_out.*: mode output (mass, momentum, etc.) properties.dat: summary of input data The * indicates the task number (associated with the input file) and the processor id: * = task_number*(number of procs) + proc_id. The output files are written every cycle of num_step lattice-Boltzmann steps and alternate between processors each cycle. Thus for n processors cycle 1, n+1 2n+1 etc is written to processor 0, cycle 2, n+2, to processor 1, etc. All jobs should be run from the Susp3D_Run directory. Scripts to manage parallel jobs can be copied from Susp3D/utils to Susp3D_Run. Suggested particle sizes and the effective hydrodynamic radii for different viscosities are tabulated in samples/calibration/a_eff.txt. The corresponding ranges for the lubrication forces are also included. -------------------------------------------------------------------- -------------------------------------------------------------------- FEATURES The code has been extensively tested for settling, fluidization, and shearing flows. It should also work for extensional flows, but I have only done one or two simple tests. Its limited to spherical particles, and most testing has been for monodisperse suspensions. Martin van der Hoef has used it for porous media made up of bidisperse particles, but it hasn't been tested for moving particles. The code handles lubrication and also can incorporate a short range cut off, as would occur in a gas solid suspension. Thanks to Rolf for the implementation. You may need help getting the parameters right for this problem. Rolf also added code to model a bumpy wall, made up of arrays of moving spherical particles. My grad student Quyen Nguyen helped developed an implicit update for clusters of neighboring particles. This allows us to simulate suspensions with strong lubrication forces. -------------------------------------------------------------------- -------------------------------------------------------------------- BUGS Some features are not yet implemented 1) The particles must be spherical, so that shape_flag (in c_inp.000) must be 0 and the orientation vectors are unused. 2) A list of updates, bugs, and fixes are in RELEASE_NOTES.txt. -------------------------------------------------------------------- ----------------------------------------------------------------------- Tony Ladd Chemical Engineering University of Florida 6-24-03 -----------------------------------------------------------------------