.. _Chap:Driver: Driver ====== The ``Driver`` class is the top-level class which runs ``chombo-discharge`` simulations. The primary purpose of the ``Driver`` class is to #. Coordinate the simulation advance, i.e., run the relevant :ref:`Chap:TimeStepper` that is supplied. This can also involve restarting simulations from a user-provided time step. #. Initiate and coordinate regrid operations. #. Coordinate HDF5 I/O operations. The constructor for this class is .. literalinclude:: ../../../../Source/Driver/CD_Driver.H :lines: 39-49 :language: c++ :dedent: 2 Here, the ``Driver`` class takes as input a user-provided geometry ``a_computationalGeometry``, a user-provided physics module ``a_timestepper``, and the AMR infrastructure ``a_amrMesh``. The ``Driver`` class does not *require* an instance of :ref:`Chap:CellTagger`, which is the responsible for flagging cells for refinement. If users decide to omit a cell tagger as in the above constructor, regridding functionality is completely turned off and only the initially generated grids will be used throughout the entire simulation. .. tip:: Here is the `Driver C++ API `_. .. warning:: Usage of injection of the ``AmrMesh`` object is likely to change in future versions of ``chombo-discharge``. Simulation setup ---------------- For setting up an running simulations, only a single routine is used: .. code-block:: c++ void setupAndRun(); 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 :ref:`Chap:ComputationalGeometry` to generate the cut-cell moments. #. Collect all the cut-cells and ask :ref:`Chap:AmrMesh` to set up an initial grid and generate the initial AMR infrastructure. This initial grid is always generated by flagging cells for refinement along solid boundaries. If no such cells exist, a uniform grid on the coarsest domain is generated. Various options are available for configuring this initial grid, see :ref:`Chap:RefinementPhilosophy`. Also note that it is possible to restrict the maximum level that can be generated from the geometric tags. #. Ask the :ref:`Chap: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. I.e., initial data is always regenerated on the finest grid and is not interpolated from coarse grid. #. Let :ref:`Chap:TimeStepper` perform a *post-initialization* routine. Whether or not this post-initialization does anything depends on the physics module begin used. Restarting simulations ______________________ If a simulation uses the restart functionality (i.e., *does not start* from the first time step), ``Driver`` 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 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. ``Driver`` 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. Note that these functions are abstract functions in :ref:`Chap:TimeStepper`, so the actual contents of these will differ between physics modules. Regrids, plot files, and checkpoint files are written at certain step intervals, or specified time intervals. In brief, the algorithm looks like this: .. code-block:: none 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 } } .. _Chap:DriverRegridding: Regridding ---------- Regrids are called by the ``Driver`` class and proceed as follows: #. :ref:`Chap:CellTagger` generates tags for grid refinement and coarsening. #. :ref:`Chap:TimeStepper` stores data that is required during regrids. This is necessary because we often need storage containers to store the solver states on both the old and the new grids. For mesh-based data, data is usually generated by interpolating data from the old grid to the new one. #. :ref:`Chap:AmrMesh` generates the new grid boxes and associated EB information, and performs an initial load balancing. #. :ref:`Chap:TimeStepper` checks if the application should re-balance the grids. #. :ref:`Chap:AmrMesh` reinstantiates the EB and AMR grid infrastructure (e.g., interpolation operators). #. :ref:`Chap:TimeStepper` performs a regrid operation of the physics module. #. :ref:`Chap:TimeStepper` performs a *post-regrid* operation (e.g., filling solvers with auxiliary data). In C++ pseudo-code, this looks something like: .. code-block:: c++ 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() } Class options ------------- Various class options are available for adjusting the behavior of the ``Driver`` class. Below, we include the current template options file for the ``Driver`` class. .. literalinclude:: ../../../../Source/Driver/CD_Driver.options :emphasize-lines: 4,8-13,17-18,20-21,24-27,29-33 :caption: Template input options for the ``Driver`` class. Runtime adjustable options are highlighted. We point out that the ``output_directory`` directory variable is *only* for the HDF5 plot files, whereas other files like ``pout.*`` are put in the directory in which the executable was ran. From the user perspective, the most commonly adjusted parameters concern the I/O operations (plot and checkpoint intervals), and geometric refinement parameters.