4. Overview of FLASH architecture

The files that make up the FLASH source are organized in the directory structure according to their functionality and grouped into components called units. Throughout this manual, we use the word `unit' to refer to a group of related files that control a single aspect of a simulation, and that provide the user with an interface of publicly available functions. FLASH can be viewed as a collection of units, which are selectively grouped to form one application.

A typical FLASH simulation requires only a subset of all of the units in the FLASH code. When the user gives the name of the simulation to the setup tool, the tool locates and brings together the units required by that simulation, using the FLASH Config files (described in Chp:The FLASH configuration script) as a guide. Thus, it is important to distinguish between the entire FLASH source code and a given FLASH application. the FLASH units can be broadly classified into five functionally distinct categories: infrastructure, physics, monitor, driver, and simulation.

The infrastructure category encompasses the units responsible for FLASH housekeeping tasks such as the management of runtime parameters, the handling of input and output to and from the code, and the administration of the grid, which describes the simulation's physical domain.

Units in the physics category such as Hydro (hydrodynamics), Eos (equation of state), and Gravity implement algorithms to solve the equations describing specific physical phenomena.

The monitoring units Logfile, Profiler, and Timers track the progress of an application, while the Driver unit implements the time advancement methods and manages the interaction between the included units.

The simulation unit is of particular significance because it defines how a FLASH application will be built and executed. When the setup script is invoked, it begins by examining the simulation's Config file, which specifies the units required for the application, and the simulation-specific runtime parameters. Initial conditions for the problem are provided in the routines Simulation_init and Simulation_initBlock. As mentioned in Chp:Creating new problems, the Simulation unit allows the user to overwrite any of FLASH's default function implementations by writing a function with the same name in the application-specific directory. Additionally, runtime parameters declared in the simulation's Config file override definitions of same-named parameters in other FLASH units. These helpful features enable users to customize their applications, and are described in more detail below in Sec:Inheritance and online in Architecture Tips. The simulation unit also provides some useful interaces for modifying the behaviour of the application while it is running. For example there is an interface Simulation_adjustEvolution which is called at every time step. Most applications would use the null implementation, but its implementation can be placed in the Simulation directory of the application to customize behavior. The API functions of the Simulation unit are unique in that except Simulation_initSpecies, none of them have any default general implementations. At the API level there are the null implementations, actual implementations exist only for specific applications. The general implementations of Simulation_initSpecies exist for different classes of applications, such as those utilizing nuclear burning or ionization.

FLASH3 Transition: Why the name change from “modules” in FLASH2 to “units” in FLASH3? The term “module” caused confusion among users and developers because it could refer both to a FORTRAN90 module and to the FLASH-specific code entity. In order to avoid this problem, FLASH3 started using the word “module” to refer exclusively to an F90 module, and the word “unit” for the basic FLASH code component. Also, FLASH no longer uses F90 modules to implement units. Fortran's limitation of one file per module is too restrictive for some of FLASH4's units, which are too complex to be described by a single file. Instead, FLASH4 uses interface blocks, which enable the code to take advantage of some of the advanced features of FORTRAN90, such as pointer arguments and optional arguments. Interface blocks are used throughout the code, even when such advanced features are not called for. For a given unit, the interface block will be supplied in the file "Unit_interface.F90". Please note that files containing calls to API-level functions must include the line use Unit, ONLY: function-name1, function-name2, etc. at the top of the file.