Class table3d (o2scl)

O2scl : Class List

class table3d

A data structure containing one or more slices of two-dimensional data points defined on a grid.

Todo

In class table3d:

• Future: Improve interpolation and derivative caching, possibly through non-const versions of the interpolation functions.

• Future: Should there be a clear_grid() function separate from clear_data() and clear()?

• Future: Allow the user to more clearly probe ‘size_set’ vs. ‘xy_set’? (AWS 07/18: This is apparently resolved.)

Iterator types

typedef std::map<std::string, size_t, std::greater<std::string>>::iterator map_iter

typedef std::map<std::string, size_t, std::greater<std::string>>::const_iterator map_const_iter

Data storage

std::map<std::string, double> constants

The list of constants.

size_t numx

The size of the x grid.

size_t numy

The size of the y grid.

std::map<std::string, size_t, std::greater<std::string>> tree

A tree connecting column names to list indexes.

std::string xname

The name for the x grid.

std::string yname

The name for the y grid.

std::vector<ubmatrix> list

The pointers to the matrices.

ubvector xval

The x grid.

ubvector yval

The y grid.

bool xy_set

True if the grid has been set.

bool size_set

True if the size of the grid has been set.

bool has_slice

True if the table has at least one slice.

size_t itype

The interpolation type.

Initialization

template<class vec_t, class vec2_t>
inline void set_xy(std::string x_name, size_t nx, const vec_t &x, std::string y_name, size_t ny, const vec2_t &y)

Initialize the x-y grid.

This function will not allow you to redefine the grid when there is data in the if a grid of a different size was already set from a previous call to either set_xy() or set_size(). However, you may freely redefine the grid after a call to clear_data() or clear_table(). You may change individual grid points at any time with set_grid_x() and set_grid_y().

void set_xy(std::string x_name, uniform_grid<double> gx, std::string y_name, uniform_grid<double> gy)

Initialize the x-y grid with uniform_grid objects.

This function will not allow you to redefine the grid when there is data in the if a grid of a different size was already set from a previous call to either set_xy() or set_size(). However, you may freely redefine the grid after a call to clear_data() or clear_table(). You may change individual grid points at any time with set_grid_x() and set_grid_y().

void set_size(size_t nx, size_t ny)

Initialize size.

This function will not allow you to resize the if it already has data or if the size has already been set with the set_xy() function, unless you clear the data with clear_data() or the with clear_table() first.

On-grid get and set methods

void set(size_t ix, size_t iy, std::string name, double val)

Set element in slice name at location ix,iy to value val.

void set(size_t ix, size_t iy, size_t z, double val)

Set element in slice of index z at location ix,iy to value val .

double &get(size_t ix, size_t iy, std::string name)

Get element in slice name at location ix,iy

const double &get(size_t ix, size_t iy, std::string name) const

Get element in slice name at location ix,iy (const version)

double &get(size_t ix, size_t iy, size_t z)

Get element in slice of index z at location ix,iy

const double &get(size_t ix, size_t iy, size_t z) const

Get element in slice of index z at location ix,iy (const version)

Off-grid get and set methods

These methods return the value of a slice on the grid point nearest to a user-specified location. For interpolation into a point off the grid, use table3d::interp().

void set_val(double x, double y, std::string name, double val)

Set element in slice name at the nearest location to x,y to value val.

void set_val(double x, double y, size_t z, double val)

Set element in slice of index z at the nearest location to x,y to value val.

double &get_val(double x, double y, std::string name)

Get element in slice name at location closest to x,y

const double &get_val(double x, double y, std::string name) const

Get element in slice name at location closest to x,y

double &get_val(double x, double y, size_t z)

Get element in slice of index z at location closest to x,y

const double &get_val(double x, double y, size_t z) const

Get element in slice of index z at location closest to x,y

template<class vec_t>
inline void set_slices(double x, double y, size_t nv, vec_t &vals)

Set elements in the first nv slices at the nearest location to x,y to value val.

template<class vec_t>
inline void get_slices(double x, double y, size_t nv, vec_t &v)

Get the data for every slice at the nearest location to x,y

Off-grid get and set methods returning nearest point

void set_val_ret(double &x, double &y, std::string name, double val)

Set element in slice name at the nearest location to x,y to value val.

void set_val_ret(double &x, double &y, size_t z, double val)

Set element in slice of index z at the nearest location to x,y to value val.

double &get_val_ret(double &x, double &y, std::string name)

Get element in slice name at location closest to x,y, and also return the corresponding values of x and y.

const double &get_val_ret(double &x, double &y, std::string name) const

Get element in slice name at location closest to x,y, and also return the corresponding values of x and y.

double &get_val_ret(double &x, double &y, size_t z)

Get element in slice of index z at location closest to x,y, and also return the corresponding values of x and y.

const double &get_val_ret(double &x, double &y, size_t z) const

Get element in slice of index z at location closest to x,y, and also return the corresponding values of x and y.

void add_slice_from_table(table3d &source, std::string slice, std::string dest_slice = "", int verbose = 0)

This function adds a slice from a different table3d object, interpolating the results into the current table3d object.

template<class vec_t>
inline void set_slices_ret(double &x, double &y, size_t nv, vec_t &vals)

Set elements in the first nv slices at the nearest location to x,y to values vals.

template<class vec_t>
inline void get_slices_ret(double &x, double &y, size_t nv, vec_t &vals)

Get elements in the first nv slices at the nearest location to x,y to value val.

Grid information get and set methods

void set_grid_x(size_t ix, double val)

Set x grid point at index ix.

void set_grid_y(size_t iy, double val)

Set y grid point at index iy.

double get_grid_x(size_t ix) const

Get x grid point at index ix.

double get_grid_y(size_t iy) const

Get y grid point at index iy.

std::string get_x_name() const

Get the name of the x grid variable.

std::string get_y_name() const

Get the name of the y grid variable.

void set_x_name(std::string name)

Set the name of the x grid variable.

void set_y_name(std::string name)

Set the name of the y grid variable.

const ubvector &get_x_data() const

Get a const reference to the full x grid.

const ubvector &get_y_data() const

Get a const reference to the full y grid.

Size get methods

void get_size(size_t &nx, size_t &ny) const

Get the size of the slices.

size_t get_nx() const

Get the x size.

size_t get_ny() const

Get the y size.

size_t get_nslices() const

Get the number of slices.

bool is_size_set() const

True if the size of the table has been set.

bool is_xy_set() const

True if the grid has been set.

Slice manipulation

void line_of_names(std::string names)

Create a set of new slices specified in the string names.

std::string get_slice_name(size_t z) const

Returns the name of slice with index z.

void new_slice(std::string name)

Add a new slice.

void set_slice_all(std::string name, double val)

Set all of the values in slice name to val.

size_t lookup_slice(std::string name) const

Find the index for slice named name.

bool is_slice(std::string name, size_t &ix) const

Return true if slice is already present.

void rename_slice(std::string olds, std::string news)

Rename slice named olds to news.

This is slow since we have to delete the column and re-insert it. This process in turn mangles all of the iterators in the list.

void delete_slice(std::string sl)

void copy_slice(std::string src, std::string dest)

Make a new slice named dest which is a copy of the slice with name given in src.

void init_slice(std::string slice, double val)

Initialize all values of slice named scol to val.

Note

This will call the error handler if the value val is not finite (i.e. either Inf or NaN).

const ubmatrix &get_slice(std::string slice) const

Return a constant reference to a slice.

const ubmatrix &get_slice(size_t iz) const

Return a constant reference to a slice.

ubmatrix &get_slice(std::string slice)

Return a constant reference to a slice.

ubmatrix &get_slice(size_t iz)

Return a constant reference to a slice.

const std::vector<ubmatrix> &get_data()

Return a constant reference to all the slice data.

template<class mat_t>
inline void copy_to_slice(mat_t &m, std::string slice_name)

Copy to a slice from a generic matrix object.

The type mat_t can be any type with an operator(,) method.

Lookup and search methods

void lookup_x(double val, size_t &ix) const

Look for a value in the x grid.

void lookup_y(double val, size_t &iy) const

Look for a value in the y grid.

void lookup(double val, std::string slice, size_t &ix, size_t &iy) const

Look for a value in a specified slice.

Interpolation, differentiation, and integration

void set_interp_type(size_t interp_type)

Specify the interpolation type.

size_t get_interp_type() const

Get the interpolation type.

double interp(double x, double y, std::string name) const

Interpolate x and y in slice named name.

double deriv_x(double x, double y, std::string name) const

Interpolate the derivative of the data with respect to the x grid at point x and y in slice named name.

double deriv_y(double x, double y, std::string name) const

Interpolate the derivative of the data with respect to the y grid at point x and y in slice named name.

double deriv_xy(double x, double y, std::string name) const

Interpolate the mixed second derivative of the data at point x and y in slice named name.

double integ_x(double x1, double x2, double y, std::string name) const

Interpolate the integral of the data respect to the x grid.

double integ_y(double x, double y1, double y2, std::string name) const

Interpolate the integral of the data respect to the y grid.

template<class vec_t>
inline void interp_slices(double x, double y, size_t nv, vec_t &v)

Fill a vector of interpolated values from each slice at the point x,y

void deriv_x(std::string fname, std::string fpname)

Create a new slice, named fpname, containing the derivative of fname with respect to the x coordinate.

void deriv_y(std::string fname, std::string fpname)

Create a new slice, named fpname, containing the derivative of fname with respect to the y coordinate.

Extract 2-dimensional tables

void extract_x(double x, table<> &t)

Extract a table at a fixed x grid point.

Note

All of the information previously stored in t will be lost.

void extract_y(double y, table<> &t)

Extract a table at a fixed y grid point.

Note

All of the information previously stored in t will be lost.

Clear methods

void zero_table()

Zero the data entries but keep the slice names and grid.

void clear()

Clear everything.

void clear_data()

Remove all of the data by setting the number of lines to zero.

This leaves the column names intact and does not remove the constants.

Summary method

void summary(std::ostream *out = 0, int ncol = 79) const

Output a summary of the information stored.

Outputs the number of constants, the grid information, and a list of the slice names

friend void hdf_output(o2scl_hdf::hdf_file &hf, const table3d &t, std::string name)

friend void hdf_input(o2scl_hdf::hdf_file &hf, table3d &t, std::string name)

Contour lines method

template<class vec_t>
inline void slice_contours(std::string name, size_t nlev, vec_t &levs, std::vector<contour_line> &clines)

Create contour lines from the slice named name.

This uses contour to compute contour lines (stored in clines) from slice name given nlev contour levels in levs .

Manipulating constants

virtual void add_constant(std::string name, double val)

Add a constant, or if the constant already exists, change its value.

virtual void remove_constant(std::string name)

Remove a constant.

virtual int set_constant(std::string name, double val, bool err_on_notfound = true)

Set a constant equal to a value, but don’t add it if not already present.

If err_on_notfound is true (the default), then this function throws an exception if a constant with name name is not found. If err_on_notfound is false, then if a constant with name name is not found this function just silently returns o2scl::exc_enotfound.

virtual bool is_constant(std::string name) const

Test if name is a constant.

virtual double get_constant(std::string name)

Get a constant.

virtual void get_constant(size_t ix, std::string &name, double &val) const

Get a constant by index.

inline virtual size_t get_nconsts() const

Get the number of constants.

Miscellaneous methods

int read_gen3_list(std::istream &fin, int verbose = 0, double eps = 1.0e-12)

Read a generic table3d object specified as a text file.

This function reads a set of columns of numerical values, presuming that the first column is the x-grid value, the second column is the y-grid value, and the remaining columns are slices to be added. If the first row appears to be strings rather than numerical values, then the first row is used for the x name, y name, and slice names. Values in the first two columns which differ by less than eps are assumed to refer to the same grid point. If not all combinations of x and y are found, then those entries are left unchanged in all slices.

\verbatim embed:rst

.. todo:: 

   In class table3d::read_gen3_list():

   Future: It would be great to add a function which generates
   a text file in this format as well. 

   Future: This function is very similar to from_table() below,
   so it might be possible just to avoid code duplication
   between these two functions.

\endverbatim

template<class vec_t>
inline int read_table(const o2scl::table<vec_t> &tab, std::string xname2 = "", std::string yname2 = "", double empty_value = 0.0, int verbose = 0, bool err_on_fail = true, double eps = 1.0e-12)

Set the current table3d object by reading a o2scl::table.

The function reads the table \c tab and attempts to convert it
to a table3d object by using column \c xname2 and \c yname2 as
the values for the x- and y-grids. This function is particularly
useful for a table which has the following structure:
\verbatim
x y z
1 1 4.5
1 2 2.0
1 3 1.6
2 1 1.5
2 3 4.7
3 1 3.9
3 2 4.5
3 3 4.8
\endverbatim
If \c xname2 or \c yname2 are empty strings, then the first or
second column is presumed to hold the value for the x- or
y-grid, respectively. The grids in the table3d object are set
to include all possible values in the associated column,
treating any values with a relative deviation of \c eps as
identical. In the example above, using "x" and "y" as the
columns for the table3d grid, the grids would both be [1,2,3].

New slices are created in the table3d for each column in the
table object which is not part of the grid. Any current data
stored in the table3d object is destroyed. All slices are
filled with \c empty_value before being assigned values from
\c tab. For example, in the table above, the slice named "z"
in the new table3d object would have a final entry of 0.0 for
(x,y) at (2,2) because there is no entry in the original table
for that location.

template<class vec_t, class vec2_t, class vec3_t>
inline void create_table_hist_set(vec_t &grid, std::string direction, std::string name, vec2_t &bin_edges, vec3_t &bin_grid, std::string bin_name, o2scl::table_units<> &t, std::string pattern, std::string slice, bool use_regex = false, int verbose = 0)

Create a table3d object by histogramming a series of columns from a o2scl::table_units object.

Create a new table3d object from a histogram a series of columns from a table_units object. If direction is “x”, then arrange these histograms “vertically”, so that the x-coordinate (named name) of the ith column is taken from the ith entry of grid. If direction is “y”, then arrange these histograms “horizontally”, so that the y-coordinate (named name) of the ith column is taken from the ith entry of grid. The histograms (in either case) are all created using the bin edges from bin_edges. When direction is “x” (“y”), bin_grid is used for the y-coordinate (x-coordinate) of the new table3d object. This coordinate is named bin_name. The columns are taken from all those columns in t which match the regular expression in pattern. All of the new histogram data is imported into a slice named slide in a new table3d object. one

The vector bin_grid must have a size which is exactly 1 smaller than the size of the vector bin_edges. The number of columns matched from table t by the pattern specified in pattern must be exactly equal to the size of the vector grid.

Any data in the current table3d object is destroyed.

template<class vec_t>
inline void create_table_hist_set_minmax(vec_t &grid, std::string direction, std::string name, size_t n_bins, std::string bin_name, o2scl::table_units<> &t, std::string pattern, std::string slice, double factor = 1.0e-10, bool use_regex = false, int verbose = 0)

Create a table3d object by histogramming a series of columns from a o2scl::table_units object.

This function works very similarly to the more detailed function with the same name, but it uses the minimum and maximum values of the table columns in order to automatically create the histogram bin edges from a set of n_bins bins. It uses these bin edges to create the bin_grid and bin_edges objects.

template<class vec_t, class vec2_t>
inline void create_table_hist_set_edgeonly(vec_t &grid, std::string direction, std::string name, vec2_t &bin_edges, std::string bin_name, o2scl::table_units<> &t, std::string pattern, std::string slice, bool use_regex = false, int verbose = 0)

Create a table3d object by histogramming a series of columns from a o2scl::table_units object.

This function works very similarly to the more detailed function with the same name, but it uses bin_edges to automatically compute the bin_grid argument. If bin_edges appears logarithmic, it uses the geometric mean of adjacent edges, otherwise it uses the arithmetic mean.

inline virtual const char *type()

Return the type, "table3d".

Parsing mathematical functions specified as strings

template<class resize_mat_t>
inline int function_matrix(std::string function, resize_mat_t &mat, bool throw_on_err = true)

Fill a matrix from the function specified in function.

void function_slice(std::string function, std::string col)

Make a column from function and add it to the table.

If the column already exists, the data already present is overwritten with the result.

table3d slice_to_uniform_grid(std::string slice, size_t xpts, bool log_x, size_t ypts, bool log_y)

Copy slice named slice to a new o2scl::table3d object with a uniform grid using the current interpolation type.

table3d table_to_uniform_grid(size_t xpts, bool log_x, size_t ypts, bool log_y)

Copy entire table to a new o2scl::table3d object with a uniform grid using the current interpolation type.

hist_2d to_hist_2d(std::string slice, int verbose = 1)

Convert slice named slice to a hist_2d object.

hist to_hist(std::string slice, size_t n_bins, int verbose = 1)

Convert slice named slice to a hist object.

Tree iterator boundaries

inline map_iter begin()

Return the beginning of the slice tree.

inline map_iter end()

Return the end of the slice tree.

inline map_const_iter const_begin() const

Return the beginning of the slice tree.

inline map_const_iter const_end() const

Return the end of the slice tree.

Public Types

typedef boost::numeric::ublas::vector<double> ubvector

typedef boost::numeric::ublas::matrix<double> ubmatrix

typedef boost::numeric::ublas::matrix_row<const ubmatrix> ubmatrix_row

typedef boost::numeric::ublas::matrix_column<const ubmatrix> ubmatrix_column

Public Functions

table3d()

Create a new 3D .

virtual ~table3d()

table3d(o2scl::table_units<> &t, std::string colx, std::string coly)

Create a table3d object from a table, assuming scolx and scoly store the x- and y-grid data, respectively.

table3d(const table3d &t)

Copy constructor.

table3d &operator=(const table3d &t)

Copy constructor.