Difference between revisions of "Contrib/multiSolver"

Revision as of 01:41, 5 July 2010

Subpage contents
> glossary
> implementation
> In depth - moving this to programming
> multiControlDict
> multiPost
> programming

1 What is it?

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:

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

2 Features

• Multiple solvers - multiple solvers can be used in sequence on the same data set.

• Changing boundary conditions - the boundary conditions can change at distinct time intervals.

• Independent time - each solver can operate with an independent time value, although universal time can still be used.

• 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 fields - To save memory and hard drive space, not all solvers have to use all the fields. Rather, they can "store" any unneeded fields, leaving more memory and disk space. The next solver retrieves all stored fields, and no data is lost.

3 Why would you need this?

A fundamental assumption in the design of OpenFOAM is the existence of a universal time. Therefore the time object is the top-level objectRegistry (i.e. runTime hosts the database for your simulation). This design works for nearly all simulations imaginable, except for those that require more than one time frame. For these situations, multiSolver will come in handy.

4 When would you need this?

The capabilities of multiSolver are 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.

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.

5 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.

6 How do you program applications with it?

For a detailed look at programming with multiSolver, see TestMarupio/programming. Here's a simple multiSolver-enabled application, or "superSolver":

/*---------------------------------------------------------------------------*\
                             ... STANDARD HEADER ...
\*---------------------------------------------------------------------------*/
 
#include "fvCFD.H"
#include "multiSolver.H"
 
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
int main(int argc, char *argv[])
{
 
#   include "setRootCase.H"
#   include "createMultiSolver.H"
 
// * * * * * * * * * * * * * * * * icoFoam  * * * * * * * * * * * * * * * * //
 
    Info << "*** Switching to icoFoam1 ***\n" << endl;
    solverDomain = "icoFoam";
#   include "setSolverDomain.H"
 
// Paste everything from icoFoam.C, starting with #include "createTime.H",
// and ending just before (but not including) return 0;
 
// * * * * * * * * * * * * * scalarTransportFoam * * * * * * * * * * * * * * //
 
    Info << "*** Switching to scalarTransportFoam ***\n" << endl;
    solverDomain = "scalarTransportFoam";
#   include "setSolverDomain.H"
 
// Paste everything from scalarTransportFoam.C, again, starting with
// #include "createTime.H", and ending just before (but not including)
// return 0;
 
#   include "endMultiSolver.H"
    return(0);
}
 
// ************************************************************************* //

Basic strategy:

• Write (or choose existing) solvers that you intend to use with your superSolver;
• The createFields.H files (and associate #include statements) have to be renamed if they differ between solvers;
• Add #include "multiSolver.H" to the top of the solver;
• Just after <tt>#include "setRootCase.H", add: #include "createMultiSolver.H"
• Between solvers use:

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

• End with:

#include "endMultiSolver.H"
return (0);

7 How do you run simulations with it?

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

7.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.

7.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.

Multidicts:

• sit in the same directory as the dictionary they are managing;
• have the prefix multi, followed by the name of their child dictionary; and
• are not required if the dictionary doesn't need to change between solvers.

For example, a typical constant directory might look like:

constant
|-environmentalProperties    standard dictionary (does not change)
|-multiTransportProperties   multiDictionary (describes change)
'-transportProperties        auto-generated dictionary (changes)

In this directory, there are three files:

• environmentalProperties - this is a standard dictionary. It is user-editable and will not change during a run. multiSolver ignores these files;
• multTransportProperties - this is a multiDict. It is also user-editable and will not change during a run. multiSolver recognizes it by its prefix "multi". It describes how the dictionary transportProperties should change during a run;
• transportProperties - this dictionary is automatically generated by multiSolver. Its content changes during a run (and during post-processing). Editing this file is only useful for runTime modification.

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
    }
    solverDomainName3 // etc..
    {
    }
    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
    }
}

Sometimes, two or more solverDomains will have identical dictionaries. Rather than write out their settings several times, the sameAs keyword is available:
sameAs keyword not yet implemented

solverDomainName1
{
    // settings for the first solver go here
}
solverDomainName2
{
    sameAs   solverDomainName1;
}

Remember: although the multiControlDict has the same naming conventions, this file is not a multiDict. It contains the main control settings for multiSolver, and has a different format from a multiDict.

7.3 Boundary conditions and initial values

The boundary conditions and initial values are located in:

case/multiSolver/[solverDomainName]/initial/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 initial/0.

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

More advanced boundary condition behaviour is planned.

7.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.

7.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, multiPost is available. multiPost has four main commands:

• -load - copy data files from their storage location to case/time (i.e. load the data for post-processing);
• -purge - delete data files;
• -list - display the contents found in the case directory storage location; and
• -set - make the case directory appear as required for the given solver name.

For more details, see multiPost.

7.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.

7.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.) Therefore there are two defined time values:

• localTime - the value known to the solver; and
• globalTime - the universal time, known only by multiSolver.

7.7.1 Initial start

The multiControlDict has settings for an initial start defined gloablly (initialStartAt), and an initial start defined for each solveDomain (startAt). Sometimes these settings may appear to come into conflict. What happens when initialStartAt is set to latestTimeAllDomains, but startAt is set to startTime = 0?

The initialStartAt settings are where the initial data is read from. The startAt settings are where the local time value starts from. Sometimes you may be trying to resume from the middle of a run, and the initial time value should pick up from where it left off. multiSolver tries to determine when this is the case. The rules are:

• startAt time is equal to the localTime of the initialStartAt data source;
• if the initialStartAt is from a different solverDomain than the initial solverDomain, the startAt time specified in the multiControlDict is used instead.

7.7.2 Switching domains

When switching domains:

• globalTime stays the same (i.e. time does not step when switching domains); and
• localTime is set to the value specified by the startAt settings in the multiControlDict.

7.7.3 End time

The local stopAt settings are always compared with the global finalStopAt settings. If the finalStopAt value occurs before the local stopAt value, the finalStopAt value is used, and the end condition is set.

7.7.4 Initial superLoop

The initial superLoop value is determined by the initialStartAt settings. It is set to be equal to the superLoop value of the initialStartAt data source. If the initialStartAt data source is from a different solverDomain than the initial solverDomain, the next superLoop is used.

7.8 Store fields

Some solvers may not need to use all the fields created by other solvers. On the other hand, these other solvers need the latest values for these fields. There are two options for handling this:

1. add the unneeded fields to the createFields.H of the solver. The extra fields will be carried in memory, and written out at every time step. This may be convenient from a post-processing perspective.
2. declare these fields as storeFields in the multiControlDict. With this option, for the solver that doesn't need them, these fields will not be loaded in memory, and will be written only to the first timestep in each run.

Note: If the first solverDomain to run has a storeFields declared, that field must also exist in this solver's initial/0 directory.

8 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], and copies the latest field values to the initial time the next solver expects.

For more details about the inner-workings of multiSolver, see implementation.