Process Model Refactor

The purpose of the process model refactor is go generalize the higher-level routines within PFLOTRAN enabling easier coupling and synchronization of process modeling. Two new classes (i.e. the process_model and process model coupler) are introduced along with supporting factory modules and modified/extended simulation classes to accommodate the process model approach. A brief description of these classes and modules follows:

• Process Model - The process model (PM) class provides the procedures necessary to setup and evaluate the governing equations defined for a process. In the context of solving a nonlinear system of equations, this is includes the residual and Jacobian evaluation, update of auxiliarry state variables, etc. For the time being, the PM classes (e.g. Process_Model_Richards_class in process_model_richards) serve as wrappers around the existing flow modes and reactive transport (e.g. richards.F90 and supporting modules). In the future, all procedures and data structures within the old implementations will be migrated to the PMs (i.e. reactive_transport.F90 -> process_model_rt.F90.
• Process Model Coupler - The process model coupler (PMC) governs the solution of a tightly-coupled set of governing equations. It provides the time integrator (i.e. timestepper) and solvers to do so along with procedures for synchronizing state variables, outputing process-specific simulation results, etc. The PMC may contain more than one PM, but all processes own by the PMC must be solved simultaneously. Multiple PMCs are coupled through a 2D linked list with pointers to %next and %below. Assuming a 2D row/column layout, PMCs in a row are "next" to each other continue to take time steps up to a specified synchronization time set external to the PMCs. PMCs in a colum are above/below each other. The PMC below takes as many time steps as necessary to catch up with a single time step from the PMC above (i.e. the PMC above provides the synchronization time for the PMC below). All calls to the next/below PMCs are recursive.
• Simulation - The simulation class is still the highest-level class/object in PFLOTRAN. The extendable class serves as a container for data structures and process model couplers. For instance, the Subsurface_Simulation_class stores pointers to two process model couplers (i.e. flow and reactive transport), the realization, and the regression classes. The simulation object is in charge of creating (through an associated factory), managing, and destroying these data structures. Process models and process model couplers may point to the data structures owned by the simulation class. However, they may not create or destroy the objects. That is the job of the factory.
• Factory - The factory module (e.g. subsurface_factory) provides procedures for querying command line arguments, reading the input deck, setting up data structures, ordering PMCs, etc. The factory essentially get the simulation off the ground, and once the simulation is airborne, it will proceed until completion and destroy itself.

Example Simulation Classes

Top Level Workflow

Explanation

OptionInitMPI (option.F90): Initializes MPI

• MPIInit
• MPI_Comm_rank
• MPI_Comm_size
• MPI_Comm_group

PFLOTRANInitialize (pflotran_factory.F90):

• PFLOTRANInitializePrePetsc
  • PFLOTRANInitCommandLineSettings: Reads command line arguments that are not process model specific (e.g. -simulation_mode, -input_prefix, etc.)
• OptionInitPetsc (option.F90):
  • Sets PETSC_COMM_WORLD to option%mycomm
  • PetscInitialize
  • Checks command line for verbosity
• PFLOTRANInitializePostPetsc()
  • LoggingCreate()
  • OptionBeginTiming()

SubsurfaceInitialize (subsurface_factory.F90):

• SubsurfaceSimulationCreate (subsurface_simulation.F90): Allocates and initializes (zeros or nullifies contents of) subsurface simulation object.
• SubsurfaceInitializePostPetsc
  • SubsurfInitCommandLineSettings: Reads command line arguments specific to subsurface simulation.
• Init (init.F90): Routines that set up PFLOTRAN in the past.
• HijackSimulation: Sets up process models and process model couplers for subsurrface simulation, pointing to many legacy data structures.
• SubsurfaceJumpStart: Gets the simulation off the ground and ready for time stepping (restart, update of constraints, output of initial condition, etc.).

simulation%InitializeRun => SubsurfaceInitializeRun (subsurface_simulation.F90)

• InitializeRun (pmc_base.F90): Recursively traverses the process model and process model coupler linked list initializing individual process model couplers. Note that all current subsurface process models are coupled through pmc_subsurface.F90, but that class does not override the pmc_base%InitializeRun()
  • InitializeRun (specific to the process model [e.g. process_model_richards.F90, process_model_rt.F90] associated with the process model coupler [pmc_subsurface].
    • PMRichardsInitializeRun (process_model_richards.F90): At this point does nothing, though restart should likely be moved to this routine in the future.
    • PMRTInitializeRun (process_model_rt.F90)
      • PMRTUpdateSolution2: Updates solution without updating kinetic state variables.

simulation%ExecuteRun (simulation_base.F90): Executes simulation up to final waypoint time.

• simulation%RunToTime
  • process_model_list%RunToTime (specific to PMC): Executes each process model coupler up to specified sync time (in this case final waypoint time).

simulation%FinalizeRun => SubsurfaceFinalizeRun (subsurface_simulation.F90)

• SimulationBaseFinalizeRun (simulation_base.F90): Recursively prints out final performance metrics for each process model coupler.
• Prints regression output.

simulation%Strip => SubsurfaceSimulationStrip (subsurface_simulation.F90): Recursively deallocates all data structures and classes. To be replaced with a F2003 Finalize() routine once gfortran supports it.

PFLOTRANFinalize (subsurface_factory.F90): Ends timing and logging.

OptionFinalize (option.F90): Destroy option object and finalizes PETSc and MPI.