objective.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) 2007-2023 PCOpt/NTUA
    Copyright (C) 2013-2023 FOSS GP
    Copyright (C) 2019-2020 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::objective

Description
    Abstract base class for objective functions. No point in making this
    runTime selectable since its children will have different constructors.

SourceFiles
    objective.C

\*---------------------------------------------------------------------------*/

#ifndef objective_H
#define objective_H

#include "localIOdictionary.H"
#include "autoPtr.H"
#include "runTimeSelectionTables.H"
#include "OFstream.H"
#include "boundaryFieldsFwd.H"
#include "solverControl.H"
#include "objectiveFwd.H"

// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

namespace Foam
{

/*---------------------------------------------------------------------------*\
                          Class objective Declaration
\*---------------------------------------------------------------------------*/

class objective
:
    public localIOdictionary
{
protected:

    // Protected data

        const fvMesh& mesh_;
        dictionary dict_;
        const word adjointSolverName_;
        const word primalSolverName_;
        const word objectiveName_;
        bool computeMeanFields_;
        bool nullified_;
        bool normalize_;
        bool shouldWrite_;

        //- Objective function value and weight
        scalar J_;

        //- Average objective value
        scalar JMean_;

        //- Objective weight
        scalar weight_;

        //- Whether the objective is computed or not
        //  Some objective (e.g. geometric ones) might not change from one
        //  iteration of the primal solver to the next and might be expensive
        //  to evaluate. This can be used to compute them only once per
        //  optimisation cycle
        bool computed_;

        //- Normalization factor
        autoPtr<scalar> normFactor_;

        //- Target value, in case the objective is used as a constraint
        //  Should be used with caution and with updateMethods
        //  than get affected by the target value, without
        //  requiring a sqr (e.g. SQP, MMA)
        autoPtr<scalar> target_;

        //- Target on the left hand-side of a double inequality,
        //- for double sided constraints
        autoPtr<scalar> targetLeft_;

        //- Objective integration start and end times (for unsteady flows)
        autoPtr<scalar> integrationStartTimePtr_;
        autoPtr<scalar> integrationEndTimePtr_;

        //- List of adjoint fields for which this objective will contribute
        //- sources to their equations.
        //  Only for volume-based objectives for the moment
        wordList fieldNames_;

        //- Contribution to field sensitivity derivatives
        //  Topology optimisation or other variants with
        //  as many design variables as the mesh cells
        //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        autoPtr<volScalarField> dJdbPtr_;

        //- Contribution to sensitivity derivatives with a
        //- random number of design variables
        //- (neither surface, nor volume based)
        //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        autoPtr<scalarField> dJdbFieldPtr_;

        // Contribution to surface sensitivity derivatives
        // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        //- Term from material derivative
        autoPtr<boundaryVectorField> bdJdbPtr_;

        //- Term multiplying delta(n dS)/delta b
        autoPtr<boundaryVectorField> bdSdbMultPtr_;

        //- Term multiplying delta(n)/delta b
        autoPtr<boundaryVectorField> bdndbMultPtr_;

        //- Term multiplying delta(x)/delta b at the boundary
        autoPtr<boundaryVectorField> bdxdbMultPtr_;

        //- Term multiplying delta(x)/delta b at the boundary
        //- for objectives that directly depend on x, e.g. moment
        //- Needed in both FI and SI computations
        autoPtr<boundaryVectorField> bdxdbDirectMultPtr_;

        //- Contribution located in specific parts of a patch.
        //- Mainly intended for patch boundary edges contributions, e.g.
        //- NURBS surfaces G1 continuity
        autoPtr<vectorField3> bEdgeContribution_;

        // Contribution to volume-based sensitivities from volume-based
        // objective functions
        // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        //- Multiplier of d(Volume)/db
        autoPtr<volScalarField> divDxDbMultPtr_;

        //- Emerging from volume objectives that include spatial derivatives
        autoPtr<volTensorField> gradDxDbMultPtr_;

        //- Output file variables
        fileName objFunctionFolder_;

        //- File to keep the objective values after the end of the primal solver
        mutable autoPtr<OFstream> objFunctionFilePtr_;

        //- File to keep the objective values at each iteration of the primal
        //- solver
        mutable autoPtr<OFstream> instantValueFilePtr_;

        //- File to keep the average objective values after the end of the
        //- primal solver
        mutable autoPtr<OFstream> meanValueFilePtr_;

        //- Default width of entries when writing in the objective files
        unsigned int width_;


    // Protected Member Functions

        //- Set the output file ptr
        void setObjectiveFilePtr() const;

        //- Set the output file ptr for the instantaneous value
        void setInstantValueFilePtr() const;

        //- Set the output file ptr for the mean value
        void setMeanValueFilePtr() const;


private:

    // Private Member Functions

        //- No copy construct
        objective(const objective&) = delete;

        //- No copy assignment
        void operator=(const objective&) = delete;

        //- Make objective Function Folder
        void makeFolder();


public:

    //- Runtime type information
    TypeName("objective");


    // Declare run-time constructor selection table

        declareRunTimeNewSelectionTable
        (
            autoPtr,
            objective,
            objective,
            (
                const fvMesh& mesh,
                const dictionary& dict,
                const word& adjointSolverName,
                const word& primalSolverName
            ),
            (mesh, dict, adjointSolverName, primalSolverName)
        );


    // Constructors

        //- Construct from components
        objective
        (
            const fvMesh& mesh,
            const dictionary& dict,
            const word& adjointSolverName,
            const word& primalSolverName
        );


    // Selectors

        //- Return a reference to the selected turbulence model
        static autoPtr<objective> New
        (
            const fvMesh& mesh,
            const dictionary& dict,
            const word& objectiveType,
            const word& adjointSolverName,
            const word& primalSolverName
        );


    //- Destructor
    virtual ~objective() = default;


    // Member Functions

        virtual bool readDict(const dictionary& dict);

        //- Return the instantaneous objective function value
        virtual scalar J() = 0;

        //- Return the objective function of the optimisation cycle.
        //  This corresponds to the mean value, if it exists, or the
        //  instantaneous value otherwise
        virtual scalar JCycle(bool negate = false) const;

        //- Accumulate contribution for the mean objective value
        //  For steady-state runs
        virtual void accumulateJMean(solverControl& solverControl);
        

        //- Accumulate contribution for the mean objective value
        //  For unsteady runs
        virtual void accumulateJMean();

        //- Return the objective function weight
        virtual scalar weight() const;

        //- Is the objective normalized
        virtual bool normalize() const;

        //- Normalize all fields allocated by the objective
        virtual void doNormalization();

        //- Check whether this is an objective integration time
        virtual bool isWithinIntegrationTime() const;

        //- Increment integration times
        virtual void incrementIntegrationTimes(const scalar timeSpan);

        //- Contribution to field sensitivities
        inline const volScalarField& dJdb() const;

        //- Contribution to sensitivities with a random number of designVars
        inline const scalarField& dJdbField() const;

        //- Contribution to surface sensitivities for a specific patch
        inline const fvPatchVectorField& boundarydJdb(const label) const;

        //- Multiplier of delta(n dS)/delta b
        inline const fvPatchVectorField& dSdbMultiplier(const label) const;

        //- Multiplier of delta(n dS)/delta b
        inline const fvPatchVectorField& dndbMultiplier(const label) const;

        //- Multiplier of delta(x)/delta b
        inline const fvPatchVectorField& dxdbMultiplier(const label) const;

        //- Multiplier of delta(x)/delta b
        inline const fvPatchVectorField& dxdbDirectMultiplier
        (
            const label
        ) const;

        //- Multiplier located at patch boundary edges
        inline const vectorField& boundaryEdgeMultiplier
        (
            const label patchI,
            const label edgeI
        ) const;

        //- Contribution to surface sensitivities for all patches
        inline const boundaryVectorField& boundarydJdb() const;

        //- Multiplier of delta(n dS)/delta b for all patches
        inline const boundaryVectorField& dSdbMultiplier() const;

        //- Multiplier of delta(n dS)/delta b for all patches
        inline const boundaryVectorField& dndbMultiplier() const;

        //- Multiplier of delta(x)/delta b for all patches
        inline const boundaryVectorField& dxdbMultiplier() const;

        //- Multiplier of delta(x)/delta b for all patches
        inline const boundaryVectorField& dxdbDirectMultiplier() const;

        //- Multiplier located at patch boundary edges
        inline const vectorField3& boundaryEdgeMultiplier() const;

        //- Multiplier of grad( delta(x)/delta b) for volume-based sensitivities
        inline const volScalarField& divDxDbMultiplier() const;

        //- Multiplier of grad( delta(x)/delta b) for volume-based sensitivities
        inline const volTensorField& gradDxDbMultiplier() const;

        //- Update objective function derivatives
        virtual void update() = 0;

        //- Nullify adjoint contributions
        virtual void nullify();

        //- Update normalization factors, for objectives in
        //- which the factor is not known a priori
        virtual void updateNormalizationFactor();


        virtual void update_dJdb()
        {}

        virtual void update_dJdbField()
        {}

        //- Update objective function derivative term
        virtual void update_boundarydJdb()
        {}

        //- Update d (normal dS) / db multiplier. Surface-based sensitivity term
        virtual void update_dSdbMultiplier()
        {}

        //- Update d (normal) / db multiplier. Surface-based sensitivity term
        virtual void update_dndbMultiplier()
        {}

        //- Update d (x) / db multiplier. Surface-based sensitivity term
        virtual void update_dxdbMultiplier()
        {}

        //- Update d (x) / db multiplier. Surface and volume-based sensitivity
        //- term
        virtual void update_dxdbDirectMultiplier()
        {}

        //- Update boundary edge contributions
        virtual void update_boundaryEdgeContribution()
        {}

        //- Update div( dx/db multiplier). Volume-based sensitivity term
        virtual void update_divDxDbMultiplier()
        {}

        //- Update grad( dx/db multiplier). Volume-based sensitivity term
        virtual void update_gradDxDbMultiplier()
        {}


        //- Manipulate fvVectorMatrix through the objective
        virtual void addSource(fvVectorMatrix& matrix)
        {}

        //- Manipulate fvVectorMatrix through the objective
        virtual void addSource(fvScalarMatrix& matrix)
        {}

        //- Write objective function history
        virtual bool write(const bool valid = true) const;

        //- Write objective function history at each primal solver iteration
        virtual void writeInstantaneousValue() const;

        //- Append a blank line after the end of optimisation cycle to the
        //- file holding the instantaneous objective values to facilitate
        //- plotting
        virtual void writeInstantaneousSeparator() const;

        //- Write mean objective function history
        virtual void writeMeanValue() const;

        //- Write averaged objective for continuation
        virtual bool writeData(Ostream& os) const;

        // Helper write functions

            //- Write any information that needs to go the header of the file
            //  (e.g. targets, directions, etc)
            virtual void addHeaderInfo() const;

            //- Write headers for additional columns
            virtual void addHeaderColumns() const;

            //- Write information to additional columns
            virtual void addColumnValues() const;

        //- Return the objective name
        inline const word& objectiveName() const;

        //- Should the objective be written to file upon calling write()?
        inline bool shouldWrite() const;

        //- Should the objective be written to file upon calling write()?
        inline void setWrite(const bool shouldWrite);

        // Inline functions for checking whether pointers are set or not
        inline bool hasdJdb() const noexcept;
        inline bool hasdJdbField() const noexcept;
        inline bool hasBoundarydJdb() const noexcept;
        inline bool hasdSdbMult() const noexcept;
        inline bool hasdndbMult() const noexcept;
        inline bool hasdxdbMult() const noexcept;
        inline bool hasdxdbDirectMult() const noexcept;
        inline bool hasBoundaryEdgeContribution() const noexcept;
        inline bool hasDivDxDbMult() const noexcept;
        inline bool hasGradDxDbMult() const noexcept;

        // Inline functions for checking whether integration times are set
        inline bool hasIntegrationStartTime() const noexcept;
        inline bool hasIntegrationEndTime() const noexcept;

        //- Set the computed status of the objective
        inline void setComputed(const bool isComputed) noexcept;

        //- Return objective dictionary
        const dictionary& dict() const;
};


// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

} // End namespace Foam

// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

#include "objectiveI.H"

// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

#endif

// ************************************************************************* //