Merge branch 'master' of /home/noisy3/OpenFOAM/OpenFOAM-dev

ReleaseNotes-dev

@@ -35,43 +35,44 @@
 *** Core library
     + Large number of code refinements and consistency improvements to support
       other developments.
-      Parallel : using non-blocking communications wherever possible. This will
+    + Parallel : using non-blocking communications wherever possible. This will
       lead to lower requirements for MPI_BUFFER_SIZE and possibly better
       start-up performance on larger numbers of processors.
 *** Turbulence modelling
 *** *Updated* thermophysical libraries
     + Now use the more descriptive dictionary input format, e.g. for a single
       component mixture:
+      #+BEGIN_SRC c++
+      thermoType      hPsiThermo<pureMixture<sutherlandTransport<specieThermo<hConstThermo<perfectGas>>>>>;
 
-    thermoType      hPsiThermo<pureMixture<sutherlandTransport<specieThermo<hConstThermo<perfectGas>>>>>;
+      mixture
-
+      {
-    mixture
+          nMoles      1;
-    {
+          molWeight   28.9;
-        nMoles      1;
+          Cp          1007;
-        molWeight   28.9;
+          Hf          0;
-        Cp          1007;
+          As          1.4792e-06;
-        Hf          0;
+          Ts          116;
-        As          1.4792e-06;
+      }
-        Ts          116;
+      #+END_SRC
-    }
 *** Lagrangian intermediate library
-    Extensively updated
+    + Extensively updated
-    *Updated* input format
+    + *Updated* input format
-    Extended to include steady cloud tracking
+    + Extended to include steady cloud tracking
-    *New* collision modelling
+    + *New* collision modelling
-    *Coupled* to new surface film modelling library
+    + *Coupled* to new surface film modelling library
-    *New* sub-models
+    + *New* sub-models
-    + NonSphereDrag: drag model to account for non-spherical particles
+      + NonSphereDrag: drag model to account for non-spherical particles
-    + ParticleTracks: post-processing model to generate track data, typically
+      + ParticleTracks: post-processing model to generate track data, typically
-      during steady calculations
+        during steady calculations
-    *Updated* sub-models
+    + *Updated* sub-models
-    + Devolatilisation models: now act on a per-specie basis
+      + Devolatilisation models: now act on a per-specie basis
 
 *** DSMC
 *** Dynamic Mesh
 *** Numerics
 *** *Updated* command line help, e.g. `snappyHexMesh -help' now gives:
-
+    #+BEGIN_SRC c++
     Usage: snappyHexMesh [OPTIONS]
     options:
       -case <dir>       specify alternate case directory, default is the cwd
@@ -80,12 +81,13 @@
       -srcDoc           display source code in browser
       -doc              display application documentation in browser
       -help             print the usage
-
+    #+END_SRC
 *** *New* basicSolidThermo solids thermophysical library
     + Used in all conjugate heat transfer solvers
       + constant properties
       + temperature dependent properties
-      + temperature and direction (in local coordinate system) dependent properties
+      + temperature and direction (in local coordinate system) dependent
+        properties
 *** *New* Surface film library
     + Creation of films by particle addition, or initial film distribution
     + Coupled with the lagrangian/intermediate cloud hierarchy library
@@ -113,13 +115,16 @@
     polyPatches holding data can map the data.
 *** *Updated* particle tracking algorithm
     + uses non-blocking parallel transfers
-    + does 'minimum-tet' decomposition of face to work with warped faces (snappyHexMesh!)
+    + does 'minimum-tet' decomposition of face to work with warped faces
+      (snappyHexMesh!)
     + reuses tracking state in interpolation - improves consistency and speed
-*** *Updated* split cyclics into two separate patches. See doc/changed/splitCyclics.txt
+*** *Updated* split cyclics into two separate patches.
+    See [[./doc/changes/splitCyclic.txt]]
   * *Updated* interpolation (volPointInterpolation) now works without the
     globalPointPatch. Moving mesh cases can now be run non-parallel and
     continued in parallel and reconstructed without any limitation.
-*** *New* compact binary I/O for faces and cells. This speeds up reading/writing meshes in binary.
+*** *New* compact binary I/O for faces and cells.
+    This speeds up reading/writing meshes in binary.
 *** *Updated* runTimeModifiable
     + user selectable model to use for checking run-time modifiable
       dictionaries (see also doc/changes/inotify.txt):
@@ -129,32 +134,33 @@
         contents from master.
       + inotifyMaster : only master checks and reads file. Slaves get file
         contents from master.
-    + on linux optionally uses inotify instead of time stamps - more efficient for large
+    + on linux optionally uses inotify instead of time stamps - more efficient
-      numbers of monitored files. No more fileModificationSkew needed.
+      for large numbers of monitored files. No more fileModificationSkew needed.
     + single integer reduction instead of one reduction per monitored file.
     + only files that can be re-read are being checked. Drastic reduction of
       number of files to check.
-*** *New* #codeStream dictionary entry method. Uses on-the-fly compilation
+*** *New* #codeStream dictionary entry
-    of OpenFOAM C++ code to construct dictionary.
+    Uses on-the-fly compilation of OpenFOAM C++ code to construct dictionary.
     E.g. in blockMeshDict:
+    #+BEGIN_SRC c++
+    convertToMeters 0.001;
 
-        convertToMeters 0.001;
+    vertices #codeStream
-
+    {
-        vertices #codeStream
+        code
-        {
+        #{
-            code
+            label nVerts =
-            #{
+                readLabel(dict.lookup("nx"))
-                label nVerts =
+               *readLabel(dict.lookup("ny"))
-                    readLabel(dict.lookup("nx"))
+               *readLabel(dict.lookup("nz"));
-                  * readLabel(dict.lookup("ny"))
+            pointField verts(nVerts);
-                  * readLabel(dict.lookup("nz"));
+            // Now fill verts here
-                pointField verts(nVerts);
+            // ..
-                // Now fill verts here
+            os  << verts;
-                // ..
+        #};
-                os  << verts;
+    }
-            #};
+    #+END_SRC
-        }
+    See also ./[[doc/changes/codeStream.org]]
-    See also doc/changes/onTheFly.txt
 
 * Solvers
   A number of new solvers have been developed for a range of engineering
@@ -187,7 +193,7 @@
       to e.g. sample fields just above wall (e.g. for streaklines)
   + *New* codedFixedValue: Uses the on-the-fly code compilation from #codeStream
     to provide an in-line fixedValueFvPatchScalarField. E.g.
-
+    #+BEGIN_SRC c++
     outlet
     {
         type            codedFixedValue<scalar>;
@@ -199,8 +205,8 @@
             operator==(min(10, 0.1*this->db().time().value()));
         #};
     }
-
+    #+END_SRC
-    See doc/changes/onTheFly.txt
+    See also [[./doc/changes/codeStream.org]]
 
 * Utilities
   There have been some utilities added and updated in this release.
@@ -221,23 +227,24 @@
     + =topoSet=: replacement of cellSet,faceSet,pointSet utilities.
       Comparable to a dictionary driven =setSet= utility.
 *** Updated utilities
-    + =setFields=: optionally use faceSets to set patch values (see e.g. hotRoom tutorial).
+    + =setFields=: optionally use faceSets to set patch values (see
+      e.g. =hotRoom= tutorial).
     + =blockMesh=: specify patches via dictionary instead of type only. This
       makes rereading the boundary file superfluous. see
       e.g. pitzDailyDirectMapped tutorial.
-    + =setSet=: allows time range (e.g. 0:100) in combination with -batch argument
+    + =setSet=: allows time range (e.g. 0:100) in combination with -batch
-    to execute the commands for multiple times.
+    argument to execute the commands for multiple times.
     + =extrudeMesh=:
-            - option to add extrusion to existing mesh.
+      - option to add extrusion to existing mesh.
-            - works in parallel
+      - works in parallel
     + =snappyHexMesh=:
-        + extrude across multi-processor boundaries
+      + extrude across multi-processor boundaries
-        + preserve faceZones during layering
+      + preserve faceZones during layering
 * Post-processing
   + =paraFoam=, =foamToVTK=: full support for polyhedral cell type in recent
      Paraview versions.
-  + =foamToEnsight=: parallel continuous data. new =-nodeValues= option to generate and output nodal
+  + =foamToEnsight=: parallel continuous data. new =-nodeValues= option to
-    field data.
+    generate and output nodal field data.
   + =singleCellMesh=: new utility to convert mesh and fields to a single cell
     mesh. Great for postprocessing.
   + =steadyParticleTracks=: Generates VTK tracks from the output of the cloud

doc/changes/codeStream.org

@@ -0,0 +1,135 @@
+#                            -*- mode: org; -*-
+#
+#+TITLE:           =codeStream=: On-the-fly code compilation
+#+AUTHOR:                      OpenCFD Ltd.
+#+DATE:                            TBA
+#+LINK:                  http://www.openfoam.com
+#+OPTIONS: author:nil ^:{}
+# Copyright (c) 2011 OpenCFD Ltd.
+
+* Dictionary preprocessing directive: =#codeStream=
+  This is a dictionary preprocessing directive ('=functionEntry=') which
+  provides a snippet of OpenFOAM C++ code which gets compiled and executed to
+  provide the actual dictionary entry. The snippet gets provided as three
+  sections of C++ code which just gets inserted into a template:
+  - =code= section: the actual body of the code. It gets called with arguments
+    =const dictionary& dict, OStream& os= and the C++ code can do a
+    =dict.lookup= to find current dictionary values.
+  - optional =codeInclude= section: any #include statements to include OpenFOAM
+    files.
+  - optional 'codeOptions' section: any extra compilation flags to be added to
+    =EXE_INC= in =Make/options=
+
+  To ease inputting mulit-line code there is the =#{ #}= syntax. Anything in
+  between these two delimiters becomes a string with all newlines, quotes etc
+  preserved.
+
+  Example: Look up dictionary entries and do some calculation
+  #+BEGIN_SRC c++
+    startTime       0;
+    endTime         100;
+    ..
+    writeInterval   #codeStream
+    {
+        code
+        #{
+            scalar start = readScalar(dict["startTime"]);
+            scalar end = readScalar(dict["endTime"]);
+            label nDumps = 5;
+            label interval = end-start
+            os  << ((start-end)/nDumps)
+        #}
+    };
+  #+END_SRC
+
+* Implementation
+  - the =#codeStream= entry reads the dictionary following it, extracts the
+    =code=, =codeInclude=, =codeOptions= sections (these are just strings) and
+    calculates the SHA1 checksum of the contents.
+  - it copies a template file
+    =($FOAM_CODESTREAM_TEMPLATE_DIR/codeStreamTemplate.C)=, substituting all
+    occurences of =code=, =codeInclude=, =codeOptions=.
+  - it writes library source files to =constant/codeStream/<sha1>= and compiles
+    it using =wmake libso=.
+  - the resulting library gets loaded (=dlopen=, =dlsym=) and the function
+    executed
+  - the function will have written its output into the Ostream which then gets
+    used to construct the entry to replace the whole =#codeStream= section.
+  - using the sha1 means that same code will only be compiled and loaded once.
+
+* Boundary condition: =codedFixedValue=
+  This uses the code from codeStream to have an in-line specialised
+  =fixedValueFvPatchScalarField=. For now only for scalars:
+  #+BEGIN_SRC c++
+  outlet
+  {
+      type            codedFixedValue<scalar>;
+      value           uniform 0;
+      redirectType    fixedValue10;
+
+      code
+      #{
+          operator==(min(10, 0.1*this->db().time().value()));
+      #};
+  }
+  #+END_SRC
+  It by default always includes =fvCFD.H= and adds the =finiteVolume= library to
+  the include search path.
+
+* Security
+  Allowing the case to execute C++ code does introduce security risks.  A
+  third-party case might have a =#codeStream{#code system("rm -rf .");};= hidden
+  somewhere in a dictionary.  =#codeStream= is therefore not enabled by default
+  you have to enable it by setting in the system-wide =controlDict=
+  #+BEGIN_SRC c++
+  InfoSwitches
+  {
+      // Allow case-supplied c++ code (#codeStream, codedFixedValue)
+      allowSystemOperations   1;
+  }
+  #+END_SRC
+
+* Field manipulation
+  Fields are read in as =IOdictionary= so can be upcast to provide access to the
+  mesh:
+  #+BEGIN_SRC c++
+  internalField  #codeStream
+  {
+      codeInclude
+      #{
+          #include "fvCFD.H"
+      #};
+
+      code
+      #{
+          const IOdictionary& d = dynamicCast<const IOdictionary>(dict);
+          const fvMesh& mesh = refCast<const fvMesh>(d.db());
+          scalarField fld(mesh.nCells(), 12.34);
+          fld.writeEntry("", os);
+      #};
+
+      codeOptions
+      #{
+          -I$(LIB_SRC)/finiteVolume/lnInclude
+      #};
+  };
+  #+END_SRC
+
+* Exceptions
+  There are unfortunately some exceptions. Following applications read
+  the field as a dictionary, not as an =IOdictionary=:
+  - =foamFormatConvert=
+  - =changeDictionaryDict=
+  - =foamUpgradeCyclics=
+  - =fieldToCell=
+
+  Note: above field initialisation has the problem that the boundary conditions
+  are not evaluated so e.g. processor boundaries will not hold the opposite cell
+  value.
+
+* Other
+  - the implementation is still a bit raw - it compiles code overly much
+  - both =codeStream= and =codedFixedValue= take the contents of the dictionary
+    and extract values and re-assemble list of files and environment vars to
+    replace.  Should just directly pass the dictionary into =codeStreamTools=.
+  - parallel running not tested a lot. What about distributed data parallel?

doc/changes/onTheFly.txt

@@ -1,139 +0,0 @@
-On-the-fly code compilation
----------------------------
-
-1. #codeStream
-This is a dictionary preprocessing directive ('functionEntry') which provides
-a snippet of OpenFOAM
-C++ code which gets compiled and executed to provide the actual dictionary
-entry. The snippet gets provided as three sections of C++ code which just gets
-inserted into a template:
-- 'code' section: the actual body of the code. It gets called with
-    arguments
-
-        const dictionary& dict,
-        OStream& os
-
-    and the C++ code can do a dict.lookup to find current dictionary values.
-
-- optional 'codeInclude' section: any #include statements to include
-OpenFOAM files.
-
-- optional 'codeOptions' section: any extra compilation flags to be added to
-EXE_INC in Make/options
-
-To ease inputting mulit-line code there is the #{ #} syntax. Anything
-inbetween these two delimiters becomes a string with all newlines, quotes etc
-preserved.
-
-Example: Look up dictionary entries and do some calculation
-
-    startTime       0;
-    endTime         100;
-    ..
-    writeInterval   #codeStream
-    {
-        code
-        #{
-            scalar start = readScalar(dict["startTime"]);
-            scalar end = readScalar(dict["endTime"]);
-            label nDumps = 5;
-            label interval = end-start
-            os  << ((start-end)/nDumps)
-        #}
-    };
-
-
-
-2. Implementation
-- the #codeStream entry reads the dictionary following it, extracts the
-code, codeInclude, codeOptions sections (these are just strings) and
-calculates the SHA1 checksum of the contents.
-- it copies a template file
-($FOAM_CODESTREAM_TEMPLATE_DIR/codeStreamTemplate.C), substituting all
-occurences of code, codeInclude, codeOptions.
-- it writes library source files to constant/codeStream/<sha1> and compiles it
-using 'wmake libso'.
-- the resulting library gets loaded (dlopen, dlsym) and the function
-executed
-- the function will have written its output into the Ostream which then
-gets used to construct the entry to replace the whole #codeStream section.
-- using the sha1 means that same code will only be compiled & loaded once.
-
-
-3. codedFixedValue
-This uses the code from codeStream to have an in-line specialised
-fixedValueFvPatchScalarField. For now only for scalars:
-
-    outlet
-    {
-        type            codedFixedValue<scalar>;
-        value           uniform 0;
-        redirectType    fixedValue10;
-
-        code
-        #{
-            operator==(min(10, 0.1*this->db().time().value()));
-        #};
-    }
-
-It by default always includes fvCFD.H and adds the finiteVolume library
-to the include search path.
-
-
-4. Security
-Allowing the case to execute C++ code does introduce security risks.
-A thirdparty case might have a #codeStream{#code system("rm -rf .");};
-hidden somewhere in a dictionary. #codeStream is therefore not enabled by
-default - you have to enable it by setting in the system-wide controlDict
-
-    InfoSwitches
-    {
-        // Allow case-supplied c++ code (#codeStream, codedFixedValue)
-        allowSystemOperations   1;
-    }
-
-
-5. Field manipulation.
-Fields are read in as IOdictionary (*) so can be upcast to provide access
-to the mesh:
-
-internalField  #codeStream
-{
-    codeInclude
-    #{
-        #include "fvCFD.H"
-    #};
-
-    code
-    #{
-        const IOdictionary& d = dynamicCast<const IOdictionary>(dict);
-        const fvMesh& mesh = refCast<const fvMesh>(d.db());
-        scalarField fld(mesh.nCells(), 12.34);
-        fld.writeEntry("", os);
-    #};
-
-    codeOptions
-    #{
-        -I$(LIB_SRC)/finiteVolume/lnInclude
-    #};
-};
-
-* There are unfortunately some exceptions. Following applications read
-the field as a dictionary, not as an IOdictionary:
-- foamFormatConvert
-- changeDictionaryDict
-- foamUpgradeCyclics
-- fieldToCell
-
-
-Note: above field initialisation has the problem that the boundary
-conditions are not evaluated so e.g. processor boundaries will
-not hold the opposite cell value.
-
-
-6. Other
-- the implementation is still a bit raw - it compiles code overly much
-- both codeStream and codedFixedValue take the contents of the dictionary
-and extract values and re-assemble list of files and environment vars to
-replace. Should just directly pass the dictionary into codeStreamTools.
-- parallel running not tested a lot. What about distributed data parallel?