lsst.astshim g545b398f03+ce83317b7e
Public Member Functions | Protected Member Functions | Friends | List of all members
ast::PolyMap Class Reference

#include <PolyMap.h>

Inheritance diagram for ast::PolyMap:
ast::Mapping ast::Object

Public Member Functions

 PolyMap (ConstArray2D const &coeff_f, ConstArray2D const &coeff_i, std::string const &options="IterInverse=0")
 
 PolyMap (ConstArray2D const &coeff_f, int nout, std::string const &options="IterInverse=0")
 
virtual ~PolyMap ()
 
 PolyMap (PolyMap const &)=default
 Copy constructor: make a deep copy. More...
 
 PolyMap (PolyMap &&)=default
 
PolyMapoperator= (PolyMap const &)=delete
 
PolyMapoperator= (PolyMap &&)=default
 
std::shared_ptr< PolyMapcopy () const
 Return a deep copy of this object. More...
 
bool getIterInverse () const
 Get IterInverse: does this provide an iterative inverse transformation? More...
 
int getNIterInverse () const
 Get NIterInverse: maximum number of iterations for iterative inverse. More...
 
double getTolInverse () const
 Get TolInverse: target relative error for iterative inverse. More...
 
PolyMap polyTran (bool forward, double acc, double maxacc, int maxorder, std::vector< double > const &lbnd, std::vector< double > const &ubnd) const
 
- Public Member Functions inherited from ast::Mapping
virtual ~Mapping ()
 
 Mapping (Mapping const &)=default
 Copy constructor: make a deep copy. More...
 
 Mapping (Mapping &&)=default
 
Mappingoperator= (Mapping const &)=delete
 
Mappingoperator= (Mapping &&)=default
 
std::shared_ptr< Mappingcopy () const
 Return a deep copy of this object. More...
 
int getNIn () const
 
int getNOut () const
 
bool getIsSimple () const
 
bool isInverted () const
 
bool getIsLinear () const
 
bool getReport () const
 
bool hasForward () const
 
bool hasInverse () const
 
std::shared_ptr< Mappinginverted () const
 
Array2D linearApprox (PointD const &lbnd, PointD const &ubnd, double tol) const
 
SeriesMap then (Mapping const &next) const
 
ParallelMap under (Mapping const &next) const
 
double rate (PointD const &at, int ax1, int ax2) const
 
void setReport (bool report)
 
std::shared_ptr< Mappingsimplified () const
 
void applyForward (ConstArray2D const &from, Array2D const &to) const
 
Array2D applyForward (ConstArray2D const &from) const
 
std::vector< double > applyForward (std::vector< double > const &from) const
 
void applyInverse (ConstArray2D const &from, Array2D const &to) const
 
Array2D applyInverse (ConstArray2D const &from) const
 
std::vector< double > applyInverse (std::vector< double > const &from) const
 
void tranGridForward (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, Array2D const &to) const
 
Array2D tranGridForward (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, int nPts) const
 
void tranGridInverse (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, Array2D const &to) const
 
Array2D tranGridInverse (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, int nPts) const
 
- Public Member Functions inherited from ast::Object
virtual ~Object ()
 
 Object (Object const &object)
 Copy constructor: make a deep copy. More...
 
 Object (Object &&)=default
 
Objectoperator= (Object const &)=delete
 
Objectoperator= (Object &&)=default
 
bool operator== (Object const &rhs) const
 
bool operator!= (Object const &rhs) const
 
std::shared_ptr< Objectcopy () const
 Return a deep copy of this object. More...
 
void clear (std::string const &attrib)
 
bool hasAttribute (std::string const &attrib) const
 
std::string getClassName () const
 
std::string getID () const
 Get ID: object identification string that is not copied. More...
 
std::string getIdent () const
 Get Ident: object identification string that is copied. More...
 
int getNObject () const
 
int getObjSize () const
 Get ObjSize: the in-memory size of the AST object in bytes. More...
 
int getRefCount () const
 
bool getUseDefs () const
 Get UseDefs: allow use of default values for Object attributes? More...
 
void lock (bool wait)
 
bool same (Object const &other) const
 
void setID (std::string const &id)
 Set ID: object identification string that is not copied. More...
 
void setIdent (std::string const &ident)
 Set Ident: object identification string that is copied. More...
 
void setUseDefs (bool usedefs)
 Set UseDefs: allow use of default values for Object attributes? More...
 
void show (std::ostream &os, bool showComments=true) const
 
std::string show (bool showComments=true) const
 
bool test (std::string const &attrib) const
 
void unlock (bool report=false)
 
AstObject const * getRawPtr () const
 
AstObject * getRawPtr ()
 

Protected Member Functions

virtual std::shared_ptr< ObjectcopyPolymorphic () const override
 
 PolyMap (AstPolyMap *map)
 Construct a PolyMap from an raw AST pointer. More...
 
- Protected Member Functions inherited from ast::Mapping
 Mapping (AstMapping *rawMap)
 
template<typename Class >
std::shared_ptr< Class > decompose (int i, bool copy) const
 
- Protected Member Functions inherited from ast::Object
 Object (AstObject *object)
 
template<typename T , typename AstT >
std::shared_ptr< T > copyImpl () const
 
bool getB (std::string const &attrib) const
 
std::string const getC (std::string const &attrib) const
 
double getD (std::string const &attrib) const
 
float getF (std::string const &attrib) const
 
int getI (std::string const &attrib) const
 
long int getL (std::string const &attrib) const
 
void set (std::string const &setting)
 
void setB (std::string const &attrib, bool value)
 
void setC (std::string const &attrib, std::string const &value)
 
void setD (std::string const &attrib, double value)
 
void setF (std::string const &attrib, float value)
 
void setI (std::string const &attrib, int value)
 
void setL (std::string const &attrib, long int value)
 

Friends

class Object
 

Additional Inherited Members

- Public Types inherited from ast::Object
using ObjectPtr = std::unique_ptr< AstObject, Deleter >
 unique pointer holding an AST raw pointer More...
 
- Static Public Member Functions inherited from ast::Object
static std::shared_ptr< ObjectfromString (std::string const &str)
 
template<typename Class >
static std::shared_ptr< Class > fromAstObject (AstObject *rawObj, bool copy)
 
- Static Protected Member Functions inherited from ast::Object
template<typename ShimT , typename AstT >
static std::shared_ptr< ShimT > makeShim (AstObject *p)
 

Detailed Description

PolyMap is a Mapping which performs a general polynomial transformation. Each output coordinate is a polynomial function of all the input coordinates. The coefficients are specified separately for each output coordinate. The forward and inverse transformations are defined independantly by separate sets of coefficients. If no inverse transformation is supplied, an iterative method can be used to evaluate the inverse based only on the forward transformation.

Attributes

All those of Mapping plus:

Constructor & Destructor Documentation

◆ PolyMap() [1/5]

ast::PolyMap::PolyMap ( ConstArray2D const &  coeff_f,
ConstArray2D const &  coeff_i,
std::string const &  options = "IterInverse=0" 
)
inlineexplicit

Construct a PolyMap with specified forward and/or inverse transforms.

The two sets of coefficients are independent of each other: the inverse transform need not undo the forward transform.

Parameters
[in]coeff_fA matrix of coefficients describing the forward transformation. If coeff_f is empty then no forward transformation is provided.
[in]coeff_iA matrix of coefficients describing the inverse transformation. If coeff_i is empty then no inverse transformation is provided, unless you specify suitable options to request an iterative inverse; see the other constructor for details.
[in]optionsComma-separated list of attribute assignments.
Exceptions
std::invalid_argumentif neither transform is specified (coeff_f and coeff_i are both empty)

Coefficient Matrices

The coefficients describing a forward transformation are specified as 2-dimensional ndarray, with one row per coefficient. Each row contains the following consecutive (2 + nin) values:

  • The first element is the coefficient value.
  • The next element is the integer index of the PolyMap output which uses the coefficient within its defining polynomial (the first output has index 1).
  • The remaining elements give the integer power to use with each corresponding input coordinate value, or 0 to ignore that input coordinate. Powers must not be negative and floating point values are rounded to the nearest integer.

For example, suppose you want to make a PolyMap with 3 inputs and 2 outputs. Then each row of coeff_f must have 5 = 2 + nin elements. A row with values (1.2, 2, 6, 3, 0) describes a coefficient that increments output 2 as follows:

`out2 += 1.2 * in1^6 * in2^3 * in3^0`

and a row with values (-1.5, 1, 0, 0, 0) describes a coefficient that increments output 2 with a constant value of -1.5 (since all powers are 0):

`out1 += -1.5 * in1^0 * in2^0 * in3^0`

The final value of each output coordinate is the sum of all values specified by coefficients which increment that output coordinate, or 0 if there are no such coefficients.

The coefficients describing the inverse transformation work the same way, of course, but each coefficient is described by (2 + nout) values.

◆ PolyMap() [2/5]

ast::PolyMap::PolyMap ( ConstArray2D const &  coeff_f,
int  nout,
std::string const &  options = "IterInverse=0" 
)
inlineexplicit

Construct a PolyMap with only the forward transform specified.

If the polynomial is invertible and you want an inverse you have two choices: either specify suitable options to request an iterative inverse, or call polyTran to fit an inverse. Both have advantages:

  • The iterative inverse should provide valid values even if multiple choices exist, and nan if no valid choice exists, whereas polyTran will raise an exception if a single-valued inverse cannot be found over the specified range.
  • The iterative inverse has no range restriction, whereas polyTran produces an inverse that is valid over a specified range.
  • The polyTran inverse is more efficient to compute.
Parameters
[in]coeff_fA (2 + nin) x ncoeff_f matrix of coefficients describing the forward transformation. If coeff_f is empty then no forward transformation is provided.
[in]noutNumber of output coordinates.
[in]optionsComma-separated list of attribute assignments. Useful attributes include: IterInverse, NIterInverse and TolInverse.
Exceptions
std::invalid_argumentif the forward transform is not specified (coeff_f is empty)

◆ ~PolyMap()

virtual ast::PolyMap::~PolyMap ( )
inlinevirtual

◆ PolyMap() [3/5]

ast::PolyMap::PolyMap ( PolyMap const &  )
default

Copy constructor: make a deep copy.

◆ PolyMap() [4/5]

ast::PolyMap::PolyMap ( PolyMap &&  )
default

◆ PolyMap() [5/5]

ast::PolyMap::PolyMap ( AstPolyMap *  map)
protected

Construct a PolyMap from an raw AST pointer.

Member Function Documentation

◆ copy()

std::shared_ptr< PolyMap > ast::PolyMap::copy ( ) const
inline

Return a deep copy of this object.

◆ copyPolymorphic()

virtual std::shared_ptr< Object > ast::PolyMap::copyPolymorphic ( ) const
inlineoverrideprotectedvirtual

Return a deep copy of this object. This is called by copy.

Each subclass must override this method. The standard implementation is:

return copyImpl<astshim_class, ast_class>();

for example Frame implements this as:

return copyImpl<Frame, AstFrame>();

Reimplemented from ast::Mapping.

◆ getIterInverse()

bool ast::PolyMap::getIterInverse ( ) const
inline

Get IterInverse: does this provide an iterative inverse transformation?

◆ getNIterInverse()

int ast::PolyMap::getNIterInverse ( ) const
inline

Get NIterInverse: maximum number of iterations for iterative inverse.

◆ getTolInverse()

double ast::PolyMap::getTolInverse ( ) const
inline

Get TolInverse: target relative error for iterative inverse.

◆ operator=() [1/2]

PolyMap & ast::PolyMap::operator= ( PolyMap &&  )
default

◆ operator=() [2/2]

PolyMap & ast::PolyMap::operator= ( PolyMap const &  )
delete

◆ polyTran()

PolyMap ast::PolyMap::polyTran ( bool  forward,
double  acc,
double  maxacc,
int  maxorder,
std::vector< double > const &  lbnd,
std::vector< double > const &  ubnd 
) const

This function creates a new PolyMap which is a copy of this one, in which a specified transformation (forward or inverse) has been replaced by a new polynomial transformation. The coefficients of the new transformation are estimated by sampling the other transformation and performing a least squares polynomial fit in the opposite direction to the sampled positions and values.

IterInverse will be cleared in the returned mapping if the inverse was fit by polyTran.

This method can only be used on (1-input,1-output) or (2-input, 2-output) PolyMaps.

The transformation to create is specified by the forward parameter. In what follows "X" refers to the inputs of the PolyMap, and "Y" to the outputs of the PolyMap. The forward transformation transforms input values (X) into output values (Y), and the inverse transformation transforms output values (Y) into input values (X). Within a PolyMap, each transformation is represented by an independent set of polynomials, P_f or P_i: Y=P_f(X) for the forward transformation and X=P_i(Y) for the inverse transformation.

The forward parameter specifies the transformation to be replaced. If it is true, a new forward transformation is created by first finding the input values (X) using the inverse transformation (which must be available) at a regular grid of points (Y) covering a rectangular region of the PolyMap's output space. The coefficients of the required forward polynomial, Y=P_f(X), are chosen in order to minimise the sum of the squared residuals between the sampled values of Y and P_f(X).

If forward is false (probably the most likely case), a new inverse transformation is created by first finding the output values (Y) using the forward transformation (which must be available) at a regular grid of points (X) covering a rectangular region of the PolyMap's input space. The coefficients of the required inverse polynomial, X=P_i(Y), are chosen in order to minimise the sum of the squared residuals between the sampled values of X and P_i(Y).

This fitting process is performed repeatedly with increasing polynomial orders (starting with linear) until the target accuracy is achieved, or a specified maximum order is reached. If the target accuracy cannot be achieved even with this maximum-order polynomial, the best fitting maximum-order polynomial is returned so long as its accuracy is better than "maxacc". If it is not, an error is reported.

Parameters
[in]forwardIf true the forward transformation is replaced. Otherwise the inverse transformation is replaced.
[in]accThe target accuracy, expressed as a geodesic distance within the PolyMap's input space (if forward is false) or output space (if forward is true).
[in]maxaccThe maximum allowed accuracy for an acceptable polynomial, expressed as a geodesic distance within the PolyMap's input space (if forward is false) or output space (if forward is true).
[in]maxorderThe maximum allowed polynomial order. This is one more than the maximum power of either input axis. So for instance, a value of 3 refers to a quadratic polynomial. Note, cross terms with total powers greater than or equal to maxorder are not inlcuded in the fit. So the maximum number of terms in each of the fitted polynomials is maxorder*(maxorder + 1)/2.
[in]lbndA vector holding the lower bounds of a rectangular region within the PolyMap's input space (if forward is false) or output space (if forward is true). The new polynomial will be evaluated over this rectangle. The length should equal getNIn() or getNOut(), depending on forward.
[in]ubndA vector holding the upper bounds of a rectangular region within the PolyMap's input space (if forward is false) or output space (if forward is true). The new polynomial will be evaluated over this rectangle. The length should equal getNIn() or getNOut(), depending on forward.
Exceptions
std::invalid_argumentif the size of lbnd or ubnd does not match getNIn() (if forward false) or getNOut() (if forward true).
std::invalid_argumentif forward true and the inverse transform is iterative (even if this transform also has inverse coefficients, since the result is unlikely to match user expectations)
std::invalid_argumentif forward false and the forward transform is iterative (even if this transform also has forward coefficients, since the result is unlikely to match user expectations)

Friends And Related Function Documentation

◆ Object

friend class Object
friend

The documentation for this class was generated from the following files: