Contrib multiSolver/Using multiSolver
Contents
1 Case directory structure
The case directory for a superSolver is different than a standard solver. The directory transforms itself while the solver runs. It contains transient files that are continuously modified by multiSolver, and static files that you use to describe the change.
1.1 Data
Now, you don't have to worry about this as it is handled automatically, but the most notable difference between a superSolver and a standard solver is where they keep their data.
A typical normal solver
[caseName] |-system |-constant |-0 |-0.2 [timeDirectory] |-0.4 [timeDirectory] ... more [timeDirectories]
A typical superSolver
[caseName] |-system |-constant '-multiSolver |-[solverDomain1] | |-initial | |-0 [superLoop] | | |-0 [timeDirectory] | | |-0.2 [timeDirectory] | | |-0.4 [timeDirectory] | | ... more [timeDirectories] | |-1 [superLoop] | | |-1.2 [timeDirectory] | | |-1.4 [timeDirectory] | | |-1.6 [timeDirectory] | | ... more [timeDirectories] | ... more [superLoops] |-[solverDomain2] | |-initial | |-0 [superLoop] | | |-0 [timeDirectory] | | |-0.2 [timeDirectory] | | |-0.4 [timeDirectory] | | ... more [timeDirectories] | |-1 [superLoop] | | |-1.2 [timeDirectory] | | |-1.4 [timeDirectory] | | |-1.6 [timeDirectory] | | ... more [timeDirectories] | ... more [superLoops] ... more [solverDomains]
In short, standard solvers keep their data in:
[caseName]/[timeValue]
whereas superSolvers sort their data into superLoop subdirectories within subdirectories named after the solverDomain:
[caseName]/multiSolver/[solverDomainName]/[superLoopIndex]/[timeValue]
The standard location of case/[timeValue] is used as a temporary loading area, mostly for post-processing. You don't have to worry about this, as it is handled automatically by multiSolver and its associated post-processing application.
1.2 multiDicts
A regular solver reads information from various dictionary files, and these affect its behaviour. When using multiSolver, there will be dictionaries whose contents 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 |-reactionProperties standard dictionary (does not change) |-multiTransportProperties multiDictionary (describes change) '-transportProperties auto-generated dictionary (changes)
In this directory, there are three files:
- reactionProperties - this is a standard dictionary. (You can tell because there's no multiReactionProperties.) It is user-editable and will not change during a run. multiSolver ignores these files;
- multiTransportProperties - 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:
solverDomainName1
{
// settings for the first solver go here
}
solverDomainName2
{
sameAs solverDomainName1;
}
Exception! The multiControlDict contains the settings for multiSolver. It is not a standard multiDict. See the next section for details.
1.3 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.
1.4 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.
1.4.1 Changing boundary conditions
multiSolver allows the boundary conditions to change between solverDomains. To accomplish this, the latest internalField is combined with the boundaryField from initial/0.
1.4.2 Advanced boundary condition settings
I built in some functionality into multiSolver that I don't think is actually necessary. It basically allows you to have the updated boundary field values skip solverDomains. The feature is also untested. I'm commenting out the documentation for this section. If you want to read it, view the source.
2 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:
- 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.
- 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: The first solverDomain to run must have all fields from all solvers defined in its initial/0 directory.
3 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.
3.1 Initial start
The multiControlDict has settings for an initial start defined gloablly (initialStartAt), and an initial start defined for each solverDomain (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.
3.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.
3.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.
3.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.
4 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.
