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
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | Friends | List of all members
ast::MathMap Class Reference

A MathMap is a Mapping which allows you to specify a set of forward and/or inverse transformation functions using arithmetic operations and mathematical functions similar to those available in C. More...

#include <MathMap.h>

Inheritance diagram for ast::MathMap:
ast::Mapping ast::Object

Public Types

using ObjectPtr = std::unique_ptr< AstObject, Deleter >
 unique pointer holding an AST raw pointer More...
 

Public Member Functions

 MathMap (int nin, int nout, std::vector< std::string > const &fwd, std::vector< std::string > const &rev, std::string const &options="")
 Construct a Mathmap. More...
 
virtual ~MathMap ()
 
 MathMap (MathMap const &)=default
 Copy constructor: make a deep copy. More...
 
 MathMap (MathMap &&)=default
 
MathMapoperator= (MathMap const &)=delete
 
MathMapoperator= (MathMap &&)=default
 
std::shared_ptr< MathMapcopy () const
 Return a deep copy of this object. More...
 
int getSeed () const
 Get Seed: random number seed. More...
 
bool getSimpFI () const
 Get SimpFI: can forward-inverse MathMap pairs safely simplify? More...
 
bool getSimpIF () const
 Get SimpIF: can inverse-forward MathMap pairs safely simplify? More...
 
int getNIn () const
 Get NIn: the number of input axes. More...
 
int getNOut () const
 Get NOut: the number of output axes. More...
 
bool getIsSimple () const
 Get IsSimple: has the mapping been simplified? More...
 
bool isInverted () const
 Is this an inverted mapping? More...
 
bool getIsLinear () const
 Get IsLinear: is the Mapping linear? More...
 
bool getReport () const
 Get Report: report transformed coordinates to stdout? More...
 
bool hasForward () const
 Is the forward transform available? More...
 
bool hasInverse () const
 Is the inverse transform available? More...
 
std::shared_ptr< Mappinginverted () const
 Get an inverse mapping. More...
 
Array2D linearApprox (PointD const &lbnd, PointD const &ubnd, double tol) const
 Compute a linear approximation to the forward transformation. More...
 
SeriesMap then (Mapping const &next) const
 Return a series compound mapping this(first(input)) containing shallow copies of the original. More...
 
ParallelMap under (Mapping const &next) const
 Return a parallel compound mapping containing shallow copies of the original. More...
 
double rate (PointD const &at, int ax1, int ax2) const
 Evaluate the rate of change of the Mapping with respect to a specified input, at a specified position. More...
 
void setReport (bool report)
 Set Report: report transformed coordinates to stdout? More...
 
std::shared_ptr< Mappingsimplified () const
 Return a simplied version of the mapping (which may be a compound Mapping such as a CmpMap). More...
 
void applyForward (ConstArray2D const &from, Array2D const &to) const
 Perform a forward transformation on 2-D array, putting the results into a pre-allocated 2-D array. More...
 
Array2D applyForward (ConstArray2D const &from) const
 Perform a forward transformation on a 2-D array, returning the results as a new array. More...
 
std::vector< double > applyForward (std::vector< double > const &from) const
 Perform a forward transformation on a vector, returning the results as a new vector. More...
 
void applyInverse (ConstArray2D const &from, Array2D const &to) const
 Perform an inverse transformation on a 2-D array, putting the results into a pre-allocated 2-D array. More...
 
Array2D applyInverse (ConstArray2D const &from) const
 Perform an inverse transformation on a 2-D array, returning the results as a new 2-D array. More...
 
std::vector< double > applyInverse (std::vector< double > const &from) const
 Perform an inverse transformation on a vector, returning the results as a new vector. More...
 
void tranGridForward (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, Array2D const &to) const
 Transform a grid of points in the forward direction. More...
 
Array2D tranGridForward (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, int nPts) const
 Transform a grid of points in the inverse direction, returning the results as a new Array2D. More...
 
void tranGridInverse (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, Array2D const &to) const
 Transform a grid of points in the inverse direction. More...
 
Array2D tranGridInverse (PointI const &lbnd, PointI const &ubnd, double tol, int maxpix, int nPts) const
 Transform a grid of points in the inverse direction. More...
 
bool operator== (Object const &rhs) const
 Return True if this and rhs are the equal. More...
 
bool operator!= (Object const &rhs) const
 Return True if this and rhs are not equal. More...
 
void clear (std::string const &attrib)
 Clear the values of a specified set of attributes for an Object. More...
 
bool hasAttribute (std::string const &attrib) const
 Does this object have an attribute with the specified name? More...
 
std::string getClassName () const
 Get Class: the name of the class (e.g. More...
 
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
 Get NObject: number of AST objects in existence of the same type as the underlying AST class. More...
 
int getObjSize () const
 Get ObjSize: the in-memory size of the AST object in bytes. More...
 
int getRefCount () const
 Get RefCount: number of active pointers to the underlying AST object. More...
 
bool getUseDefs () const
 Get UseDefs: allow use of default values for Object attributes? More...
 
void lock (bool wait)
 Lock this object for exclusive use by the calling thread. More...
 
bool same (Object const &other) const
 Does this contain the same AST object as another? More...
 
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
 Print a textual description the object to an ostream. More...
 
std::string show (bool showComments=true) const
 Return a textual description the object as a string. More...
 
bool test (std::string const &attrib) const
 Has this attribute been explicitly set (and not subsequently cleared)? More...
 
void unlock (bool report=false)
 Unlock this object previously locked using lock, so that other threads can use this object. More...
 
AstObject const * getRawPtr () const
 Get the raw AST pointer. More...
 
AstObject * getRawPtr ()
 Get the raw AST pointer. More...
 

Static Public Member Functions

static std::shared_ptr< ObjectfromString (std::string const &str)
 Construct an Object from a string, using astFromString. More...
 
template<typename Class >
static std::shared_ptr< Class > fromAstObject (AstObject *rawObj, bool copy)
 Given a bare AST object pointer return a shared pointer to an ast::Object of the correct type. More...
 

Protected Member Functions

virtual std::shared_ptr< ObjectcopyPolymorphic () const override
 Return a deep copy of this object. More...
 
 MathMap (AstMathMap *rawptr)
 Construct a MathMap from a raw AST pointer. More...
 
template<typename Class >
std::shared_ptr< Class > decompose (int i, bool copy) const
 Return a deep copy of one of the two component mappings. More...
 
template<typename T , typename AstT >
std::shared_ptr< T > copyImpl () const
 Implementation of deep copy. More...
 
bool getB (std::string const &attrib) const
 Get the value of an attribute as a bool. More...
 
std::string const getC (std::string const &attrib) const
 Get the value of an attribute as a string. More...
 
double getD (std::string const &attrib) const
 Get the value of an attribute as a double. More...
 
float getF (std::string const &attrib) const
 Get the value of an attribute as a float. More...
 
int getI (std::string const &attrib) const
 Get the value of an attribute as an int. More...
 
long int getL (std::string const &attrib) const
 Get the value of an attribute as a long int. More...
 
void set (std::string const &setting)
 Assign a set of attribute values, over-riding any previous values. More...
 
void setB (std::string const &attrib, bool value)
 Set the value of an attribute as a bool. More...
 
void setC (std::string const &attrib, std::string const &value)
 Set the value of an attribute as a string. More...
 
void setD (std::string const &attrib, double value)
 Set the value of an attribute as a double. More...
 
void setF (std::string const &attrib, float value)
 Set the value of an attribute as a float. More...
 
void setI (std::string const &attrib, int value)
 Set the value of an attribute as an int. More...
 
void setL (std::string const &attrib, long int value)
 Set the value of an attribute as a long int. More...
 

Static Protected Member Functions

template<typename ShimT , typename AstT >
static std::shared_ptr< ShimT > makeShim (AstObject *p)
 Functor to make an astshim instance from a raw AST pointer of the corresponding type. More...
 

Friends

class Object
 

Detailed Description

A MathMap is a Mapping which allows you to specify a set of forward and/or inverse transformation functions using arithmetic operations and mathematical functions similar to those available in C.

The MathMap interprets these functions at run-time, whenever its forward or inverse transformation is required. Because the functions are not compiled in the normal sense (unlike an IntraMap), they may be used to describe coordinate transformations in a transportable manner. A MathMap therefore provides a flexible way of defining new types of Mapping whose descriptions may be stored as part of a dataset and interpreted by other programs.

Notes

Attributes

In addition to those attributes provided by Mapping and Object, MathMap has the following attributes:

Definition at line 61 of file MathMap.h.

Member Typedef Documentation

◆ ObjectPtr

using ast::Object::ObjectPtr = std::unique_ptr<AstObject, Deleter>
inherited

unique pointer holding an AST raw pointer

Definition at line 59 of file Object.h.

Constructor & Destructor Documentation

◆ MathMap() [1/4]

ast::MathMap::MathMap ( int  nin,
int  nout,
std::vector< std::string > const &  fwd,
std::vector< std::string > const &  rev,
std::string const &  options = "" 
)
inline

Construct a Mathmap.

Parameters
[in]ninNumber of input variables for the MathMap.
[in]noutNumber of output variables for the MathMap.
[in]fwdAn array contain the expressions defining the forward transformation. The syntax of these expressions is described below.
[in]revAn array contain the expressions defining the reverse transformation. The syntax of these expressions is described below.
[in]optionsComma-separated list of attribute assignments.

Defining Transformation Functions:

A MathMap's transformation functions are supplied as a set of expressions in an array of character strings. Normally you would supply the same number of expressions for the forward transformation, via the fwd parameter, as there are output variables (given by the MathMap's NOut attribute). For instance, if NOut is 2 you might use:

  • "r = sqrt(x*x + y*y)"
  • "theta = atan2(y, x)" which defines a transformation from Cartesian to polar coordinates. Here, the variables that appear on the left of each expression (r and theta ) provide names for the output variables and those that appear on the right (x and y) are references to input variables.

To complement this, you must also supply expressions for the inverse transformation via the "inv" parameter. In this case, the number of expressions given would normally match the number of MathMap input coordinates (given by the NIn attribute). If NIn is 2, you might use:

  • "x = r * cos(theta)"
  • "y = r * sin(theta)" which expresses the transformation from polar to Cartesian coordinates. Note that here the input variables (x and y) are named on the left of each expression, and the output variables (r and theta are referenced on the right.

Normally, you cannot refer to a variable on the right of an expression unless it is named on the left of an expression in the complementary set of functions. Therefore both sets of functions (forward and inverse) must be formulated using the same consistent set of variable names. This means that if you wish to leave one of the transformations undefined, you must supply dummy expressions which simply name each of the output (or input) variables. For example, you might use:

  • x
  • " y" for the inverse transformation above, which serves to name the input variables but without defining an inverse transformation.

Calculating Intermediate Values:

It is sometimes useful to calculate intermediate values and then to use these in the final expressions for the output (or input) variables. This may be done by supplying additional expressions for the forward (or inverse) transformation functions. For instance, the following array of five expressions describes 2-dimensional pin-cushion distortion:

  • "r=sqrt(xin * xin + yin * yin)"
  • "rout = r * (1 + 0.1 * r * r)"
  • "theta = atan2(yin, xin)"
  • "xout=rout * cos(theta)"
  • "yout=rout * sin(theta)"

Here, we first calculate three intermediate results ("r" , " rout" and "theta" ) and then use these to calculate the final results ("xout" and "yout" ). The MathMap knows that only the final two results constitute values for the output variables because its NOut attribute is set to 2. You may define as many intermediate variables in this way as you choose. Having defined a variable, you may then refer to it on the right of any subsequent expressions.

Note that when defining the inverse transformation you may only refer to the output variables "xout" and " yout" . The intermediate variables "r", "rout" and "theta" (above) are private to the forward transformation and may not be referenced by the inverse transformation. The inverse transformation may, however, define its own private intermediate variables.

Expression Syntax:

The expressions given for the forward and inverse transformations closely follow the syntax of the C programming language (with some extensions for compatibility with Fortran). They may contain references to variables and literal constants, together with arithmetic, boolean, relational and bitwise operators, and function invocations. A set of symbolic constants is also available. Each of these is described in detail below. Parentheses may be used to over-ride the normal order of evaluation. There is no built-in limit to the length of expressions and they are insensitive to case or the presence of additional white space.

Variables:

Variable names must begin with an alphabetic character and may contain only alphabetic characters, digits, and the underscore character " _" . There is no built-in limit to the length of variable names.

Literal Constants:

Literal constants, such as 0, 1, 0.007 or 2.505e-16 may appear in expressions, with the decimal point and exponent being optional (a D may also be used as an exponent character for compatibility with Fortran). A unary minus - may be used as a prefix.

Arithmetic Precision:

All arithmetic is floating point, performed in double precision.

Propagation of Missing Data:

Unless indicated otherwise, if any argument of a function or operator has the value AST__BAD (indicating missing data), then the result of that function or operation is also AST__BAD, so that such values are propagated automatically through all operations performed by MathMap transformations. The special value AST__BAD can be represented in expressions by the symbolic constant <bad>. A <bad> result (i.e. equal to AST__BAD) is also produced in response to any numerical error (such as division by zero or numerical overflow), or if an invalid argument value is provided to a function or operator.

Arithmetic Operators:

The following arithmetic operators are available:

  • x1 + x2: x1 plus x2.
  • x1 - x2: x1 minus x2.
  • x1 * x2: x1 times x2.
  • x1 / x2: x1 divided by x2.
  • x1 ** x2: x1 raised to the power of x2.
  • +x: Unary plus, has no effect on its argument.
  • -x: Unary minus, negates its argument.

Boolean Operators:

Boolean values are represented using zero to indicate false and non-zero to indicate true. In addition, the value AST__BAD is taken to mean unknown . The values returned by boolean operators may therefore be 0, 1 or AST__BAD. Where appropriate, "tri-state" logic is implemented. For example, a||b may evaluate to 1 if a is non-zero, even if b has the value AST__BAD. This is because the result of the operation would not be affected by the value of b, so long as a is non-zero.

The following boolean operators are available:

  • x1 && x2: Boolean AND between x1 and x2, returning 1 if both x1 and x2 are non-zero, and 0 otherwise. This operator implements tri-state logic. (The synonym " .and." is also provided for compatibility with Fortran.)
  • x1 || x2: Boolean OR between x1 and x2, returning 1 if either x1 or x2 are non-zero, and 0 otherwise. This operator implements tri-state logic. (The synonym " .or." is also provided for compatibility with Fortran.)
  • x1 ^^ x2: Boolean exclusive OR (XOR) between x1 and x2, returning 1 if exactly one of x1 and x2 is non-zero, and 0 otherwise. Tri-state logic is not used with this operator. (The synonyms " .neqv." and " .xor." are also provided for compatibility with Fortran, although the second of these is not standard.)
  • x1 .eqv. x2: This is provided only for compatibility with Fortran and tests whether the boolean states of x1 and x2 (i.e. true/false) are equal. It is the negative of the exclusive OR (XOR) function. Tri-state logic is not used with this operator.
  • !x: Boolean unary NOT operation, returning 1 if x is zero, and 0 otherwise. (The synonym " .not." is also provided for compatibility with Fortran.)

Relational Operators:

Relational operators return the boolean result (0 or 1) of comparing the values of two floating point values for equality or inequality. The value AST__BAD may also be returned if either argument is <bad>.

The following relational operators are available:

  • x1 == x2: Tests whether x1 equals x1. (The synonym " .eq." is also provided for compatibility with Fortran.)
  • x1 != x2: Tests whether x1 is unequal to x2. (The synonym " .ne." is also provided for compatibility with Fortran.)
  • x1 > x2: Tests whether x1 is greater than x2. (The synonym " .gt." is also provided for compatibility with Fortran.)
  • x1 >= x2: Tests whether x1 is greater than or equal to x2. (The synonym " .ge." is also provided for compatibility with Fortran.)
  • x1 < x2: Tests whether x1 is less than x2. (The synonym " .lt." is also provided for compatibility with Fortran.)
  • x1 <= x2: Tests whether x1 is less than or equal to x2. (The synonym " .le." is also provided for compatibility with Fortran.)

Note that relational operators cannot usefully be used to compare values with the <bad> value (representing missing data), because the result is always <bad>. The isbad() function should be used instead.

Bitwise Operators:

The bitwise operators provided by C are often useful when operating on raw data (e.g. from instruments), so they are also provided for use in MathMap expressions. In this case, however, the values on which they operate are floating point values rather than pure integers. In order to produce results which match the pure integer case, the operands are regarded as fixed point binary numbers (i.e. with the binary equivalent of a decimal point) with negative numbers represented using twos-complement notation. For integer values, the resulting bit pattern corresponds to that of the equivalent signed integer (digits to the right of the point being zero). Operations on the bits representing the fractional part are also possible, however.

The following bitwise operators are available:

  • x1 >> x2: Rightward bit shift. The integer value of x2 is taken (rounding towards zero) and the bits representing x1 are then shifted this number of places to the right (or to the left if the number of places is negative). This is equivalent to dividing x1 by the corresponding power of 2.
  • x1 << x2: Leftward bit shift. The integer value of x2 is taken (rounding towards zero), and the bits representing x1 are then shifted this number of places to the left (or to the right if the number of places is negative). This is equivalent to multiplying x1 by the corresponding power of 2.
  • x1 & x2: Bitwise AND between the bits of x1 and those of x2 (equivalent to a boolean AND applied at each bit position in turn).
  • x1 | x2: Bitwise OR between the bits of x1 and those of x2 (equivalent to a boolean OR applied at each bit position in turn).
  • x1 ^ x2: Bitwise exclusive OR (XOR) between the bits of x1 and those of x2 (equivalent to a boolean XOR applied at each bit position in turn).

Note that no bit inversion operator (~ in C) is provided. This is because inverting the bits of a twos-complement fixed point binary number is equivalent to simply negating it. This differs from the pure integer case because bits to the right of the binary point are also inverted. To invert only those bits to the left of the binary point, use a bitwise exclusive OR with the value -1 (i.e. x^-1).

Functions:

The following functions are available:

  • abs(x): Absolute value of x (sign removal), same as fabs(x).
  • acos(x): Inverse cosine of x, in radians.
  • acosd(x): Inverse cosine of x, in degrees.
  • acosh(x): Inverse hyperbolic cosine of x.
  • acoth(x): Inverse hyperbolic cotangent of x.
  • acsch(x): Inverse hyperbolic cosecant of x.
  • aint(x): Integer part of x (round towards zero), same as int(x).
  • asech(x): Inverse hyperbolic secant of x.
  • asin(x): Inverse sine of x, in radians.
  • asind(x): Inverse sine of x, in degrees.
  • asinh(x): Inverse hyperbolic sine of x.
  • atan(x): Inverse tangent of x, in radians.
  • atand(x): Inverse tangent of x, in degrees.
  • atanh(x): Inverse hyperbolic tangent of x.
  • atan2(x1, x2): Inverse tangent of x1/x2, in radians.
  • atan2d(x1, x2): Inverse tangent of x1/x2, in degrees.
  • ceil(x): Smallest integer value not less then x (round towards plus infinity).
  • cos(x): Cosine of x in radians.
  • cosd(x): Cosine of x in degrees.
  • cosh(x): Hyperbolic cosine of x.
  • coth(x): Hyperbolic cotangent of x.
  • csch(x): Hyperbolic cosecant of x.
  • dim(x1, x2): Returns x1-x2 if x1 is greater than x2, otherwise 0.
  • exp(x): Exponential function of x.
  • fabs(x): Absolute value of x (sign removal), same as abs(x).
  • floor(x): Largest integer not greater than x (round towards minus infinity).
  • fmod(x1, x2): Remainder when x1 is divided by x2, same as mod(x1, x2).
  • gauss(x1, x2): Random sample from a Gaussian distribution with mean x1 and standard deviation x2.
  • int(x): Integer part of x (round towards 0), same as aint(x).
  • isbad(x): Returns 1 if x has the
  • log(x): Natural logarithm of x.
  • log10(x): Logarithm of x to base
  • max(x1, x2, ...): Maximum of two or
  • min(x1, x2, ...): Minimum of two or
  • mod(x1, x2): Remainder when x1 is divided by x2, same as fmod(x1, x2).
  • nint(x): Nearest integer to x (round to nearest).
  • poisson(x): Random integer-valued sample from a Poisson distribution with mean x.
  • pow(x1, x2): x1 raised to the power of x2.
  • qif(x1, x2, x3): Returns x2 if x1 is true, and " x3" otherwise.
  • rand(x1, x2): Random sample from a uniform distribution in the range x1 to x2 inclusive.
  • sech(x): Hyperbolic secant of x.
  • sign(x1, x2): Absolute value of x1 with the sign of x2 (transfer of sign).
  • sin(x): Sine of x in radians.
  • sinc(x): Sinc function of x [= " sin(x)/x" ].
  • sind(x): Sine of x in degrees.
  • sinh(x): Hyperbolic sine of x.
  • sqr(x): Square of x (= " x*x" ).
  • sqrt(x): Square root of x.
  • tan(x): Tangent of x in radians.
  • tand(x): Tangent of x in degrees.
  • tanh(x): Hyperbolic tangent of x.

Symbolic Constants:

The following symbolic constants are available (the enclosing <> brackets must be included):

  • <bad>: The "bad" value (AST__BAD) used to flag missing data. Note that you cannot usefully compare values with this constant because the result is always <bad>. The isbad() function should be used instead.
  • <dig>: Number of decimal digits of precision available in a floating point (double) value.
  • <e>: Base of natural logarithms.
  • <epsilon>: Smallest positive number such that 1.0+<epsilon> is distinguishable from unity.
  • <mant_dig>: The number of base <radix> digits stored in the mantissa of a floating point (double) value.
  • <max>: Maximum representable floating point (double) value.
  • <max_10_exp>: Maximum integer such that 10 raised to that power can be represented as a floating point (double) value.
  • <max_exp>: Maximum integer such that <radix> raised to that power minus 1 can be represented as a floating point (double) value.
  • <min>: Smallest positive number which can be represented as a normalised floating point (double) value.
  • <min_10_exp>: Minimum negative integer such that 10 raised to that power can be represented as a normalised floating point (double) value.
  • <min_exp>: Minimum negative integer such that <radix> raised to that power minus 1 can be represented as a normalised floating point (double) value.
  • <pi>: Ratio of the circumference of a circle to its diameter.
  • <radix>: The radix (number base) used to represent the mantissa of floating point (double) values.
  • <rounds>: The mode used for rounding floating point results after addition. Possible values include: -1 (indeterminate), 0 (toward zero), 1 (to nearest), 2 (toward plus infinity) and 3 (toward minus infinity). Other values indicate machine-dependent behaviour.

Evaluation Precedence and Associativity:

Items appearing in expressions are evaluated in the following order (highest precedence first):

  • Constants and variables
  • Function arguments and parenthesised expressions - Function invocations
  • Unary + - ! .not.
  • **
  • *\/
  • +-
  • << >>
  • < .lt. <=.le. > .gt. >=.ge.
  • == .eq. != .ne.
  • &
  • ^
  • |
  • && .and.
  • ^^
  • || .or.
  • .eqv. .neqv. .xor.

All operators associate from left-to-right, except for unary +, unary -, !, .not. and ** which associate from right-to-left.

Definition at line 375 of file MathMap.h.

377  : Mapping(reinterpret_cast<AstMapping *>(astMathMap(nin, nout, fwd.size(), getCStrVec(fwd).data(),
378  rev.size(), getCStrVec(rev).data(), "%s",
379  options.c_str()))) {
380  assertOK();
381  }
char * data
Definition: BaseRecord.cc:61
Mapping(Mapping const &)=default
Copy constructor: make a deep copy.
void assertOK(AstObject *rawPtr1=nullptr, AstObject *rawPtr2=nullptr)
Throw std::runtime_error if AST's state is bad.
Definition: base.cc:49
T size(T... args)

◆ ~MathMap()

virtual ast::MathMap::~MathMap ( )
inlinevirtual

Definition at line 383 of file MathMap.h.

383 {}

◆ MathMap() [2/4]

ast::MathMap::MathMap ( MathMap const &  )
default

Copy constructor: make a deep copy.

◆ MathMap() [3/4]

ast::MathMap::MathMap ( MathMap &&  )
default

◆ MathMap() [4/4]

ast::MathMap::MathMap ( AstMathMap *  rawptr)
inlineexplicitprotected

Construct a MathMap from a raw AST pointer.

Definition at line 415 of file MathMap.h.

415  : Mapping(reinterpret_cast<AstMapping *>(rawptr)) {
416  if (!astIsAMathMap(getRawPtr())) {
418  os << "this is a " << getClassName() << ", which is not a MathMap";
419  throw std::invalid_argument(os.str());
420  }
421  }
std::ostream * os
Definition: Schema.cc:557
std::string getClassName() const
Get Class: the name of the class (e.g.
Definition: Object.h:139
AstObject const * getRawPtr() const
Get the raw AST pointer.
Definition: Object.h:292

Member Function Documentation

◆ applyForward() [1/3]

Array2D ast::Mapping::applyForward ( ConstArray2D const &  from) const
inlineinherited

Perform a forward transformation on a 2-D array, returning the results as a new array.

Parameters
[in]frominput coordinates, with dimensions (nPts, nIn)
Returns
the results as a new array with dimensions (nPts, nOut)

Definition at line 268 of file Mapping.h.

268  {
269  Array2D to = ndarray::allocate(getNOut(), from.getSize<1>());
270  _tran(from, true, to);
271  return to;
272  }
table::Key< int > from
table::Key< int > to
int getNOut() const
Get NOut: the number of output axes.
Definition: Mapping.h:82
ndarray::Array< double, 2, 2 > Array2D
2D array of const double; typically used for lists of const points
Definition: base.h:42

◆ applyForward() [2/3]

void ast::Mapping::applyForward ( ConstArray2D const &  from,
Array2D const &  to 
) const
inlineinherited

Perform a forward transformation on 2-D array, putting the results into a pre-allocated 2-D array.

Parameters
[in]frominput coordinates, with dimensions (nPts, nIn)
[out]totransformed coordinates, with dimensions (nPts, nOut)

Definition at line 260 of file Mapping.h.

260 { _tran(from, true, to); }

◆ applyForward() [3/3]

std::vector<double> ast::Mapping::applyForward ( std::vector< double > const &  from) const
inlineinherited

Perform a forward transformation on a vector, returning the results as a new vector.

Parameters
[in]frominput coordinates as a vector, with axes adjacent, e.g. x0, y0, x1, y1...xn, yn
Returns
the results as a new vector

Definition at line 280 of file Mapping.h.

280  {
281  auto fromArr = arrayFromVector(from, getNIn());
282  std::vector<double> to(fromArr.getSize<1>() * getNOut());
283  auto toArr = arrayFromVector(to, getNOut());
284  _tran(fromArr, true, toArr);
285  return to;
286  }
int getNIn() const
Get NIn: the number of input axes.
Definition: Mapping.h:77
ConstArray2D arrayFromVector(std::vector< double > const &vec, int nAxes)
Reshape a vector as a 2-dimensional array that shares the same memory.
Definition: base.cc:65

◆ applyInverse() [1/3]

Array2D ast::Mapping::applyInverse ( ConstArray2D const &  from) const
inlineinherited

Perform an inverse transformation on a 2-D array, returning the results as a new 2-D array.

Parameters
[in]fromoutput coordinates, with dimensions (nPts, nOut)
Returns
the results as a new array with dimensions (nPts, nIn)

Definition at line 302 of file Mapping.h.

302  {
303  Array2D to = ndarray::allocate(getNIn(), from.getSize<1>());
304  _tran(from, false, to);
305  return to;
306  }

◆ applyInverse() [2/3]

void ast::Mapping::applyInverse ( ConstArray2D const &  from,
Array2D const &  to 
) const
inlineinherited

Perform an inverse transformation on a 2-D array, putting the results into a pre-allocated 2-D array.

Parameters
[in]frominput coordinates, with dimensions (nPts, nOut)
[out]totransformed coordinates, with dimensions (nPts, nIn)

Definition at line 294 of file Mapping.h.

294 { _tran(from, false, to); }

◆ applyInverse() [3/3]

std::vector<double> ast::Mapping::applyInverse ( std::vector< double > const &  from) const
inlineinherited

Perform an inverse transformation on a vector, returning the results as a new vector.

Parameters
[in]frominput coordinates as a vector, with axes adjacent, e.g. x0, y0, x1, y1...xn, yn
Returns
the results as a new vector

Definition at line 314 of file Mapping.h.

314  {
315  auto fromArr = arrayFromVector(from, getNOut());
316  std::vector<double> to(fromArr.getSize<1>() * getNIn());
317  auto toArr = arrayFromVector(to, getNIn());
318  _tran(fromArr, false, toArr);
319  return to;
320  }

◆ clear()

void ast::Object::clear ( std::string const &  attrib)
inlineinherited

Clear the values of a specified set of attributes for an Object.

Clearing an attribute cancels any value that has previously been explicitly set for it, so that the standard default attribute value will subsequently be used instead. This also causes the astTest function to return the value zero for the attribute, indicating that no value has been set.

Definition at line 119 of file Object.h.

119  {
120  astClear(getRawPtr(), attrib.c_str());
121  assertOK();
122  }

◆ copy()

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

Return a deep copy of this object.

Definition at line 392 of file MathMap.h.

392 { return std::static_pointer_cast<MathMap>(copyPolymorphic()); }
virtual std::shared_ptr< Object > copyPolymorphic() const override
Return a deep copy of this object.
Definition: MathMap.h:410

◆ copyImpl()

template<typename T , typename AstT >
std::shared_ptr<T> ast::Object::copyImpl ( ) const
inlineprotectedinherited

Implementation of deep copy.

Should be called to implement copyPolymorphic by all derived classes.

Definition at line 320 of file Object.h.

320  {
321  auto *rawptr = reinterpret_cast<AstT *>(astCopy(getRawPtr()));
322  auto retptr = std::shared_ptr<T>(new T(rawptr));
323  assertOK();
324  return retptr;
325  }

◆ copyPolymorphic()

virtual std::shared_ptr<Object> ast::MathMap::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.

Definition at line 410 of file MathMap.h.

410  {
411  return copyImpl<MathMap, AstMathMap>();
412  }

◆ decompose()

template<typename Class >
template std::shared_ptr< Mapping > ast::Mapping::decompose ( int  i,
bool  copy 
) const
protectedinherited

Return a deep copy of one of the two component mappings.

This is intended to be exposed by classes that need it (e.g. CmpMap, CmpFrame and TranMap) as operator[].

Template Parameters
Classastshim class of returned object, typically Mapping or Frame.
Parameters
[in]iIndex: 0 for the first mapping, 1 for the second
[in]copyIf true make a deep copy, else a shallow copy
Exceptions
std::invalid_argumentif i is not 0 or 1.
std::runtime_errorif this mapping is not a compound mapping.

Definition at line 64 of file Mapping.cc.

64  {
65  if ((i < 0) || (i > 1)) {
67  os << "i =" << i << "; must be 0 or 1";
68  throw std::invalid_argument(os.str());
69  }
70  // Report pre-existing problems now so our later test for "not a compound object" is accurate
71  assertOK();
72 
73  AstMapping *rawMap1;
74  AstMapping *rawMap2;
75  int series, invert1, invert2;
76  astDecompose(getRawPtr(), &rawMap1, &rawMap2, &series, &invert1, &invert2);
77  assertOK();
78 
79  if (!rawMap2) {
80  // Not a compound object; free rawMap1 (rawMap2 is null, so no need to free it) and throw an exception
81  astAnnul(reinterpret_cast<AstObject *>(rawMap1));
83  os << "This " << getClassName() << " is not a compound object";
84  throw std::runtime_error(os.str());
85  }
86 
87  // Make a deep copy of the returned object and free the shallow copies
88  AstMapping *retRawMap;
89  int invert;
90  if (i == 0) {
91  retRawMap = reinterpret_cast<AstMapping *>(astCopy(reinterpret_cast<AstObject *>(rawMap1)));
92  invert = invert1;
93  } else {
94  retRawMap = reinterpret_cast<AstMapping *>(astCopy(reinterpret_cast<AstObject *>(rawMap2)));
95  invert = invert2;
96  }
97  astAnnul(reinterpret_cast<AstObject *>(rawMap1));
98  astAnnul(reinterpret_cast<AstObject *>(rawMap2));
99  assertOK();
100 
101  // If the mapping's internal invert flag does not match the value used when the CmpMap was made
102  // then invert the mapping. Note that it is not possible to create such objects in astshim
103  // but it is possible to read in objects created by other software.
104  if (invert != astGetI(retRawMap, "Invert")) {
105  astInvert(retRawMap);
106  assertOK();
107  }
108 
109  return Object::fromAstObject<Class>(reinterpret_cast<AstObject *>(retRawMap), copy);
110 }
std::shared_ptr< Mapping > copy() const
Return a deep copy of this object.
Definition: Mapping.h:72
Relationship invert(Relationship r)
Given the relationship between two sets A and B (i.e.
Definition: Relationship.h:55

◆ fromAstObject()

template<typename Class >
template std::shared_ptr< Object > ast::Object::fromAstObject< Object > ( AstObject *  rawObj,
bool  copy 
)
staticinherited

Given a bare AST object pointer return a shared pointer to an ast::Object of the correct type.

The returned object takes ownership of the pointer. This is almost always what you want, for instance astDecompose returns shallow copies of the internal pointers.

Template Parameters
ClassThe class of the returned shared pointer. (The actual class will be the correct class of rawPtr.)
Parameters
[in]rawObjA bare AST object pointer
[in]copyIf True then make a deep copy of the pointer (and free the original)

Definition at line 138 of file Object.cc.

138  {
139  AstObject *rawObjCopy = rawObj;
140  if (copy) {
141  rawObjCopy = reinterpret_cast<AstObject *>(astCopy(rawObj));
142  astAnnul(rawObj);
143  }
144  assertOK(rawObjCopy);
145 
146  // Make the appropriate ast shim object and dynamically cast to the desired output type
147  auto retObjectBeforeCast = Object::_basicFromAstObject(rawObjCopy);
148  auto retObject = std::dynamic_pointer_cast<Class>(retObjectBeforeCast);
149  if (!retObject) {
151  os << "The component is of type " << retObject->getClassName()
152  << ", which could not be cast to the desired type " << typeid(Class).name();
153  throw std::runtime_error(os.str());
154  }
155  return retObject;
156 }
table::Key< std::string > name
Definition: Amplifier.cc:116
std::shared_ptr< Object > copy() const
Return a deep copy of this object.
Definition: Object.h:109

◆ fromString()

static std::shared_ptr<Object> ast::Object::fromString ( std::string const &  str)
inlinestaticinherited

Construct an Object from a string, using astFromString.

Definition at line 88 of file Object.h.

88  {
89  auto *rawPtr = reinterpret_cast<AstObject *>(astFromString(str.c_str()));
90  assertOK(rawPtr);
91  return Object::_basicFromAstObject(rawPtr);
92  }

◆ getB()

bool ast::Object::getB ( std::string const &  attrib) const
inlineprotectedinherited

Get the value of an attribute as a bool.

If possible, the attribute value is converted to the type you request.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 348 of file Object.h.

348  {
349  bool val = astGetI(getRawPtr(), attrib.c_str());
350  assertOK();
351  return val;
352  }
ImageT val
Definition: CR.cc:146

◆ getC()

std::string const ast::Object::getC ( std::string const &  attrib) const
inlineprotectedinherited

Get the value of an attribute as a string.

If possible, the attribute value is converted to the type you request.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 361 of file Object.h.

361  {
362  char const *rawval = astGetC(getRawPtr(), attrib.c_str());
363  assertOK();
364  return std::string(rawval);
365  }

◆ getClassName()

std::string ast::Object::getClassName ( ) const
inlineinherited

Get Class: the name of the class (e.g.

ZoomMap)

Note: if AST returns "CmpMap" then the name will be changed to "SeriesMap" or "ParallelMap", as appropriate.

Definition at line 139 of file Object.h.

139 { return detail::getClassName(getRawPtr()); }
std::string getClassName(AstObject const *rawObj)
Get the AST class name, changing CmpMap to SeriesMap or ParallelMap as appropriate.
Definition: utils.cc:37

◆ getD()

double ast::Object::getD ( std::string const &  attrib) const
inlineprotectedinherited

Get the value of an attribute as a double.

If possible, the attribute value is converted to the type you request.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 374 of file Object.h.

374  {
375  double val = astGetD(getRawPtr(), attrib.c_str());
376  assertOK();
377  return val;
378  }

◆ getF()

float ast::Object::getF ( std::string const &  attrib) const
inlineprotectedinherited

Get the value of an attribute as a float.

If possible, the attribute value is converted to the type you request.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 387 of file Object.h.

387  {
388  float val = astGetF(getRawPtr(), attrib.c_str());
389  assertOK();
390  return val;
391  }

◆ getI()

int ast::Object::getI ( std::string const &  attrib) const
inlineprotectedinherited

Get the value of an attribute as an int.

If possible, the attribute value is converted to the type you request.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 400 of file Object.h.

400  {
401  int val = astGetI(getRawPtr(), attrib.c_str());
402  assertOK();
403  return val;
404  }

◆ getID()

std::string ast::Object::getID ( ) const
inlineinherited

Get ID: object identification string that is not copied.

Definition at line 142 of file Object.h.

142 { return getC("ID"); }
std::string const getC(std::string const &attrib) const
Get the value of an attribute as a string.
Definition: Object.h:361

◆ getIdent()

std::string ast::Object::getIdent ( ) const
inlineinherited

Get Ident: object identification string that is copied.

Definition at line 145 of file Object.h.

145 { return getC("Ident"); }

◆ getIsLinear()

bool ast::Mapping::getIsLinear ( ) const
inlineinherited

Get IsLinear: is the Mapping linear?

Definition at line 100 of file Mapping.h.

100 { return getB("IsLinear"); }
bool getB(std::string const &attrib) const
Get the value of an attribute as a bool.
Definition: Object.h:348

◆ getIsSimple()

bool ast::Mapping::getIsSimple ( ) const
inlineinherited

Get IsSimple: has the mapping been simplified?

Definition at line 87 of file Mapping.h.

87 { return getI("IsSimple"); }
int getI(std::string const &attrib) const
Get the value of an attribute as an int.
Definition: Object.h:400

◆ getL()

long int ast::Object::getL ( std::string const &  attrib) const
inlineprotectedinherited

Get the value of an attribute as a long int.

If possible, the attribute value is converted to the type you request.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 413 of file Object.h.

413  {
414  long int val = astGetL(getRawPtr(), attrib.c_str());
415  assertOK();
416  return val;
417  }

◆ getNIn()

int ast::Mapping::getNIn ( ) const
inlineinherited

Get NIn: the number of input axes.

Definition at line 77 of file Mapping.h.

77 { return getI("NIn"); }

◆ getNObject()

int ast::Object::getNObject ( ) const
inlineinherited

Get NObject: number of AST objects in existence of the same type as the underlying AST class.

Warning
Intended only for debugging astshim.

Definition at line 153 of file Object.h.

153 { return getI("NObject"); }

◆ getNOut()

int ast::Mapping::getNOut ( ) const
inlineinherited

Get NOut: the number of output axes.

Definition at line 82 of file Mapping.h.

82 { return getI("NOut"); }

◆ getObjSize()

int ast::Object::getObjSize ( ) const
inlineinherited

Get ObjSize: the in-memory size of the AST object in bytes.

Definition at line 156 of file Object.h.

156 { return getI("ObjSize"); }

◆ getRawPtr() [1/2]

AstObject* ast::Object::getRawPtr ( )
inlineinherited

Get the raw AST pointer.

Intended for internal use only, but cannot be made protected without endless "friend class" declarations.

Definition at line 294 of file Object.h.

294 { return &*_objPtr; };

◆ getRawPtr() [2/2]

AstObject const* ast::Object::getRawPtr ( ) const
inlineinherited

Get the raw AST pointer.

Intended for internal use only, but cannot be made protected without endless "friend class" declarations.

Definition at line 292 of file Object.h.

292 { return &*_objPtr; };

◆ getRefCount()

int ast::Object::getRefCount ( ) const
inlineinherited

Get RefCount: number of active pointers to the underlying AST object.

Warning
Intended only for debugging astshim.

Definition at line 163 of file Object.h.

163 { return getI("RefCount"); }

◆ getReport()

bool ast::Mapping::getReport ( ) const
inlineinherited

Get Report: report transformed coordinates to stdout?

Definition at line 105 of file Mapping.h.

105 { return getB("Report"); }

◆ getSeed()

int ast::MathMap::getSeed ( ) const
inline

Get Seed: random number seed.

Definition at line 397 of file MathMap.h.

397 { return getI("Seed"); }

◆ getSimpFI()

bool ast::MathMap::getSimpFI ( ) const
inline

Get SimpFI: can forward-inverse MathMap pairs safely simplify?

Definition at line 402 of file MathMap.h.

402 { return getB("SimpFI"); }

◆ getSimpIF()

bool ast::MathMap::getSimpIF ( ) const
inline

Get SimpIF: can inverse-forward MathMap pairs safely simplify?

Definition at line 407 of file MathMap.h.

407 { return getB("SimpIF"); }

◆ getUseDefs()

bool ast::Object::getUseDefs ( ) const
inlineinherited

Get UseDefs: allow use of default values for Object attributes?

Definition at line 166 of file Object.h.

166 { return getB("UseDefs"); }

◆ hasAttribute()

bool ast::Object::hasAttribute ( std::string const &  attrib) const
inlineinherited

Does this object have an attribute with the specified name?

Definition at line 127 of file Object.h.

127  {
128  bool ret = astHasAttribute(getRawPtr(), attrib.c_str());
129  assertOK();
130  return ret;
131  }

◆ hasForward()

bool ast::Mapping::hasForward ( ) const
inlineinherited

Is the forward transform available?

Note
This gets the TranForward attribute, but is named hasForward instead of getTranForward for clarity, since it does not return a transform.

Definition at line 114 of file Mapping.h.

114 { return getB("TranForward"); }

◆ hasInverse()

bool ast::Mapping::hasInverse ( ) const
inlineinherited

Is the inverse transform available?

Note
This gets the TranInverse attribute, but is named hasInverse instead of getTranInverse for clarity, since it does not return a transform.

Definition at line 123 of file Mapping.h.

123 { return getB("TranInverse"); }

◆ inverted()

std::shared_ptr< Mapping > ast::Mapping::inverted ( ) const
inherited

Get an inverse mapping.

An inverse mapping is a deep copy of a mapping whose Invert attribute has been toggled, as indicated by isInverted. This swaps the meaning of "input" and "output", and of "forward" and "inverse". Thus it swaps the behavior of applyForward and applyInverse, getNIn and getNOut, hasForward and hasInverse and so on.

Note that the inverse mapping contains exactly the same model coefficients as the original, but they are used by applyInverse instead of applyForward. Thus for example if a ZoomMap has a zoom factor of 4.0 then its inverse also reports a zoom factor of 4.0 (despite behaving like an uninverted ZoomMap with zoom factor of 0.25).

Definition at line 41 of file Mapping.cc.

41  {
42  auto rawCopy = reinterpret_cast<AstMapping *>(astCopy(getRawPtr()));
43  astInvert(rawCopy);
44  assertOK(reinterpret_cast<AstObject *>(rawCopy));
45  // use false because the pointer has already been copied
46  return Object::fromAstObject<Mapping>(reinterpret_cast<AstObject *>(rawCopy), false);
47 }

◆ isInverted()

bool ast::Mapping::isInverted ( ) const
inlineinherited

Is this an inverted mapping?

Note: this gets the Invert attribute. This method is not called getInvert because that sounds like it might return the inverse.

Definition at line 95 of file Mapping.h.

95 { return getB("Invert"); }

◆ linearApprox()

Array2D ast::Mapping::linearApprox ( PointD const &  lbnd,
PointD const &  ubnd,
double  tol 
) const
inherited

Compute a linear approximation to the forward transformation.

Parameters
[in]lbndInput point defining the lower bounds of the box over which the linear approximation is computed.
[in]ubndInput point defining the upper bounds of the box over which the linear approximation is computed.
[in]tolThe maximum permitted deviation from linearity, expressed as apositive Cartesian displacement in the output coordinate space. If a linear fit to the forward transformation of the Mapping deviates from the true transformation by more than this amount at any point which is tested, then raise an exception.
Returns
The co-efficients of the linear approximation to the specified transformation, as an 1 + nIn x nOut array. The first index is [constant, gradiant for input 1, gradiant for input 2...] and the second index is [output 1, output 2, ...]. For example, if the Mapping has 2 inputs and 3 outputs then the coefficients are:
X_out = fit[0, 0] + fit[1, 0] X_in + fit[2, 0] Y_in
Y_out = fit[0, 1] + fit[1, 1] X_in + fit[2, 1] Y_in
Z_out = fit[0, 2] + fit[1, 2] X_in + fit[2, 2] Y_in
Exceptions
std::runtime_errorif the forward transformation cannot be modeled to within the specified tol.

Definition at line 49 of file Mapping.cc.

49  {
50  int const nIn = getNIn();
51  int const nOut = getNOut();
52  detail::assertEqual(lbnd.size(), "lbnd.size", static_cast<std::size_t>(nIn), "nIn");
53  detail::assertEqual(ubnd.size(), "ubnd.size", static_cast<std::size_t>(nIn), "nIn");
54  Array2D fit = ndarray::allocate(ndarray::makeVector(1 + nIn, nOut));
55  int isOK = astLinearApprox(getRawPtr(), lbnd.data(), ubnd.data(), tol, fit.getData());
56  assertOK();
57  if (!isOK) {
58  throw std::runtime_error("Mapping not sufficiently linear");
59  }
60  return fit;
61 }
void assertEqual(T1 val1, std::string const &descr1, T2 val2, std::string const &descr2)
Definition: utils.h:48

◆ lock()

void ast::Object::lock ( bool  wait)
inlineinherited

Lock this object for exclusive use by the calling thread.

The thread-safe public interface to AST is designed so that an error is reported if any thread attempts to use an Object that it has not previously locked for its own exclusive use using this function. When an Object is created, it is initially locked by the thread that creates it, so newly created objects do not need to be explicitly locked. However, if an Object pointer is passed to another thread, the original thread must first unlock it (using astUnlock) and the new thread must then lock it (using astLock) before the new thread can use the Object.

Parameters
[in]waitIf the Object is curently locked by another thread then this function will either report an error or block. If a non-zero value is supplied for "wait", the calling thread waits until the object is available for it to use. Otherwise, an error is reported and the function returns immediately without locking the Object.

Notes

  • The Locked object will belong to the current AST context.
  • This function returns without action if the Object is already locked by the calling thread.
  • If simultaneous use of the same object is required by two or more threads, Object::copy should be used to to produce a deep copy of the Object for each thread. Each copy should then be unlocked by the parent thread (i.e. the thread that created the copy), and then locked by the child thread (i.e. the thread that wants to use the copy).
  • This function returns without action if the AST library has been built without POSIX thread support (i.e. the "-with-pthreads" option was not specified when running the "configure" script).

Definition at line 202 of file Object.h.

202  {
203  astLock(getRawPtr(), static_cast<int>(wait));
204  assertOK();
205  }

◆ makeShim()

template<typename ShimT , typename AstT >
static std::shared_ptr<ShimT> ast::Object::makeShim ( AstObject *  p)
inlinestaticprotectedinherited

Functor to make an astshim instance from a raw AST pointer of the corresponding type.

Template Parameters
ShimTOutput astshim class
AstTOutput AST class

Definition at line 310 of file Object.h.

310  {
311  return std::shared_ptr<ShimT>(new ShimT(reinterpret_cast<AstT *>(p)));
312  }

◆ operator!=()

bool ast::Object::operator!= ( Object const &  rhs) const
inlineinherited

Return True if this and rhs are not equal.

See operator== for details

Definition at line 82 of file Object.h.

82  {
83  return !(*this == rhs); };

◆ operator=() [1/2]

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

◆ operator=() [2/2]

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

◆ operator==()

bool ast::Object::operator== ( Object const &  rhs) const
inherited

Return True if this and rhs are the equal.

For two objects be equal, they both must have the same attributes and all contained objects must be equal.

Definition at line 85 of file Object.cc.

85  {
86  auto thisStr = this->show(false);
87  auto rhsStr = rhs.show(false);
88  return rhsStr == thisStr;
89 }
void show(std::ostream &os, bool showComments=true) const
Print a textual description the object to an ostream.
Definition: Object.cc:158

◆ rate()

double ast::Mapping::rate ( PointD const &  at,
int  ax1,
int  ax2 
) const
inlineinherited

Evaluate the rate of change of the Mapping with respect to a specified input, at a specified position.

The result is estimated by interpolating the function using a fourth order polynomial in the neighbourhood of the specified position. The size of the neighbourhood used is chosen to minimise the RMS residual per unit length between the interpolating polynomial and the supplied Mapping function. This method produces good accuracy but can involve evaluating the Mapping 100 or more times.

Parameters
[in]atThe input position at which the rate of change is to be evaluated.
[in]ax1The index of the output for which the rate of change is to be found (1 for first output).
[in]ax2The index of the input which is to be varied in order to find the rate of change (1 for the first input).
Returns
The rate of change of Mapping output ax1 with respect to input ax2, evaluated at at, or nan if the value cannot be calculated.

Definition at line 215 of file Mapping.h.

215  {
216  detail::assertEqual(at.size(), "at.size", static_cast<std::size_t>(getNIn()), "nIn");
217  double result = astRate(getRawPtr(), const_cast<double *>(at.data()), ax1, ax2);
218  assertOK();
219  return result;
220  }
py::object result
Definition: _schema.cc:429

◆ same()

bool ast::Object::same ( Object const &  other) const
inlineinherited

Does this contain the same AST object as another?

This is a test of identity, not of equality.

Definition at line 212 of file Object.h.

212 { return astSame(getRawPtr(), other.getRawPtr()); }

◆ set()

void ast::Object::set ( std::string const &  setting)
inlineprotectedinherited

Assign a set of attribute values, over-riding any previous values.

The attributes and their new values are specified via a character string, which should contain a comma-separated list of the form: "attribute_1 = value_1, attribute_2 = value_2, ... " where "attribute_n" specifies an attribute name, and the value to the right of each " =" sign should be a suitable textual representation of the value to be assigned. This value will be interpreted according to the attribute's data type.

Notes

  • Attribute names are not case sensitive and may be surrounded by white space
  • Attribute names are not case sensitive and may be surrounded by white space.
  • White space may also surround attribute values, where it will generally be ignored (except for string-valued attributes where it is significant and forms part of the value to be assigned).
  • To include a literal comma or percent sign in the value assigned to an attribute, the whole attribute value should be enclosed in quotation markes.
Exceptions
std::runtime_errorif the attribute is read-only

Definition at line 440 of file Object.h.

440  {
441  astSet(getRawPtr(), "%s", setting.c_str());
442  assertOK();
443  }

◆ setB()

void ast::Object::setB ( std::string const &  attrib,
bool  value 
)
inlineprotectedinherited

Set the value of an attribute as a bool.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 452 of file Object.h.

452  {
453  astSetI(getRawPtr(), attrib.c_str(), value);
454  assertOK();
455  }

◆ setC()

void ast::Object::setC ( std::string const &  attrib,
std::string const &  value 
)
inlineprotectedinherited

Set the value of an attribute as a string.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 464 of file Object.h.

464  {
465  astSetC(getRawPtr(), attrib.c_str(), value.c_str());
466  assertOK();
467  }

◆ setD()

void ast::Object::setD ( std::string const &  attrib,
double  value 
)
inlineprotectedinherited

Set the value of an attribute as a double.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 476 of file Object.h.

476  {
477  astSetD(getRawPtr(), attrib.c_str(), value);
478  assertOK();
479  }

◆ setF()

void ast::Object::setF ( std::string const &  attrib,
float  value 
)
inlineprotectedinherited

Set the value of an attribute as a float.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 488 of file Object.h.

488  {
489  astSetF(getRawPtr(), attrib.c_str(), value);
490  assertOK();
491  }

◆ setI()

void ast::Object::setI ( std::string const &  attrib,
int  value 
)
inlineprotectedinherited

Set the value of an attribute as an int.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 500 of file Object.h.

500  {
501  astSetI(getRawPtr(), attrib.c_str(), value);
502  assertOK();
503  }

◆ setID()

void ast::Object::setID ( std::string const &  id)
inlineinherited

Set ID: object identification string that is not copied.

Definition at line 215 of file Object.h.

215 { setC("ID", id); }
void setC(std::string const &attrib, std::string const &value)
Set the value of an attribute as a string.
Definition: Object.h:464

◆ setIdent()

void ast::Object::setIdent ( std::string const &  ident)
inlineinherited

Set Ident: object identification string that is copied.

Definition at line 218 of file Object.h.

218 { setC("Ident", ident); }

◆ setL()

void ast::Object::setL ( std::string const &  attrib,
long int  value 
)
inlineprotectedinherited

Set the value of an attribute as a long int.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions
std::runtime_errorif the attribute does not exist or the value cannot be converted

Definition at line 512 of file Object.h.

512  {
513  astSetL(getRawPtr(), attrib.c_str(), value);
514  assertOK();
515  }

◆ setReport()

void ast::Mapping::setReport ( bool  report)
inlineinherited

Set Report: report transformed coordinates to stdout?

Definition at line 225 of file Mapping.h.

225 { setB("Report", report); }
void setB(std::string const &attrib, bool value)
Set the value of an attribute as a bool.
Definition: Object.h:452

◆ setUseDefs()

void ast::Object::setUseDefs ( bool  usedefs)
inlineinherited

Set UseDefs: allow use of default values for Object attributes?

Definition at line 221 of file Object.h.

221 { setB("UseDefs", usedefs); }

◆ show() [1/2]

std::string ast::Object::show ( bool  showComments = true) const
inherited

Return a textual description the object as a string.

Parameters
[in]showCommentsShow comments?

Definition at line 165 of file Object.cc.

165  {
167  show(os, showComments);
168  return os.str();
169 }

◆ show() [2/2]

void ast::Object::show ( std::ostream os,
bool  showComments = true 
) const
inherited

Print a textual description the object to an ostream.

Parameters
[in,out]osThe stream to which to write the string representation.
[in]showCommentsShow comments?

Definition at line 158 of file Object.cc.

158  {
159  Stream stream(nullptr, &os);
160  Channel ch(stream, showComments ? "" : "Comment=0");
161  ch.write(*this);
162  assertOK();
163 }

◆ simplified()

std::shared_ptr<Mapping> ast::Mapping::simplified ( ) const
inlineinherited

Return a simplied version of the mapping (which may be a compound Mapping such as a CmpMap).

Simplification eliminates redundant computational steps and merges separate steps which can be performed more efficiently in a single operation. As a simple example, a Mapping which multiplied coordinates by 5, and then multiplied the result by 10, could be simplified to a single step which multiplied by 50. Similarly, a Mapping which multiplied by 5, and then divided by 5, could be reduced to a simple copying operation.

This function should typically be applied to Mappings which have undergone substantial processing or have been formed by merging other Mappings. It is of potential benefit, for example, in reducing execution time if applied before using a Mapping to transform a large number of coordinates.

Note
If the supplied Mapping is a FrameSet, the returned Mapping will be a deep copy of the supplied FrameSet in which all the inter-Frame Mappings have been simplified. Mappings that have a set value for their ref Object_Ident "Ident" attribute are unchanged by simplification. This is so that their individual identity is preserved. This restriction does not apply to the simplification of Frames. The returned mapping is always independent of the original (a deep copy), unlike astSimplify.

Definition at line 248 of file Mapping.h.

248  {
249  AstObject *rawSimpMap = reinterpret_cast<AstObject *>(astSimplify(getRawPtr()));
250  assertOK(rawSimpMap);
251  return Object::fromAstObject<Mapping>(rawSimpMap, true);
252  }

◆ test()

bool ast::Object::test ( std::string const &  attrib) const
inlineinherited

Has this attribute been explicitly set (and not subsequently cleared)?

Warning
Unlike the underlying astTest function, throws an exception if an error results

Notes

  • Attribute names are not case sensitive and may be surrounded by white space.
  • As you might expect, the returned value for a read-only attribute is always false.
Exceptions
std::runtime_errorif an error results.

Definition at line 250 of file Object.h.

250  {
251  bool res = astTest(getRawPtr(), attrib.c_str());
252  assertOK();
253  return res;
254  }

◆ then()

SeriesMap ast::Mapping::then ( Mapping const &  next) const
inherited

Return a series compound mapping this(first(input)) containing shallow copies of the original.

Parameters
[in]nextthe mapping whose input is the output of this mapping
Exceptions
std::invalid_argumentif the number of input axes of next does not match the number of output axes of this mapping.
Warning
The contained mappings are shallow copies (just like AST); if you want deep copies then make them manually.

Definition at line 37 of file Mapping.cc.

37 { return SeriesMap(*this, next); }

◆ tranGridForward() [1/2]

void ast::Mapping::tranGridForward ( PointI const &  lbnd,
PointI const &  ubnd,
double  tol,
int  maxpix,
Array2D const &  to 
) const
inlineinherited

Transform a grid of points in the forward direction.

Parameters
[in]lbndThe coordinates of the centre of the first pixel in the input grid along each dimension, size = nIn
[in]ubndThe coordinates of the centre of the last pixel in the input grid along each dimension, size = nIn
[in]tolThe maximum tolerable geometrical distortion which may be introduced as a result of approximating non-linear Mappings by a set of piece-wise linear transformations. This should be expressed as a displacement within the output coordinate system of the Mapping.

If piece-wise linear approximation is not required, a value of zero may be given. This will ensure that the Mapping is used without any approximation, but may increase execution time.

If the value is too high, discontinuities between the linear approximations used in adjacent panel will be higher. If this is a problem, reduce the tolerance value used.

Parameters
[in]maxpixA value which specifies an initial scale size (in input grid points) for the adaptive algorithm which approximates non-linear Mappings with piece-wise linear transformations. Normally, this should be a large value (larger than any dimension of the region of the input grid being used). In this case, a first attempt to approximate the Mapping by a linear transformation will be made over the entire input region. If a smaller value is used, the input region will first be divided into sub-regions whose size does not exceed " maxpix" grid points in any dimension. Only at this point will attempts at approximation commence. This value may occasionally be useful in preventing false convergence of the adaptive algorithm in cases where the Mapping appears approximately linear on large scales, but has irregularities (e.g. holes) on smaller scales. A value of, say, 50 to 100 grid points can also be employed as a safeguard in general-purpose software, since the effect on performance is minimal. If too small a value is given, it will have the effect of inhibiting linear approximation altogether (equivalent to setting " tol" to zero). Although this may degrade performance, accurate results will still be obtained.
[in]toComputed points, with dimensions (nPts, nOut), where nPts the desired number of points

Definition at line 358 of file Mapping.h.

359  {
360  _tranGrid(lbnd, ubnd, tol, maxpix, true, to);
361  }

◆ tranGridForward() [2/2]

Array2D ast::Mapping::tranGridForward ( PointI const &  lbnd,
PointI const &  ubnd,
double  tol,
int  maxpix,
int  nPts 
) const
inlineinherited

Transform a grid of points in the inverse direction, returning the results as a new Array2D.

See the overload of tranGridForward that outputs the data as the last argument for more information

Definition at line 369 of file Mapping.h.

369  {
370  Array2D to = ndarray::allocate(nPts, getNOut());
371  _tranGrid(lbnd, ubnd, tol, maxpix, true, to);
372  return to;
373  }

◆ tranGridInverse() [1/2]

void ast::Mapping::tranGridInverse ( PointI const &  lbnd,
PointI const &  ubnd,
double  tol,
int  maxpix,
Array2D const &  to 
) const
inlineinherited

Transform a grid of points in the inverse direction.

See tranGridForward for the arguments, swapping nIn and nOut

Definition at line 380 of file Mapping.h.

381  {
382  _tranGrid(lbnd, ubnd, tol, maxpix, false, to);
383  }

◆ tranGridInverse() [2/2]

Array2D ast::Mapping::tranGridInverse ( PointI const &  lbnd,
PointI const &  ubnd,
double  tol,
int  maxpix,
int  nPts 
) const
inlineinherited

Transform a grid of points in the inverse direction.

See tranGridForward for the arguments, swapping nIn and nOut

Definition at line 390 of file Mapping.h.

390  {
391  Array2D to = ndarray::allocate(nPts, getNIn());
392  _tranGrid(lbnd, ubnd, tol, maxpix, false, to);
393  return to;
394  }

◆ under()

ParallelMap ast::Mapping::under ( Mapping const &  next) const
inherited

Return a parallel compound mapping containing shallow copies of the original.

The resulting mapping has getNIn() + next.getNIn() inputs and getNOut() + next.getNOut() outputs. The first getNIn() axes of input are transformed by this mapping, producing the first getNOut() axes of output. The remaining axes of input are processed by next, resulting in the remaining axes of output.

The name comes the way vectors are sometimes shown for matrix multiplication: vertically, with the first axis at the bottom and the last axis at the top.

Parameters
[in]nextthe mapping that processes the final next.getNin() axes of input to produce the final next.getNout() axes of output.
Warning
The contained mappings are shallow copies (just like AST); if you want deep copies then make them manually.

Definition at line 39 of file Mapping.cc.

39 { return ParallelMap(*this, next); }

◆ unlock()

void ast::Object::unlock ( bool  report = false)
inlineinherited

Unlock this object previously locked using lock, so that other threads can use this object.

See lock for further details.

Parameters
[in]reportIf true, an error will be reported if the supplied Object, or any Object contained within the supplied Object, is not currently locked by the running thread. If false, such Objects will be left unchanged, and no error will be reported.

Notes

  • This function attempts to execute even if AST's global error status is set, but no further error report will be made if it subsequently fails under these circumstances.
  • All unlocked Objects are excluded from AST context handling until they are re-locked using astLock.
  • This function returns without action if the Object is not currently locked by any thread. If it is locked by the running thread, it is unlocked. If it is locked by another thread, an error will be reported if "error" is non-zero.
  • This function returns without action if the AST library has been built without POSIX thread support (i.e. the "-with-pthreads" option was not specified when running the "configure" script).

Definition at line 280 of file Object.h.

280  {
281  astUnlock(getRawPtr(), static_cast<int>(report));
282  assertOK();
283  }

Friends And Related Function Documentation

◆ Object

friend class Object
friend

Definition at line 62 of file MathMap.h.


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