Merge commit 'OpenCFD/master' into olesenm

ReleaseNotes-1.6

@@ -38,155 +38,120 @@
 
 *** Regular Expressions
     The addition of regular expressions marks a major improvement in usability.
-
     + *New* =regExp= class provides support for accessing POSIX extended regular
-      expresssions from within OpenFOAM.
+      expresssions from within OpenFOAM.  See the manpages on your system (/man
-      See the manpages on your system (/man 7 regex/) for more information
+      7 regex/) for more information about the extended regular expression
-      about the extended regular expresssion syntax. Since entire strings are
+      syntax. Since entire strings are matched, the =^= and =$= anchors are not
-      matched, the =^= and =$= anchors are not required.
+      required.
-
+    + *New* =wordRe= class can contain a =word= or a =regExp= .  The match()
-    + *New* =wordRe= class can contain a =word= or a =regExp= .
+      method matches appropriately (as a =word= or as a =regExp=).
-      The match() method matches appropriately (as a =word= or as a =regExp=).
-
     + *New* =stringListOps= to search string lists based on regular expressions,
       =wordRe= or =wordReList= .
-
+    + =Istream= and =Ostream= now retain backslashes when reading/writing
-    + =Istream= and =Ostream= now retain backslashes when reading/writing strings.
+      strings.  The backslash continues to be used as an escape character for
-      The backslash continues to be used as an escape character for double-quote
+      double-quote and newline, but otherwise get passed through "as-is" without
-      and newline, but otherwise get passed through "as-is" without any other
+      any other special meaning (ie, they are /not/ C-style strings). This
-      special meaning (ie, they are /not/ C-style strings). This especially
+      especially helps with input/output of regular expressions.
-      helps with input/output of regular expressions.
-
 
 *** Dictionary improvements/changes
-    + Dictionaries can use words (unquoted) or regular expressions (quoted)
+    + Dictionaries can use words (unquoted) or regular expressions (quoted) for
-      for their keywords. When searching, an exact match has priority
+      their keywords. When searching, an exact match has priority over a regular
-      over a regular expression match.
+      expression match.
-
     + The default =#inputMode= is now '=merge=', which corresponds to the most
-      general usage. The =#inputMode warn= corresponds to the previous
+      general usage. The =#inputMode warn= corresponds to the previous default
-      default behaviour.
+      behaviour.
-
+    + The *new* =#inputMode protect= can be used to conditionally merge default
-    + The *new* =#inputMode protect=  can be used to conditionally merge default
       values into existing dictionaries.
-
     + *New* =digest()= method to calculate and return the SHA1 message digest
 
-
 *** Improved list containers
     + It is now possible to append a =UList= to an existing =List= or
       =DynamicList= .
-
     + =DynamicList= is now much more flexible. It can be used with the
-      =append()= method, or with the =setSize()= method and =operator[]=, as
+      =append()= method, or with the =setSize()= method and =operator[]=, as per
-      per =List= .  =DynamicList= also has more methods for adjusting the
+      =List= .  =DynamicList= also has more methods for adjusting the space
-      space allocated.
+      allocated.
-
     + =SortableList= now uses stable sort and allows =reverseSort()= as well.
       =SortableList= is also more versatile - the indices mostly remain
-      unallocated until they are required in the =sort()= method.
+      unallocated until they are required in the =sort()= method.  The sort
-      The sort indices can be deallocated with the =shrink()= method.
+      indices can be deallocated with the =shrink()= method.  Works as expected
-      Works as expected with =transfer()= and assignment from other lists.
+      with =transfer()= and assignment from other lists.
-
     + Specialization for =UList<bool>::operator[](..) const= to return =false=
       for out-of-range elements. This allows lazy evaluation with no noticeable
       change in performance.
-
+    + =PackedList= has much better performance, *new* lazy evaluation and *new*
-    + =PackedList= has much better performance, *new* lazy evaluation and
+      auto-vivify of elements on assignment. Any auto-vivified elements will
-      *new* auto-vivify of elements on assignment. Any auto-vivified
+      also flood-fill the gaps with zero.  The =append()= method can be used
-      elements will also flood-fill the gaps with zero.  The =append()= method
+      like in =DynamicList= to append a single element. The =set()= method can
-      can be used like in =DynamicList= to append a single element. The =set()=
+      be used like in =labelHashSet= .  A =PackedBoolList= can thus replace
-      method can be used like in =labelHashSet= .
+      =labelHashSet= in many places.
-      A =PackedBoolList= can thus replace =labelHashSet= in many places.
-
     + *New* =UIndirectList= for an indirect list without storing the addressing.
 
-
 *** New hashing algorithms
     + Bob Jenkins' hash routine for performance improvement (5-10% faster for
       string hashing than the previous algorithm) and fewer collisions.
-
     + SHA1 hashing and SHA1 message digests (NIST specification FIPS-180-1)
-      added. The SHA1 digest provides a compact (20 bytes) means of
+      added. The SHA1 digest provides a compact (20 bytes) means of determining
-      determining if the contents of an object have changed. The *new*
+      if the contents of an object have changed. The *new* =OSHA1stream= class
-      =OSHA1stream= class can be used to calculate SHA1 digests for anything
+      can be used to calculate SHA1 digests for anything that can write to an
-      that can write to an output stream.
+      output stream.
-
 
 *** HashTable/HashSet improvements
    + Performance improvements for querying on empty tables
-
+   + The =erase()= method can take a list of keys or the keys from any another
-   + The =erase()= method can take a list of keys or the keys from any
+     =HashTable=/=HashSet= .
-     another =HashTable=/=HashSet= .
+   + =HashSet= has an =operator[]() const= that allows the same syntax to be
-
+     used for =boolList=, =PackedBoolList= and =labelHashSet= .
-   + =HashSet= has an =operator[]() const= that allows the same syntax
-     to be used for =boolList=, =PackedBoolList= and =labelHashSet= .
-
    + =HashSet has additional operators '+=', '-=', '&=' to add, remove or
      intersect keys, respectively.
 
-
 *** Improved bool/Switch
-   + The =Switch= class has reduced the storage to be on par with =bool= .
+   + The =Switch= class has reduced the storage to be on par with =bool= .  It
-     It is now more flexible and behaves much more like a =bool= .
+     is now more flexible and behaves much more like a =bool= .
-
    + The IO for =bool= uses =Switch= internally for reading, so the end-user
      doesn't need to know if a particular class used =bool= or =Switch= .
 
-
 *** Miscellaneous container class improvments
-    + *New* Boost-style =StaticAssert= added.
+    + *New* Boost-style =StaticAssert= added.  Which is useful to catch invalid
-      Which is useful to catch invalid template sizes, for example.
+      template sizes, for example.
-
+    + Various containers now have C++0x-style =cbegin()=, =cend()= iterator
-    + Various containers now have C++0x-style =cbegin()=, =cend()= iterator methods.
+      methods.
-
     + Various containers now have STL-style =empty()= method, which may be more
       readable and universal than =!size()= or =!valid()= conditions.
-
     + various containers now have an =xfer()= method for yielding their contents
       to a corresponding =Xfer= class.
 
-
 *** *New* Xfer class
     Provides finer grained control over copying or transferring objects with
     very little overhead. It can be used for any object that has a =transfer()=
-    method and a =operator=()= copy method.
+    method and a =operator=()= copy method.  Since it is decided upon
-    Since it is decided upon construction of the =Xfer= object whether the
+    construction of the =Xfer= object whether the parameter is to be copied or
-    parameter is to be copied or transferred, the contents of the resulting
+    transferred, the contents of the resulting Xfer object can be transferred
-    Xfer object can be transferred unconditionally. This greatly simplifies
+    unconditionally. This greatly simplifies defining constructors or methods in
-    defining constructors or methods in other classes with mixed
+    other classes with mixed transfer/copy semantics without requiring 2^N
-    transfer/copy semantics without requiring 2^N different versions.
+    different versions.
-
+    + =xferCopy()=, =xferMove()= and =xferCopyTo()=, =xferMoveTo()= functions to
-    + =xferCopy()=, =xferMove()= and =xferCopyTo()=, =xferMoveTo()= functions
+      ease the use of the =Xfer= class.
-      to ease the use of the =Xfer= class.
 
 *** Convenience changes
     + =IOobject= has a *new* constructor for creating an =IOobject= from a
       single-path specification (eg, see =blockMesh -dict= option).
-
+    + =argList= has *new* convenience methods for accessing options more
-    + =argList= has *new* convenience methods for accessing options more directly:
+      directly: =option()=, =optionFound()=, =optionLookup()=, =optionRead()=,
-      =option()=, =optionFound()=, =optionLookup()=, =optionRead()=,
       =optionReadIfPresent()= .
-
+    + The *new* =readList(Istream&)= can read a bracket-delimited list or handle
-    + The *new* =readList(Istream&)= can read a bracket-delimited list or
+      a single value as a list of size 1. This can be a useful convenience when
-      handle a single value as a list of size 1. This can be a useful
+      processing command-line options.
-      convenience when processing command-line options.
-
 
 *** Misc. improvements
     + Improved consistency and interoperability between =face= and =triFace= classes.
-
     + =face::triangles()= can split and append to a =DynamicList=
-
     + =coordinateSystems= can access global systems (similar to =MeshObject=)
 
-
-
 ** Turbulence modelling
    + Major development of turbulence model libraries to give extra flexibility
      at the solver level.  For solvers that can support either RAS/LES
-     computations, the selection is made in the
+     computations, the selection is made in the /constant/turbulenceProperties/,
-     /constant/turbulenceProperties/,
      by setting the =simulationType= keyword to:
      - =laminar=
      - =RASModel=
@@ -197,17 +162,15 @@
 
 **** RAS wall functions
      Wall functions are now run-time selectable per patch for RAS.
+     + Velocity:
+       - Apply to turbulent viscosities =nut= or =mut=
+       - Apply to =k=, =Q=, =R=
+       - Apply to =epsilon=, =omega=
+     + Temperature:
+       - Apply to turbulent thermal diffusivity, =alphat= (compressible only)
 
-****** Velocity:
+     + To apply wall functions:
-       + Apply to turbulent viscosities =nut= or =mut=
+       - To recapture the functionality of previous OpenFOAM versions (v1.5 and
-       + Apply to =k=, =Q=, =R=
-       + Apply to =epsilon=, =omega=
-
-****** Temperature:
-       + Apply to turbulent thermal diffusivity, =alphat= (compressible only)
-
-****** To apply wall functions:
-       + To recapture the functionality of previous OpenFOAM versions (v1.5 and
          earlier) assign:
          - for velocity:
            - =nut=: =nutWallFunction=
@@ -217,7 +180,7 @@
            - =k=, =Q=, =R=: =kQRWallFunction=
          - for temperature:
            - =alphat=: =alphatWallFunction=
-       + New =alphaSgsJayatillekeWallFunction= thermal wall function for
+       - New =alphaSgsJayatillekeWallFunction= thermal wall function for
          compressible LES
 
 **** *New* LES turbulence models
@@ -259,10 +222,10 @@
 ** Lagrangian
 
 **** Intermediate
-     - Overhaul of the underlying framework
+     + Overhaul of the underlying framework
-     - Reacting now split into reacting and reacting multiphase
+     + Reacting now split into reacting and reacting multiphase
-     - New structure for variable composition
+     + New structure for variable composition
-     - Many new sub-models, including:
+     + Many new sub-models, including:
        - Injection
          - =PatchInjection= - injection local to patch face cells
          - =FieldActivatedInjection= - injection based on satisfying external
@@ -278,30 +241,24 @@
          - liquid evaporation
 
 **** Coal combustion
-     - *New* library - extension of reacting-multiphase functionality
+     + *New* library - extension of reacting-multiphase functionality
        - Surface reaction/combustion models
 
 ** Discrete methods
-    - *New* library offering DSMC simulation functionality - see =dsmcFoam=
+    + *New* library offering DSMC simulation functionality - see =dsmcFoam=
       below
-    - *New* libraries offering molecular dynamics simulation functionality - see
+    + *New* libraries offering molecular dynamics simulation functionality - see
       =mdFoam= and =mdEquilibrationFoam=: below.
 
-
 ** *New* surfMesh library
    Provides a more efficient storage mechanism than possible with =triSurface=
-   without restrictions on the shape of the face (templated parameter).
+   without restrictions on the shape of the face (templated parameter).  It will
-   It will however take quite some time before it can fully replace
+   however take quite some time before it can fully replace =triSurface= .
-   =triSurface= .
-
    + =MeshedSurface= class - with zero or more contiguous =surfZones= .
-
+   + =UnsortedMeshedSurface= class - unordered surface zones (as per
-   + =UnsortedMeshedSurface= class - unordered surface zones
+     =triSurface=)
-     (as per =triSurface=)
-
    + =surfMesh= class - for reading/writing in native OpenFOAM format
 
-
 * Solver restructuring
   The upgrade to the turbulence models means that the simulation type, i.e.
   laminar, RAS or LES can be selected at run time. This has allowed a reduction
@@ -318,48 +275,41 @@
     - =channelOodles= \rightarrow =channelFoam= (LES)
 
 * General changes
-  - pd to p ------------------------------------------------------------ [HENRY]
+  + pd to p ------------------------------------------------------------ [HENRY]
-  - gravity ------------------------------------------------------------ [HENRY]
+  + gravity ------------------------------------------------------------ [HENRY]
 
 ** Solver control improvments
    Use dictionary entries instead of an =Istream= for the solver controls.
    + This Allows dictionary substitutions and regular expressions in
      /system/fvSolution/
-
    + The old solver control syntax is still supported (warning emitted), but
      the *new* =foamUpgradeFvSolution= utility can be used to convert
      /system/fvSolution/ to the new format.
 
-
 * Tutorial restructuring
   to reflect solver application structure
 
 * Post-processing ---------------------------------------------------- [MATTIJS]
-  - SAMPLING - improved plane, iso-surface handling
+  + SAMPLING - improved plane, iso-surface handling
-  - Output to any surface geometry format supported by the =surfMesh= library.
+  + Output to any surface geometry format supported by the =surfMesh= library.
 
 * *New* Solvers
   + =buoyantBoussinesqSimpleFoam=
     Steady state heat transfer solver using a Boussinesq approximation for
     buoyancy, with laminar, RAS or LES turbulence modelling
-
   + =buoyantBoussinesqPisoFoam=
     Transient heat transfer solver using a Boussinesq approximation for
     buoyancy, with laminar, RAS or LES turbulence modelling
-
   + =coalChemistryFoam=
     Transient, reacting lagrangian solver, employing a coal cloud and a thermo
     cloud, with chemistry, and laminar, RAS or LES turbulence modelling
-
   + =porousExplicitSourceReactingParcelFoam=
     Transient, reacting lagrangian solver, employing a single phase reacting
     cloud, with porous media, explicit mass sources, and laminar, RAS or LES
     turbulence modelling
-
   + =rhoReactingFoam=
     Density-based thermodynamics variant of the reactingFoam solver, i.e. now
     applicable to liquid systems
-
   + =dsmcFoam=
     DSMC (Direct Simulation Monte-Carlo) solver for rarefied gas dynamics
     simulations, able to simulate mixtures of an arbitrary number of gas species.
@@ -377,7 +327,6 @@
     molecules interact with short-range dispersion forces and pairwise
     electrostatic interactions using methods described in:
     Fennell and Gezelter, J. Chem. Phys. 124, 234104 (2006)
-
   + =mdEquilibrationFoam=
     Similar to mdFoam, but employs velocity scaling to adjust the simulation
     temperature to a target value. Useful to equilibrate a case before
@@ -390,30 +339,28 @@
      which allows a chaining of operations. It is thus internally more
      efficient when /system/controlDict/ uses =functions {..}= instead of
      =functions (..)=, but both forms are supported.
-
    + The =functionObject= now has an additional =end()= method that is called
      when =Time::loop()= or =Time::run()= determine that the time-loop exits.
      Accordingly, one of these two idioms should be used in solver code:
      1. =while (runTime.loop() { ... }=
      2. =while (runTime.run()) { runTime++; ... }=
-
    + *New* - =functionObjectList= now tracks the SHA1 message digest of the
      sub-directories. This avoids reloading a =functionObject= when
      something unrelated in /system/controlDict/ changed.
 
 ** *New* function objects:
-    - =systemCall= - executes a list of system instructions
+    + =systemCall= - executes a list of system instructions
-    - =fieldMinMax= - computes the min/max of a <field>
+    + =fieldMinMax= - computes the min/max of a <field>
-    - =staticPressure= - converts kinematic pressure to static pressure
+    + =staticPressure= - converts kinematic pressure to static pressure
-    - =dsmcFields= - calculates intensive fields (velocity and temperature) from
+    + =dsmcFields= - calculates intensive fields (velocity and temperature) from
       averaged extensive fields (i.e. momentum and energy)
 
 ** Usage
-    - Improved output control: =timeStep= or =outputTime=
+    + Improved output control: =timeStep= or =outputTime=
 
 * Boundary conditions
-  - Improved set of direct mapped boundary conditions
+  + Improved set of direct mapped boundary conditions
-  - Buoyancy boundary condition ---------------------------------------- [HENRY]
+  + Buoyancy boundary condition ---------------------------------------- [HENRY]
 
 * Utilities
 
@@ -430,14 +377,14 @@
     be useful when post-processing results incrementally.
 
 ** *New* utilities
-  - =particleTracks= - generate particle tracks for lagrangian calculations
+  + =particleTracks= - generate particle tracks for lagrangian calculations
-  - =dsmcInitialise= - preprocessing utility to create initial configurations of
+  + =dsmcInitialise= - preprocessing utility to create initial configurations of
     DSMC particles in a geometry
 
 *** *New* foamCalc functions
-    - =interpolate= - performs fvc::interpolate(<field>)
+    + =interpolate= - performs fvc::interpolate(<field>)
-    - =randomise= - randomises a <field> by a given perturbation
+    + =randomise= - randomises a <field> by a given perturbation
-    - =addSubtract= - simple add/subtract field functionality
+    + =addSubtract= - simple add/subtract field functionality
 
 ** Usage
   + =timeSelector= can now combine =-time ranges= and =-latestTime= options.
@@ -450,9 +397,7 @@
 ** Improvements to Paraview reader module
   + =PV3FoamReader= added mesh region handling. The region name is parsed
     from the filename. Eg, /case{region}.OpenFOAM/
-
   + =paraFoam= with a *new* =-region= option for specifying an alternative
     region. A *new* =-touch= option to generate the /.OpenFOAM/ file only.
     Only creates (and removes) /.OpenFOAM/ files if they didn't already
     exist, which is useful in connection with the =-touch= option.
-