mattijs authored 1 year ago and Andrew Heather committed 1 year ago

- uses read&write handlers
- fixes initialisation of partial handlers
- 'uniform' copied to wrong place
- -overwrite not deleting old processors dirs

mattijs authored 1 year ago and Andrew Heather committed 1 year ago

BUG: collated: cooperate with non-parallel

- can be broadly categorised as 'unthreaded'
  or 'collated' (threading requirement depends on buffering)
  without other opaque inheritances.

CONFIG: add hostUncollated to bash completion prompt

- use local function for the decision making, whether worldComm or a
  dedicated communicator is needed (and which sibling ranks are
  involved)

Co-authored-by: mattijs <mattijs>

- accept plain lists (space or comma separated) as well as the
  traditional OpenFOAM lists. This simplifies argument handling
  with job scripts.

  For example,
     simpleFoam -ioRanks 0,4,8 ...
  vs
     simpleFoam -ioRanks '(0 4 8)'  ...

  It is also possible to select the IO ranks on a per-host basis:

     simpleFoam -ioRanks host  ...

- expose rank/subrank handling as static fileOperation methods

- previously checked on destruction, but it is robuster to check for a
  locally defined communicator during construction

- add InfoProxy output for fileOperation

ENH: add fileOperation::storeComm()

- transfers management of the communicator from external to internal.
  Use with caution

Mark OLESEN authored 2 years ago and Andrew Heather committed 2 years ago

- make fileHandler deletion mechanism more
  transparent by providing a nullptr signature. A nullptr parameter
  is already being used in the argList destructor for shutdown, but that
  relied on an implicit conversion to autoPtr to trigger things.

- improved handling of file handler replacement.

  Previously had a very basic check on old vs new handlers using their
  type() values (string comparison!!), which would unfortunately
  prevent proper swapping of the contents.
  Check the actual pointers instead.

  As part of the change, treat any empty autoPtr as no-op instead of as
  deletion (which is handled explicitly as nullptr instead).

  In addition to making the internal logic simpler, it means that the
  current file handler always changes to a valid state without
  inadvertently removing everything and falling back to creating a new
  default handler (again).

  This handling of no-ops also simplifies call code. For example,

  <code>
      autoPtr<fileHandler> oldHandler;
      autoPtr<fileHandler> writeHandler;
      word handlerName;

      if (arg.readIfPresent("writeHandler", handlerName))
      {
          writeHandler = fileOperation::New(handlerName);
      }

      oldHandler = fileHandler(std::move(writeHandler));

      ... do something

      writeHandler = fileHandler(std::move(oldHandler));
  </code>

  If the "writeHandler" is not specified, each call is a no-op.
  If it is specified, the handlers are swapped out each time.

- the management of the fileHandler communicators is now encapsulated
  privately (managedComm_) with the final layer being responsible for
  cleaning up after itself. This makes delegation/inheritance clearer
  and avoids the risk of freeing an MPI communicator twice.

STYLE: uniformFile static check relocated to fileOperation layer

mattijs authored 2 years ago and Mark OLESEN committed 2 years ago

- recover the target of symbolic links.
  This is needed when re-creating a file tree on another rank.

ENH: handle checkGzip, followLink flags in fileHander filePath()

- previously just relied on the backend defaults, now pass through
- separate init(...) for common constructor init steps

- with ATOMIC, an intermediary file is created - eg, (fileAbc~tmp~)
  where all of the output is written to. When the stream goes out of
  scope, this intermediary file is moved/renamed to the actually
  output name - eg, (fileAbc~tmp~) -> (fileAbc).

  This adds some safety if the simulation crashes while writing the
  file, since it will the partial (corrupt) file will be left
  behind as (fileAbc~tmp~) and not as (fileAbc), which means it will
  will be treated as a backup file and not loaded again on restart.

ENH: provided enumeration for APPEND/NON_APPEND

- clearer than using bool (with comments).
  Since append mode is primarily only used by masterOFstream etc
  this change is unlikely to affect user coding.

ENH: use file atomic for ensight file creation

- avoids corrupt (truncated) files being referenced by the ensight
  case file if the simulation crashes while writing the ensight file.

STYLE: qualify format/version/compression with IOstreamOption not IOstream

STYLE: reduce number of lookups when scanning {fa,fv}Solution

STYLE: call IOobject::writeEndDivider as static

BUG: masterUncollatedFileOperation checking of file-size

- used Foam:fileSize check to decide on scheduled/nonBlocking but this
  was being done on all ranks and subsequently broadcast.
  Now avoid unnecessary filesystem access on non-master ranks.

- simplifies local toggling.

- centralize fileModification static variables into IOobject.
  They were previously scattered between IOobject and regIOobject

Mark OLESEN authored 4 years ago and Andrew Heather committed 4 years ago

- currently add to mesh zones to provide a table of contents
  of the zone names that allows downstream consumers quick access to
  the information without needing to parse the entire file.

Mark OLESEN authored 4 years ago and Andrew Heather committed 4 years ago

- support selective enable/disable of the file banner.

ENH: improve code isolation for decomposedBlockData

- use readBlockEntry/writeBlockEntry to encapsulate the IO handling,
  which ensures more consistency

- new decomposedBlockData::readHeader for chaining into the
  block header information.

- remove unused constructors for decomposedBlockData

ENH: minor cleanup of collated fileOperations

Mark OLESEN authored 4 years ago and Andrew Heather committed 4 years ago

- improves interface and data consistency.
  Older signatures are still active (via the Foam_IOstream_extras
  define).

- refine internals for IOstreamOption streamFormat, versionNumber

ENH: improve data alignment for IOstream and IOobject

- fit sizeof label/scalar into unsigned char

STYLE: remove dead code

- robuster matching behaviour when encountering paths that themselves
  contain the word "processor" in them. For example,

    "/path/processor0generation2/case1/processor10/system"
    will now correctly match on processor10 instead of failing.

- use procRangeType for encapsulating the processor ranges

- provision for information of distributed vs non-distributed roots.
  The information is currently available from the initial setup, but
  can useful to access directly within fileOperation.

STYLE: modernize list iteration

- missed detection of system libraries when installed with multiarch
  paths like /usr/lib/x86_64-linux-gnu

CONFIG: improve handling of group/user config files (#928)

- changed bashrc handling of FOAM_CONFIG_NOUSER to use
  FOAM_CONFIG_MODE instead. Propagate into foamEtcFile to make this
  a stickier control.

  This change allows better control, but also enables cluster
  installations to define their own value within the OpenFOAM prefs.sh
  file to prevent users accidentally mis-configuring things if
  necessary.

- remove undocumented handling of an (a)ll mode in foamEtcFile to
  avoid potential pitfalls.

- add support for FOAM_CONFIG_ETC handling.
  This allows injection of an extra search layer when finding
  project etc files

ENH: improvements to foamConfigurePaths (#928)

- handle FOAM_CONFIG_ETC implicitly, or explicitly with the new
  -etc option.

STYLE: more explicit wording in foamConfigurePaths usage (#1602)

- document that an absolute path (eg, -scotch-path) overrides/ignores
  the equivalent ThirdParty setting (eg, -scotch)

- longer options -system-compiler and -third-compiler for -system
  and -third, respectively. Clearer as to their purpose.

- adjust the location sanity check to look for META-INFO directory.

- missed detection of system libraries when installed with multiarch
  paths like /usr/lib/x86_64-linux-gnu

CONFIG: improve handling of group/user config files (#928)

- changed bashrc handling of FOAM_CONFIG_NOUSER to use
  FOAM_CONFIG_MODE instead. Propagate into foamEtcFile to make this
  a stickier control.

  This change allows better control, but also enables cluster
  installations to define their own value within the OpenFOAM prefs.sh
  file to prevent users accidentally mis-configuring things if
  necessary.

- remove undocumented handling of an (a)ll mode in foamEtcFile to
  avoid potential pitfalls.

- add support for FOAM_CONFIG_ETC handling.
  This allows injection of an extra search layer when finding
  project etc files

ENH: improvements to foamConfigurePaths (#928)

- handle FOAM_CONFIG_ETC implicitly, or explicitly with the new
  -etc option.

STYLE: more explicit wording in foamConfigurePaths usage (#1602)

- document that an absolute path (eg, -scotch-path) overrides/ignores
  the equivalent ThirdParty setting (eg, -scotch)

- longer options -system-compiler and -third-compiler for -system
  and -third, respectively. Clearer as to their purpose.

- adjust the location sanity check to look for META-INFO directory.

Mark OLESEN authored 5 years ago and Mark OLESEN committed 5 years ago

- reduces the number of parameters that are being passed around
  and allows future additions into the IOstreamOption with mininal
  effort.

- can be convenient to bundle IO options as a single parameter

- allows suppression when the banner is suppressed

- add compile-time detection of deprecated findIndex() function

- replace occurrences of findIndex() with the equivalent container
  method

This method waits until all the threads have completed IO operations and
then clears any cached information about the files on disk. This
replaces the deactivation of threading by means of zeroing the buffer
size when writing and reading of a file happen in sequence. It also
allows paraFoam to update the list of available times.

Patch contributed by Mattijs Janssens
Resolves bug report https://bugs.openfoam.org/view.php?id=2962

twoPhaseMixtureThermo writes the temperatures during construction only
for them to be read again immediately after by construction of the
individual phases' thermo models. When running with collated file
handling this behaviour is not thread safe. This change deactivates
threading for the duration of this behaviour.

Patch contributed by Mattijs Janssens

- check for excess input on command-line arguments

- reduce fileHandler warning verbosity when the output banner is
  disabled

Improvements to existing functionality
--------------------------------------
  - MPI is initialised without thread support if it is not needed e.g. uncollated
  - Use native c++11 threading; avoids problem with static destruction order.
  - etc/cellModels now only read if needed.
  - etc/controlDict can now be read from the environment variable FOAM_CONTROLDICT
  - Uniform files (e.g. '0/uniform/time') are now read only once on the master only
    (with the masterUncollated or collated file handlers)
  - collated format writes to 'processorsNNN' instead of 'processors'.  The file
    format is unchanged.
  - Thread buffer and file buffer size are no longer limited to 2Gb.

The global controlDict file contains parameters for file handling.  Under some
circumstances, e.g. running in parallel on a system without NFS, the user may
need to set some parameters, e.g. fileHandler, before the global controlDict
file is read from file.  To support this, OpenFOAM now allows the global
controlDict to be read as a string set to the FOAM_CONTROLDICT environment
variable.

The FOAM_CONTROLDICT environment variable can be set to the content the global
controlDict file, e.g. from a sh/bash shell:

    export FOAM_CONTROLDICT=$(foamDictionary $FOAM_ETC/controlDict)

FOAM_CONTROLDICT can then be passed to mpirun using the -x option, e.g.:

    mpirun -np 2 -x FOAM_CONTROLDICT simpleFoam -parallel

Note that while this avoids the need for NFS to read the OpenFOAM configuration
the executable still needs to load shared libraries which must either be copied
locally or available via NFS or equivalent.

New: Multiple IO ranks
----------------------
The masterUncollated and collated fileHandlers can now use multiple ranks for
writing e.g.:

    mpirun -np 6 simpleFoam -parallel -ioRanks '(0 3)'

In this example ranks 0 ('processor0') and 3 ('processor3') now handle all the
I/O.  Rank 0 handles 0,1,2 and rank 3 handles 3,4,5.  The set of IO ranks should always
include 0 as first element and be sorted in increasing order.

The collated fileHandler uses the directory naming processorsNNN_XXX-YYY where
NNN is the total number of processors and XXX and YYY are first and last
processor in the rank, e.g. in above example the directories would be

    processors6_0-2
    processors6_3-5

and each of the collated files in these contains data of the local ranks
only. The same naming also applies when e.g. running decomposePar:

decomposePar -fileHandler collated -ioRanks '(0 3)'

New: Distributed data
---------------------

The individual root directories can be placed on different hosts with different
paths if necessary.  In the current framework it is necessary to specify the
root per slave process but this has been simplified with the option of specifying
the root per host with the -hostRoots command line option:

    mpirun -np 6 simpleFoam -parallel -ioRanks '(0 3)' \
        -hostRoots '("machineA" "/tmp/" "machineB" "/tmp")'

The hostRoots option is followed by a list of machine name + root directory, the
machine name can contain regular expressions.

New: hostCollated
-----------------

The new hostCollated fileHandler automatically sets the 'ioRanks' according to
the host name with the lowest rank e.g. to run simpleFoam on 6 processors with
ranks 0-2 on machineA and ranks 3-5 on machineB with the machines specified in
the hostfile:

    mpirun -np 6 --hostfile hostfile simpleFoam -parallel -fileHandler hostCollated

This is equivalent to

    mpirun -np 6 --hostfile hostfile simpleFoam -parallel -fileHandler collated -ioRanks '(0 3)'

This example will write directories:

    processors6_0-2/
    processors6_3-5/

A typical example would use distributed data e.g. no two nodes, machineA and
machineB, each with three processes:

    decomposePar -fileHandler collated -case cavity

    # Copy case (constant/*, system/*, processors6/) to master:
    rsync -a cavity machineA:/tmp/

    # Create root on slave:
    ssh machineB mkdir -p /tmp/cavity

    # Run
    mpirun --hostfile hostfile icoFoam \
        -case /tmp/cavity -parallel -fileHandler hostCollated \
        -hostRoots '("machineA" "/tmp" "machineB" "/tmp")'

Contributed by Mattijs Janssens

Mark Olesen authored 7 years ago and Mark OLESEN committed 7 years ago

- better documentation of the file contents.
- quicker to obtain number of blocks without reading an entire file.

Original commit message:
------------------------

Parallel IO: New collated file format

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.