6. mglData class

Class for working with data array. This class is defined in #include <mgl/mgl_data.h>. The class has functions for easy and safe allocation, resizing, loading and saving, modifying of data arrays. Also it can numerically differentiate and integrate data, interpolate, fill data by formula and so on. Class supports data with dimensions up to 3 (like function of 3 variables – x,y,z). The internal representation of numbers is float. Float type was chosen because it has smaller size in memory and usually it has enough precision in plotting purposes. You can change it by selecting option --enable-double at the library configuring (see section Installation and usage).

6.1 Public variables

Variable of mglData: float * a

Data array itself. The flat data representation is used. For example, matrix [nx x ny] is presented as flat (1d-) array with length nx*ny. The element with indexes {i, j, k} is a[i+nx*j+nx*ny*k] (indexes are zero based).

Variable of mglData: int nx

Number of points in 1st dimensions (’x’ dimension).

Variable of mglData: int ny

Number of points in 2nd dimensions (’y’ dimension).

Variable of mglData: int nz

Number of points in 3d dimensions (’z’ dimension).

Variable of mglData: char * id

Column (or slice if nz>1) names – one character per column.

6.2 Create and delete

Constructor on mglData: mglData (int mx=1, int my=1, int mz=1)

Default constructor. Allocates the memory for data array and initializes it by zero.

Constructor on mglData: mglData (const char *fname)

Initializes the data by reading from file.

Constructor on mglData: mglData (const mglData &dat)

Initiates by other mglData instance.

Method on mglData (C++, Python): void Create (int mx, int my=1, int mz=1)

C function: void mgl_data_create (HMDT dat, int mx, int my, int mz)

Creates or recreates the array with specified size and fills it by zero. This function does nothing if one of parameters mx, my, mz is zero or negative.

Method on mglData (C++): void Set (const float *A, int NX, int NY=1, int NZ=1)

Method on mglData (C++): void Set (const double *A, int NX, int NY=1, int NZ=1)

C function: void mgl_data_set_float (HMDT dat, const float *A, int NX, int NY, int NZ)

C function: void mgl_data_set_double (HMDT dat, const double *A, int NX, int NY, int NZ)

Allocates memory and copies the data from the flat float* or double* array.

Method on mglData (C++): void Set (const float **A, int N1, int N2)

Method on mglData (C++): void Set (const double **A, int N1, int N2)

C function: void mgl_data_set_float2 (HMDT dat, const float **A, int N1, int N2)

C function: void mgl_data_set_double2 (HMDT dat, const double **A, int N1, int N2)

Allocates memory and copies the data from the float** or double** array with dimensions N1, N2, i.e. from array defined as float a[N1][N2];.

Method on mglData (C++): void Set (const float ***A, int N1, int N2)

Method on mglData (C++): void Set (const double ***A, int N1, int N2)

C function: void mgl_data_set_float3 (HMDT dat, const float ***A, int N1, int N2)

C function: void mgl_data_set_double3 (HMDT dat, const double ***A, int N1, int N2)

Allocates memory and copies the data from the float*** or double*** array with dimensions N1, N2, N3, i.e. from array defined as float a[N1][N2][N3];.

Method on mglData (C++): void Set (gsl_vector *v)

C function: void mgl_data_set_vector (HMDT dat, gsl_vector *v)

Allocates memory and copies the data from the gsl_vector * structure.

Method on mglData (C++): void Set (gsl_matrix *m)

C function: void mgl_data_set_matrix (HMDT dat, gsl_matrix *m)

Allocates memory and copies the data from the gsl_matrix * structure.

Method on mglData (C++, Python): inline void Set (const mglData &from)

C function: void mgl_data_set (HMDT dat, const HMDT from)

Copies the data from mglData instance from.

Method on mglData (C++): void Set (const std::vector<int> &d)

Method on mglData (C++): void Set (const std::vector<float> &d)

Method on mglData (C++): void Set (const std::vector<double> &d)

Allocates memory and copies the data from the std::vector<T> array.

Method on mglData (C+, Python): void Set (const char *str, int NX, int NY=1, int NZ=1)

C function: void mgl_data_set_values (const char *str, int NX, int NY, int NZ)

Allocates memory and scanf the data from the string.

6.3 Fill

Method on mglData (C++, Python): void Fill (float x1, float x2, char dir='x')

C function: void mgl_data_fill (HMDT dat, float x1, float x2, char dir)

Equidistantly fills the data values to range [x1, x2] in direction dir={‘x’,‘y’,‘z’}.

Method on mglData (C++, Python): void Fill (const char *eq, mglPoint Min, mglPoint Max, const mglData *vdat=0, const mglData *wdat=0)

C function: void mgl_data_fill (HMGL gr, HMDT dat, const char *eq, const HMDT *vdat, const HMDT *wdat)

Fills the value of array according to the formula in string eq. Formula is an arbitrary expression depending on variables ‘x’, ‘y’, ‘z’, ‘u’, ‘v’, ‘w’. Coordinates ‘x’, ‘y’, ‘z’ are supposed to be normalized in range Min x Max (in difference from Modify functions). Variable ‘u’ is the original value of the array. Variables ‘v’ and ‘w’ are values of vdat, wdat which can be NULL (i.e. can be omitted).

Method on mglData (C++, Python): void Modify (const char *eq, int dim=0)

Method on mglData (C++, Python): void Modify (const char *eq, const mglData &v)

Method on mglData (C++, Python): void Modify (const char *eq, const mglData &v, const mglData &w)

C function: void mgl_data_modify (HMDT dat, const char *eq, int dim)

C function: void mgl_data_modify_vw (HMDT dat, const char *eq, const HMDT v, const HMDT w)

Fills the value of array according to the formula in string eq. Formula is an arbitrary expression depending on variables ‘x’, ‘y’, ‘z’, ‘u’, ‘v’, ‘w’. Coordinates ‘x’, ‘y’, ‘z’ are supposed to be normalized in range [0,1] (in difference from Fill functions). Variable ‘u’ is the original value of the array. Variables ‘v’ and ‘w’ are values of vdat, wdat which can be NULL (i.e. can be omitted). If dim>0 is specified then modification will be fulfilled only for slices >=dim.

Method on mglData (C++, Python): void Put (float val, int i=-1, int j=-1, int k=-1)

mglData: void mgl_data_put_val (HMDT a, float val, int i, int j, int k)

Function sets value(s) of array a[i, j, k] = val. Negative indexes i, j, k=-1 set the value val to whole range in corresponding direction(s). For example, Put(val,-1,0,-1); sets a[i,0,j]=val for i=0...(nx-1), j=0...(nz-1).

Method on mglData (C++, Python): void Put (const mglData &v, int i=-1, int j=-1, int k=-1)

mglData: void mgl_data_put_dat (HMDT a, const HMDT v, int i, int j, int k)

Function copies value(s) from array v to the range of original array. Negative indexes i, j, k=-1 set the range in corresponding direction(s). At this minor dimensions of array v should be large than corresponding dimensions of this array. For example, Put(v,-1,0,-1); sets a[i,0,j]=v.ny>nz ? v[i,j] : v[i], where i=0...(nx-1), j=0...(nz-1) and condition v.nx>=nx is true.

C function: void mgl_data_set_value (HMDT dat, float v, int i, int j, int k)

Sets the value in specified cell of the data with border checking.

C function: float mgl_data_get_value (HMDT dat, int i, int j, int k)

Gets the value in specified cell of the data with border checking.

Method on mglData (C+, Python): void GetNx ()

C function: float mgl_data_get_nx (HMDT dat)

Gets the x-size of the data.

Method on mglData (C+, Python): void GetNy ()

C function: float mgl_data_get_ny (HMDT dat)

Gets the y-size of the data.

Method on mglData (C+, Python): void GetNz ()

C function: float mgl_data_get_nz (HMDT dat)

Gets the z-size of the data.

6.4 Rearrange

Method on mglData (C++, Python): void Rearrange (int mx, int my=0, int mz=0)

C function: void mgl_data_rearrange (HMDT dat, int mx, int my, int mz)

Rearrange dimensions without changing data array so that resulting sizes should be mx*my*mz < nx*ny*nz. If some of parameter my or mz are zero then it will be selected to optimal fill of data array. For example, if my=0 then it will be change to my=nx*ny*nz/mx and mz will be 1.

Method on mglData (C++, Python): void Extend (int n1, int n2=0)

C function: void mgl_data_extend (HMDT dat, int n1, int n2)

Increase the dimensions of the data by inserting new (|n1|+1)-th slices after (for n1>0) or before (for n1<0) of existed one. It is possible to insert 2 dimensions simultaneously for 1d data by using parameter n2. Data to new slices is copy from existed one. For example, for n1>0 new array will be a_ij^new = a_i^old where j=0...n1. Correspondingly, for n1<0 new array will be a_ij^new = a_j^old where i=0...|n1|.

Method on mglData (C++, Python): void Transpose (const char *dim="yx")

C function: void mgl_data_transpose (const char *dim)

Transposes (shift order of) dimensions of the data. New order of dimensions is specified int string dim. This function may be useful also for the reading of one-dimensional data.

Method on mglData (C++, Python): void Squeeze (int rx, int ry=1, int rz=1, bool smooth=false)

C function: void mgl_data_squeeze (HMDT dat, int rx, int ry, int rz, int smooth)

Reduces the data size by excluding data elements which indexes are not divisible by rx, ry, rz correspondingly. Parameter smooth set to use smoothing (i.e. out[i]=\sum_{j=i,i+r} a[j]/r) or not (i.e. out[i]=a[j*r]).

Method on mglData (C++, Python): void Crop (int n1, int n2, char dir='x')

C function: void mgl_data_crop (HMDT dat, int n1, int n2, char dir)

Cuts off edges of the data i<n1 and i>n2 if n2>0 or i>n[xyz]-n2 if n2<=0 along direction dir.

Method on mglData (C++, Python): void InsertRows (int at, int num=1, const char *eq=NULL)

Insert num rows (slice along y-direction) at position at and fill it by formula eq (if eq!=0) or by zeros.

Method on mglData (C++, Python): void InsertColumns (int at, int num=1, const char *eq=NULL)

Insert num columns (slice along x-direction) at position at and fill it by formula eq (if eq!=0) or by zeros.

Method on mglData (C++, Python): void InsertSlices (int at, int num=1, const char *eq=NULL)

Insert num slices (slice along z-direction) at position at and fill it by formula eq (if eq!=0) or by zeros.

Method on mglData (C++, Python): void DeleteRows (int at, int num=1)

Delete num rows (slice along y-direction) at position at.

Method on mglData (C++, Python): void DeleteColumns (int at, int num=1)

Delete num columns (slice along x-direction) at position at.

Method on mglData (C++, Python): void DeleteSlices (int at, int num=1)

Delete num slices (slice along z-direction) at position at.

Method on mglData (C++, Python): void Insert (char dir, int pos=0, int num=1)

C function: void mgl_data_insert (HMDT dat, char dir, int pos, char num)

Insert num slices along dir-direction at position pos and fill it by zeros.

Method on mglData (C++, Python): void Delete (char dir, int pos=0, int num=1)

C function: void mgl_data_delete (HMDT dat, char dir, int pos, char num)

Delete num slices along dir-direction at position pos.

6.5 File I/O

Method on mglData (C++, Python): void Read (const char *fname)

C function: void mgl_data_read (HMDT dat, const char *fname)

Reads data from tab-separated text file with auto determining sizes of the data.

Method on mglData (C++, Python): void Read (const char *fname, int mx, int my=1, int mz=1)

C function: void mgl_data_read_dim (HMDT dat, const char *fname, int mx, int my, int mz)

Reads data from text file with specified data sizes. This function does nothing if one of parameters mx, my or mz is zero or negative.

Method on mglData (C++, Python): void ReadMat (const char *fname, int dim=2)

C function: void mgl_data_read_mat (HMDT dat, const char *fname, int dim)

Read data from text file with size specified at beginning of the file by first dim numbers. At this, variable dim set data dimensions.

Method on mglData (C++, Python): void ReadRange (const char *templ, float from, float to, float step=1.f, bool as_slice=false)

Join data arrays from several text files. The file names are determined by function call sprintf(fname,templ,val);, where val changes from from to to with step step. The data load one-by-one in the same slice if as_slice=false or as slice-by-slice if as_slice=true.

Method on mglData (C++, Python): void ReadAll (const char *templ, bool as_slice=false)

Join data arrays from several text files which filenames satisfied the template templ (for example, templ="t_*.dat"). The data load one-by-one in the same slice if as_slice=false or as slice-by-slice if as_slice=true.

Method on mglData (C++, Python): void Save (const char *fname, int ns=-1) const

C function: void mgl_data_save (const HMDT dat, const char *fname, int ns)

Saves the whole data array (for ns=-1) or only ns-th slice to text file.

Method on mglData (C++, Python): void ReadHDF (const char *fname, const char *dname)

Reads data array named dname from HDF5 or HDF4 file. This function does nothing if NO_HDF5|NO_HDF4 was defined during library compilation.

Method on mglData (C++, Python): void SaveHDF (const char *fname, const char *dname, bool rewrite=false) const

Saves data array named dname from HDF5 or HDF4 file. This function does nothing if NO_HDF5|NO_HDF4 was defined during library compilation.

Method on mglData (C++, Python): void Import (const char *fname, const char *scheme, float v1=0, float v2=1)

C function: void mgl_data_import (HMDT dat, const char *fname, const char *scheme, float v1, float v2)

Reads data from bitmap file (now support only PNG format). The RGB values of bitmap pixels are transformed to float values in range [v1, v2] using color scheme scheme (see section Color scheme).

Method on mglData (C++, Python): void Export (const char *fname, const char *scheme, float v1=0, float v2=0, int ns=-1) const

C function: void mgl_data_export (HMDT dat, const char *fname, const char *scheme, float v1, float v2, int ns) const

Saves data matrix (or ns-th slice for 3d data) to bitmap file (now support only PNG format). The data values are transformed from range [v1, v2] to RGB pixels of bitmap using color scheme scheme (see section Color scheme). If v1>=v2 then the values of v1, v2 are automatically determined as minimal and maximal value of the data array.

6.6 Make another data

Method on mglData (C++, Python): mglData SubData (int xx, int yy=-1, int zz=-1) const

C function: HMDT mgl_data_subdata (const HMDT dat, int xx, int yy, int zz)

Extracts sub-array data from the original data array keeping fixed positive index. For example SubData(-1,2) extracts 3d row (indexes are zero based), SubData(4,-1) extracts 5th column, SubData(-1,-1,3) extracts 4th slice and so on.

Method on mglData (C++, Python): mglData SubData (const mglData &xx, const mglData &yy, const mglData &zz) const

C function: HMDT mgl_data_subdata_ext (const HMDT dat, const HMDT xx, const HMDT yy, const HMDT zz)

Extracts sub-array data from the original data array for indexes specified by arrays xx, yy, zz (indirect access). The resulting array have the same dimensions as input arrays for 2D and 3D arguments. This function work like previous one for 1D arguments (or numbers). The dimensions of all argument must be the same if they are 2D or 3D arrays.

Method on mglData (C++, Python): mglData Column (const char *eq) const

C function: HMDT mgl_data_column (const HMDT dat, const char *eq)

Get column (or slice) of the data filled by formula eq of other named columns. For example, Column("n*w^2/exp(t)");. The column ids must be defined first by SetColumnId() function.

Method on mglData (C++, Python): void SetColumnId (const char *ids)

C function: void mgl_data_set_id (HMDT dat, const char *ids)

Set the symbol id for data columns. The string must contain one symbol ’a’...’z’ per column (without spaces).

Method on mglData (C++, Python): mglData Trace () const

Gets array of diagonal elements a[i,i] (for 2D case) or a[i,i,i] (for 3D case) where i=0...nx-1. Function return copy of itself for 1D case. Data array must have dimensions ny,nz >= nx or ny,nz = 1.

Method on mglData (C++, Python): mglData Hist (int n, float v1=0, float v2=1, int nsub=0) const

C function: HMDT mgl_data_hist (const HMDT dat, int n, float v1, float v2, int nsub)

Creates n-th points distribution of the data values in range [v1, v2]. Parameter nsub define the number of additional interpolated points (for smoothness of histogram).

Method on mglData (C++, Python): mglData Hist (const mglData &w, int n, float v1=0, float v2=1, int nsub=0) const

C function: HMDT mgl_data_hist_w (const HMDT dat, const HMDT w, int n, float v1, float v2, int nsub)

Creates n-th points distribution of the data values in range [v1, v2]. Array w specifies weights of the data elements. Parameter nsub define the number of additional interpolated points (for smoothness of histogram).

Method on mglData (C++, Python): mglData Momentum (char dir, const char *how) const

C function: HMDT mgl_data_momentum (const HMDT dat, char dir, const char *how)

Get momentum (1D-array) of the data along direction dir. String how contain kind of momentum. The momentum is defined like as res_k = \sum_ij how(x_i,y_j,z_k) a_ij/ \sum_ij a_ij if var=‘z’ and so on. Coordinates ‘x’, ‘y’, ‘z’ are data indexes normalized in range [0,1].

Method on mglData (C++, Python): mglData Sum (const char *dir) const

C function: HMDT mgl_data_sum (const HMDT dat, const char *dir)

Gets array which is the result of summation in given direction or direction(s).

Method on mglData (C++, Python): mglData Max (const char *dir) const

C function: HMDT mgl_data_max_dir (const HMDT dat, const char *dir)

Gets array which is the maximal data values in given direction or direction(s).

Method on mglData (C++, Python): mglData Min (const char *dir) const

C function: HMDT mgl_data_min_dir (const HMDT dat, const char *dir)

Gets array which is the maximal data values in given direction or direction(s).

Method on mglData (C++, Python): mglData Combine (const mglData &a) const

C function: HMDT mgl_data_combine (const HMDT dat, const HMDT a)

Return direct multiplication of arrays (like, res[i,j] = this[i]*a[j] and so on).

Method on mglData (C++, Python): mglData Evaluate (const mglData &idat, bool norm=true) const

Method on mglData (C++, Python): mglData Evaluate (const mglData &idat, const mglData &jdat, bool norm=true) const

Method on mglData (C++, Python): mglData Evaluate (const mglData &idat, const mglData &jdat, const mglData &kdat, bool norm=true) const

C function: HMDT mgl_data_evaluate_i (const HMDT dat, const HMDT idat, int norm)

C function: HMDT mgl_data_evaluate_ij (const HMDT dat, const HMDT idat, const HMDT jdat, int norm)

C function: HMDT mgl_data_evaluate_ijk (const HMDT dat, const HMDT idat, const HMDT jdat, const HMDT kdat, int norm)

Get array which values is result of interpolation of original array for coordinates from other arrays. All dimensions must be the same for data idat, jdat, kdat. Coordinates from idat, jdat, kdat are supposed to be normalized in range [0,1] (if norm=true) or in ranges [0,nx], [0,ny], [0,nz] correspondingly.

Method on mglData (C++, Python): mglData Resize (int mx, int my=1, int mz=1, float x1=0, float x2=1, float y1=0, float y2=1, float z1=0, float z2=1) const

C function: HMDT mgl_data_resize (const HMDT dat, int mx, int my, int mz)

C function: HMDT mgl_data_resize_box (const HMDT dat, int mx, int my, int mz, float x1, float x2, float y1, float y2, float z1, float z2)

Resizes the data to new size mx, my, mz from box (part) [x1,x2] x [y1,y2] x [z1,z2] of original array. Initially x,y,z coordinates are supposed to be in [0,1].

6.7 Change data

These functions change the data in some direction like differentiations, integrations and so on. The direction in which the change will applied is specified by the string parameter, which may contain ‘x’, ‘y’ or ‘z’ characters for 1-st, 2-nd and 3-d dimension correspondengly.

Method on mglData (C++, Python): void CumSum (const char *dir)

C function: void mgl_data_cumsum (HMDT dat, const char *dir)

Cumulative summation of the data in given direction or directions.

Method on mglData (C++, Python): void Integral (const char *dir)

C function: void mgl_data_integral (HMDT dat, const char *dir)

Integrates (like cumulative summation) the data in given direction or directions.

Метод класса mglData (C++, Python): void Diff (const char *dir)

Функция С: void mgl_data_diff (HMDT dat, const char *dir)

Differentiates the data in given direction or directions.

Метод класса mglData (C++, Python): void Diff (const mglData &x, const mglData &y)

Метод класса mglData (C++, Python): void Diff (const mglData &x, const mglData &y, const mglData &z)

Функция С: void mgl_data_diff_par (HMDT dat, const HMDT x, const HMDTy, const HMDTz)

Differentiates the data specified parametrically in direction x with y, z=constant. Parametrical differentiation uses the formula (for 2D case): da/dx = (a_j*y_i-a_i*y_j)/(x_j*y_i-x_i*y_j) where a_i=da/di, a_j=da/dj denotes usual differentiation along 1st and 2nd dimensions. The similar formula is used for 3D case. Note, that you may change the order of arguments – for example, if you have 2D data a(i,j) which depend on coordinates {x(i,j), y(i,j)} then usual derivative along ‘x’ will be Diff(x,y); and usual derivative along ‘y’ will be Diff(y,x);.

Метод класса mglData (C++, Python): void Diff2 (const char *dir)

Функция С: void mgl_data_diff2 (const char *dir)

Double-differentiates (like Laplace operator) the data in given direction.

Метод класса mglData (C++, Python): void SinFFT (const char *dir)

Функция С: void mgl_data_sinfft (HMDT dat, const char *dir)

Do Sine transform of the data in given direction or directions. The Sine transform is \sum a_i \sin(k i).

Метод класса mglData (C++, Python): void CosFFT (const char *dir)

Функция С: void mgl_data_cosfft (HMDT dat, const char *dir)

Do Cosine transform of the data in given direction or directions. The Cosine transform is \sum a_i \cos(k i).

Метод класса mglData (C++, Python): void Hankel (const char *dir)

Функция С: void mgl_data_hankel (HMDT dat, const char *dir)

Do Hankel transform of the data in given direction or directions. The Hankel transform is \sum a_i J_0(k i).

Метод класса mglData (C++, Python): void Swap (const char *dir)

Функция С: void mgl_data_swap (HMDT dat, const char *dir)

Swaps the left and right part of the data in given direction (useful for Fourier spectrum).

Метод класса mglData (C++, Python): void Roll (char dir, num)

Функция С: void mgl_data_roll (HMDT dat, char dir, num)

Rolls the data along direction dir. Resulting array will be out[i] = ini[(i+num)%nx] if dir='x'.

Метод класса mglData (C++, Python): void Mirror (const char *dir)

Функция С: void mgl_data_mirror (HMDT dat, const char *dir)

Mirror the left-to-right part of the data in given direction. Looks like change the value index i->n-i.

Метод класса mglData (C++, Python): void Sew (const char *dir, float da=2*M_PI)

Функция С: void mgl_data_sew (HMDT dat, const char *dir, float da)

Remove value steps (like phase jumps after inverse trigonometric functions) with period da in given direction.

Метод класса mglData (C++, Python): void Smooth (int Type, const char *dir, float delta=0)

Функция С: void mgl_data_smooth (HMDT dat, int Type, float delt, const char *dirs)

Smooths the data on specified direction or directions by method Type. Now 4 methods are supported: SMOOTH_NONE does nothing for delta=0 or approaches data to zero with the step delta, SMOOTH_LINE_3 linear averaging by 3 points, SMOOTH_LINE_5 linear averaging by 5 points, SMOOTH_QUAD_5 quadratic averaging by 5 points. Parameter delta forbids to change values of array more than delta from the original ones. String dirs specifies the dimensions which will be smoothed. It may contain characters: ’x’ for 1st dimension, ’y’ for 2nd dimension, ’z’ for 3d dimension.

Метод класса mglData (C++, Python): void Smooth (const char *dir)

Smooths the data on specified direction(s). This is the same as Smooth() but argument Type is specified in string as ‘0’ for SMOOTH_NONE, ‘3’ for SMOOTH_LINE_3, ‘5’ for SMOOTH_LINE_5. If string dir don’t contain digits ‘035’ then Type=SMOOTH_QUAD_5 is used.

Метод класса mglData (C++, Python): void Envelop (char dir='x')

Функция С: void mgl_data_envelop (HMDT dat, char dir)

Find envelop for data values along direction dir.

Метод класса mglData (C++, Python): void Norm (float v1=0, float v2=1, bool sym=false, int dim=0)

Normalizes the data to range [v1,v2]. If flag sym=true then symmetrical interval [-max(|v1|,|v2|), max(|v1|,|v2|)] is used. Modification will be applied only for slices >=dim.

Метод класса mglData (C++, Python): void NormSl (float v1=0, float v2=1, char dir='z', bool keep_en=true, bool sym=false)

Функция С: void mgl_data_norm_slice (HMDT dat, float v1, float v2, char dir, int keep_en, int sym)

Normalizes data slice-by-slice along direction dir the data in slices to range [v1,v2]. If flag sym=true then symmetrical interval [-max(|v1|,|v2|), max(|v1|,|v2|)] is used. If keep_en is set then maximal value of k-th slice will be limited by \sqrt\sum a_ij(k)/\sum a_ij(0).

6.8 Interpolation

Method on mglData (C++, Python): float Spline (float x, float y=0, float z=0) const

C function: float mgl_data_spline (const HMDT dat, float x, float y, float z)

Interpolates data by cubic spline to the given point x in [0...nx-1], y in [0...ny-1], z in [0...nz-1].

Method on mglData (C++, Python): float Spline1 (float x, float y=0, float z=0) const

C function: float mgl_data_spline1 (const HMDT dat, float x, float y, float z)

Interpolates data by cubic spline to the given point x, y, z which assumed to be normalized in range [0, 1].

Method on mglData (C++, Python): float Linear (float x, float y=0, float z=0) const

C function: float mgl_data_linear (const HMDT dat, float x, float y, float z)

Interpolates data by linear function to the given point x in [0...nx-1], y in [0...ny-1], z in [0...nz-1].

Method on mglData (C++, Python): float Linear1 (float x, float y=0, float z=0) const

C function: float mgl_data_linear1 (const HMDT dat, float x, float y, float z)

Interpolates data by linear function to the given point x, y, z which assumed to be normalized in range [0, 1].

Method on mglData (C++, Python): float v (int i, int j=0, int k=0) const

C function: float mgl_data_get_value (const HMDT dat, int i, int j, int k)

Gets the value in specified cell of the data with border checking.

Method on mglData (C++, Python): float Spline5 (float x, float y, float z, float &dx, float &dy, float &dz) const

Interpolate by 5-th order splain the data to given point x, y, z which normalized in range [0, 1] and evaluate its derivatives.

C function: float * mgl_data_value (HMDT dat, int i, int j, int k)

Gets the pointer to data element.

C function: const float * mgl_data_data (const HMDT dat)

Gets the pointer to internal data array.

6.9 Informational functions

Метод класса mglData (C++): void PrintInfo (char *buf, bool all=false) const

Print information about the data (sizes and momentum) to string buf. Parameter all set to print most of information (if true) or just basic one like dimensions, maximal an minimal values.

Метод класса mglData (C++): void PrintInfo (FILE *fp) const

Print information about the data (sizes and momentum) to FILE (for example, stdout).

Метод класса mglData (C++, Python): float Maximal () const

Функция С: float mgl_data_max (const HMDT dat)

Gets maximal value of the data.

Метод класса mglData (C++, Python): float Minimal () const

Функция С: float mgl_data_min (HMDT dat) const

Gets minimal value of the data.

Метод класса mglData (C++, Python): float Maximal (int &i, int &j, int &k) const

Функция С: float mgl_data_max_int (const HMDT dat, int *i, int *j, int *k)

Gets maximal value of the data and its position in the array to variables i, j, k.

Метод класса mglData (C++, Python): float Minimal (int &i, int &j, int &k) const

Функция С: float mgl_data_min_int (const HMDT dat, int *i, int *j, int *k)

Gets minimal value of the data and its position in the array to variables i, j, k.

Метод класса mglData (C++, Python): float Maximal (float &i, float &j, float &k) const

Функция С: float mgl_data_max_real (const HMDT dat, float *x, float *y, float *z)

Gets maximal value of the data and its approximated (interpolated) position to variables i, j, k.

Метод класса mglData (C++, Python): float Minimal (float &i, float &j, float &k) const

Функция С: float mgl_data_min_real (const HMDT dat, float *x, float *y, float *z)

Gets minimal value of the data and its approximated (interpolated) position to variables i, j, k.

Метод класса mglData (C++, Python): float Momentum (char dir, float &m, float &w) const

Функция С: float mgl_data_momentum_mw (const HMDT dat, char dir, float *m, float *w)

Gets zero-momentum (energy, I=\sum a_i) and write first momentum (median, m = \sum \xi_i a_i/I) and second momentum (width, w^2 = \sum (\xi_i-m)^2 a_i/I) to variables. Here \xi is corresponding coordinate if dir is ‘'x'’, ‘'y'’ or ‘'z'’. Otherwise median is m = \sum a_i/N, width is w^2 = \sum (a_i-m)^2/N.

Метод класса mglData (C++): float Momentum (char dir, float &m, float &w, float &s, float &k) const

Gets zero-momentum (energy, I=\sum a_i) and write first momentum (median, m = \sum \xi_i a_i/I), second momentum (width, w^2 = \sum (\xi_i-m)^2 a_i/I), third momentum (skewness, s = \sum (\xi_i-m)^3 a_i/ I w^3) and fourth momentum (kurtosis, k = \sum (\xi_i-m)^4 a_i / 3 I w^4) to variables. Here \xi is corresponding coordinate if dir is ‘'x'’, ‘'y'’ or ‘'z'’. Otherwise median is m = \sum a_i/N, width is w^2 = \sum (a_i-m)^2/N and so on.

Метод класса mglData (C++, Python): float Find (const char *cond, int &i, int &j, int &k) const

Функция С: float mgl_data_first (const HMDT dat, const char *cond, int *i, int *j, int *k)

Find position (after specified in i, j, k) of first nonzero value of formula cond. Function return the data value at found position.

Метод класса mglData (C++, Python): float Last (const char *cond, int &i, int &j, int &k) const

Функция С: float mgl_data_last (const HMDT dat, const char *cond, int *i, int *j, int *k)

Find position (before specified in i, j, k) of last nonzero value of formula cond. Function return the data value at found position.

Метод класса mglData (C++, Python): int Find (const char *cond, char dir, int i=0, int j=0, int k=0) const

Функция С: float mgl_data_find (const HMDT dat, const char *cond, int i, int j, int k)

Return position of first in direction dir nonzero value of formula cond. The search is started from point {i,j,k}.

Метод класса mglData (C++, Python): bool FindAny (const char *cond) const

Функция С: float mgl_data_find_any (const HMDT dat, const char *cond)

Determines if any nonzero value of formula in the data array.

6.10 Operators

Method on mglData (C++, Python): void operator= (const mglData &d)

Copies data from other variable.

Method on mglData (C++, Python): void operator*= (const mglData &d)

C function: void mgl_data_mul_dat (HMDT dat, const HMDT d)

Multiplies the data by the other one for each element.

Method on mglData (C++, Python): void operator/= (const mglData &d)

C function: void mgl_data_div_dat (HMDT dat, const HMDT d)

Divides the data by the other one for each element.

Method on mglData (C++, Python): void operator+= (const mglData &d)

C function: void mgl_data_add_dat (HMDT dat, const HMDT d)

Adds the other data.

Method on mglData (C++, Python): void operator-= (const mglData &d)

C function: void mgl_data_sub_dat (HMDT dat, const HMDT d)

Subtracts the other data.

Method on mglData (C++, Python): void operator*= (float d)

C function: void mgl_data_mul_num (HMDT dat, float d)

Multiplies each element by the number.

Method on mglData (C++, Python): void operator/= (float d)

C function: void mgl_data_div_num (HMDT dat, float d)

Divides each element by the number.

Method on mglData (C++, Python): void operator+= (float d)

C function: void mgl_data_add_num (HMDT dat, float d)

Adds the number to each element.

Method on mglData (C++, Python): void operator-= (float d)

C function: void mgl_data_sub_num (HMDT dat, float d)

Subtracts the number to each element.

Library Function: mglData operator+ (const mglData &a, const mglData &b)

Adds the other data.

Library Function: mglData operator+ (float a, const mglData &b)

Adds the number.

Library Function: mglData operator+ (const mglData &a, float b)

Adds the number.

Library Function: mglData operator- (const mglData &a, const mglData &b)

Subtracts the other data.

Library Function: mglData operator- (float a, const mglData &b)

Subtracts from the number.

Library Function: mglData operator- (const mglData &a, float b)

Subtracts the number.

Library Function: mglData operator* (const mglData &a, const mglData &b)

Multiplies by the other data.

Library Function: mglData operator* (float a, const mglData &b)

Multiplies by the number.

Library Function: mglData operator* (const mglData &a, float b)

Multiplies by the number.

Library Function: mglData operator/ (const mglData &a, const mglData &b)

Divides by the other data.

Library Function: mglData operator/ (const mglData &a, float b)

Divides by the number.

6.11 Global functions

These functions are not methods of mglData class. However it have additional functionality to handle data. So I put it in this chapter.

Global function: mglData mglTransform (const mglData &real, const mglData &imag, const char *type)

C function: HMDT mgl_transform (const HMDT real, const HMDT imag, const char *type)

Do integral transformation of complex data real, imag on specified direction. The order of transformations is specified in string type: first character for x-dimension, second one for y-dimension, third one for z-dimension. The possible character are: ‘f’ is forward Fourier transformation, ‘i’ is inverse Fourier transformation, ‘s’ is Sine transform, ‘c’ is Cosine transform, ‘h’ is Hankel transform, ‘n’ or ‘ ’ is no transformation.

Global function: mglData mglTransformA const mglData &ampl, const mglData &phase, const char *type)

C function: HMDT mgl_transform_a const HMDT ampl, const HMDT phase, const char *type)

The same as previous but with specified amplitude ampl and phase phase of complex numbers.

Global function: mglData mglSTFA (const mglData &real, const mglData &imag, int dn, char dir='x')

C function: HMDT mgl_data_stfa (const HMDT real, const HMDT imag, int dn,char dir)

Short time Fourier transformation for real and imaginary parts. Output is amplitude of partial Fourier of length dn. For example if dir=‘x’, result will have size {int(nx/dn), dn, ny} and it will contain res[i,j,k]=|\sum_d^dn exp(I*j*d)*(real[i*dn+d,k]+I*imag[i*dn+d,k])|/dn.

Global function: mglData mglPDE (const char *ham, const mglData &ini_re, const mglData &ini_im, mglPoint Min, mglPoint Max, float dz=0.1, float k0=100)

C function: HMDT mgl_pde_solve (HMGL gr, const char *ham, const HMDT ini_re, const HMDT ini_im, float dz, float k0)

Solves equation du/dz = i*k0*ham(p,q,x,y,z,|u|)[u], where p=-i/k0*d/dx, q=-i/k0*d/dy are pseudo-differential operators. Parameters ini_re, ini_im specify real and imaginary part of initial field distribution. Parameters Min, Max set the bounding box for the solution. Note, that really this ranges are increased by factor 3/2 for purpose of reducing reflection from boundaries. Parameter dz set the step along evolutionary coordinate z. At this moment, simplified form of function ham is supported – all “mixed” terms (like ‘x*p’->x*d/dx) are excluded. For example, in 2D case this function is effectively ham = f(p,z) + g(x,z,u). However commutable combinations (like ‘x*q’->x*d/dy) are allowed. Here variable ‘u’ is used for field amplitude |u|. This allow one solve nonlinear problems – for example, for nonlinear Shrodinger equation you may set ham="p^2 + q^2 - u^2". You may specify imaginary part for wave absorption, like ham = "p^2 + i*x*(x>0)", but only if dependence on variable ‘i’ is linear (i.e. ham = hre+i*him). See section PDE sample, for sample code and picture. See section PDE sample, for sample code and picture.

Global function: mglData mglRay (const char *ham, mglPoint r0, mglPoint p0, float dt=0.1, float tmax=10)

C function: HMDT mgl_ray_trace (const char *ham, float x0, float y0, float z0, float px, float py, float pz, float dt, float tmax)

Solves GO ray equation like dr/dt = d ham/dp, dp/dt = -d ham/dr. This is Hamiltonian equations for particle trajectory in 3D case. Here ham is Hamiltonian which may depend on coordinates ‘x’, ‘y’, ‘z’, momentums ‘p’=px, ‘q’=py, ‘v’=pz and time ‘t’: ham = H(x,y,z,p,q,v,t). The starting point (at t=0) is defined by variables r0, p0. Parameters dt and tmax specify the integration step and maximal time for ray tracing. Result is array of {x,y,z,p,q,v,t} with dimensions {7 * int(tmax/dt+1) }. See section Beam tracing sample, for sample code and picture.

Global function: mglData mglQO2d (const char *ham, const mglData &ini_re, const mglData &ini_im, const mglData &ray, float r=1, float k0=100, mglData *xx=0, mglData *yy=0, bool UseR=true)

C function: HMDT mgl_qo2d_solve (const char *ham, const HMDT ini_re, const HMDT ini_im, const HMDT ray, float r, float k0, HMDT xx, HMDT yy)

Solves equation du/dt = i*k0*ham(p,q,x,y,|u|)[u], where p=-i/k0*d/dx, q=-i/k0*d/dy are pseudo-differential operators (see mglPDE() for details). Parameters ini_re, ini_im specify real and imaginary part of initial field distribution. Parameters ray set the reference ray, i.e. the ray around which the accompanied coordinate system will be maked. You may use, for example, the array created by mglRay() function. Note, that the reference ray must be smooth enough to make accompanied coodrinates unambiguity. Otherwise errors in the solution may appear. If xx and yy are non-zero then Cartesian coordinates for each point will be written into them. See also mglPDE(). See section Beam tracing sample, for sample code and picture.

Global function: mglData mglJacobian (const mglData &x, const mglData &y)

Global function: mglData mglJacobian (const mglData &x, const mglData &y, const mglData &z)

C function: HMDT mgl_jacobian_2d (const HMDT x, const HMDT y)

C function: HMDT mgl_jacobian_3d (const HMDT x, const HMDT y, const HMDT z)

Computates the Jacobian for transformation {i,j,k} to {x,y,z} where initial coordinates {i,j,k} are data indexes normalized in range [0,1]. The Jacobian is determined by formula det||dr_\alpha/d\xi_\beta|| where r={x,y,z} and \xi={i,j,k}. All dimensions must be the same for all data arrays. Data must be 3D if all 3 arrays {x,y,z} are specified or 2D if only 2 arrays {x,y} are specified.

This document was generated by Alexey Balakin on May 2, 2013 using texi2html 1.82.