LBPM Tutorial, Step 9. Restarting Simulations

For long-running simulations, the capability to restart from a checkpoint file is often important. When writing checkpoint files, LBPM will write the entire simulation state (lattice Boltzmann distributions) to disk for each MPI process, which are stored in raw binary format in the files Restart.xxxxx. In addition to the raw data, an LBPM also writes an input database to the file Restart.db, which will include user-specified parameters as well as internal parameters that are used to re-initialize the simulation. For example, timestep will be automatically populated into Restart.db so that the simulation begins from the timestep associated with the most recent interval for checkpoint. As noted previously, this interval is set within the Analysis database, e.g.

Analysis {
       restart_interval = 50000
       // (Other settings go here...)
}

Within the Color database, setting the boolean variable Restart = true will result in lbpm_color_simulator reading the initial condition from a restart file. If Restart = false the simulation will start over. When LBPM writes Restart.db it will automatically populate the database with Restart = true. However, this will only be read into lbpm_color_simulator if Restart.db is provided as the input database, e.g.

mpirun -np 1 lbpm_color_simulator Restart.db

Since Restart.db is simply an input database, the simulation parameters can be modified so that the simulation restarts with a different set of parameters. For example, we could restart the simulation case presented in Step 8, but with a higher flow rate based on the specified flux

Domain {
   Filename = "mask_water_flooded_water_and_oil.raw"  
   ReadType = "16bit"  // data type
   N = 601, 594, 1311  // size of original image
   nproc = 1, 1, 1     // process grid
   n = 300, 297, 500   // sub-domain size
   voxel_length = 7.0  // voxel length (in microns)
   ReadValues = 0, 1, 2  // labels within the original image
   WriteValues = 0, 2, 1 // associated labels to be used by LBPM
   BC = 4                // boundary condition type (0 for flux)
   Sw = 0.35
}
MRT {
   tau = 1.0
   F = 0.0, 0.0, 1.0e-5
   timestepMax = 20000
   tolerance = 0.01
}
Color {
    tauA = 0.7;             // relaxation time for fluid A (labeled as "1")       
    tauB = 0.7;             // relaxation time for fluid B (labeled as "2") 
    rhoA   = 1.0;           // density for fluid A (in lattice units)
    rhoB   = 1.0;           // density for fluid B (in lattice units)
    alpha = 1e-3;           // controls the surface tension
    beta  = 0.95;           // controls the interface width 
    F = 0, 0, 0             // controls the external force
    Restart = true         // initialize simulation from restart file?
    timestep = 1000
    timestepMax = 3000    // maximum number of timesteps to perform before exit
    ComponentLabels = 0     // number of immobile component labels in the input image
    ComponentAffinity = -1.0  // wetting condition for each immobile component
    flux = 20.0               // volumetric flux at the z-inlet in voxels per timestep
}
Analysis {
    analysis_interval = 1000         // Frequency to perform analysis
    visualization_interval = 100000  // Frequency to write visualization data
    restart_interval = 1000000       // Frequency to write restart data
    restart_file = "Restart"         // Filename to use for restart file (will append rank)
    N_threads    = 4                 // Number of threads to use for analysis
    load_balance = "independent"     // Load balance method to use: "none", "default", "independent"
}
Visualization {
}

In general, any of the simulation parameters can be changed. However, it is not possible to alter the domain structure and restart, since the structure restart file assumes that the domain structure will not change. Put another way, you are free to modify any parameter set within the Color section of the input file, but you should not attempt to restart after modifying any parameter contained within the Domain section. For example, if it is necessary to restart with a different boundary condition, consider saving an 8-bit binary file and providing this as the input Filename for a new simulation.

Proceed to next step in tutorial