User Guide

Setting Up a New Case

Setting up a new simulation case in LEAP is easy. Advanced users may create a new case from scratch very quickly following the guide below. New users are encouraged to review the provided examples in /path/to/leap/src/examples first.

Modifying an existing case

There are several examples provided for both CDIFS and GRANS solvers:

CDIFS examples/ 
├── Lid-driven cavity flow
├── Laminar and turbulent channel flow
├── Sphere rebound on a wall
├── Settling sphere in an unbounded domain
├── Flow Past a Cylinder
├── Lamb-Oseen vortex tubes
├── Taylor Green vortex
├── Vortex dipole
└── Vortex-wall Impingement

GRANS examples/ 
├── Homogeneous cooling
├── Dry collisions between spheres and sphere-walls
└── Granular channel flow

Users can compile these examples using

cd /path/to/leap
make examples
make install

This will produce binaries and input files under: /path/to/leap/install/folder/examples/.

Each case directory contains the following basic structure

/path/to/case
-- src/
----- case_name.f90
----- Makefile
----- Makefile.in
-- bin/
-- mod/
-- obj/

If one of these examples suits your needs (e.g. same configuration, boundary conditions, and initialization), you may use it as it is. You still have control over a number of parameters using the simulation input file.

If you want to tweak the case, you may edit the file /path/to/case/src/case_name.f90 , then recompile the case.

Creating a case from scratch

Each case is a small Fortran program that generates files required to start up a simulation. Start-up files may include any or all of the following:

Block file: (typically named block.hdf5) contains information about the Cartesian grid, number of grid points, and domain periodicity.
BCS file: (typically named bcs.hdf5) describes the different domain boundaries (called Regions in LEAP), Dirichlet and Neumann conditions for each applicable variable.
Fields file: (typically named fields_ini.h5) contains initial conditions for fields like velocity and pressure.
IB file: (typically named ib_ini.h5) contains Immersed Boundary data at start-up.
RP files: (2 files, typically named rp_ini_centers.h5 and rp_ini_markers.h5) contain initial data for Resolved Particle centers and surface points.
PP file: (typically named pp_ini.h5) contains initial data for Point Particles.

To create your own case, start by creating a repository with the following basic structure

# /path/to/new_case/
# ├── configure.ac         # Automake configuration file
# ├── Makefile.am
# └── src/
#   ├── Makefile.am
#   └── my_new_case.f90    # Initialization program

mkdir /path/to/new_case 
mkdir /path/to/new_case/src
cd /path/to/new_case

Create the configure.ac file:

# Create configure.ac
cat << 'EOF' > configure.ac

EOF

Create the Makefile.am file:

# Create Makefile.am
cat << 'EOF' > Makefile.am

EOF

Create the src/Makefile.am file (update the fortran file name):

# Create src/Makefile.am
cat << 'EOF' > src/Makefile.am

EOF

Lastly, create your case file src/my_new_case.f90.

A generic case looks like this.

!>   Contents of src/my_new_case.f90
program main
  !>--------------------------------------------------------------------------
  ! This is a generic program, to be filled by user.
  ! --------------------------------------------------------------------------
  use leapKinds
  use leapParser
  use leapParallel
  use leapBlock
  use leapEulerian
  implicit none
  type(parallel_obj)  :: parallel                          !! Utility that handles parallel (MPI) functions
  type(parser_obj)    :: parser                            !! Utility that parses input files
  type(block_obj)     :: block                             !! Block object manages the Cartesian grid

  ! Initialize parser
  call parser%Initialize()

  ! Parse input file
  call parser%ParseFile()

  ! Initialize parallel environment
  call parallel%Initialize()

  ! Set the block info
  call SetUpCaseBlock()

  ! Set the initial fields
  call SetUpCaseFields()

  ! Set the immersed boundary
  call SetUpCaseIB()

  ! Set boundary conditions
  call SetUpCaseBCS()

  ! Free up data
  call block%Finalize()
  call parser%Finalize()
  call parallel%Finalize()
  contains
    subroutine SetUpCaseBlock()
      !> Setup and write the block file
      implicit none
      ! Work variables
      character(str64) :: filename

      ! Get info from parser
      call parser%Get("Block file",  filename)

      ! ...
      ! ...
      ! ...

      ! Write block to disk
      call block%Write(filename)

      return
    end subroutine SetUpCaseBlock
    subroutine SetUpCaseFields()
      !> Set the initial flow field
      implicit none
      ! Work variables
      type(Eulerian_set)   :: fields
      character(str64)     :: filename

      ! Get info from parser
      call parser%Get("Fields IC file",  filename)

      ! Initialize fields container
      call fields%Initialize(block,parallel)

      ! ...
      ! ...
      ! ...

      ! Write data to disk
      call fields%SetWriteFileName(filename)
      call fields%Write(0,0.0_wp)

      ! Clear data
      call fields%Finalize()

      return
    end subroutine SetUpCaseFields
    subroutine SetUpCaseIB
      !> Setup the immersed boundaries
      use immersed_boundaries
      implicit none
      type(marker_set)    :: IB
      character(str64)    :: filename

      ! Get info from parser
      call parser%Get("IB IC file",        filename)

      ! Initialize Immersed Boundaries
      call IB%Initialize('IB',block,parallel)

      ! ...
      ! ...
      ! ...

      ! Write data to disk
      call IB%SetWriteFileName(filename)
      call IB%Write(0,0.0_WP)

      ! Finalize
      call IB%Finalize()
      return
    end subroutine SetUpCaseIB
    subroutine SetUpCaseBCS()
      !> Setup the boundary conditions
      use leapBC
      implicit none
      ! Work variables
      type(bc_set)         :: bcs

      ! Initialize utility that handles boundary conditions
      call bcs%Initialize(block,parallel)

      ! ...
      ! ...
      ! ...

      ! Write boundary conditions
      call bcs%Write(0,0.0_wp)

      ! Clear data
      call bcs%Finalize()

      return
    end subroutine SetUpCaseBCS
end program main

The parser utility in this example will read parameters (like density, viscosity, etc) form an input file (a text file), such that not everything needs to be hard coded in the Fortran source code.

Once you are done building your case, compile the program to get the case binaries

cd path/to/new_case

autoreconf -fi

# Replace mpifort with your actual mpi fortran compiler,
# and the paths below.
./configure FC=mpifort                         \
  --prefix="/path/to/case/installation/folder" \
  --with-leap=/path/to/leap/install/folder/    \
  --with-szip=/path/to/szip/                   \
  --with-zlib=/path/to/zlib/                   \
  --with-hdf5=/path/to/hdf5/                   \
  --with-silo=/path/to/silo/                   \
  --with-hypre=/path/to/hypre/

make
make install

You can now run your simulation.

First, call your case to generate initialization files, then, call LEAP to integrate the solution forward in time:

# Create a simulation folder
mkdir /path/to/simulation/folder
cd /path/to/simulation/folder

# Example for a simulation with 4 cores
mpiexec -n 4 /path/to/new_case/install/folder/bin/my_new_case -i input
mpiexec -n 4 /path/to/leap/install/folder/bin/leap            -i input