LSST Applications  21.0.0-172-gfb10e10a+18fedfabac,22.0.0+297cba6710,22.0.0+80564b0ff1,22.0.0+8d77f4f51a,22.0.0+a28f4c53b1,22.0.0+dcf3732eb2,22.0.1-1-g7d6de66+2a20fdde0d,22.0.1-1-g8e32f31+297cba6710,22.0.1-1-geca5380+7fa3b7d9b6,22.0.1-12-g44dc1dc+2a20fdde0d,22.0.1-15-g6a90155+515f58c32b,22.0.1-16-g9282f48+790f5f2caa,22.0.1-2-g92698f7+dcf3732eb2,22.0.1-2-ga9b0f51+7fa3b7d9b6,22.0.1-2-gd1925c9+bf4f0e694f,22.0.1-24-g1ad7a390+a9625a72a8,22.0.1-25-g5bf6245+3ad8ecd50b,22.0.1-25-gb120d7b+8b5510f75f,22.0.1-27-g97737f7+2a20fdde0d,22.0.1-32-gf62ce7b1+aa4237961e,22.0.1-4-g0b3f228+2a20fdde0d,22.0.1-4-g243d05b+871c1b8305,22.0.1-4-g3a563be+32dcf1063f,22.0.1-4-g44f2e3d+9e4ab0f4fa,22.0.1-42-gca6935d93+ba5e5ca3eb,22.0.1-5-g15c806e+85460ae5f3,22.0.1-5-g58711c4+611d128589,22.0.1-5-g75bb458+99c117b92f,22.0.1-6-g1c63a23+7fa3b7d9b6,22.0.1-6-g50866e6+84ff5a128b,22.0.1-6-g8d3140d+720564cf76,22.0.1-6-gd805d02+cc5644f571,22.0.1-8-ge5750ce+85460ae5f3,master-g6e05de7fdc+babf819c66,master-g99da0e417a+8d77f4f51a,w.2021.48
LSST Data Management Base Package
Function.h
Go to the documentation of this file.
1 // -*- LSST-C++ -*-
2 
3 /*
4  * LSST Data Management System
5  * Copyright 2008, 2009, 2010 LSST Corporation.
6  *
7  * This product includes software developed by the
8  * LSST Project (http://www.lsst.org/).
9  *
10  * This program is free software: you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License as published by
12  * the Free Software Foundation, either version 3 of the License, or
13  * (at your option) any later version.
14  *
15  * This program is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18  * GNU General Public License for more details.
19  *
20  * You should have received a copy of the LSST License Statement and
21  * the GNU General Public License along with this program. If not,
22  * see <http://www.lsstcorp.org/LegalNotices/>.
23  */
24 
25 #ifndef LSST_AFW_MATH_FUNCTION_H
26 #define LSST_AFW_MATH_FUNCTION_H
27 /*
28  * Define the basic Function classes.
29  */
30 #include <cmath>
31 #include <stdexcept>
32 #include <sstream>
33 #include <vector>
34 
35 #include "boost/format.hpp"
36 
37 #include "lsst/pex/exceptions.h"
38 
40 
41 namespace lsst {
42 namespace afw {
43 namespace math {
44 
50 template <typename T>
51 bool constexpr IS_NOTHROW_INIT = noexcept(static_cast<T>(1.0));
52 
82 template <typename ReturnT>
83 class Function : public afw::table::io::PersistableFacade<Function<ReturnT>>,
85 public:
91  explicit Function(unsigned int nParams)
92  : _params(nParams), _isCacheValid(false) {}
93 
97  explicit Function(std::vector<double> const& params)
98  : _params(params), _isCacheValid(false) {}
99 
100  Function(Function const&) = default;
101  Function(Function&&) = default;
102  Function& operator=(Function const&) = default;
103  Function& operator=(Function&&) = default;
104 
105  ~Function() noexcept override = default;
106 
112  unsigned int getNParameters() const noexcept { return _params.size(); }
113 
119  virtual double getParameter(unsigned int ind)
120  const {
121  return _params[ind];
122  }
123 
129  std::vector<double> const& getParameters() const noexcept { return _params; }
130 
138  virtual bool isLinearCombination() const noexcept { return false; }
139 
143  void setParameter(unsigned int ind,
144  double newValue)
145  {
146  _isCacheValid = false;
147  _params[ind] = newValue;
148  }
149 
156  void setParameters(std::vector<double> const& params)
157  {
158  if (_params.size() != params.size()) {
159  throw LSST_EXCEPT(
161  (boost::format("params has %d entries instead of %d") % params.size() % _params.size())
162  .str());
163  }
164  _isCacheValid = false;
165  _params = params;
166  }
167 
173  virtual std::string toString(std::string const&) const {
175  os << "parameters: [ ";
176  for (std::vector<double>::const_iterator i = _params.begin(); i != _params.end(); ++i) {
177  if (i != _params.begin()) os << ", ";
178  os << *i;
179  }
180  os << " ]";
181  return os.str();
182  }
183 
184 protected:
186  mutable bool _isCacheValid;
187 
188  std::string getPythonModule() const override { return "lsst.afw.math"; }
189 
190  /* Default constructor: intended only for serialization */
191  explicit Function() : _params(0), _isCacheValid(false) {}
192 };
193 
201 template <typename ReturnT>
202 class Function1 : public afw::table::io::PersistableFacade<Function1<ReturnT>>, public Function<ReturnT> {
203 public:
209  explicit Function1(unsigned int nParams)
210  : Function<ReturnT>(nParams) {}
211 
215  explicit Function1(std::vector<double> const& params)
216  : Function<ReturnT>(params) {}
217 
218  Function1(Function1 const&) = default;
219  Function1(Function1&&) = default;
220  Function1& operator=(Function1 const&) = default;
222 
223  ~Function1() noexcept override = default;
224 
236  virtual std::shared_ptr<Function1<ReturnT>> clone() const = 0;
237 
238  virtual ReturnT operator()(double x) const = 0;
239 
240  std::string toString(std::string const& prefix = "") const override {
241  return std::string("Function1: ") + Function<ReturnT>::toString(prefix);
242  }
243 
244  virtual void computeCache(int const n) {}
245 
246 protected:
247  /* Default constructor: intended only for serialization */
248  explicit Function1() : Function<ReturnT>() {}
249 };
250 
258 template <typename ReturnT>
259 class Function2 : public afw::table::io::PersistableFacade<Function2<ReturnT>>, public Function<ReturnT> {
260 public:
266  explicit Function2(unsigned int nParams)
267  : Function<ReturnT>(nParams) {}
268 
274  explicit Function2(std::vector<double> const& params)
275  : Function<ReturnT>(params) {}
276 
277  Function2(Function2 const&) = default;
278  Function2(Function2&&) = default;
279  Function2& operator=(Function2 const&) = default;
281 
282  ~Function2() noexcept override = default;
283 
295  virtual std::shared_ptr<Function2<ReturnT>> clone() const = 0;
296 
297  virtual ReturnT operator()(double x, double y) const = 0;
298 
299  std::string toString(std::string const& prefix = "") const override {
300  return std::string("Function2: ") + Function<ReturnT>::toString(prefix);
301  }
305  virtual std::vector<double> getDFuncDParameters(double, double) const {
307  "getDFuncDParameters is not implemented for this class");
308  }
309 
310 protected:
311  /* Default constructor: intended only for serialization */
312  explicit Function2() : Function<ReturnT>() {}
313 };
314 
325 template <typename ReturnT>
326 class BasePolynomialFunction2 : public Function2<ReturnT> {
327 public:
335  explicit BasePolynomialFunction2(unsigned int order)
337 
347  : Function2<ReturnT>(params),
348  _order(BasePolynomialFunction2::orderFromNParameters(static_cast<int>(params.size()))) {}
349 
354 
355  ~BasePolynomialFunction2() noexcept override = default;
356 
360  int getOrder() const noexcept { return _order; }
361 
362  bool isLinearCombination() const noexcept override { return true; }
363 
369  static int nParametersFromOrder(int order) {
370  if (order < 0) {
372  os << "order=" << order << " invalid: must be >= 0";
374  }
375  return (order + 1) * (order + 2) / 2;
376  }
377 
392  static int orderFromNParameters(int nParameters) {
393  int order = static_cast<int>(
394  0.5 + ((-3.0 + (std::sqrt(1.0 + (8.0 * static_cast<double>(nParameters))))) / 2.0));
397  os << "nParameters=" << nParameters << " invalid: order is not an integer";
399  }
400  return order;
401  }
402 
411  std::vector<double> getDFuncDParameters(double x, double y) const override {
412  unsigned int const numParams = this->getNParameters(); // Number of parameters
413  std::vector<double> deriv(numParams); // Derivatives, to return
414 
416  this->clone(); // Dummy function to evaluate for derivatives
417  for (unsigned int i = 0; i < numParams; ++i) {
418  dummy->setParameter(i, 0.0);
419  }
420 
421  for (unsigned int i = 0; i < numParams; ++i) {
422  dummy->setParameter(i, 1.0);
423  deriv[i] = (*dummy)(x, y);
424  dummy->setParameter(i, 0.0);
425  }
426 
427  return deriv;
428  }
429 
430 protected:
431  int _order;
432 
433  /* Default constructor: intended only for serialization */
434  explicit BasePolynomialFunction2() : Function2<ReturnT>(1), _order(0) {}
435 };
436 
440 template <typename ReturnT>
441 class NullFunction1 : public Function1<ReturnT> {
442 public:
443  explicit NullFunction1() : Function1<ReturnT>(0) {}
446  }
447 
448 private:
449  ReturnT operator()(double) const noexcept(IS_NOTHROW_INIT<ReturnT>) override {
450  return static_cast<ReturnT>(0);
451  }
452 };
453 
457 template <typename ReturnT>
458 class NullFunction2 : public Function2<ReturnT> {
459 public:
460  explicit NullFunction2() : Function2<ReturnT>(0) {}
463  }
464 
465 private:
466  ReturnT operator()(double, double) const noexcept(IS_NOTHROW_INIT<ReturnT>) override {
467  return static_cast<ReturnT>(0);
468  }
469 };
470 } // namespace math
471 } // namespace afw
472 } // namespace lsst
473 
474 #endif // #ifndef LSST_AFW_MATH_FUNCTION_H
double x
#define LSST_EXCEPT(type,...)
Create an exception with a given type.
Definition: Exception.h:48
std::ostream * os
Definition: Schema.cc:557
std::string prefix
Definition: SchemaMapper.cc:72
int y
Definition: SpanSet.cc:48
T begin(T... args)
Base class for 2-dimensional polynomials of the form:
Definition: Function.h:326
static int nParametersFromOrder(int order)
Compute number of parameters from polynomial order.
Definition: Function.h:369
bool isLinearCombination() const noexcept override
Is the function a linear combination of its parameters?
Definition: Function.h:362
BasePolynomialFunction2(BasePolynomialFunction2 &&)=default
BasePolynomialFunction2(unsigned int order)
Construct a polynomial function of specified order.
Definition: Function.h:335
std::vector< double > getDFuncDParameters(double x, double y) const override
Return the derivative of the Function with respect to its parameters.
Definition: Function.h:411
int getOrder() const noexcept
Get the polynomial order.
Definition: Function.h:360
BasePolynomialFunction2(BasePolynomialFunction2 const &)=default
BasePolynomialFunction2(std::vector< double > params)
Construct a polynomial function with specified parameters.
Definition: Function.h:346
static int orderFromNParameters(int nParameters)
Compute polynomial order from the number of parameters.
Definition: Function.h:392
~BasePolynomialFunction2() noexcept override=default
BasePolynomialFunction2 & operator=(BasePolynomialFunction2 &&)=default
BasePolynomialFunction2 & operator=(BasePolynomialFunction2 const &)=default
A Function taking one argument.
Definition: Function.h:202
~Function1() noexcept override=default
Function1(Function1 const &)=default
Function1(std::vector< double > const &params)
Construct a Function1 given the function parameters.
Definition: Function.h:215
Function1 & operator=(Function1 &&)=default
std::string toString(std::string const &prefix="") const override
Return a string representation of the function.
Definition: Function.h:240
Function1(unsigned int nParams)
Construct a Function1 given the number of function parameters.
Definition: Function.h:209
virtual void computeCache(int const n)
Definition: Function.h:244
virtual std::shared_ptr< Function1< ReturnT > > clone() const =0
Return a pointer to a deep copy of this function.
Function1(Function1 &&)=default
Function1 & operator=(Function1 const &)=default
A Function taking two arguments.
Definition: Function.h:259
virtual std::shared_ptr< Function2< ReturnT > > clone() const =0
Return a pointer to a deep copy of this function.
Function2(unsigned int nParams)
Construct a Function2 given the number of function parameters.
Definition: Function.h:266
~Function2() noexcept override=default
Function2(Function2 const &)=default
Function2 & operator=(Function2 const &)=default
virtual std::vector< double > getDFuncDParameters(double, double) const
Return the derivative of the Function with respect to its parameters.
Definition: Function.h:305
std::string toString(std::string const &prefix="") const override
Return a string representation of the function.
Definition: Function.h:299
Function2(Function2 &&)=default
Function2 & operator=(Function2 &&)=default
Function2(std::vector< double > const &params)
Construct a Function2 given the function parameters.
Definition: Function.h:274
Basic Function class.
Definition: Function.h:84
std::vector< double > const & getParameters() const noexcept
Return all function parameters.
Definition: Function.h:129
virtual std::string toString(std::string const &) const
Return a string representation of the function.
Definition: Function.h:173
void setParameter(unsigned int ind, double newValue)
Set one function parameter without range checking.
Definition: Function.h:143
Function(Function &&)=default
std::vector< double > _params
Definition: Function.h:185
std::string getPythonModule() const override
Return the fully-qualified Python module that should be imported to guarantee that its factory is reg...
Definition: Function.h:188
virtual bool isLinearCombination() const noexcept
Is the function a linear combination of its parameters?
Definition: Function.h:138
Function(Function const &)=default
void setParameters(std::vector< double > const &params)
Set all function parameters.
Definition: Function.h:156
Function & operator=(Function &&)=default
Function & operator=(Function const &)=default
~Function() noexcept override=default
virtual double getParameter(unsigned int ind) const
Get one function parameter without range checking.
Definition: Function.h:119
Function(unsigned int nParams)
Construct a Function given the number of function parameters.
Definition: Function.h:91
unsigned int getNParameters() const noexcept
Return the number of function parameters.
Definition: Function.h:112
Function(std::vector< double > const &params)
Construct a Function given the function parameters.
Definition: Function.h:97
a class used in function calls to indicate that no Function1 is being provided
Definition: Function.h:441
std::shared_ptr< Function1< ReturnT > > clone() const override
Return a pointer to a deep copy of this function.
Definition: Function.h:444
a class used in function calls to indicate that no Function2 is being provided
Definition: Function.h:458
std::shared_ptr< Function2< ReturnT > > clone() const override
Return a pointer to a deep copy of this function.
Definition: Function.h:461
A CRTP facade class for subclasses of Persistable.
Definition: Persistable.h:176
A base class for objects that can be persisted via afw::table::io Archive classes.
Definition: Persistable.h:74
Reports invalid arguments.
Definition: Runtime.h:66
Reports attempts to access elements using an invalid key.
Definition: Runtime.h:151
T end(T... args)
constexpr bool IS_NOTHROW_INIT
Test that a Function's return value is nothrow-castable to T.
Definition: Function.h:51
def format(config, name=None, writeSourceLine=True, prefix="", verbose=False)
Definition: history.py:174
A base class for image defects.
STL namespace.
T size(T... args)
T sqrt(T... args)
table::Key< int > order