Driver

The Driver class runs chombo-discharge simulations. The primary purpose of the Driver class is to coordinate the simulation advance (i.e. TimeStepper integration) together with I/O and regrid functionality. The constructor for this class is

Driver(const RefCountedPtr<ComputationalGeometry>& a_compgeom,
       const RefCountedPtr<TimeStepper>&           a_timestepper,
       const RefCountedPtr<AmrMesh>&               a_amr,
       const RefCountedPtr<CellTagger>&            a_celltagger = RefCountedPtr<CellTagger>(nullptr),
       const RefCountedPtr<GeoCoarsener>&          a_geocoarsen = RefCountedPtr<GeoCoarsener>(nullptr));

Tip

Driver C++ API.

Simulation setup

For setting up an running simulations, only a single routine is used:

void setupAndRun(const std::string a_inputFile);

This routine will set up and run a simulation.

New simulations

If a simulation starts from the first time step, the Driver class will perform the following steps in setupAndRun().

Ask ComputationalGeometry to generate the cut-cell moments.
Collect all the cut-cells and ask AmrMesh to set up an initial grid. This initial grid is always generated by flagging cells for refinement along the boundary. Various options are available for configuring this initial grid, see Cell refinement philosophy. Also note that it is possible to restrict the maximum level that can be generated from the geometric tags, or remove some of the cut-cell refinement flags through the auxiliary class GeoCoarsener.
Ask the TimeStepper to set up relevant solvers and fill them with initial data.
Perform the number of initial regrids that the user asks for. After the regrid, the solvers are re-filled with initial data (rather than regridding).
Ask TimeStepper to perform a post-initialization routine.

Restarting simulations

If a simulation uses restart file, i.e. one that does not start from the first time step, the Driver class will execute the following steps in setupAndRun(...).

Ask ComputationalGeometry to generate the cut-cell moments.
Read a checkpoint file that contains the grids and all the data that have been checkpointed by the solvers. Driver will issue an error and abort if the checkpoint file does not exist.
Ask TimeStepper to perform a post-checkpoint step. This functionality has been included because not all data in every solver needs to be checkpointed. For example, an electric field solver only needs to write the electric potential to the checkpoint file because the electric field is simply obtained by taking the gradient.
Perform the number of initial regrids that the user asks for.

Simulation advancement

The algorithm for running a simulation is conceptually simple; the Driver class calls TimeStepper::computeDt for computing a reasonable time step for advancing the equations, and uses Real TimeStepper::advance(Real dt) to actually perform the advance. Regrids, plot files, and checkpoint files are written at certain step intervals (or when the TimeStepper demands them). In brief, the algorithm looks like this:

Driver::run(...){

   while(KeepRunningTheSimulation){
      if(RegridEverything){
         Driver->regrid()
      }

      tryDt    = TimeStepper->computeDt()
      actualDt = TimeStepper->advance(tryDt)

      if(WriteAPlotFile or EndOfSimulation){
         Driver->writePlotFile();
      }
      if(TimeToWriteACheckpointFile or EndOfSimulation){
         Driver->writeCheckpointFile()
      }

      KeepRunningTheSimulation = true or false
   }
}

Regridding

Regrids are called by the Driver class and proceed as follows:

CellTagger generates tags for grid refinement and coarsening.
The TimeStepper class stores data that is subject to regrids so that we have access to previously defined data when we interpolate to the new grids.
The AmrMesh class generates the new grid boxes and EB information.
TimeStepper checks if the defined realms show be load balanced.
AmrMesh regrids the realms and EBAMR operators.
The TimeStepper class regrids its solvers and internal data.
The TimerStepper performs a post-regrid operation (e.g. filling solvers with auxiliary data).

In C++ pseudo-code, this looks something like:

Driver::regrid(){

   // Tag cells
   CellTagger->tagCellsForRefinement()

   // Store old data and free up some memory
   TimeStepper->storeOldGridData()

   // Generate the new grids
   AmrMesh->makeNewGrids()

   if(loadBalance) {
     TimeStepper->loadBalance();
   }

   // AmrMesh finalizes the EBAMR grids
   AmrMesh->regridOperators()

   // Regrid timestepper
   TimeStepper->regrid()

   // Do a post-regrid step
   TimeStepper->postRegrid()
}

Note

Driver class does not require an instance of CellTagger (which is responsible for flagging cells for refinement). If users decide to omit a cell tagger, regridding functionality is completely turned off and only the initially generated grids will be used throughout the simulation.

Class options

Various class options are available for adjusting the behavior of the Driver class

Driver.verbosity controls output will be given to pout.n. We use 2 or 3 - higher values are for debugging.
Driver.geometry_generation controls the grid generation method (see Geometry generation). Valid options are chombo-discharge or chombo.
Driver.geometry_scan_level. Which refinement level to initiate the chombo-discharge geometry generation method. This entry indicates the number of refinements of the coarsest AMR level used in the simulation. E.g. if the Driver.geometry_scan_level=1 and the coarsest AMR level is \(128^3\) then the signed distance pruning (see Geometry generation) begins at the AMR level \(256^3\). Note that negative numbers are also permitted, in which case the pruning initiates at a coarsened level.
Driver.output_dt. Time interval between output files. This overrides step-based output and also affects the selected time steps.
Driver.plot_interval. Time steps between each plot file.
Driver.checkpoint_interval. Time steps between each checkpoint file.
Driver.regrid_interval. Time steps between each regrid.
Driver.write_regrid_files. Write plot files during regrids. Valid options are true or false.
Driver.write_restart_files.Write plot files during restarts. Valid options are true or false.
Driver.initial_regrids. Number of initial regrids to perform when starting (or restarting) a simulation.
Driver.start_time. Simulation start time.
Driver.stop_time.Simulation stop time.
Driver.max_steps. Maximum number of simulation time steps.
Driver.geometry_only. If true, do not run the simulation and only write the geometry to file.
Driver.write_memory. Write MPI memory report. Valid options are true or false.
Driver.write_loads. Write computational loads. Valid options are true or false.
Driver.output_directory. Output directory.
Driver.output_names. Simulation file names.
Driver.max_plot_depth. Maximum plot depth. Values \(< 0\) means all levels.
Driver.max_chk_depth. Maximum checkpoint file depth. Values \(< 0\) means all levels.
Driver.num_plot_ghost. Number of ghost cells in plot files.
Driver.plt_vars. Plot variables for Driver. Valid options are tags, mpi_rank, levelset, loads.
Driver.restart. Restart step (less or equal to 0 implies fresh simulation)
Driver.allow_coarsening. Allows removal of grid levels if cell tags dont run deep enough.
Driver.grow_geo_tags. How much to grow cut-cell refinement tags.
Driver.refine_angles. Refine cells if the angle between normal vector in neighboring cells exceed this threshold.
Driver.refine_electrodes. Refine electrode surfaces. Values \(< 0\) will refine all the way down.
Driver.refine_dielectrics. Refine dielectric surfaces. Values \(< 0\) will refine all the way down.

Runtime options

Driver can parse options during run-time (i.e. between simulation steps), see Run-time configurations. The following options are run-time adjustable:

Driver.verbosity.
Driver.plot_interval.
Driver.checkpoint_interval.
Driver.regrid_interval.
Driver.write_regrid_files.
Driver.write_restart_files.
Driver.stop_time.
Driver.max_steps.
Driver.write_memory.
Driver.write_loads.
Driver.num_plot_ghost.
Driver.plt_vars.
Driver.allow_coarsening.
Driver.grow_geo_tags.
Driver.refine_angles.
Driver.refine_electrodes.
Driver.refine_dielectrics.