STYLE: avoid unrestricted dictionary lookup in lumpedPointMotion (issue #762)

- improve doxygen for lumpedPointMotion

src/lumpedPointMotion/lumpedPointDisplacementPointPatchVectorField.H

@@ -25,10 +25,6 @@ Class
     Foam::lumpedPointDisplacementPointPatchVectorField
 
 Description
-
-    Interpolates pre-specified motion with motion specified as
-    pointVectorFields.
-
     This is the point-patch responsible for managing the force
     integration on a 'lumped-point' basis, waiting for the external
     application, reading back the response from the external program
@@ -38,24 +34,15 @@ Description
     The internal patch type name is 'lumpedPointDisplacement'.
 
     \heading Patch usage
-
     Example:
     \verbatim
     walls
     {
-        type                lumpedPointDisplacement;
+        type    lumpedPointDisplacement;
-        value               uniform (0 0 0);
+        value   uniform (0 0 0);
-        fieldName           wantedDisplacement;
-        interpolationScheme linear;
     }
     \endverbatim
 
-    This will scan the case for \a wantedDisplacement pointVectorFields
-    and interpolate those in time (using \c linear interpolation) to
-    obtain the current displacement.
-    The advantage of specifying displacement in this way is that it
-    automatically works through decomposePar.
-
 SourceFiles
     lumpedPointDisplacementPointPatchVectorField.C
 
@@ -78,6 +65,7 @@ SourceFiles
 namespace Foam
 {
 
+// Forward declarations
 class interpolationWeights;
 
 /*---------------------------------------------------------------------------*\
@@ -94,15 +82,16 @@ class lumpedPointDisplacementPointPatchVectorField
     typedef lumpedPointDisplacementPointPatchVectorField patchType;
     typedef DimensionedField<vector, pointMesh> fieldType;
 
-    // Private Member Functions
 
 protected:
 
-    //- The starting locations (obtained from the motionSolver).
+    // Protected Member Functions
-    const pointField& points0() const;
 
-    //- The auto-vivifying singleton for movement.
+        //- The starting locations (obtained from the motionSolver).
-    const lumpedPointMovement& movement() const;
+        const pointField& points0() const;
+
+        //- The auto-vivifying singleton for movement.
+        const lumpedPointMovement& movement() const;
 
 
 public:
@@ -172,7 +161,7 @@ public:
             );
         }
 
-    //- Destructor
+    //- Destructor. De-register movement if in use and managed by this patch
     virtual ~lumpedPointDisplacementPointPatchVectorField();
 
 
@@ -185,7 +174,7 @@ public:
         virtual void updateCoeffs();
 
         //- Write
-        virtual void write(Ostream&) const;
+        virtual void write(Ostream& os) const;
 };
 
 

src/lumpedPointMotion/lumpedPointIOMovement.C

@@ -99,15 +99,8 @@ Foam::lumpedPointIOMovement::lumpedPointIOMovement
 }
 
 
-// * * * * * * * * * * * * * * * * Destructor  * * * * * * * * * * * * * * * //
-
-Foam::lumpedPointIOMovement::~lumpedPointIOMovement()
-{}
-
-
 // * * * * * * * * * * * * * * * Member Functions  * * * * * * * * * * * * * //
 
-
 bool Foam::lumpedPointIOMovement::readData(Istream& is)
 {
     dictionary dict(is);

src/lumpedPointMotion/lumpedPointIOMovement.H

@@ -100,7 +100,7 @@ public:
 
 
     //- Destructor
-    ~lumpedPointIOMovement();
+    ~lumpedPointIOMovement() = default;
 
 
     // Member Functions

src/lumpedPointMotion/lumpedPointMovement.C

@@ -54,7 +54,7 @@ const Foam::Enum
 >
 Foam::lumpedPointMovement::scalingNames
 {
-    { scalingType::LENGTH, "plain" },
+    { scalingType::LENGTH, "length" },
     { scalingType::FORCE, "force" },
     { scalingType::MOMENT, "moment" }
 };
@@ -266,7 +266,7 @@ void Foam::lumpedPointMovement::readDict(const dictionary& dict)
     // assume the worst
     deleteDemandDrivenData(thresholdPtr_);
 
-    dict.lookup("axis") >> axis_;
+    dict.read("axis", axis_);
 
     division_ = 0;
     if (dict.readIfPresent("division", division_))
@@ -283,7 +283,7 @@ void Foam::lumpedPointMovement::readDict(const dictionary& dict)
 
     dict.readIfPresent("relax", relax_);
 
-    dict.lookup("locations") >> locations_;
+    dict.read("locations", locations_);
 
     if (dict.readIfPresent("interpolationScheme", interpolationScheme_))
     {
@@ -304,8 +304,8 @@ void Foam::lumpedPointMovement::readDict(const dictionary& dict)
 
     // TODO: calcFrequency_  = dict.lookupOrDefault("calcFrequency", 1);
 
-    commDict.lookup("inputName")  >> inputName_;
+    commDict.read("inputName", inputName_);
-    commDict.lookup("outputName") >> outputName_;
+    commDict.read("outputName", outputName_);
     commDict.readIfPresent("logName", logName_);
 
     inputFormat_ = lumpedPointState::formatNames.lookup
@@ -512,8 +512,7 @@ bool Foam::lumpedPointMovement::forcesAndMoments
 
     const polyBoundaryMesh& patches = pmesh.boundaryMesh();
 
-    const word pName = forcesDict_.lookupOrDefault<word>("p", "p");
+    const word pName(forcesDict_.lookupOrDefault<word>("p", "p"));
-
     scalar pRef   = forcesDict_.lookupOrDefault<scalar>("pRef",   0.0);
     scalar rhoRef = forcesDict_.lookupOrDefault<scalar>("rhoRef", 1.0);
 

src/lumpedPointMotion/lumpedPointMovement.H

@@ -25,11 +25,63 @@ Class
     Foam::lumpedPointMovement
 
 Description
-    The movement 'driver' that describes initial point locations, the
+    The movement \a driver that describes initial point locations, the
     segmentation for pressure integration, the current state of the
-    points/rotations, and forwarding to the communication
+    points/rotations, and forwarding to the externalFileCoupler
-    coordinator. The 'lumpedPointIOMovement' class is simply a
+    communication coordinator.
-    registered version of the same.
+
+    The lumpedPointIOMovement class is simply a registered version of
+    the same.
+
+    See externalFileCoupler for more information about some of
+    the communication parameters and setup.
+
+    \heading Dictionary parameters
+    \table
+        Property    | Description                           | Required | Default
+        axis        | Reference axis for the locations      | yes |
+        locations   | List of lumped point locations        | yes |
+        centre      | Offset of patch points to locations   | no | automatic
+        division    | Division (0-1) for pressure forces    | no | 0
+        relax       | Relaxation/scaling for updating positions | no  |
+        interpolationScheme | The interpolation scheme      | yes |
+        forces      | Optional forces dictionary            | no |
+        communication | Required communication dictionary   | yes |
+    \endtable
+
+    \heading Parameters for communication dictionary
+    \table
+        Property    | Description                       | Required | Default
+        inputName   | Name of positions input file      | yes |
+        outputName  | Name of forces output file        | yes |
+        logName     | Name of log file                  | no  | movement.log
+        inputFormat | Input format: dictionary/plain    | yes |
+        outputFormat | Output format: dictionary/plain  | yes |
+        scaleInput  | Input scaling parameter dictionary | no |
+        scaleOutput | Output scaling parameter dictionary | no |
+    \endtable
+
+    \heading Parameters for optional communication/scaleInput dictionary
+    \table
+        Property    | Description                       | Required | Default
+        length      | Scaling for input positions       | no | 1
+    \endtable
+
+    \heading Parameters for optional communication/scaleOutput dictionary
+    \table
+        Property    | Description                       | Required | Default
+        length      | Scaling for output positions      | no  | 1
+        force       | Scaling for force                 | no  | 1
+        moment      | Scaling for moment                | no  | 1
+    \endtable
+
+    \heading Parameters for optional forces dictionary
+    \table
+        Property    | Description                           | Required | Default
+        p           | Name of the pressure field            | no  | p
+        pRef        | Reference pressure in Pa              | no  | 0
+        rhoRef      | Reference density for incompressible  | no  | 1
+    \endtable
 
 SourceFiles
     lumpedPointMovement.C
@@ -76,16 +128,16 @@ public:
     //- Output format types
     enum class outputFormatType
     {
-        PLAIN,
+        PLAIN,      //!< "plain" is a simple ASCII format
-        DICTIONARY
+        DICTIONARY  //!< "dictionary" is the OpenFOAM dictionary format
     };
 
     //- Output format types
     enum scalingType
     {
-        LENGTH = 0,
+        LENGTH = 0, //!< The "length" scaling
-        FORCE,
+        FORCE,      //!< The "force" scaling
-        MOMENT
+        MOMENT      //!< The "moment" scaling
     };
 
     // Static data

src/lumpedPointMotion/lumpedPointMovement.dict

@@ -72,9 +72,6 @@ communication
     inputFormat     dictionary;
     outputFormat    dictionary;
 
-    debugTable      "$FOAM_CASE/output.txt";
-
-
     // Scaling applied to values read from 'inputName'
     scaleInput
     {

src/lumpedPointMotion/lumpedPointState.C

@@ -83,8 +83,8 @@ void Foam::lumpedPointState::calcRotations() const
 
 void Foam::lumpedPointState::readDict(const dictionary& dict)
 {
-    dict.lookup("points") >> points_;
+    dict.read("points", points_);
-    dict.lookup("angles") >> angles_;
+    dict.read("angles", angles_);
     degrees_ = dict.lookupOrDefault("degrees", false);
     deleteDemandDrivenData(rotationPtr_);
 }
@@ -228,8 +228,8 @@ bool Foam::lumpedPointState::readPlain(Istream& is)
 
     points_.setSize(count);
     angles_.setSize(count);
-
     degrees_ = false;
+
     deleteDemandDrivenData(rotationPtr_);
 
     return count;

src/lumpedPointMotion/lumpedPointState.H

@@ -25,10 +25,31 @@ Class
     Foam::lumpedPointState
 
 Description
-    The 'state' of lumped points corresponds to positions and rotations.
+    The \a state of lumped points corresponds to positions and rotations.
 
-    Encapsulates the response from the external application.
+    This class encapsulates the response from the external application and
-    Entry place for applying relaxation and sub-stepping etc.
+    serves as the entry point for applying relaxation, sub-stepping etc.
+
+    \heading Dictionary input format
+    \table
+        Property    | Description                           | Required | Default
+        points      | List of points                        | yes |
+        angles      | List of Euler rotation angles         | yes |
+        degrees     | Rotation angles in degrees            | no  | false
+    \endtable
+
+    \heading Plain input format.
+    Blank and comment lines starting with a '#' character are ignored.
+    The angles are always in radians.
+    \verbatim
+    NumPoints
+    x0 y0 z0 eulerz0 eulerx'0 eulerz''0
+    x1 y1 z1 eulerz1 eulerx'1 eulerz''1
+    ...
+    \endverbatim
+
+SeeAlso
+    EulerCoordinateRotation
 
 SourceFiles
     lumpedPointState.C
@@ -58,7 +79,6 @@ class Ostream;
                       Class lumpedPointState Declaration
 \*---------------------------------------------------------------------------*/
 
-//- Bundling of position/rotation
 class lumpedPointState
 {
 public:
@@ -66,8 +86,8 @@ public:
     //- Input format types
     enum class inputFormatType
     {
-        PLAIN,
+        PLAIN,      //!< "plain" is a simple ASCII format
-        DICTIONARY
+        DICTIONARY  //!< "dictionary" is the OpenFOAM dictionary format
     };
 
     // Static data

src/lumpedPointMotion/lumpedPointTools.C

@@ -83,7 +83,7 @@ Foam::lumpedPointTools::lumpedPointStates(Istream& is)
         (
             lumpedPointStateTuple
             (
-                readScalar(dict.lookup("time")),
+                dict.get<scalar>("time"),
                 lumpedPointState(dict)
             )
         );