- When compiling additional modules or user code, we need more control
for the installation locations beyond the usual FOAM_USER_LIBBIN,
FOAM_SITE_LIBBIN, FOAM_LIBBIN, and wish to have these values be
modifiable without editing files.
- provide wmake rules for handling standard defaults:
* GENERAL_RULES/module-path-user
* GENERAL_RULES/module-path-group
* GENERAL_RULES/module-path-project
which are incorporated as follows:
Make/options:
include $(GENERAL_RULES)/module-path-user
Make/files:
LIB = $(FOAM_MODULE_LIBBIN)/libMyLibrary
By default these would compile into FOAM_USER_{APPBIN,LIBBIN} but
could be adjusted at compilation time. For example,
```
wmake -module-prefix=/path/my-install-location
```
Or
```
./Allwmake -module-prefix=/path/my-install-location
./Allwmake -prefix=/path/my-install-location
```
Or
```
FOAM_MODULE_PREFIX=/path/my-install-location ./Allwmake
```
ENH: add -no-recursion option for AllwmakeParseArguments
- more descriptive naming than the -fromWmake option (still supported)
- remove wmake/scripts/wmake.{cmake,wmake}-args since the -prefix
handling and -no-recursion is now directly handled by AllwmakeParseArguments
- Provide Allwmake-mpi scripts for handling the MPI-only build segment.
- Adjust Make/options to support a FOAM_MPI_LIBBIN target location.
This will simply default to FOAM_LIBBIN/FOAM_MPI, but allows different
types of builds with out-of-tree targets.
Example,
Build OpenFOAM with default MPI settings (eg, system openmpi)
```
./Allwmake
```
Rebuild MPI-layers with different MPI.
For any given and known type
```
othermpi()
{
export WM_MPLIB=OPENMPI
export FOAM_MPI=openmpi-3.1.3
export OPAL_PREFIX=$WM_THIRD_PARTY_DIR/platforms/$WM_ARCH$WM_COMPILER/$FOAM_MPI
export MPI_ARCH_PATH="$OPAL_PREFIX"
}
```
May wish to build/rebuild ptscotch
```
(
othermpi
$WM_THIRD_PARTY_DIR/makeSCOTCH
)
```
Rebuild the mpi-dependent parts. Can also provide install location
```
for script in $(find src -name Allwmake-mpi)
do
(
other_mpi
export FOAM_MPI_LIBBIN="$HOME/tmp/install-prefix/lib/$FOAM_MPI"
)
done
```
- dependency handling relocated from cmakeFunctions to wmakeFunctions
and reused for mpi-versioned builds. This allows more checks for
configuration parameters and removes hard-code build path
information.
CONFIG: remove spurious mplibHPMPI entries
CONFIG: remove ADIOS1 rules (antiquated)
- previously used a Pstream::exit() invoked from the argList
destructor to handle all MPI shutdown, but this has the unfortunate
side-effect of using a fixed return value for the program exit.
Instead use the Pstream::shutdown() method in the destructor and allow
the normal program exit codes as usual. This means that the
following code now works as expected.
```
argList args(...);
if (...)
{
InfoErr<< "some error\n";
return 1;
}
```
- Eg, with surface writers now in surfMesh, there are fewer libraries
depending on conversion and sampling.
COMP: regularize linkage ordering and avoid some implicit linkage (#1238)
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
- generalize some of the library extensions (.so vs .dylib).
Provide as wmake 'sysFunctions'
- added note about unsupported/incomplete system support
- centralize detection of ThirdParty packages into wmake/ subdirectory
by providing a series of scripts in the spirit of GNU autoconfig.
For example,
have_boost, have_readline, have_scotch, ...
Each of the `have_<package>` scripts will generally provide the
following type of functions:
have_<package> # detection
no_<package> # reset
echo_<package> # echoing
and the following type of variables:
HAVE_<package> # unset or 'true'
<package>_ARCH_PATH # root for <package>
<package>_INC_DIR # include directory for <package>
<package>_LIB_DIR # library directory for <package>
This simplifies the calling scripts:
if have_metis
then
wmake metisDecomp
fi
As well as reducing clutter in the corresponding Make/options:
EXE_INC = \
-I$(METIS_INC_DIR) \
-I../decompositionMethods/lnInclude
LIB_LIBS = \
-L$(METIS_LIB_DIR) -lmetis
Any additional modifications (platform-specific or for an external build
system) can now be made centrally.
so the write thread does not have to do any parallel communication. This avoids
the bugs in the threading support in OpenMPI.
Patch contributed by Mattijs Janssens
Resolves bug-report https://bugs.openfoam.org/view.php?id=2669
- warn or fatal if Pstream::init or Pstream::exit are called multiple
times.
- additional Pstream::initNull method as failsafe to initialize MPI
when the underlying OpenFOAM process is not running in parallel but
the application still needs MPI.
- Pstream::exit() can now also be called without having used MPI::init(),
which means it can be used to cleanup serial process or for
applications that used the special purpose Pstream::initNull()
mechanism.
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.
- Could be related to interrupted builds.
So if there are any parts of the build that rely on an explicit
'wmakeLnInclude', make sure that the contents are properly updated.
--
ENH: improved feedback from top-level Allwmake
- Report which section (libraries, applications) is being built.
- Provide final summary of date, version, etc, which can be helpful
for later diagnosis or record keeping.
- The -log=XXX option for Allwmake now accepts a directory name
and automatically appends an appropriate log name.
Eg,
./Allwmake -log=logs/ ->> logs/log.linux64GccDPInt32Opt
The default name is built from the value of WM_OPTIONS.
--
BUG: shell not exiting properly in combination with -log option
- the use of 'tee' causes the shell to hang around.
Added an explicit exit to catch this.
--
- Detecting the '-k' (-non-stop) option at the top-level Allwmake, which
may improve robustness.
- Explicit continue-on-error for foamyMesh (as optional component)
- unify format of script messages for better readability
COMP: reduce warnings when building Pstream (old-style casts in openmpi)
Pstream: added maxCommsSize setting to do (unstructured) parallel transfers in blocks.
Tested:
- with maxCommsSize 0 produces exactly same result as plus.develop
- compiles with label64
- with maxCommsSize e.g. 3 produces exactly same result as plus.develop
- with maxCommsSize=0 exactly the same messages (with Pstream::debug = 1) as plus.develop
See merge request !85
This is controlled by the setting maxCommsSize in etc/controlDict which
specifies the max number of bytes per exchange. If set to <= 0 it
is ignored. This max size of messages is important when doing e.g.
load balancing which can send over whole meshes.
