exprDriver.H

Go to the documentation of this file.

/*---------------------------------------------------------------------------*\
  =========                 |
  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
   \\    /   O peration     |
    \\  /    A nd           | www.openfoam.com
     \\/     M anipulation  |
-------------------------------------------------------------------------------
    Copyright (C) 2010-2018 Bernhard Gschaider
    Copyright (C) 2019-2022 OpenCFD Ltd.
-------------------------------------------------------------------------------
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::expressions::exprDriver
 
Description
    Base driver for parsing (field) values.
 
    Largely based on code and ideas from swak4foam
 
    Properties
    \table
        Property     | Description                          | Required | Default
        variables    | List of variables for expressions    | no  | ()
        functions<scalar> | Dictionary of scalar Function1   | no  | {}
        functions<vector> | Dictionary of vector Function1   | no  | {}
        allowShadowing | Allow variables to shadow field names | no  | false
    \endtable
 
    Debug Properties
    \table
        Property      | Description                         | Required | Default
        debug.driver  | Debug level (int) for base driver   | no  |
        debug.scanner | Add debug for scanner               | no  | false
        debug.parser  | Add debug for parser                | no  | false
    \endtable
 
    The \c functions<scalar> and \c functions<vector> entries are
    dictionaries of Foam::Function1 definitions that can either be used
    to establish a time-varying quantity, to remap a field of scalar
    values, or both.
 
SourceFiles
    exprDriverI.H
    exprDriverContextI.H
    exprDriver.C
    exprDriverFields.C
    exprDriverFunctions.C
    exprDriverIO.C
    exprDriverTemplates.C
 
\*---------------------------------------------------------------------------*/
 
#ifndef Foam_expressions_exprDriver_H
#define Foam_expressions_exprDriver_H
 
#include "exprResult.H"
#include "exprString.H"
#include "exprTraits.H"
#include "pointField.H"
#include "primitiveFields.H"
#include "objectRegistry.H"
#include "HashTable.H"
#include "HashSet.H"
#include "Function1.H"
 
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
namespace Foam
{
 
// Forward Declarations
class TimeState;
 
namespace expressions
{
 
/*---------------------------------------------------------------------------*\
                         Class exprDriver Declaration
\*---------------------------------------------------------------------------*/
 
class exprDriver
{
public:
 
    // Data Types
 
        //- Search/caching controls
        enum searchControls
        {
            NO_SEARCH = 0,
            SEARCH_REGISTRY = 1,   
            SEARCH_FILES = 2,      
            CACHE_READ_FIELDS = 4, 
            DEFAULT_SEARCH = (SEARCH_REGISTRY)
        };
 
 
    //- Externally defined context fields
    typedef HashTable<const regIOobject*> contextObjectTableType;
 
 
private:
 
    // Private Member Functions
 
        //- Get search/caching controls from dictionary entries
        static int getSearchControls(const dictionary& dict);
 
        //- Read/reset Function1 entries
        void resetFunctions(const dictionary& dict);
 
        //- Helper for lookup of Function1 in table
        template<class Type>
        static const Function1<Type>* getFunction1Ptr
        (
            const word& name,
            const HashTable<refPtr<Function1<Type>>>& tbl,
            wordList* listFailure = nullptr
        );
 
 
protected:
 
    // Protected Data
 
    // Stored Data
 
        //- The dictionary with all input data/specification
        const dictionary& dict_;
 
        //- The result
        exprResult result_;
 
        //- Variable definitions, as read from a dictionary
        List<expressions::exprString> variableStrings_;
 
        //- The variables table
        HashTable<exprResult> variables_;
 
        //- Function1 mappings/timelines (scalar),
        //- evaluated at the simulation time or with arbitrary scalars
        HashTable<refPtr<Function1<scalar>>> scalarFuncs_;
 
        //- Function1 mappings/timelines (vector),
        //- evaluated at the simulation time or with arbitrary scalars
        HashTable<refPtr<Function1<vector>>> vectorFuncs_;
 
        //- Externally defined context fields
        contextObjectTableType contextObjects_;
 
        //- Special-purpose scalar reference argument
        scalar arg1Value_;
 
        //- Reference to the time-state
        mutable const TimeState* timeStatePtr_;
 
        //- Pointer to an object registry (for functions etc).
        const objectRegistry* obrPtr_;
 
 
    // Controls, tracing etc.
 
        //- Internal bookkeeping as "look-behind" parsing context
        mutable int stashedTokenId_;
 
        //- Request debugging for scanner
        bool debugScanner_;
 
        //- Request debugging for parser
        bool debugParser_;
 
        //- Allow variable names to mask field names
        bool allowShadowing_;
 
        //- Use value of previous iteration when oldTime is requested
        bool prevIterIsOldTime_;
 
        //- Registry/disk/caching control
        searchControls searchCtrl_;
 
 
    // Protected Member Functions
 
        inline bool searchRegistry() const noexcept;
        inline bool searchFiles() const noexcept;
        inline bool cacheReadFields() const noexcept;
 
        //- Reset the time-state reference
        void resetTimeReference(const TimeState* ts);
 
        //- Reset the time-state reference
        void resetTimeReference(const TimeState& ts);
 
        //- Write scalar/vector Function1 entries in dictionary format
        void writeFunctions(Ostream& os) const;
 
 
    // Variables
 
        //- Non-const access to the named variable (sub-classes only)
        inline virtual exprResult& variable(const word& name);
 
 
    // Fields
 
        //- Fill a random field
        //
        //  \param field the field to populate
        //  \param seed the seed value. If zero or negative, use as an offset
        //      to the current timeIndex (if a time-state is available)
        //  \param gaussian generate a Gaussian distribution
        void fill_random
        (
            scalarField& field,
            label seed = 0,
            const bool gaussian = false
        ) const;
 
        //- The (global) weighted average of a field, with stabilisation
        template<class Type>
        static Type weightedAverage
        (
            const scalarField& weights,
            const Field<Type>& fld
        );
 
        //- The (global) weighted sum (integral) of a field
        template<class Type>
        static Type weightedSum
        (
            const scalarField& weights,
            const Field<Type>& fld
        );
 
        //- Return the location of the min value
        static point getPositionOfMinimum
        (
            const scalarField& vals,
            const pointField& locs
        );
 
        //- Return the location of the max value
        static point getPositionOfMaximum
        (
            const scalarField& vals,
            const pointField& locs
        );
 
 
    // Updating
 
        //- Update things
        virtual bool update();
 
        //- Examine current variable values and update stored variables
        virtual void updateSpecialVariables(bool force=false);
 
 
    // Results
 
        //- Get the result from another driver.
        //  Override to allow mapping
        virtual exprResult getRemoteResult(const exprDriver& other) const;
 
 
public:
 
    //- Runtime type information
    TypeName("exprDriver");
 
 
    // Generated Methods
 
        //- No copy construct
        exprDriver(const exprDriver&) = delete;
 
        //- No copy assignment
        void operator=(const exprDriver&) = delete;
 
 
    // Constructors
 
        //- Default construct, and default construct with search preferences
        explicit exprDriver
        (
            enum searchControls search = searchControls::DEFAULT_SEARCH,
            const dictionary& dict = dictionary::null
        );
 
        //- Copy construct with new dictionary reference
        exprDriver(const exprDriver& rhs, const dictionary& dict);
 
        //- Construct from a dictionary
        explicit exprDriver(const dictionary& dict);
 
 
    //- Destructor
    virtual ~exprDriver() = default;
 
 
    // Public Member Functions
 
        //- The natural field size for the expression
        virtual label size() const
        {
            return 1;
        }
 
        //- The point field size for the expression
        virtual label pointSize() const
        {
            return 1;
        }
 
        //- Reference to the current time-state (can be nullptr)
        const TimeState* timeState() const noexcept;
 
        //- The current time value
        virtual scalar timeValue() const;
 
        //- The current deltaT value
        virtual scalar deltaT() const;
 
 
        //- The dictionary with all input data/specification
        const dictionary& dict() const noexcept
        {
            return dict_;
        }
 
        //- Const access to expression result
        const exprResult& result() const noexcept
        {
            return result_;
        }
 
        //- Non-const access to expression result
        exprResult& result() noexcept
        {
            return result_;
        }
 
        //- Clear the result
        void clearResult();
 
        //- Return the expression result as a tmp field
        //  This also clears the result and associated memory.
        template<class Type>
        tmp<Field<Type>> getResult(bool wantPointData=false);
 
        //- The result type as word - same as result().valueType()
        const word& getResultType() const noexcept
        {
            return result_.valueType();
        }
 
 
    // External References
 
        //- Reset the objectRegistry (for functions)
        void resetDb(const objectRegistry* obrPtr = nullptr);
 
        //- Reset the objectRegistry (for functions)
        void resetDb(const objectRegistry& db);
 
 
    // Specials
 
        //- Get special-purpose scalar reference argument.
        //  Typically available as \c arg() in an expression and
        //  may correspond to table index, time value etc.
        inline scalar argValue() const noexcept;
 
 
    // General Controls
 
        //- Get "look-behind" parsing context (internal bookkeeping)
        inline int stashedTokenId() const noexcept;
 
        //- Reset "look-behind" parsing context (mutable operation)
        //  \return the previous value
        inline int resetStashedTokenId(int tokenId=0) const noexcept;
 
 
        //- Set the scanner/parser debug
        void setDebugging(bool scannerDebug, bool parserDebug);
 
        //- Set the scanner/parser debug to match the input
        void setDebugging(const exprDriver& rhs);
 
        //- Toggle CACHE_READ_FIELDS control
        bool setCaching(bool on) noexcept;
 
        //- Set search behaviour,
        //- with additional CACHE_READ_FIELDS toggle on
        void setSearchBehaviour
        (
            enum searchControls search,
            const bool caching = false
        );
 
        //- Set search behaviour to be identical to rhs
        void setSearchBehaviour(const exprDriver& rhs);
 
        //- Read access to scanner debug
        inline bool debugScanner() const noexcept;
 
        //- Read access to parser debug
        inline bool debugParser() const noexcept;
 
        bool prevIterIsOldTime() const { return prevIterIsOldTime_; }
 
 
    // Variables
 
        //- Clear temporary variables, reset from expression strings
        virtual void clearVariables();
 
        //- Set special-purpose scalar reference argument.
        //  Typically available as \c arg() in an expression and
        //  may corrspond to table index, time value etc.
        inline void setArgument(const scalar val) noexcept;
 
        //- True if named variable exists
        inline virtual bool hasVariable(const word& name) const;
 
        //- Return const-access to the named variable
        inline virtual const exprResult& variable(const word& name) const;
 
        //- Add/set string expressions for variables
        //  Can include multiple definitions inline
        void addVariables
        (
            const expressions::exprString& expr,
            bool clear = true  
        );
 
        //- Add/set string expressions for variables
        //  Can include multiple definitions inline
        void addVariables
        (
            const UList<expressions::exprString>& list,
            bool clear = true  
        );
 
        //- Add a uniform variable from an outside caller
        template<class T>
        inline void addUniformVariable
        (
            const word& name,
            const T& val
        );
 
 
    // Context fields (similar to objectRegistry)
 
        //- True if any context fields are defined
        inline bool hasContextObjects() const;
 
        //- Find named context field, if it exists
        inline const regIOobject* cfindContextIOobject(const word& name) const;
 
        //- Find context field object of specified type
        //  \return nullptr if not found
        template<class ObjType>
        const ObjType* cfindContextObject(const word& name) const;
 
        //- Add the object to the context
        inline void addContextObject(const word& name, const regIOobject*);
 
        //- Add the object to the context
        inline void addContextObject(const regIOobject*);
 
        //- Remove the object from the context
        inline void removeContextObject(const word& name);
 
        //- Remove the object from the context
        inline void removeContextObject(const regIOobject*);
 
        //- Read access to the object context
        inline const contextObjectTableType& contextObjects() const noexcept;
 
        //- Write access to the object context
        inline contextObjectTableType& contextObjects() noexcept;
 
 
    // Scalar mappings (timelines / lookups)
 
        //- Named mapping with given type exists
        template<class Type>
        bool isFunction(const word& name) const;
 
        //- Evaluate named mapping for the given time/value.
        //- Zero for undefined/unknown
        template<class Type>
        Type getFunctionValue(const word& name, const scalar x) const;
 
        //- Fill result with values remapped according to the named Function1
        template<class Type>
        void fillFunctionValues
        (
            Field<Type>& result,
            const word& name,
            const scalarField& input
        ) const;
 
 
    // Fields
 
        //- Test existence of a local variable
        template<class T>
        bool isLocalVariable
        (
            const word& name,
            bool wantPointData = false,
            label expectedSize = -1
        ) const;
 
        //- Retrieve local/global variable as a tmp field
        //
        //  \param name The name of the local/global field
        //  \param expectSize  The size check on the variable, -1 to ignore
        //  \param mandatory A missing variable is Fatal, or return
        //      an invalid tmp
        template<class Type>
        tmp<Field<Type>> getLocalVariable
        (
            const word& name,
            label expectSize,
            const bool mandatory = true
        ) const;
 
 
    // Evaluation
 
        //- Execute the parser.
        //  The return value currently has no meaning.
        virtual unsigned parse
        (
            const std::string& expr,
            size_t pos = 0,
            size_t len = std::string::npos
        ) = 0;
 
        //- Evaluate the expression and return the field.
        //  This also clears the result and associated memory.
        template<class Type>
        inline tmp<Field<Type>>
        evaluate
        (
            const expressions::exprString& expr,
            bool wantPointData = false
        );
 
        //- Evaluate the expression and return a single value.
        //  Does not clear the result.
        template<class Type>
        inline Type evaluateUniform
        (
            const expressions::exprString& expr,
            bool wantPointData = false
        );
 
 
        //- Evaluate the expression
        //- and save as the specified named variable
        void evaluateVariable
        (
            const word& varName,
            const expressions::exprString& expr
        );
 
        //- Evaluate an expression on a remote
        //- and save as the specified named variable
        virtual void evaluateVariableRemote
        (
            string remote,
            const word& varName,
            const expressions::exprString& expr
        );
 
 
    // Fields
 
        //- Return a new field with the size()
        template<class Type>
        tmp<Field<Type>>
        newField(const Type& val = pTraits<Type>::zero) const;
 
        //- Return a new field with the pointSize()
        template<class Type>
        tmp<Field<Type>>
        newPointField(const Type& val = pTraits<Type>::zero) const;
 
 
    // Reading
 
        //- Read an expression string and do substitutions
        static expressions::exprString readExpression
        (
            const word& name,
            const dictionary& dict
        );
 
        //- Read the list of variable strings
        //  (or initialize with a single string)
        static List<expressions::exprString> readVariableStrings
        (
            const dictionary& dict,
            const word& name = "variables",
            bool mandatory = false
        );
 
        //- Read an expression string (with the current dictionary)
        //- and do substitutions
        expressions::exprString readExpression(const word& name);
 
 
        //- Read variables, tables etc.
        //  Also usable for objects not constructed from a dictionary.
        virtual bool readDict(const dictionary& dict);
 
        //- Read "variables" and assigns to the list of expression strings
        //  \return the number variable strings read.
        label setVariableStrings
        (
            const dictionary& dict,
            bool mandatory = false
        );
 
 
    // Writing
 
        //- Write "variables"
        Ostream& writeVariableStrings
        (
            Ostream& os,
            const word& keyword = ""
        ) const;
};
 
 
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
} // End namespace expressions
} // End namespace Foam
 
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
#include "exprDriverI.H"
#include "exprDriverContextI.H"
 
#ifdef NoRepository
    #include "exprDriverTemplates.C"
#endif
 
// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
#endif
 
// ************************************************************************* //