- prefer this to using the OPENFOAM define since this improves the
internal consistency with the build information.
The API information could change between builds without the
etcFiles.C being recompiled whereas the value of
Foam::foamVersion::api is force updated during the build (triggers
recompilation of globals.Cver)
- Within strings it is preferable to use the "<etc>" instead.
Most use cases for the old "~OpenFOAM" expansion have been obsoleted
by the #includeEtc directive.
- use std::string instead of c-string for the string constants
- centralize some definitions of resources into foamVersion.H
Now expose some of the hard-coded values used in foamEtcFiles()
so that they can be known or even overridden as required.
Relocate to src/OpenFOAM/include as a constant location.
- For compatibility, access to the old global names is provided via
macros
#define FOAMversion foamVersion::version
#define FOAMbuild foamVersion::build
#define FOAMbuildArch foamVersion::buildArch
- this isolation makes it easier to provide additional scoped methods
for dealing with version related information. Eg, printBuildInfo()
- generalize output text wrapping, use for usage notes
- add -help-man option for generating manpage content for any OpenFOAM
application or solver.
bin/tools/foamCreateManpage as helper
- Start brief descriptions with 'Deprecated(YYYY-MM)' so that it is
readily visible in the short method description. Consistent date
format (YYYY-MM), placed immediately after the \deprecated tag.
- use the dictionary 'get' methods instead of readScalar for
additional checking
Unchecked: readScalar(dict.lookup("key"));
Checked: dict.get<scalar>("key");
- In templated classes that also inherit from a dictionary, an additional
'template' keyword will be required. Eg,
this->coeffsDict().template get<scalar>("key");
For this common use case, the predefined getXXX shortcuts may be
useful. Eg,
this->coeffsDict().getScalar("key");
- the opposite problem from issue #762. Now we also test if the input
token stream had any tokens at all.
- called by the dictionary get<> and readEntry() methods.
Using: OpenFOAM-plus (see www.OpenFOAM.com)
Build: plus-7ab57cc5d014 (OPENFOAM=1807)
Arch: LSB;label=32;scalar=64
- This can be useful for development versions, or when the version
at build time uses some other naming scheme (#1010)
- With argList::noFunctionObjects() we use the logic added in
4b93333292 (issue #352)
By removing the '-noFunctionObjects' option, we automatically
suppress the creation of function-objects via Time (with argList
as a parameter).
There is generally no need in these cases for an additional
runTime.functionObjects().off() statement
Use the argList::noFunctionObjects() for more direct configuration
and reduce unnecessary clutter in the -help information.
In previous versions, the -noFunctionObjects would have been redundant
anyhow, so we can also just ignore it now instead.
General:
* -roots, -hostRoots, -fileHandler
Specific:
* -to <coordinateSystem> -from <coordinateSystem>
- Display -help-compat when compatibility or ignored options are available
STYLE: capitalization of options text
- avoids compiler ambiguity when virtual methods such as
IOdictionary::read() exist.
- the method was introduced in 1806, and was thus not yet widely used
- advanced options are not displayed with -help, but only with
-help-full, which helps retain a better overview of the standard
options. Replaces previous ad hoc suppression of -listSwitches,
-listRegisteredSwitches etc.
- enclosed with a #ifdef Foam_argList_1712 .. #endif pair
(defined by default).
In a later release, this can be disabled by default.
ENH: add input length check for -hostRoots option
- aids with detection of excess tokens (issue #762)
- deprecated dictionary::operator[] in favour of the lookup() method
which offers more flexibilty and clarity of purpose.
Additionally, the read<> and get<> forms should generally be used
instead anyhow.
- relocate some standard functionality to TimePaths to allow a lighter
means of managing time directories without using the entire Time
mechanism.
- optional enableLibs for Time construction (default is on)
and a corresponding argList::noLibs() and "-no-libs" option
STYLE:
- mark Time::outputTime() as deprecated MAY-2016
- use pre-increment for runTime, although there is no difference in
behaviour or performance.
- add additional control via a Foam::infoDetailLevel flag, which is
supported by a 'DetailLevel' macro. Eg,
DetailLevel << "some information" << nl
- When infoDetailLevel is zero, the stdout for all Foam::system() calls
are also redirected to stderr to prevent child output from
appearing on the parent.
- close stdin before exec in system call.
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
- since PackedBoolList is now a compatibility typedef for bitSet,
it is useful to have an additional means of distinction.
STYLE: simplify internal version tests and compiler defines.
- the API version is now conveyed via the OPENFOAM define directly.
The older OPENFOAM_PLUS define is provided for existing code.
- can be used to handle when options become redundant, but it is
undesirable to treat its presence as an error. Can now tag it as
being ignored.
argList::ignoreOptionCompat({"oldOption", 1706}, true);
argList::ignoreOptionCompat({"oldBoolOpttion", 1706}, false);
command -oldOption xyz -oldBoolOpttion
- use succincter method names that more closely resemble dictionary
and HashTable method names. This improves method name consistency
between classes and also requires less typing effort:
args.found(optName) vs. args.optionFound(optName)
args.readIfPresent(..) vs. args.optionReadIfPresent(..)
...
args.opt<scalar>(optName) vs. args.optionRead<scalar>(optName)
args.read<scalar>(index) vs. args.argRead<scalar>(index)
- the older method names forms have been retained for code compatibility,
but are now deprecated
- regression introduced by part of commit 2787a8664d.
Specifically the way that scalarRanges is written, it parses through
until it hits invalid input. This works fine with an IStringStream,
but the ITstream is pickier and reports this as being an error.
So revert to IStringStream and be less picky about argList parsing.
in the longer-term, should fix scalarRanges instead.
- the readList<T>(Istream&) function was introduced to handle command
-options with either a single or a list value, but was also used for
the #remove dictionary directive. However, the parsing was fragile
if the list did not start with a '('.
Now handle command-line arg/option list directly (via ITstream)
and #remove with special-purpose reading of a string or word list.
This removes ambiguity and reduces potential future problems.
STYLE: use ITstream instead of IStringStream for command-line lookups
- parses directly to a tokenList without a string copy.
- unknown options or missing option values now emit a shorter message
without the entire usage. This makes it easier to identify the errors
and is better aligned with the behaviour of GNU system tools.
====
$ simpleFoam -case
Using: OpenFOAM-plus (see www.OpenFOAM.com)
Build: plus-01234
Error: option '-case' requires an argument
See 'simpleFoam -help' for usage
====
- provide for reduced (-help) and full (-help-full) usage information.
In many cases the reduced usage provided sufficient and easier
to find the information.
- make -srcDoc an alias for -doc-source
- no warnings about option aliases for future dates.
- in rare cases we may wish to have command-line arguments that are
non-mandatory. This can now be reflected in the usage output, provided
that the argList::nonMandatoryArgs() has been used.
- added setRootCaseNonMandatoryArgs.H that applies the
argList::nonMandatoryArgs() settings and otherwise performs largely
as per setRootCase.H, except that the check for mandatory arguments
is deferred to later user code.
- 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.
