teca_coordinate_util Namespace Reference

Codes dealing with operations on coordinate systems. More...

Classes
struct	ascend_bracket
	comparator implementing bracket for ascending input arrays More...
struct	descend_bracket
	comparator implementing bracket for descending input arrays More...
struct	equal_error
struct	equal_tt
	traits classes used to get default tolerances for comparing numbers of a given precision. More...
struct	equal_tt< double >
struct	equal_tt< float >
struct	equal_tt< long double >
struct	geq
	Greater than or equal to predicate. More...
struct	gt
	Greater than predicate. More...
struct	interpolate_t
	A functor templated on order of accuracy for above Cartesian mesh interpolants. More...
struct	interpolate_t< 0 >
	Zero'th order interpolant specialization. More...
struct	interpolate_t< 1 >
	First order interpolant specialization. More...
struct	leq
	Less than or equal to predicate. More...
struct	lt
	Less than predicate. More...
class	teca_coordinate_axis_validator
	Check that cooridnate arrays from different sources match a refrence array. More...
class	teca_validate_arrays
	compares a set of arrays against a reference array More...

Functions
template<typename T >
bool	equal (T a, T b, T relTol=equal_tt< T >::relTol(), T absTol=equal_tt< T >::absTol(), typename std::enable_if< std::is_floating_point< T >::value >::type *=0)
template<typename T >
bool	equal (T a, T b, T relTol=0, T absTol=0, typename std::enable_if< std::is_integral< T >::value >::type *=0)
	Compare two integral numbers. More...
template<typename T >
bool	equal (T a, T b, std::string &diagnostic, T relTol=equal_tt< T >::relTol(), T absTol=equal_tt< T >::absTol(), typename std::enable_if< std::is_floating_point< T >::value >::type *=0)
template<typename T >
bool	equal (T a, T b, std::string &diagnostic, T relTol=0, T absTol=0, typename std::enable_if< std::is_integral< T >::value >::type *=0)
bool	equal (const const_p_teca_variant_array &array1, const const_p_teca_variant_array &array2, double absTol, double relTol, int &errorNo, std::string &errorStr)
template<typename data_t , typename bracket_t = ascend_bracket<data_t>>
int	index_of (const data_t *data, unsigned long l, unsigned long r, data_t val, bool lower, unsigned long &id)
template<typename T >
int	index_of (const T *data, size_t l, size_t r, T val, unsigned long &id)
int	bounds_to_extent (const double *bounds, const const_p_teca_variant_array &x, const const_p_teca_variant_array &y, const const_p_teca_variant_array &z, unsigned long *extent)
int	bounds_to_extent (const double *bounds, const const_p_teca_variant_array &x, unsigned long *extent)
int	bounds_to_extent (const double *bounds, const teca_metadata &md, unsigned long *extent)
template<typename T >
int	index_of (const const_p_teca_cartesian_mesh &mesh, T x, T y, T z, unsigned long &i, unsigned long &j, unsigned long &k)
int	time_step_of (const const_p_teca_variant_array &time, bool lower, bool clamp, const std::string &calendar, const std::string &units, const std::string &date, unsigned long &step)
int	time_to_string (double val, const std::string &calendar, const std::string &units, const std::string &format, std::string &date)
template<typename int_t >
void	get_table_offsets (const int_t *index, unsigned long n_rows, unsigned long &n_entities, std::vector< unsigned long > &counts, std::vector< unsigned long > &offsets, std::vector< unsigned long > &ids)
template<typename CT , typename DT >
int	interpolate_nearest (CT cx, CT cy, CT cz, const CT *p_x, const CT *p_y, const CT *p_z, const DT *p_data, unsigned long ihi, unsigned long jhi, unsigned long khi, unsigned long nx, unsigned long nxy, DT &val)
template<typename coord_t , typename data_t >
int	interpolate_nearest (coord_t cx, coord_t cy, const coord_t *p_x, const coord_t *p_y, const data_t *p_data, unsigned long ihi, unsigned long jhi, unsigned long nx, data_t &val)
template<typename CT , typename DT >
int	interpolate_linear (CT cx, CT cy, CT cz, const CT *p_x, const CT *p_y, const CT *p_z, const DT *p_data, unsigned long ihi, unsigned long jhi, unsigned long khi, unsigned long nx, unsigned long nxy, DT &val)
template<typename CT , typename DT >
int	interpolate_linear (CT cx, CT cy, const CT *p_x, const CT *p_y, const DT *p_data, unsigned long ihi, unsigned long jhi, unsigned long nx, DT &val)
int	validate_centering (int centering)
	return 0 if the centering is one of the values defined in teca_array_attributes More...
template<typename num_t >
int	convert_cell_extent (num_t *extent, int centering)
	convert from a cell extent to a face, edge or point centered extent More...
int	get_cartesian_mesh_extent (const teca_metadata &md, unsigned long *whole_extent, double *bounds)
int	get_cartesian_mesh_bounds (const const_p_teca_variant_array x, const const_p_teca_variant_array y, const const_p_teca_variant_array z, double *bounds)
	get the mesh's bounds from the coordinate axis arrays More...
template<typename num_t >
int	covers_ascending (const num_t *whole, const num_t *part)
template<typename num_t >
int	covers (const num_t *whole, const num_t *part)
template<typename num_t >
int	same_orientation (const num_t *whole, const num_t *part)
int	clamp_dimensions_of_one (unsigned long nx_max, unsigned long ny_max, unsigned long nz_max, unsigned long *extent, bool verbose)
int	validate_extent (unsigned long nx_max, unsigned long ny_max, unsigned long nz_max, unsigned long *extent, bool verbose)

Detailed Description

Codes dealing with operations on coordinate systems.

Function Documentation

bounds_to_extent()

int teca_coordinate_util::bounds_to_extent	(	const double *	bounds,
		const const_p_teca_variant_array &	x,
		const const_p_teca_variant_array &	y,
		const const_p_teca_variant_array &	z,
		unsigned long *	extent
	)

Convert bounds to extents. return non-zero if the requested bounds are not in the given coordinate arrays. coordinate arrays must not be empty.

clamp_dimensions_of_one()

int teca_coordinate_util::clamp_dimensions_of_one	(	unsigned long	nx_max,
		unsigned long	ny_max,
		unsigned long	nz_max,
		unsigned long *	extent,
		bool	verbose
	)

where array dimensions specified by nx_max, ny_max, and nz_max are 1, and the extent would be out of bounds, set the extent to [0, 0]. If verbose is set, a warning is reported when the extent was clamped in one or more directions. The return is non zero if any direction was clamped and 0 otherwise.

convert_cell_extent()

template<typename num_t >

int teca_coordinate_util::convert_cell_extent	(	num_t *	extent,
		int	centering
	)

convert from a cell extent to a face, edge or point centered extent

covers()

template<typename num_t >

int teca_coordinate_util::covers	(	const num_t *	whole,
		const num_t *	part
	)

Check that one Cartesian region covers the other, taking into account the order of the coordinates. assumes that the regions are specified in the same orientation.

covers_ascending()

template<typename num_t >

int teca_coordinate_util::covers_ascending	(	const num_t *	whole,
		const num_t *	part
	)

Check that one Cartesian region covers the other coordinates must be in ascending order. assumes that both regions are specified in ascending order.

equal() [1/5]

bool teca_coordinate_util::equal	(	const const_p_teca_variant_array &	array1,
		const const_p_teca_variant_array &	array2,
		double	absTol,
		double	relTol,
		int &	errorNo,
		std::string &	errorStr
	)

Compare two variant arrays elementwise for equality. If the arrays fail to compare within the specified tolerance errorNo will contain one of the equal_error enumerations and errorStr will conatin a diagnostic message describing the failure.

equal() [2/5]

template<typename T >

bool teca_coordinate_util::equal	(	T	a,
		T	b,
		std::string &	diagnostic,
		T	relTol = 0,
		T	absTol = 0,
		typename std::enable_if< std::is_integral< T >::value >::type *	= 0
	)

Compare two integral numbers. This overload may be used in regression tests or other contexts where a diagnostic error message should be reported if the numbers are not equal.

equal() [3/5]

template<typename T >

bool teca_coordinate_util::equal	(	T	a,
		T	b,
		std::string &	diagnostic,
		T	relTol = equal_tt<T>::relTol(),
		T	absTol = equal_tt<T>::absTol(),
		typename std::enable_if< std::is_floating_point< T >::value >::type *	= 0
	)

Compare two floating point numbers. This overload may be used in regression tests or other contexts where a diagnostic error message should be reported if the numbers are not equal.

equal() [4/5]

template<typename T >

bool teca_coordinate_util::equal	(	T	a,
		T	b,
		T	relTol = 0,
		T	absTol = 0,
		typename std::enable_if< std::is_integral< T >::value >::type *	= 0
	)

Compare two integral numbers.

equal() [5/5]

template<typename T >

bool teca_coordinate_util::equal	(	T	a,
		T	b,
		T	relTol = equal_tt<T>::relTol(),
		T	absTol = equal_tt<T>::absTol(),
		typename std::enable_if< std::is_floating_point< T >::value >::type *	= 0
	)

Compare two floating point numbers. absTol handles comparing numbers very close to zero. relTol handles comparing larger values.

get_cartesian_mesh_bounds()

int teca_coordinate_util::get_cartesian_mesh_bounds	(	const const_p_teca_variant_array	x,
		const const_p_teca_variant_array	y,
		const const_p_teca_variant_array	z,
		double *	bounds
	)

get the mesh's bounds from the coordinate axis arrays

get_cartesian_mesh_extent()

int teca_coordinate_util::get_cartesian_mesh_extent	(	const teca_metadata &	md,
		unsigned long *	whole_extent,
		double *	bounds
	)

Given Cartesian mesh metadata extract whole_extent and bounds if bounds metadata is not already present then it is initialized from coordinate arrays. It's an error if whole_extent or coordinate arrays are not present. return zero if successful.

get_table_offsets()

template<typename int_t >

void teca_coordinate_util::get_table_offsets	(	const int_t *	index,
		unsigned long	n_rows,
		unsigned long &	n_entities,
		std::vector< unsigned long > &	counts,
		std::vector< unsigned long > &	offsets,
		std::vector< unsigned long > &	ids
	)

build random access data structures for an indexed table. the index column gives each entity a unique id. the index is used to identify rows that belong in the entity. it is assumed that an entity occupies consecutive rows. the returns are: n_entities, the number of entities found; counts, the number of rows used by each entity; offsets, the starting row of each entity; ids, a new set of ids for the entities starting from 0

index_of() [1/3]

template<typename T >

int teca_coordinate_util::index_of	(	const const_p_teca_cartesian_mesh &	mesh,
		T	x,
		T	y,
		T	z,
		unsigned long &	i,
		unsigned long &	j,
		unsigned long &	k
	)

Get the i,j,k cell index of point x,y,z in the given mesh. return 0 if successful.

index_of() [2/3]

template<typename data_t , typename bracket_t = ascend_bracket<data_t>>

int teca_coordinate_util::index_of	(	const data_t *	data,
		unsigned long	l,
		unsigned long	r,
		data_t	val,
		bool	lower,
		unsigned long &	id
	)

binary search that will locate index bounding the value above or below such that data[i] <= val or val <= data[i+1] depending on the value of lower. return 0 if the value is found. the comp0 and comp1 template parameters let us operate on both ascending and descending input. defaults are set for ascending inputs.

index_of() [3/3]

template<typename T >

int teca_coordinate_util::index_of	(	const T *	data,
		size_t	l,
		size_t	r,
		T	val,
		unsigned long &	id
	)

binary search that will locate index of the given value. return 0 if the value is found.

interpolate_linear() [1/2]

template<typename CT , typename DT >

int teca_coordinate_util::interpolate_linear	(	CT	cx,
		CT	cy,
		const CT *	p_x,
		const CT *	p_y,
		const DT *	p_data,
		unsigned long	ihi,
		unsigned long	jhi,
		unsigned long	nx,
		DT &	val
	)

1st order (linear) interpolation for nodal data on stretched Cartesian mesh. This overload implements the special case where both source and target data are in a 2D x-y plane using fewer operations than the general 3D implementation. cx, cy, cz is the location to interpolate to p_x, p_y, p_z array arrays containing the source coordinates with extents [0, ihi, 0, jhi, 0, khi] p_data is the field to interpolate from val is the result returns 0 if successful, an error occurs if cx, cy, cz is outside of the source coordinate system

interpolate_linear() [2/2]

template<typename CT , typename DT >

int teca_coordinate_util::interpolate_linear	(	CT	cx,
		CT	cy,
		CT	cz,
		const CT *	p_x,
		const CT *	p_y,
		const CT *	p_z,
		const DT *	p_data,
		unsigned long	ihi,
		unsigned long	jhi,
		unsigned long	khi,
		unsigned long	nx,
		unsigned long	nxy,
		DT &	val
	)

1st order (linear) interpolation for nodal data on stretched Cartesian mesh. This overload implements the general 3D case. cx, cy, cz is the location to interpolate to p_x, p_y, p_z array arrays containing the source coordinates with extents [0, ihi, 0, jhi, 0, khi] p_data is the field to interpolate from val is the result returns 0 if successful, an error occurs if cx, cy, cz is outside of the source coordinate system

interpolate_nearest() [1/2]

template<typename coord_t , typename data_t >

int teca_coordinate_util::interpolate_nearest	(	coord_t	cx,
		coord_t	cy,
		const coord_t *	p_x,
		const coord_t *	p_y,
		const data_t *	p_data,
		unsigned long	ihi,
		unsigned long	jhi,
		unsigned long	nx,
		data_t &	val
	)

0th order (nearest neighbor) interpolation for nodal data on a stretched Cartesian mesh. This overload implements the special case where both source and target mesh data are in a 2D x-y plane using fewer operations than the general 3D implementation. cx, cy, cz is the location to interpolate to p_x, p_y, p_z array arrays containing the source coordinates with extents [0, ihi, 0, jhi, 0, khi] p_data is the field to interpolate from val is the result returns 0 if successful, an error occurs if cx, cy, cz is outside of the source coordinate system

interpolate_nearest() [2/2]

template<typename CT , typename DT >

int teca_coordinate_util::interpolate_nearest	(	CT	cx,
		CT	cy,
		CT	cz,
		const CT *	p_x,
		const CT *	p_y,
		const CT *	p_z,
		const DT *	p_data,
		unsigned long	ihi,
		unsigned long	jhi,
		unsigned long	khi,
		unsigned long	nx,
		unsigned long	nxy,
		DT &	val
	)

0th order (nearest neighbor) interpolation for nodal data on a stretched Cartesian mesh. This overload implements the general 3D case. cx, cy, cz is the location to interpolate to p_x, p_y, p_z array arrays containing the source coordinates with extents [0, ihi, 0, jhi, 0, khi] p_data is the field to interpolate from val is the result returns 0 if successful, an error occurs if cx, cy, cz is outside of the source coordinate system

same_orientation()

template<typename num_t >

int teca_coordinate_util::same_orientation	(	const num_t *	whole,
		const num_t *	part
	)

check that two Cartesian regions have the same orientation ie they are either both specified in ascending or descending order.

time_step_of()

int teca_coordinate_util::time_step_of	(	const const_p_teca_variant_array &	time,
		bool	lower,
		bool	clamp,
		const std::string &	calendar,
		const std::string &	units,
		const std::string &	date,
		unsigned long &	step
	)

given a human readable date string in YYYY-MM-DD hh:mm:ss format and a list of floating point offset times in the specified calendar and units find the closest time step. return 0 if successful see index_of for a description of lower, if clamp is true then when the date falls outside of the time values either the first or last time step is returned.

time_to_string()

int teca_coordinate_util::time_to_string	(	double	val,
		const std::string &	calendar,
		const std::string &	units,
		const std::string &	format,
		std::string &	date
	)

given a time value (val), associated time units (units), and calendar (calendar), return a human-readable rendering of the date (date) in a strftime-format (format). return 0 if successful.

validate_centering()

int teca_coordinate_util::validate_centering

(

int

centering

)

return 0 if the centering is one of the values defined in teca_array_attributes

validate_extent()

int teca_coordinate_util::validate_extent	(	unsigned long	nx_max,
		unsigned long	ny_max,
		unsigned long	nz_max,
		unsigned long *	extent,
		bool	verbose
	)

Return 0 if the passed extent does not exceed array dimensions specified in nx_max, ny_max, and nz_max. If verbose is set, an error is reported via TECA_ERROR when the extent would be out of bounds.