Difference between revisions of "Contrib multiSolver/Using multiSolver"

From OpenFOAMWiki
(Created page with "== 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 ...")
 
(Migrated to github)
 
Line 1: Line 1:
== Case directory structure ==
+
This project has migrated over to '''github'''.
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.
+
  
=== Data ===
+
'''''[http://github.com/Marupio/multiSolver/wiki Click here for the new website.]'''''
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'''
+
http://github.com/Marupio/multiSolver/wiki
''[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 [[Contrib_multiSolver/glossary#superLoop|superLoop]] subdirectories within subdirectories named after the [[Contrib_multiSolver/glossary#solverDomain|solverDomain]]:
+
 
+
<tt>''[caseName]''/multiSolver/''<nowiki>[</nowiki>[[Contrib_multiSolver/glossary#solverDomainName|solverDomainName]]<nowiki>]</nowiki>''/''<nowiki>[</nowiki>[[Contrib_multiSolver/glossary#superLoopIndex|superLoopIndex]]<nowiki>]</nowiki>''/''[timeValue]''</tt>
+
 
+
The standard location of <tt>case/[timeValue]</tt> 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.
+
 
+
=== 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 [[Contrib_multiSolver/glossary#solverDomain|solverDomain]].  To specify this behaviour, a [[Contrib_multiSolver/glossary#multiDict|multiDict]] is used.
+
 
+
multiDicts:
+
 
+
* sit in the same directory as the dictionary they are managing;
+
* have the prefix <tt>multi</tt>, 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:
+
* <tt>reactionProperties</tt> - this is a standard dictionary.  (You can tell because there's no <tt>multiReactionProperties</tt>.)  It is user-editable and will not change during a run.  '''multiSolver''' ignores these files;
+
* <tt>multiTransportProperties</tt> - this is a [[Contrib_multiSolver/glossary#multiDict|multiDict]].  It is also user-editable and will not change during a run.  '''multiSolver''' recognizes it by its prefix "<tt>multi</tt>".  It describes how the dictionary <tt>transportProperties</tt> should change during a run;
+
* <tt>transportProperties</tt> - 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 [[Contrib_multiSolver/glossary#multiDict|multiDict]] has the following structure:
+
dictionaryName  fvSchemes;
+
+
multiSolver
+
{
+
    sovlerDomainName1 // this is the [[Contrib_multiSolver/glossary#solverDomain|solverDomain]] name
+
    {
+
          // settings for the first solver go here
+
    }
+
    solverDomainName2 // another [[Contrib_multiSolver/glossary#solverDomain|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 [[Contrib_multiSolver/glossary#solverDomain|solverDomains]] will have identical dictionaries.  Rather than write out their settings several times, the <tt>sameAs</tt> keyword is available:
+
 
+
solverDomainName1
+
{
+
    // settings for the first solver go here
+
}
+
solverDomainName2
+
{
+
    sameAs  solverDomainName1;
+
}
+
 
+
'''Exception!'''  The <tt>multiControlDict</tt> contains the settings for '''multiSolver'''.  It is not a standard multiDict.  See the next section for details.
+
 
+
=== MultiControlDict ===
+
The [[Contrib_multiSolver/multiControlDict|multiControlDict]][[Contrib_multiSolver/glossary#multiControlDict|(glossary)]] is the '''multiSolver''' analogue of the <tt>controlDict</tt>.  The <tt>controlDict</tt> is auto-generated based on the content of this file.  The [[Contrib_multiSolver/multiControlDict|multiControlDict]] is the main control dictionary and therefore it does not conform to the format of a regular [[#multiDicts|multiDict]][[Contrib_multiSolver/glossary#multiDict|(glossary)]].  For the full break-down of all settings and options available in the multiControlDict, see [[Contrib_multiSolver/multiControlDict|multiControlDict]].
+
 
+
=== Boundary conditions and initial values ===
+
The boundary conditions and initial values are located in:
+
 
+
:<tt>case/multiSolver/<nowiki>[</nowiki>[[Contrib_multiSolver/glossary#solverDomainName|solverDomainName]]<nowiki>]</nowiki>/initial/0</tt>
+
 
+
This is the analogue of the <tt>case/0</tt> directory, except there is one for every [[Contrib_multiSolver/glossary#solverDomain|solverDomain]].  Unlike in a regular simulation, '''multiSolver''' will ''always'' refer to the boundary conditions located in <tt>initial/0</tt>.
+
 
+
==== Changing boundary conditions ====
+
'''multiSolver''' allows the boundary conditions to change between [[Contrib_multiSolver/glossary#solverDomain|solverDomains]].  To accomplish this, the latest ''internalField'' is combined with the ''boundaryField'' from <tt>initial/0</tt>.
+
 
+
==== 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. <!--
+
 
+
It is possible that some boundary conditions may create ''boundaryField'' values that need to be kept up to date.  These values would be lost with the default behaviour described above.  For example, say you have a custom outlet boundary condition called... I don't know... <tt>obliqueFractalInversion</tt>, and during a simulation, it creates a field called <tt>fractalness</tt>, and this field needs to be kept up to date.  In other words, you want '''multiSolver''' to ''remember'' <tt>fractalness</tt>.  To accomplish this, a <tt>multiSolverRemember</tt> list may be specified in <tt>initial/0</tt>:
+
 
+
boundaryField
+
{
+
    inlet
+
    {
+
        type                  fixedValue;
+
        value                uniform (1 0 0);
+
    }
+
    outlet
+
    {
+
        type                  obliqueFractalInversion;
+
        fractalness          uniform 0;
+
        '''multiSolverRemember  (fractalness);'''
+
    }
+
}
+
 
+
Now '''multiSolver''' will always keep this component of the boundary field up to date.  This feature also works for more than one entry in the same boundary patch; and for more than one boundary patch.  For instance:
+
 
+
boundaryField
+
{
+
    inlet
+
    {
+
        type                  fluffyPuddingInlet;
+
        dFluffinessDt        uniform (0 0 0);
+
        value                uniform (1 0 0);
+
        '''multiSolverRemember  (dFluffinessDt);'''
+
    }
+
    outlet
+
    {
+
        type                  strangeFractalInversion;
+
        fractalness          uniform 0;
+
        strangeness          uniform 1;
+
        '''multiSolverRemember  (fractalness strangeness);'''
+
    }
+
} -->
+
 
+
== 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 <tt>createFields.H</tt> of the solver.  The extra fields will be carried in memory, and written out at every time step.
+
# declare these fields as <tt>storeFields</tt> in the [[Contrib_multiSolver/glossary#multiControlDict|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'' [[Contrib_multiSolver/glossary#solverDomain|solverDomain]] to run must have all fields from all solvers defined in its <tt>initial/0</tt> directory.
+
 
+
== Local time and Global time ==
+
A fundamental principle of '''multiSolver''' is that time is independent between [[Contrib_multiSolver/glossary#solverDomain|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.
+
 
+
=== Initial start ===
+
The [[Contrib_multiSolver/multiControlDict|multiControlDict]] has settings for an initial start defined gloablly (<tt>initialStartAt</tt>), and an initial start defined for each solverDomain (<tt>startAt</tt>).  Sometimes these settings may appear to come into conflict.  What happens when <tt>initialStartAt</tt> is set to <tt>latestTimeAllDomains</tt>, but <tt>startAt</tt> is set to <tt>startTime = 0</tt>?
+
 
+
The <tt>initialStartAt</tt> settings are where the ''initial data'' is read from.  The <tt>startAt</tt> 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:
+
 
+
* <tt>startAt</tt> time is equal to the localTime of the <tt>initialStartAt</tt> data source;
+
* if the <tt>initialStartAt</tt> is from a different solverDomain than the initial solverDomain, the <tt>startAt</tt> time specified in the <tt>multiControlDict</tt> is used instead.
+
 
+
=== 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 <tt>startAt</tt> settings in the <tt>multiControlDict</tt>.
+
 
+
=== End time ===
+
The local <tt>stopAt</tt> settings are always compared with the global <tt>finalStopAt</tt> settings.  If the <tt>finalStopAt</tt> value occurs ''before'' the local <tt>stopAt</tt> value, the <tt>finalStopAt</tt> value is used, and the end condition is set.
+
 
+
=== Initial superLoop ===
+
The initial superLoop value is determined by the <tt>initialStartAt</tt> settings.  It is set to be equal to the superLoop value of the <tt>initialStartAt</tt> data source.  If the <tt>initialStartAt</tt> data source is from a different solverDomain than the initial solverDomain, the ''next'' superLoop is used.
+
 
+
== Runtime Modification ==
+
There are two levels of runtime modification: within a [[Contrib_multiSolver/glossary#solverDomain|solverDomain]], and globally.
+
 
+
* Editting a standard dictionary (e.g. <tt>controlDict</tt>, or <tt>transportProperties</tt> applies to a [[Contrib_multiSolver/glossary#solverDomain|solverDomain]].  Its effect depends on whether that solver has <tt>runTimeModifiable</tt> enabled.  This happens at the end of a solver iteration.  However, these changes will be lost in the next [[Contrib_multiSolver/glossary#superLoop|superLoop]] when the same [[Contrib_multiSolver/glossary#solverDomain|solverDomain]] is initialized.
+
 
+
* Editting a [[Contrib_multiSolver/glossary#multiDict|multiDict]] dictionary applies globally.  This is goverend by <tt>multiDictsRunTimeModifiable</tt> setting in the [[Contrib_multiSolver/multiControlDict|multiControlDict]], but these modifications do not take place until the next [[Contrib_multiSolver/glossary#solverDomain|solverDomain]] is initialized.  However, these changes are permanent.
+

Latest revision as of 21:47, 6 September 2013

This project has migrated over to github.

Click here for the new website.

http://github.com/Marupio/multiSolver/wiki