Contrib/multiSolver

Subpage contents
> glossary
> In depth
> multiControlDict
I am currently travelling and working offline. Updates will appear when I return (July 4th) or if I get internet access
multiSolver is a master control class that allows you to create a superSolver composed of multiple solvers within a superLoop. All solvers operate on the same dataset in sequence. For example:

icoFoam - runs to completion;
data is handed over to scalarTransportFoam;
scalarTransportFoam - runs to completion;
data is handed back to icoFoam, and the superLoop repeats.

Features:

Single case directory - the settings for all solvers are stored within a single case directory using a "multiDict" dictionary format.

Easy data management - All the data output is sorted into subdirectories corresponding to the solver, and can be loaded / unloaded using the multiPost utility.

Store data - Not all solvers have to use all the fields. Rather, they can "store" an unneeded field, leaving more memory and disk space. The next solver retrieves all stored fields, and no data is lost.

... still in progress ...

The settings for each solver are all stored within a single case directory using a multiDict format. All the data output is sorted into subdirectories corresponding to the solver, and can be retrieved for easy data management. This kind of behaviour is very useful for:

multi-step processes to be modelled within a single application, e.g. fluid injection, followed by settling;
modelling of a flow problem characterized by two different timescales, e.g. stirring with biochemical reactions; and
changing boundary conditions mid-run.

It turns out this type of behaviour is difficult, if not impossible, to implement in OpenFOAM without multiSolver.

1 Why is it needed?

A fundamental assumption in the design of OpenFOAM is the existence of a universal time. Therefore the time object is the top-level object registry, which means it controls the database for every solver. This design works for nearly all simulations imaginable, except for multi-step simulations.

Multi-step simulation

Here, a multi-step simulation is a simulation where:

one solver is run to completion;
the dataset is handed over to another solver;
this solver is run to completion; and
repeat from step #2 as many times as necessary for as many different solvers as necessary.

Trying to accomplish this within the existing runTime framework is problematic. multiSolver achieves this behaviour neatly.

2 When do you need it?

The runTime framework can handle nearly every simulation imaginable, but there are situations where multiSolver will make things much easier. For example:

If you are modelling a multi-step process, with clearly defined changes in boundary-conditions over time; or
If you are modelling a single problem with internal processes characterized by vastly different timescales.

Basically, if you find yourself:

frequently copying data between case directories;
frequently stopping and changing the simulation details, then restarting; or
using runTime++ more than once in your solver,

then multiSolver might help you.

2.1 Parallel runs and mesh motion not fully supported yet

NOTE: At this time, multiSolver does not support parallel runs at all; and mesh motion is allowed, provided the mesh returns to its original position between solvers. This functionality is planned for the future.

3 How do you program applications with it?

3.1 Overview

Here's a quick overview of how to program applications with multiSolver.

Download and comile it;
Write (or choose from existing) solvers that your superSolver will use;
Set up the createFields for each solver;
Add #include "multiSolver.H" to the top;
Between #include "setRootCase.H" and #include "createTime.H" add:

#   include "createMultiRun.H"
    solverDomain = "nameOfFirstSolver";
#   include "setSolverDomain.H"

6. Between each solver, add the lines:

    solverDomain = "nameOfNextSolver";
#   include "setSolverDomain.H"

where nameOfNextSovler is a solverDomainName

7. From each solver, include everything from #include "createTime.H" to just before return 0;
8. At the end, add:

#   include "endMultiSolver.H"
return 0;

3.2 More details

The example above is a simple use of multiSolver, but it is capable of more. For more details see TestMarupio/In depth.

4 How do you run simulations with it?

Here is a brief overview of how to work with a multiSolver-enabled application.

4.1 MultiControlDict

The multiControlDict (glossary) is the multiSolver analogue of the controlDict. The controlDict is auto-generated based on the content of this file. The multiControlDict is the main control dictionary and therefore it does not conform to the format of a regular multiDict (glossary). For the full break-down of all settings and options available in the multiControlDict, see multiControlDict.

4.2 MultiDicts

A regular solver reads information from various dictionary files, and these affect its behaviour. When using multiSolver, there will be dictionaries whose values need to be different for each solverDomain. To specify this behaviour, a multiDict is used.

A multiDict has the following structure:

dictionaryName   fvSchemes;

multiSolver
{
    sovlerDomainName1 // this is the solverDomain name
    {
         // settings for the first solver go here
    }
    solverDomainName2 // another solverDomain name
    {
        // settings for the second solver go here
    }
    default // optional
    {
        // default settings go here
        // these are loaded first, then overwritten by solverName (above)
        // solvers whose names are not listed above inherit only these settings, or none at all if default is absent
    }
}

4.3 Boundary conditions and initial values

The boundary conditions and initial values are located in:

case/multiSolver/[solverDomainName]/0/0

This is the analogue of the case/0 directory, except there is one for every solverDomain. Unlike in a regular simulation, multiSolver will always refer to the boundary conditions located in 0/0.

multiSolver allows the boundary conditions to change between solverDomains. To accomplish this, multiSolver will use the boundaryField specified in [solverDomainName]/0/0 and copy over the latest internalField (from the previous solverDomain).

4.4 Output Data

The data is sorted into superLoop subdirectories within subdirectories named after the solverDomain:

case/multiSolver/[solverDomainName]/[superLoopIndex]/[timeValue]

The standard location of case/[timeValue] is used as a temporary loading area, mostly for post-processing.

4.5 Post-processing

OpenFOAM is hard-coded to look for data in the case/[time] directories. In order to post-process (including sampling, and data conversion) the data needs to be there. To accomplish this,

4.6 Runtime Modification

There are two levels of runtime modification: within a solverDomain, and globally.

Editting a standard dictionary (e.g. controlDict, or transportProperties applies to a solverDomain. Its effect depends on whether that solver has runTimeModifiable enabled. This happens at the end of a solver iteration. However, these changes will be lost in the next superLoop when the same solverDomain is initialized.

Editting a multiDict dictionary applies globally. This is goverend by multiDictsRunTimeModifiable setting in the multiControlDict, but these modifications do not take place until the next solverDomain is initialized. However, these changes are permanent.

4.7 Local time and Global time

A fundamental principle of multiSolver is that time is independent between solverDomains. (If this causes you apprehension, don't worry, the default behaviour uses a standard global time.)

5 How does it work?

OpenFOAM is incredibly flexible, and easily extensible, but implementing a change of this kind challenged its founding assumptions. Therefore, the flexibility was not there on level it needed to be, leaving little option but to use a top-level wrapper implementation.

A wrapper encloses the targeted object in a class that gives it the environment it expects to operate, while simultaneously presenting a different environment to other objects interfacing with it. At the top-level, the "other objects" are users. (Strictly speaking, at the code-level, multiSolver is not a true wrapper since it doesn't include an "OpenFOAM solver" as a member variable, but it is in principle.)

multiSolver works by mutating the case directory into what each solver requires. A transient solver will see the correct ddtSchemes setting in fvSchemes; likewise a steady state solver will see steadyState for ddtSchemes. This is the purpose of the multiDict (glossary) dictionary format.

The data output and input are hard-coded to the case/[timeValue] directory. Therefore, when multiSolver initializes the next solverDomain, it archives the existing output into the correct directory at case/multiSolver/[solverDomainName]/[superLoopIndex]/[timeValue]