ENH: codedBasicSource: coded version of sources

etc/codeTemplates/dynamicCode/codedBasicSourceTemplate.C

+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | Copyright (C) 2012 OpenFOAM Foundation
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+    for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+\*---------------------------------------------------------------------------*/
+
+#include "codedBasicSourceTemplate.H"
+#include "addToRunTimeSelectionTable.H"
+#include "fvPatchFieldMapper.H"
+#include "volFields.H"
+#include "surfaceFields.H"
+#include "unitConversion.H"
+//{{{ begin codeInclude
+${codeInclude}
+//}}} end codeInclude
+
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+namespace Foam
+{
+
+// * * * * * * * * * * * * * * * Local Functions * * * * * * * * * * * * * * //
+
+//{{{ begin localCode
+${localCode}
+//}}} end localCode
+
+
+// * * * * * * * * * * * * * * * Global Functions  * * * * * * * * * * * * * //
+
+extern "C"
+{
+    // dynamicCode:
+    // SHA1 = ${SHA1sum}
+    //
+    // unique function name that can be checked if the correct library version
+    // has been loaded
+    void ${typeName}_${SHA1sum}(bool load)
+    {
+        if (load)
+        {
+            // code that can be explicitly executed after loading
+        }
+        else
+        {
+            // code that can be explicitly executed before unloading
+        }
+    }
+}
+
+// * * * * * * * * * * * * * * Static Data Members * * * * * * * * * * * * * //
+
+//makeRemovablePatchTypeField
+//(
+//    fvPatch${FieldType},
+//    ${typeName}CodedBasic${SourceType}
+//);
+defineTypeNameAndDebug(${typeName}CodedBasic${SourceType}, 0);
+addRemovableToRunTimeSelectionTable
+(
+    basicSource,
+    ${typeName}CodedBasic${SourceType},
+    dictionary
+);
+
+
+const char* const ${typeName}CodedBasic${SourceType}::SHA1sum =
+    "${SHA1sum}";
+
+
+// * * * * * * * * * * * * * * * * Constructors  * * * * * * * * * * * * * * //
+
+${typeName}CodedBasic${SourceType}::
+${typeName}CodedBasic${SourceType}
+(
+    const word& name,
+    const word& modelType,
+    const dictionary& dict,
+    const fvMesh& mesh
+)
+:
+    basicSource(name, modelType, dict, mesh)
+{
+    if (${verbose:-false})
+    {
+        Info<<"construct ${typeName} sha1: ${SHA1sum}"
+            " from components\n";
+    }
+}
+
+
+// * * * * * * * * * * * * * * * * Destructor  * * * * * * * * * * * * * * * //
+
+${typeName}CodedBasic${SourceType}::
+~${typeName}CodedBasic${SourceType}()
+{
+    if (${verbose:-false})
+    {
+        Info<<"destroy ${typeName} sha1: ${SHA1sum}\n";
+    }
+}
+
+
+// * * * * * * * * * * * * * * * Member Functions  * * * * * * * * * * * * * //
+
+void ${typeName}CodedBasic${SourceType}::correct
+(
+    GeometricField<${TemplateType}, fvPatchField, volMesh>& fld
+)
+{
+    if (${verbose:-false})
+    {
+        Info<<"${typeName}CodedBasic${SourceType}::correct()\n";
+    }
+
+//{{{ begin code
+    ${codeCorrect}
+//}}} end code
+}
+
+
+void ${typeName}CodedBasic${SourceType}::addSup
+(
+    fvMatrix<${TemplateType}>& eqn,
+    const label fieldI
+)
+{
+    if (${verbose:-false})
+    {
+        Info<<"${typeName}CodedBasic${SourceType}::addSup()\n";
+    }
+
+//{{{ begin code
+    ${codeAddSup}
+//}}} end code
+}
+
+
+void ${typeName}CodedBasic${SourceType}::setValue
+(
+    fvMatrix<${TemplateType}>& eqn,
+    const label fieldI
+)
+{
+    if (${verbose:-false})
+    {
+        Info<<"${typeName}CodedBasic${SourceType}::setValue()\n";
+    }
+
+//{{{ begin code
+    ${codeSetValue}
+//}}} end code
+}
+
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+} // End namespace Foam
+
+// ************************************************************************* //

etc/codeTemplates/dynamicCode/codedBasicSourceTemplate.H

+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | Copyright (C) 2012 OpenFOAM Foundation
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+    for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+Description
+    Template for use with dynamic code generation of a basicSource
+
+    - without state
+
+SourceFiles
+    codedBasicSourceTemplate.C
+
+\*---------------------------------------------------------------------------*/
+
+#ifndef codedBasicSourceTemplate_H
+#define codedBasicSourceTemplate_H
+
+#include "basicSource.H"
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+namespace Foam
+{
+
+/*---------------------------------------------------------------------------*\
+                         A templated CodedBasicSource
+\*---------------------------------------------------------------------------*/
+
+class ${typeName}CodedBasic${SourceType}
+:
+    public basicSource
+{
+public:
+
+    //- Information about the SHA1 of the code itself
+    static const char* const SHA1sum;
+
+    //- Runtime type information
+    TypeName("${typeName}");
+
+
+    // Constructors
+
+        //- Construct from patch and internal field
+        ${typeName}CodedBasic${SourceType}
+        (
+            const word& name,
+            const word& modelType,
+            const dictionary& dict,
+            const fvMesh& mesh
+        );
+
+    //- Destructor
+    virtual ~${typeName}CodedBasic${SourceType}();
+
+
+    // Member functions
+
+            //- Correct field
+            virtual void correct
+            (
+                GeometricField<${TemplateType}, fvPatchField, volMesh>&
+            );
+
+            //- Explicit and implicit matrix contributions
+            virtual void addSup
+            (
+                fvMatrix<${TemplateType}>& eqn,
+                const label fieldI
+            );
+
+            //- Set value
+            virtual void setValue
+            (
+                fvMatrix<${TemplateType}>& eqn,
+                const label fieldI
+            );
+};
+
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+} // End namespace Foam
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+#endif
+
+// ************************************************************************* //

src/fieldSources/Make/files

@@ -29,4 +29,6 @@ $(interRegion)/constantHeatTransfer/constantHeatTransfer.C
 $(interRegion)/tabulatedHeatTransfer/tabulatedHeatTransfer.C
 $(interRegion)/variableHeatTransfer/variableHeatTransfer.C
 
+basicSource/codedSource/codedSource.C
+
 LIB = $(FOAM_LIBBIN)/libfieldSources

src/fieldSources/basicSource/codedSource/CodedSource.C

+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | Copyright (C) 2012 OpenFOAM Foundation
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+    for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+\*---------------------------------------------------------------------------*/
+
+#include "CodedSource.H"
+#include "fvMesh.H"
+#include "fvMatrices.H"
+#include "dynamicCode.H"
+#include "dynamicCodeContext.H"
+
+// * * * * * * * * * * * * Protected Member Functions  * * * * * * * * * * * //
+
+
+// * * * * * * * * * * * * * Private Member Functions  * * * * * * * * * * * //
+
+template<class Type>
+void Foam::CodedSource<Type>::prepare
+(
+    dynamicCode& dynCode,
+    const dynamicCodeContext& context
+) const
+{
+    word sourceType(pTraits<Type>::typeName);
+
+    // Set additional rewrite rules
+    dynCode.setFilterVariable("typeName", redirectType_);
+    dynCode.setFilterVariable("TemplateType", sourceType);
+    dynCode.setFilterVariable("SourceType", sourceType + "Source");
+
+    //dynCode.removeFilterVariable("code");
+    dynCode.setFilterVariable("codeCorrect", codeCorrect_);
+    dynCode.setFilterVariable("codeAddSup", codeAddSup_);
+    dynCode.setFilterVariable("codeSetValue", codeSetValue_);
+
+    // compile filtered C template
+    dynCode.addCompileFile("codedBasicSourceTemplate.C");
+
+    // copy filtered H template
+    dynCode.addCopyFile("codedBasicSourceTemplate.H");
+
+    // debugging: make BC verbose
+    //         dynCode.setFilterVariable("verbose", "true");
+    //         Info<<"compile " << redirectType_ << " sha1: "
+    //             << context.sha1() << endl;
+
+    // define Make/options
+    dynCode.setMakeOptions
+        (
+            "EXE_INC = -g \\\n"
+            "-I$(LIB_SRC)/fieldSources/lnInclude \\\n"
+            "-I$(LIB_SRC)/finiteVolume/lnInclude \\\n"
+            "-I$(LIB_SRC)/meshTools/lnInclude \\\n"
+            "-I$(LIB_SRC)/sampling/lnInclude \\\n"
+            + context.options()
+            + "\n\nLIB_LIBS = \\\n"
+            + "    -lmeshTools \\\n"
+            + "    -lfieldSources \\\n"
+            + "    -lsampling \\\n"
+            + "    -lfiniteVolume \\\n"
+            + context.libs()
+        );
+}
+
+
+template<class Type>
+Foam::dlLibraryTable& Foam::CodedSource<Type>::libs() const
+{
+    return const_cast<Time&>(mesh_.time()).libs();
+}
+
+
+template<class Type>
+Foam::string Foam::CodedSource<Type>::description() const
+{
+    return "basicSource " + name_;
+}
+
+
+template<class Type>
+void Foam::CodedSource<Type>::clearRedirect() const
+{
+    redirectBasicSourcePtr_.clear();
+}
+
+
+template<class Type>
+const Foam::dictionary& Foam::CodedSource<Type>::codeDict() const
+{
+    return coeffs_;
+}
+
+
+// * * * * * * * * * * * * * * * * Constructors  * * * * * * * * * * * * * * //
+
+template<class Type>
+Foam::CodedSource<Type>::CodedSource
+(
+    const word& name,
+    const word& modelType,
+    const dictionary& dict,
+    const fvMesh& mesh
+)
+:
+    basicSource(name, modelType, dict, mesh)
+{
+    read(dict);
+}
+
+
+// * * * * * * * * * * * * * * * Member Functions  * * * * * * * * * * * * * //
+
+template<class Type>
+Foam::basicSource& Foam::CodedSource<Type>::redirectBasicSource()
+const
+{
+    if (!redirectBasicSourcePtr_.valid())
+    {
+        dictionary constructDict(dict_);
+        constructDict.set("type", redirectType_);
+
+        redirectBasicSourcePtr_ = basicSource::New
+        (
+            redirectType_,
+            constructDict,
+            mesh_
+        );
+    }
+    return redirectBasicSourcePtr_();
+}
+
+
+template<class Type>
+void Foam::CodedSource<Type>::correct
+(
+    GeometricField<Type, fvPatchField, volMesh>& fld
+)
+{
+    if (debug)
+    {
+        Info<< "CodedSource<"<< pTraits<Type>::typeName
+            << ">::correct for source " << name_ << endl;
+    }
+
+    updateLibrary(redirectType_);
+    redirectBasicSource().correct(fld);
+}
+
+
+template<class Type>
+void Foam::CodedSource<Type>::addSup
+(
+    fvMatrix<Type>& eqn,
+    const label fieldI
+)
+{
+    if (debug)
+    {
+        Info<< "CodedSource<"<< pTraits<Type>::typeName
+            << ">::addSup for source " << name_ << endl;
+    }
+
+    updateLibrary(redirectType_);
+    redirectBasicSource().addSup(eqn, fieldI);
+}
+
+
+template<class Type>
+void Foam::CodedSource<Type>::setValue
+(
+    fvMatrix<Type>& eqn,
+    const label fieldI
+)
+{
+    if (debug)
+    {
+        Info<< "CodedSource<"<< pTraits<Type>::typeName
+            << ">::setValue for source " << name_ << endl;
+    }
+
+    updateLibrary(redirectType_);
+    redirectBasicSource().setValue(eqn, fieldI);
+}
+
+
+// ************************************************************************* //

src/fieldSources/basicSource/codedSource/CodedSource.H

+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | Copyright (C) 2012 OpenFOAM Foundation
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+    for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+Class
+    Foam::codedSource
+
+Description
+    Constructs on-the-fly a new basicSource.
+
+    E.g. in constant/sourcesProperties
+
+    momentumSource
+    {
+        type            vectorCodedSource;
+        active          on;            //on/off switch
+        timeStart       0.0;           //start time
+        duration        1000000.0;     //duration
+        selectionMode   all;       //cellSet // points //cellZone
+
+        vectorCodedSourceCoeffs
+        {
+            fieldNames  (U);
+            redirectType    ramp;
+
+            codeCorrect
+            #{
+                Pout<< "**codeCorrect**" << endl;
+            #};
+
+            codeAddSup
+            #{
+                Pout<< "**codeAddSup**" << endl;
+            #};
+
+            codeSetValue
+            #{
+                Pout<< "**codeSetValue**" << endl;
+            #};
+
+            // Dummy entry. Make dependent on above to trigger recompilation
+            code
+            #{
+                $codeCorrect
+                $codeAddSup
+                $codeSetValue
+            #};
+        }
+
+        // Dummy entry
+        rampCoeffs
+        {}
+    }
+
+
+SourceFiles
+    codedSource.C
+
+\*---------------------------------------------------------------------------*/
+
+#ifndef CodedSource_H
+#define CodedSource_H
+
+#include "basicSource.H"
+#include "codedBase.H"
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+namespace Foam
+{
+
+/*---------------------------------------------------------------------------*\
+                       Class codedSource Declaration
+\*---------------------------------------------------------------------------*/
+
+template<class Type>
+class CodedSource
+:
+    public basicSource,
+    public codedBase
+{
+
+protected:
+
+    // Protected data
+
+        word redirectType_;
+
+        string codeCorrect_;
+        string codeAddSup_;
+        string codeSetValue_;
+
+        //- Underlying functionObject
+        mutable autoPtr<basicSource> redirectBasicSourcePtr_;
+
+
+    // Protected Member Functions
+
+        //- get the loaded dynamic libraries
+        virtual dlLibraryTable& libs() const;
+
+        //- adapt the context for the current object
+        virtual void prepare(dynamicCode &,const dynamicCodeContext&) const;
+
+        // Return a description (type + name) for the output
+        virtual string description() const;
+
+        // Clear any redirected objects
+        virtual void clearRedirect() const;
+
+        // Get the dictionary to initialize the codeContext
+        virtual const dictionary& codeDict() const;
+
+
+public:
+
+    //- Runtime type information
+    TypeName("coded");
+
+
+    // Constructors
+
+        //- Construct from components
+        CodedSource
+        (
+            const word& name,
+            const word& modelType,
+            const dictionary& dict,
+            const fvMesh& mesh
+        );
+
+
+    // Member Functions
+
+        //- Dynamically compiled basicSource
+        basicSource& redirectBasicSource() const;
+
+        // Evaluation
+
+            //- Correct field
+            virtual void correct
+            (
+                GeometricField<Type, fvPatchField, volMesh>&
+            );
+
+            //- Explicit and implicit matrix contributions
+            virtual void addSup
+            (
+                fvMatrix<Type>& eqn,
+                const label fieldI
+            );
+
+            //- Set value
+            virtual void setValue
+            (
+                fvMatrix<Type>& eqn,
+                const label fieldI
+            );
+
+
+        // I-O
+
+            //- Write the source properties
+            virtual void writeData(Ostream&) const;
+
+            //- Read source dictionary
+            virtual bool read(const dictionary& dict);
+};
+
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+} // End namespace Foam
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+#ifdef NoRepository
+#   include "CodedSource.C"
+#   include "CodedSourceIO.C"
+#endif
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+#endif
+
+// ************************************************************************* //

src/fieldSources/basicSource/codedSource/CodedSourceIO.C

+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | Copyright (C) 2012 OpenFOAM Foundation
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+    for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+\*---------------------------------------------------------------------------*/
+
+#include "CodedSource.H"
+#include "stringOps.H"
+
+// * * * * * * * * * * * * * * * Member Functions  * * * * * * * * * * * * * //
+
+template<class Type>
+void Foam::CodedSource<Type>::writeData(Ostream& os) const
+{
+    os  << indent << name_ << endl;
+    dict_.write(os);
+}
+
+
+template<class Type>
+bool Foam::CodedSource<Type>::read(const dictionary& dict)
+{
+    if (basicSource::read(dict))
+    {
+        coeffs_.lookup("fieldNames") >> fieldNames_;
+        applied_.setSize(fieldNames_.size(), false);
+        coeffs_.lookup("redirectType") >> redirectType_;
+
+        // Code snippets
+        {
+            const entry& e = coeffs_.lookupEntry
+            (
+                "codeCorrect",
+                false,
+                false
+            );
+            codeCorrect_ = stringOps::trim(e.stream());
+            stringOps::inplaceExpand(codeCorrect_, coeffs_);
+            dynamicCodeContext::addLineDirective
+            (
+                codeCorrect_,
+                e.startLineNumber(),
+                coeffs_.name()
+            );
+        }
+
+        {
+            const entry& e = coeffs_.lookupEntry
+            (
+                "codeAddSup",
+                false,
+                false
+            );
+            codeAddSup_ = stringOps::trim(e.stream());
+            stringOps::inplaceExpand(codeAddSup_, coeffs_);
+            dynamicCodeContext::addLineDirective
+            (
+                codeAddSup_,
+                e.startLineNumber(),
+                coeffs_.name()
+            );
+        }
+
+        {
+            const entry& e = coeffs_.lookupEntry
+            (
+                "codeSetValue",
+                false,
+                false
+            );
+            codeSetValue_ = stringOps::trim(e.stream());
+            stringOps::inplaceExpand(codeSetValue_, coeffs_);
+            dynamicCodeContext::addLineDirective
+            (
+                codeSetValue_,
+                e.startLineNumber(),
+                coeffs_.name()
+            );
+        }
+
+        return true;
+    }
+    else
+    {
+        return false;
+    }
+}
+
+
+// ************************************************************************* //

src/fieldSources/basicSource/codedSource/codedSource.C

+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | Copyright (C) 2012 OpenFOAM Foundation
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+    for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+\*---------------------------------------------------------------------------*/
+
+#include "makeBasicSource.H"
+#include "CodedSource.H"
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+namespace Foam
+{
+    makeBasicSource(CodedSource, scalar);
+    makeBasicSource(CodedSource, vector);
+    makeBasicSource(CodedSource, sphericalTensor);
+    makeBasicSource(CodedSource, symmTensor);
+    makeBasicSource(CodedSource, tensor);
+}
+
+
+// ************************************************************************* //