A typical Function1 entry can be read in one of three ways; with the
parameters in the current dictionary, in a separate sub-dict, or with
the entry itself as the dictionary; e.g.,
// Current-dictionary form
<entryName> sine;
amplitude 0.1;
frequency 10;
level 0.2;
// Coeff-dictionary form
<entryName> sine;
<entryName>Coeffs
{
amplitude 0.1;
frequency 10;
level 0.2;
}
// Entry-as-dictionary form
<entryName>
{
type sine;
amplitude 0.1;
frequency 10;
level 0.2;
}
The latter two sub-dictionary forms are needed when there are multiple
Function1 entries of the same type in a dictionary. Enclosing the
parameters in a separate sub-dictionary prevents the keywords (in this
case "amplitude", "frequency" and "level") from being duplicated.
Table and constant Function1 entries are different in that they have
special formats which allow the data to be appended directly to the
entry name; e.g;
<entryName> table ((0 (1 0 0)) (1 (2 0 0)));
<entryName> constant (1 0 0);
// (constant can even have the "constant" keyword omitted)
<entryName> (1 0 0);
Table also has two optional additional controls; "outOfBounds" and
"interpolationScheme". In order for these to be written out in such a
way that the entries are not duplicated, table needs to be written out
(and therefore also read in) as one of the sub-dictionary forms. To that
effect, Table has been extended to additionally permit reading in the
three forms described previously, and to write in the coeff-dictionary
form.
// Current-dictionary form
<entryName> table;
values ((0 (1 0 0)) (1 (2 0 0)));
outOfBounds repeat;
interpolationScheme linear;
// Coeff-dictionary form
<entryName> sine;
<entryName>Coeffs
{
values ((0 (1 0 0)) (1 (2 0 0)));
outOfBounds repeat;
interpolationScheme linear;
}
// Entry-as-dictionary form
<entryName>
{
type table;
values ((0 (1 0 0)) (1 (2 0 0)));
outOfBounds repeat;
interpolationScheme linear;
}
For completeness and consistency, constant has also been modified so
that it can read in these forms. However, constant has no additional
control entries, which means writing a coeff-dictionary is unecessary,
so the output has not been changed.
Function1 has been generalised in order to provide functionality
previously provided by some near-duplicate pieces of code.
The interpolationTable and tableReader classes have been removed and
their usage cases replaced by Function1. The interfaces to Function1,
Table and TableFile has been improved for the purpose of using it
internally; i.e., without user input.
Some boundary conditions, fvOptions and function objects which
previously used interpolationTable or other low-level interpolation
classes directly have been changed to use Function1 instead. These
changes may not be backwards compatible. See header documentation for
details.
In addition, the timeVaryingUniformFixedValue boundary condition has
been removed as its functionality is duplicated entirely by
uniformFixedValuePointPatchField.
When an OpenFOAM simulation runs in parallel, the data for decomposed fields and
mesh(es) has historically been stored in multiple files within separate
directories for each processor. Processor directories are named 'processorN',
where N is the processor number.
This commit introduces an alternative "collated" file format where the data for
each decomposed field (and mesh) is collated into a single file, which is
written and read on the master processor. The files are stored in a single
directory named 'processors'.
The new format produces significantly fewer files - one per field, instead of N
per field. For large parallel cases, this avoids the restriction on the number
of open files imposed by the operating system limits.
The file writing can be threaded allowing the simulation to continue running
while the data is being written to file. NFS (Network File System) is not
needed when using the the collated format and additionally, there is an option
to run without NFS with the original uncollated approach, known as
"masterUncollated".
The controls for the file handling are in the OptimisationSwitches of
etc/controlDict:
OptimisationSwitches
{
...
//- Parallel IO file handler
// uncollated (default), collated or masterUncollated
fileHandler uncollated;
//- collated: thread buffer size for queued file writes.
// If set to 0 or not sufficient for the file size threading is not used.
// Default: 2e9
maxThreadFileBufferSize 2e9;
//- masterUncollated: non-blocking buffer size.
// If the file exceeds this buffer size scheduled transfer is used.
// Default: 2e9
maxMasterFileBufferSize 2e9;
}
When using the collated file handling, memory is allocated for the data in the
thread. maxThreadFileBufferSize sets the maximum size of memory in bytes that
is allocated. If the data exceeds this size, the write does not use threading.
When using the masterUncollated file handling, non-blocking MPI communication
requires a sufficiently large memory buffer on the master node.
maxMasterFileBufferSize sets the maximum size in bytes of the buffer. If the
data exceeds this size, the system uses scheduled communication.
The installation defaults for the fileHandler choice, maxThreadFileBufferSize
and maxMasterFileBufferSize (set in etc/controlDict) can be over-ridden within
the case controlDict file, like other parameters. Additionally the fileHandler
can be set by:
- the "-fileHandler" command line argument;
- a FOAM_FILEHANDLER environment variable.
A foamFormatConvert utility allows users to convert files between the collated
and uncollated formats, e.g.
mpirun -np 2 foamFormatConvert -parallel -fileHandler uncollated
An example case demonstrating the file handling methods is provided in:
$FOAM_TUTORIALS/IO/fileHandling
The work was undertaken by Mattijs Janssens, in collaboration with Henry Weller.
e.g.
ramp
{
type quadratic;
start 200;
duration 1.6;
}
but the old format is supported for backward compatibility:
ramp linear;
rampCoeffs
{
start 200;
duration 1.6;
}
e.g. in tutorials/heatTransfer/buoyantSimpleFoam/externalCoupledCavity/0/T
hot
{
type externalCoupledTemperature;
commsDir "${FOAM_CASE}/comms";
file "data";
initByExternal yes;
log true;
value uniform 307.75; // 34.6 degC
}
Previously both 'file' and 'fileName' were used inconsistently in different
classes and given that there is no confusion or ambiguity introduced by using
the simpler 'file' rather than 'fileName' this change simplifies the use and
maintenance of OpenFOAM.
Function1 is an abstract base-class of run-time selectable unary
functions which may be composed of other Function1's allowing the user
to specify complex functions of a single scalar variable, e.g. time.
The implementations need not be a simple or continuous functions;
interpolated tables and polynomials are also supported. In fact form of
mapping between a single scalar input and a single primitive type output
is supportable.
The primary application of Function1 is in time-varying boundary
conditions, it also used for other functions of time, e.g. injected mass
is spray simulations but is not limited to functions of time.
