zhyang-dev/openfoam
1
0
Fork 0
mirror of https://develop.openfoam.com/Development/openfoam.git synced 2025-11-28 03:28:01 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge remote branch 'bundle/olesenm' into home

Browse Source
This commit is contained in:
Mark Olesen
2010-11-08 17:22:21 +01:00
parent cb6b445bbc f015bc0c82
commit fd2f0a13d8
8153 changed files with 336111 additions and 307179 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/Doxygen/Doxyfile
View File

@ -567,7 +567,7 @@ IMAGE_PATH =
# to standard output. If FILTER_PATTERNS is specified, this tag will be
# ignored.
INPUT_FILTER = doxyFilt
INPUT_FILTER = $(WM_PROJECT_DIR)/bin/tools/doxyFilter
# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
# basis. Doxygen will compare the file name with each pattern and apply the

2
doc/Doxygen/Macros/tensorOperator.sty
View File

@ -2,7 +2,7 @@
% ========= |
% \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
% \\ / O peration |
% \\ / A nd | Copyright (C) 1991-2009 OpenCFD Ltd.
% \\ / A nd | Copyright (C) 1991-2010 OpenCFD Ltd.
% \\/ M anipulation |
%------------------------------------------------------------------------------
% License

225
doc/GUIDELINES
View File

@ -1,225 +0,0 @@
The guidelines document the current style or a recommended style for
documenting OpenFOAM source code (.C and .H) files.
General
~~~~~~~
- For readability in the comment blocks, certain tags are used that are
translated by pre-filtering the file before sending it to doxygen.
- The tags start in column 1, the contents follow on the next lines and
indented by 4 spaces. The filter removes the leading 4 spaces from the
following lines until the next tag that starts in column 1.
- The 'Class' and 'Description' tags are the most important ones.
- The first paragraph following the 'Description' will be used for the brief
description, the remaining paragraphs become the detailed description.
eg,
|-------------------------
|
|Class
| Foam::myClass
|
|Description
| A class for specifying the documentation style.
|
| The class is implemented as a set of recommendations that may
| sometimes be useful.
|
|-------------------------
- The class name must be qualified by its namespace, otherwise doxygen
will think you are documenting some other class.
- If you don't have anything to say about the class (at the moment),
use the namespace-qualified class name for the description.
This aids with finding these under-documented classes later.
eg,
|-------------------------
|
|Class
| Foam::myUnderDocumentedClass
|
|Description
| Foam::myUnderDocumentedClass
|
|-------------------------
- Use 'Class' and 'Namespace' tags in the header files.
The Description block then applies to documenting the class.
- Use 'InClass' and 'InNamespace' in the source files.
The Description block then applies to documenting the file itself.
eg,
|-------------------------
|
|InClass
| Foam::myClass
|
|Description
| Implements the read and writing of files.
|
|-------------------------
Doxygen Special Commands
~~~~~~~~~~~~~~~~~~~~~~~~
Doxygen has a large number of special commands with a '\' prefix or
a (alternatively) an '@' prefix.
The '@' prefix form is recommended for most doxygen specials, since it has
the advantage of standing out. It also happens to be what projects like gcc
and VTK are using.
The '\' prefix form, however, looks a bit better for the '\n' newline command
and when escaping single characters - eg, '\@', '\<', '\>', etc.
Since the filtering removes the leading 4 spaces within the blocks,
the doxygen commmands can be inserted within the block without problems.
eg,
|-------------------------
|
|InClass
| Foam::myClass
|
|Description
| Implements the read and writing of files.
|
| An example input file:
| @verbatim
| patchName
| {
| type myPatchType;
| refValue 100;
| value uniform 1;
| }
| @endverbatim
|
| Within the implementation, a loop over all patches is done:
| @code
| forAll(patches, patchI)
| {
| ... // some operation
| }
| @endcode
|
|-------------------------
HTML Special Commands
~~~~~~~~~~~~~~~~~~~~~
Since Doxygen also handles HTML tags to a certain extent, the angle brackets
need quoting in the documentation blocks. Non-HTML tags cause doxygen to
complain, but seem to work anyhow.
eg,
The template with type <HR> is a bad example.
The template with type \<HR\> is a better example.
The template with type <Type> causes doxygen to complain about
an unknown html type, but it seems to work okay anyhow.
Documenting Namespaces
~~~~~~~~~~~~~~~~~~~~~~
- If namespaces are explictly declared with the Namespace() macro,
they should be documented there.
- If the namespaces is used to hold sub-models, the namespace can be
documented in the same file as the class with the model selector.
eg,
documented namespace 'Foam::functionEntries' within the
class 'Foam::functionEntry'
- If nothing else helps, find some sensible header.
eg,
namespace 'Foam' is documented in the foamVersion.H file
Documenting Typedefs and classes defined via macros
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
... not yet properly resolved
Documenting Applications
~~~~~~~~~~~~~~~~~~~~~~~~
Any number of classes might be defined by a particular application, but
these classes will not, however, be available to other parts of OpenFOAM. At
the moment, the sole purpuse for running doxygen on the applications is to
extract program usage information for the '-doc' option.
The documentation for a particular application is normally contained within
the first comment block in a .C source file. The solution is this to invoke
a special filter for the "applications/{solver,utilities}" directories that
only allows the initial comment block for the .C files through.
The layout of the application documentation has not yet been finalized, but
foamToVTK shows an initial attempt.
Ignored files and directories
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Ignore directories of linked files
- */lnInclude/*
Ignore test directories
- */t/*
Ignore applications that clutter everything
Ignore application-specific classes
- */applications/utilities/*.H
- */applications/solvers/*.H
Orthography (always good for a flame-war)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Given the origins of OpenFOAM, the British spellings (eg, neighbour and not
neighbor) are generally favoured. For code sections that interact with
external libraries, it can be useful to adopt American spellings, especially
for names that constitute a significant part of the external library - eg,
'color' within graphics sub-systems.
Both '-ize' and the '-ise' variant are found in the code comments.
If used as a variable or class method name, it is probably better to use '-ize',
which is considered the main form by the Oxford University Press.
Eg,
myClass.initialize()
The word "its" (possesive) vs. "it's" (colloquial for "it is" or "it has")
seems to confuse non-native (and some native) English speakers.
It is better to donate the extra keystrokes and write "it is" or "it has".
Any remaining "it's" are likely an incorrect spelling of "its".
Housekeeping
~~~~~~~~~~~~
The doc/Doxygen/tools directory contains miscellaneous scripts for finding
and possibly repairing documentation issues.
Updated: 2009-11-27

8
doc/changes/TODO Normal file
View File

@ -0,0 +1,8 @@
- check
new fvMesh
new fvMeshSubset
for consistency with createMesh.H
- Check the following:
doc/changes/inotify.txt

53
doc/changes/inotify.txt Normal file
View File

@ -0,0 +1,53 @@
2010-05-28
Cleanup of automatic regIOobject rereading.
- all files (usually only IOdictionary) that need to be monitored
should be registered using MUST_READ_IF_MODIFIED. The MUST_READ should
be used for objects that do not need to be re-read (e.g. fields).
In the old system it would actually monitor e.g. 0/U and constant/polyMesh
files.
I've temporarily added a warning in IOdictionary if constructed with MUST_READ.
Same for IOList,IOField,IOMap if constructed with MUST_READ_IF_MODIFIED
(or is rereading supported?). Please let me know if something does not work or
you see the warning
"Dictionary constructed with IOobject::MUST_READ instead of IOobject::MUST_READ_IF_MODIFIED." << nl
- any monitored and modified file will get reloaded from the exact path
that was monitored. In the old system it would/could do a re-search through all
times.
- all reductions to synchronise status on different processors are done with
a single reduction instead of one reduction per registered object. This could
be quite a gain on large numbers of processors.
- all file monitoring is done by an instance of 'fileMonitor' in the Time
class. The fileMonitor class can be found in OSspecific. Default is
to use the (linux-specific) 'inotify' system calls.
If compiled with -DFOAM_USE_STAT it will revert to the current 'stat' system
calls.
- inotify does not need timestamps. There is no need for fileModificationSkew
to allow for time differences. (there can still temporarily be a difference
in modified status between different processors due to nfs lagging)
- fileMonitor stores two hashtables per file so there is a small overhead
adding and removing files from monitoring.
- if runTimeModifiable is false at start of run no files will get monitored,
however if runTimeModified gets set to false during the run the files
will still get monitored (though never reloaded). This is only a hypothetical
problem in that the kernel still stores events for the monitored files. However
inotify is very efficient - e.g. it gets used to track changes on file systems
for desktop search engines.
- in the old system one could call modified() on any object and get
and uptodate state. In the new system it will return the state from
the last runTime++ (which if it triggered any re-reads will have reset the
state anyway).

125
doc/changes/splitCyclic.txt Normal file
View File

@ -0,0 +1,125 @@
Short overview of the changes to have cyclics split into two halves.
Cyclics
-------
The two cyclic halves are now split like processor patches. There should be no
difference in running.
Advantages:
- decomposed cyclics can now be handled properly. It just needs to preserve
the cyclic patch it originates from.
- We can now construct a table of global transformations and handle
points/edges/cells with transformations.
- face ordering after topological changes becomes much easier since we
now preserve what half the face comes from.
- cyclic handling becomes more consistent with processor handling and can
quite often be handled in the same condition.
- transformation tensors now become single entry.
The disadvantages:
- a patch-wise loop now might need to store data to go to the neighbour half
since it is no longer handled in a single patch.
- decomposed cyclics now require overlapping communications so will
only work in 'nonBlocking' mode or 'blocking' (=buffered) mode but not
in 'scheduled' mode. The underlying message passing library
will require overlapping communications with message tags.
- it is quite a code-change and there might be some oversights.
- once converted (see foamUpgradeCyclics below) cases are not backwards
compatible with previous versions.
blockMesh
---------
blockMeshDict now allows patch definition using the construct-from-dictionary
constructor. This helps defining patches that require additional input e.g.
directMapped and now cyclic:
boundary
(
sides2_half0
{
type cyclic;
neighbourPatch sides2_half1;
faces ((2 4 5 3));
}
The syntax is - like the polyMesh/boundary file - a list of dictionaries with
one additional entry 'faces' for the block faces. Above shows the new
required entry 'neighbourPatch' for cyclic.
blockMesh still reads the old format. For a cyclic it will automatically
introduce two patches for the halves, with names xxx_half0 and xxx_half1.
foamUpgradeCyclics
------------------
This is a tool which reads the polyMesh/boundary file and any vol/surface/point
fields and converts them.
It will check if anything needs to be converted, backup the current file to .old
and split any cyclic patchFields into two entries.
Mesh converters
---------------
Most mesh formats use cyclics in a single patch (i.e. the old way).
The converters have been adapted to use the patch 'oldCyclic' instead of
'cyclic'. oldCyclic uses the 17x automatic ordering but writes 'type cyclic'
so afterwards foamUpgradeCyclics can be run to upgrade.
decomposePar
------------
Decomposes cyclics into processorCyclic:
procBoundary0to1throughsides1_half0
{
type processorCyclic;
nFaces 1000;
startFace 91350;
myProcNo 0;
neighbProcNo 1;
referPatch sides1_half0;
}
They have an additional 'referPatch' entry which gives the (cyclic) patch
to use for any transformation.
Details
-------
- the cyclic patch dictionary has an entry neighbourPatch. The
patch has new member functions:
//- Get neighbouring patchID
label neighbPatchID() const
//- Get neighbouring patch
const cyclicPolyPatch& neighbPatch()
//- Am I the owner half
bool owner()
The cyclic still has forward() and reverse() transformations (with
the reverse() equal to the neighbPatch().forward()).
There is no transformLocalFace anymore - the ordering is the same for
both halves.
- 'pure' processor patches now are always coincident - they (should) have no
transformation. As said above cyclics are decomposed into a derived
type 'processorCyclic'.
- processor patches use overlapping communication using a different message
tag. This maps straight through into the MPI message tag. Each processor
'interface' (processorPolyPatch, processorFvPatch, etc.) has a 'tag()'
to use for communication.
- when constructing a GeometricField from a dictionary it will explicitly
check for non-existing entries for cyclic patches and exit with an error message
warning to run foamUpgradeCyclics. (1.7.x will check if you are trying
to run a case which has split cyclics)

92
doc/codingStyleGuide.org
View File

@ -2,7 +2,7 @@
#
#+TITLE: OpenFOAM C++ style guide
#+AUTHOR: OpenCFD Ltd.
#+DATE: April 2010
#+DATE: June 2010
#+LINK: http://www.opencfd.co.uk
#+OPTIONS: author:nil ^:{}
@ -13,9 +13,12 @@
+ The normal indentation is 4 spaces per logical level.
+ Use spaces for indentation, not tab characters.
+ Avoid trailing whitespace.
+ The body of control statements (eg, if, else, while, etc).
+ The body of control statements (eg, =if=, =else=, =while=, etc). is
always delineated with brace brackets. A possible exception can be
made with 'break' or 'continue' as part of a control structure.
made in conjunction with =break= or =continue= as part of a control
structure.
+ The body of =case= statements is usually delineated with brace brackets.
+ A fall-through =case= should be commented as such.
+ stream output
+ =<<= is always four characters after the start of the stream,
@ -72,16 +75,16 @@
\*---------------------------------------------------------------------------*/
#+END_EXAMPLE
*** The =.H= Files
*** The /.H/ Files
+ header file spacing
+ Leave two empty lines between sections
(as per functions in the =.C= file etc)
(as per functions in the /.C/ file etc)
+ use "//- Comment" comments in header file
+ use =//- Comment= comments in header file
+ add descriptions to class data and functions
+ destructor
+ If adding a comment to the destructor -
use //- and code as a normal function:
use =//-= and code as a normal function:
#+BEGIN_EXAMPLE
//- Destructor
@ -89,11 +92,11 @@
#+END_EXAMPLE
+ inline functions
+ Use inline functions where appropriate in a separate classNameI.H file.
+ Use inline functions where appropriate in a separate /classNameI.H/ file.
Avoid cluttering the header file with function bodies.
*** The =.C= Files
+ Do not open/close namespaces in a =.C= file
*** The /.C/ Files
+ Do not open/close namespaces in a /.C/ file
+ Fully scope the function name, i.e.
#+BEGIN_EXAMPLE
@ -113,7 +116,7 @@
EXCEPTION
When there are multiple levels of namespace, they may be used in the =.C=
When there are multiple levels of namespace, they may be used in the /.C/
file, i.e.
#+BEGIN_EXAMPLE
@ -132,22 +135,25 @@
+ Use two empty lines between functions
*** Coding Practice
+ passing data as arguments or return
Pass bool, label and scalar as copy, anything larger by reference.
+ passing data as arguments or return values.
+ Pass bool, label and scalar as copy, anything larger by reference.
+ const
Use everywhere it is applicable.
+ Use everywhere it is applicable.
+ variable initialisation using "="
: const className& variableName = otherClass.data();
+ variable initialisation using
#+BEGIN_EXAMPLE
const className& variableName = otherClass.data();
#+END_EXAMPLE
NOT
: const className& variableName(otherClass.data());
#+BEGIN_EXAMPLE
const className& variableName(otherClass.data());
#+END_EXAMPLE
+ virtual functions
If a class is virtual - make all derived classes virtual.
+ If a class is virtual, make all derived classes virtual.
*** Conditional Statements
#+BEGIN_EXAMPLE
@ -169,7 +175,7 @@
}
#+END_EXAMPLE
NOT (no space between "if" and "(")
NOT (no space between =if= and =(= used)
#+BEGIN_EXAMPLE
if(condition)
@ -201,7 +207,7 @@
}
#+END_EXAMPLE
NOT (no space between "for" and "(")
NOT this (no space between =for= and =(= used)
#+BEGIN_EXAMPLE
for(i = 0; i < maxI; i++)
@ -245,7 +251,7 @@
**** Splitting return type and function name
+ split initially after the function return type and left align
+ do not put "const" onto its own line - use a split to keep it with
+ do not put =const= onto its own line - use a split to keep it with
the function name and arguments.
so
@ -277,7 +283,7 @@
#+END_EXAMPLE
+ if it needs to be split again, split at the function name (leaving
behind the preceding scoping "::"s), and again, left align, i.e.
behind the preceding scoping =::=s), and again, left align, i.e.
For example,
@ -326,16 +332,19 @@
*** Maths and Logic
+ operator spacing
+ a + b, a - b
+ a*b, a/b
+ a & b, a ^ b
+ a = b, a != b
+ a < b, a > b, a >= b, a <= b
+ a || b, a && b
#+BEGIN_EXAMPLE
a + b, a - b
a*b, a/b
a & b, a ^ b
a = b, a != b
a < b, a > b, a >= b, a <= b
a || b, a && b
#+END_EXAMPLE
+ splitting formulae over several lines
Split and indent as per "splitting long lines at an "=""
Split and indent as per "splitting long lines at an ="
with the operator on the lower line. Align operator so that first
variable, function or bracket on the next line is 4 spaces indented i.e.
@ -346,7 +355,7 @@
* (k + t);
#+END_EXAMPLE
This is sometime more legible when surrounded by extra parentheses:
This is sometimes more legible when surrounded by extra parentheses:
#+BEGIN_EXAMPLE
variableName =
@ -434,15 +443,15 @@
*** Doxygen Special Commands
Doxygen has a large number of special commands with a '\' prefix or a
(alternatively) an '@' prefix.
Doxygen has a large number of special commands with a =\= prefix or
(alternatively) an =@= prefix.
The '@' prefix form is recommended for most Doxygen specials, since it
The =@= prefix form is recommended for most Doxygen specials, since it
has the advantage of standing out. It also happens to be what projects
like gcc and VTK are using.
The '\' prefix form, however, looks a bit better for the '\n' newline
command and when escaping single characters - eg, '\@', '\<', '\>', etc.
The =\= prefix form, however, looks a bit better for the =\n= newline
command and when escaping single characters - eg, =\@=, =\<=, =\>=, etc.
Since the filtering removes the leading 4 spaces within the blocks, the
Doxygen commmands can be inserted within the block without problems.
@ -511,7 +520,7 @@
#+END_EXAMPLE
*** Documenting Typedefs and classes defined via macros
*** Documenting typedefs and classes defined via macros
... not yet properly resolved
@ -525,9 +534,9 @@
option.
The documentation for a particular application is normally contained
within the first comment block in a =.C= source file. The solution is this
to invoke a special filter for the "applications/{solver,utilities}"
directories that only allows the initial comment block for the =.C= files
within the first comment block in a /.C/ source file. The solution is this
to invoke a special filter for the "/applications/{solver,utilities}/"
directories that only allows the initial comment block for the /.C/ files
through.
The layout of the application documentation has not yet been finalized,
@ -551,10 +560,7 @@
myClass.initialize()
#+END_EXAMPLE
The word "its" (possesive) vs. "it's" (colloquial for "it is" or "it has")
seems to confuse non-native (and some native) English speakers.
It is better to donate the extra keystrokes and write "it is" or "it has".
Any remaining "it's" are likely an incorrect spelling of "its".

BIN
doc/codingStyleGuide.pdf Normal file
View File

Binary file not shown.

8
doc/doxygen/Doxyfile
View File

@ -574,12 +574,14 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
# INPUT = $(WM_PROJECT_DIR)/src \
#INPUT = $(WM_PROJECT_DIR)/src \
# $(WM_PROJECT_DIR)/applications/utilities \
# $(WM_PROJECT_DIR)/applications/solvers
# limit input for testing purposes
INPUT = $(WM_PROJECT_DIR)/src/OpenFOAM/global
INPUT = $(WM_PROJECT_DIR)/src/OpenFOAM/global \
$(WM_PROJECT_DIR)/src/OpenFOAM/containers \
$(WM_PROJECT_DIR)/src/OpenFOAM/primitives
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@ -669,7 +671,7 @@ IMAGE_PATH =
# If FILTER_PATTERNS is specified, this tag will be
# ignored.
INPUT_FILTER = doxyFilt
INPUT_FILTER = $(WM_PROJECT_DIR)/bin/tools/doxyFilter
# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
# basis.

17
doc/tools/find-trailingspace Executable file
View File

@ -0,0 +1,17 @@
#!/bin/bash
# -----------------------------------------------------------------------------
# Script
# find-trailingspace
#
# Description
# Search for files with trailing whitesapce
#
# -----------------------------------------------------------------------------
set -x
cd $WM_PROJECT_DIR || exit 1
tab=$'\t'
git grep -c -E "[ $tab]+"'$' -- $@
#------------------------------------------------------------------ end-of-file

2
doc/tools/fix-Class
View File

@ -3,7 +3,7 @@
# ========= |
# \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
# \\ / O peration |
# \\ / A nd | Copyright (C) 1991-2009 OpenCFD Ltd.
# \\ / A nd | Copyright (C) 1991-2010 OpenCFD Ltd.
# \\/ M anipulation |
# ------------------------------------------------------------------------------
# License