Line data Source code
1 : // EnergyPlus, Copyright (c) 1996-2025, The Board of Trustees of the University of Illinois,
2 : // The Regents of the University of California, through Lawrence Berkeley National Laboratory
3 : // (subject to receipt of any required approvals from the U.S. Dept. of Energy), Oak Ridge
4 : // National Laboratory, managed by UT-Battelle, Alliance for Sustainable Energy, LLC, and other
5 : // contributors. All rights reserved.
6 : //
7 : // NOTICE: This Software was developed under funding from the U.S. Department of Energy and the
8 : // U.S. Government consequently retains certain rights. As such, the U.S. Government has been
9 : // granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable,
10 : // worldwide license in the Software to reproduce, distribute copies to the public, prepare
11 : // derivative works, and perform publicly and display publicly, and to permit others to do so.
12 : //
13 : // Redistribution and use in source and binary forms, with or without modification, are permitted
14 : // provided that the following conditions are met:
15 : //
16 : // (1) Redistributions of source code must retain the above copyright notice, this list of
17 : // conditions and the following disclaimer.
18 : //
19 : // (2) Redistributions in binary form must reproduce the above copyright notice, this list of
20 : // conditions and the following disclaimer in the documentation and/or other materials
21 : // provided with the distribution.
22 : //
23 : // (3) Neither the name of the University of California, Lawrence Berkeley National Laboratory,
24 : // the University of Illinois, U.S. Dept. of Energy nor the names of its contributors may be
25 : // used to endorse or promote products derived from this software without specific prior
26 : // written permission.
27 : //
28 : // (4) Use of EnergyPlus(TM) Name. If Licensee (i) distributes the software in stand-alone form
29 : // without changes from the version obtained under this License, or (ii) Licensee makes a
30 : // reference solely to the software portion of its product, Licensee must refer to the
31 : // software as "EnergyPlus version X" software, where "X" is the version number Licensee
32 : // obtained under this License and may not use a different name for the software. Except as
33 : // specifically required in this Section (4), Licensee shall not use in a company name, a
34 : // product name, in advertising, publicity, or other promotional activities any name, trade
35 : // name, trademark, logo, or other designation of "EnergyPlus", "E+", "e+" or confusingly
36 : // similar designation, without the U.S. Department of Energy's prior written consent.
37 : //
38 : // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
39 : // IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
40 : // AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
41 : // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
42 : // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
43 : // SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
44 : // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
45 : // OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
46 : // POSSIBILITY OF SUCH DAMAGE.
47 :
48 : #ifndef DataRootFinder_hh_INCLUDED
49 : #define DataRootFinder_hh_INCLUDED
50 :
51 : // ObjexxFCL Headers
52 : #include <ObjexxFCL/Array1D.hh>
53 :
54 : // EnergyPlus Headers
55 : #include <EnergyPlus/EnergyPlus.hh>
56 :
57 : namespace EnergyPlus::DataRootFinder {
58 :
59 : enum class Slope
60 : {
61 : Invalid = -1, // Undefined slope specification
62 : Increasing, // For overall increasing function F(X) between min and max points
63 : Decreasing, // For overall decreasing function F(X) between min and max points
64 : Num
65 : };
66 :
67 : enum class RootFinderStatus
68 : {
69 : Invalid = -1,
70 : ErrorSingular, // Error because the overall slope appears to be flat between the min and max points, implying that the
71 : // function might be singular over the interval: F(XMin) == F(XMax)
72 :
73 : ErrorSlope, // Error because the overall slope assumption is not observed at the min and max points:
74 : // - for an increasing function F(X), we expect F(XMin) < F(XMax) otherwise error
75 : // - for a decreasing function F(X), we expect F(XMin) > F(XMax) otherwise error
76 : // Note that this error status does not detect strict monotonicity at points
77 : // between the min and max points.
78 :
79 : ErrorBracket, // Error because the current candidate X does not lie within the current lower an upper points:
80 : // X < XLower or X > XUpper
81 :
82 : ErrorRange, // Error because the current candidate X does not lie within the min and max points:
83 : // X < XMin or X > XMax
84 :
85 : None, // Indeterminate error state (not converged), also default state
86 : OK, // Unconstrained convergence achieved with root solution so that: XMin < XRoot < XMax
87 : OKMin, // Constrained convergence achieved with solution XRoot==XMin
88 : OKMax, // Constrained convergence achieved with solution XRoot==XMax
89 : OKRoundOff, // Reached requested tolerance in X variables although Y=F(X) does not satisfy unconstrained convergence check
90 : WarningNonMonotonic, // Error because F(X) is not strictly monotonic between the lower and upper points
91 : WarningSingular, // Error because F(X) == YLower or F(X) == YUpper
92 : Num
93 : };
94 :
95 : enum class RootFinderMethod
96 : {
97 : Invalid = -1,
98 : None, // No solution method (used internally only when root finder is reset)
99 : Bracket, // Bracketing mode (used internally only to bracket root)
100 : Bisection, // Step performed using bisection method (aka interval halving)
101 : FalsePosition, // Step performed using false position method (aka regula falsi)
102 : Secant, // Step performed using secant method
103 : Brent, // Step performed using Brent's method
104 : Num
105 : };
106 :
107 : struct ControlsType
108 : {
109 : // Members
110 : DataRootFinder::Slope SlopeType; // Set to any of the iSlope<...> codes
111 : RootFinderMethod MethodType; // Desired solution method.
112 : // Set to any of the iMethod<...> codes except for iMethodNone and iMethodBracket
113 : Real64 TolX; // Relative tolerance for variable X
114 : Real64 ATolX; // Absolute tolerance for variable X
115 : Real64 ATolY; // Absolute tolerance for variable Y
116 :
117 : // Default Constructor
118 29 : ControlsType() : SlopeType(DataRootFinder::Slope::Invalid), MethodType(RootFinderMethod::None), TolX(1.0e-3), ATolX(1.0e-3), ATolY(1.0e-3)
119 : {
120 29 : }
121 : };
122 :
123 : struct PointType
124 : {
125 : // Members
126 : bool DefinedFlag; // Set to true if point has been set; false otherwise
127 : Real64 X; // X value
128 : Real64 Y; // Y value = F(X)
129 :
130 : // Default Constructor
131 261 : PointType() : DefinedFlag(false), X(0.0), Y(0.0)
132 : {
133 261 : }
134 : };
135 :
136 : struct RootFinderDataType
137 : {
138 : // Members
139 : ControlsType Controls;
140 : RootFinderStatus StatusFlag; // Current status of root finder
141 : // Valid values are any of the STATUS_<code> constants
142 : RootFinderMethod CurrentMethodType; // Solution method used to perform current step
143 : Real64 XCandidate; // Candidate X value to use next when evaluating F(X)
144 : Real64 ConvergenceRate; // Convergence rate achieved over the last 2 successive iterations
145 : PointType Increment; // Increment between last 2 iterations
146 : PointType MinPoint; // Point { XMin, F(XMin) }
147 : PointType MaxPoint; // Point { XMax, F(XMax) }
148 : PointType LowerPoint; // Point { XLower, F(XLower) } so that XLower <= XRoot
149 : PointType UpperPoint; // Point { XUpper, F(XUpper) } so that XRoot <= YUpper
150 : PointType CurrentPoint; // Last evaluated point { X, F(X) }
151 : int NumHistory; // Number of points stored in History
152 : Array1D<PointType> History; // Vector containing last 3 best iterates
153 :
154 : // Default Constructor
155 29 : RootFinderDataType()
156 87 : : StatusFlag(RootFinderStatus::None), CurrentMethodType(RootFinderMethod::None), XCandidate(0.0), ConvergenceRate(0.0), NumHistory(0),
157 29 : History(3)
158 : {
159 29 : }
160 : };
161 :
162 : } // namespace EnergyPlus::DataRootFinder
163 :
164 : #endif
|
