previous up next print clean
Next: CLASSES USED IN DEFINING Up: Dunbar: Operators and spaces Previous: Introduction


The space class contains two different things, the matrix class and the axis descriptions, along with some operations. So, in building up to the space class, let us consider the two classes that describe the axes: Axis and Axislist. Axis is basically a collection of the four things that describe an axis: the origin, delta, length, and name. These are all public variables, which can be looked at and changed freely, for anyone who has access to the Axis object. In addition, there are a few member functions which provide some useful operations that are often used with Axis objects.

NAME Axis - class to describe an axis of a <type>space.

SYNOPSIS #include <Axis.h>

DESCRIPTION The class Axis contains a description of an axis in a <type>space. The description includes the initial coordinate of the data along the axis (origin), the number of samples along this axis (length), the increment between samples (delta), and a label for this axis (name). An Axis can be constructed from either the above information, or from a SepAxis *.

PUBLIC VARIABLES float origin float delta int length char * name

PUBLIC OPERATIONS Axis(float origin,float delta,int length,char * name) Construct an Axis given a value for each of its members. The label (name) is copied.

Axis(SepAxis *) Construct an Axis which matches the SepAxis.

SepAxis * sepaxis() Returns a pointer to a new SepAxis object, which matches the Axis.

Axis() Axis(const Axis &) Axis& operator=(const Axis &)  Axis()

int operator==(const Axis &) Checks if two Axis have the same values for all their members.

int subaxis(Axis & a) Checks if the Axis is a sub-axis of a. For Axis x to be a sub-axis of Axis y, x must: (1) have the same label as y (2) have every sample of x have the same position as some sample of y.

float max() Returns origin + delta * length.

int index(float) Gets the integer index of the closest sample to the float parameter.

float value(int) Returns the float position of the sample numbered by the in parameter.

SEE ALSO Axislist, <type>space, SepAxis

The Axislist class is also a collection of things: the array of Axis objects, and the number of dimensions. Again these are public, and can be freely viewed or changed by anyone who can access the Axislist object. Also, a few useful functions are provided.

NAME Axislist - class to contain the axis information for a <type>space.

SYNOPSIS #include <Axislist.h>

DESCRIPTION An Axislist contains the axis information for a <type>space, including the number of dimensions, and 4 Axis objects. This sets the maximum on dimen- sions at four, and also means that any axes up to four will exist, even if the dimension is lower than 4. An Axislist can be created by initializing it with the number of dimensions, and then assigning Axis objects into it, or from a SepInfo *.

PUBLIC VARIABLES int ndim The number of dimensions.

Axis list[4] The four Axis.

PUBLIC OPERATIONS Axislist(int dim) Create an Axislist of dimension dim, with all empty Axis.

Axislist(SepInfo *) Construct an Axislist matching the SepInfo.

SepInfo * sepinfo(int esize) Returns a pointer to a new SepInfo matching the Axislist, given the element size.

Axislist(const Axis & a) Construct an Axislist of dimension 1, with the a as the first Axis in list.

Axislist() Axislist(const Axislist &); Axislist & operator=(const Axislist &)  Axislist()

Axis & operator[](int) Get an Axis by directly indexing the Axislist, rather than accessing member list.

Axislist transpose() Returns an Axislist that is the transpose of this one. The first two Axis are switched, which can add a dimension or subtract one, if one of the switching Axis objects are empty.

Axislist transpose(int i,int j=1,int k=2,int l=3) Returns an Axislist that is transposed according to the int

parameters. list[0] get the Axis number i, list[1] gets Axis[j], etc. The dimension is then set according to the greatest non-empty Axis.

void cleanup() Sets the dimension according to the greatest non-empty Axis.

int operator==(Axislist &) Checks if two Axislist objects match- if they have the same dimension and all their Axis objects match.

int subspace(Axislist & a) Checks if this is a subspace of a. It is if the two have the same dimension, and if all the Axis in the list are sub-axes of the match- ing Axis in a.list.

SEE ALSO Axis, <type>space,

The space class also contains a matrix class. This is (for now) M++ Dya (1991).

This brings us to the first major class: the space class. The word space is preceeded by <type> in the man pages; in practice an actual type is in that place. floatspace and complexspace are the two types currently supported.

The space class contains two things, the Axislist to describe the axes that the data lies on, and the matrix class containing that data. These are both private members, only accessable through the member functions.

There are two reasons for this,

A user of the class should only want to do things to a space that can be accomplished with the member functions.
The Axislist and matrix must match, and this could not be guaranteed if the variables could be accessed freely. (Not that it is guaranteed by them being private members, but it is a safer interface)
For the special case of operators (the class op), we can get around this restriction, see the op section for details.

The complete functionality of the space class is described in the man page below. I will discuss a few key points. The first is that the operations for a space, with a few exceptions, do not allow changing of the dimensions or axes of a space. Viewing the information about the axes, with the getaxislist() function, or changing particular values in the space, by assigning into the space, is legal, but the overall ``shape'' of the space cannot be changed. Having said this, there are a few ways to get a new space, with a different ``shape'' than the original, although the original space is not changed. These operations, which change the ``shape'', include the extract, and transpose (trans) operation.

All the arithmetic and assignment operators are supported for spaces, such as multiplication, addition, etc. These can be by a value of the type of the space, or by another space. An operation with another space, such as multiplying by another space, requires that the axis information of the two spaces is identical. This operation is then done element by element.

NAME <type>space - class for a space with elements of <type>

SYNOPSIS #include <<type>space.h>

DESCRIPTION A <type>space is a multi-dimensional array of data (of type <type>), with a description, along each dimension, of the origin, length, and delta that the data is located along. The data is stored in a <type>Array, and the axis description in an Axislist. The <type>space can be constructed from either a SepData *, or from a <type>Array and an Axislist. It can be mani- pulated with arithmetic operators, either with a matching <type>space or a <type>, and inserted from another <type>space, or extracted from a <type>space.

Linear operators, <type>op, are meant to do most of the calculations on a <type>space. They are defined as a friend, and have direct access to the matrix class, and thus can use all the operators for the matrix class to do calculations.

PUBLIC OPERATIONS Axislist getaxislist() Gets a copy of the Axislist of the <type>space. This is just a copy, and changing it will not change the internal axislist.

<type>space() <type>space(const <type>space &)

<type>space(SepInput *) Construct <type>space from a SepInput *. The <type>space and SepInput then share the data memory, so the SepInput should not be used or deleted after this.

<type>space(SepData *) Construct <type>space from a SepData *. The <type>space and SepData then share the data memory, so the SepData should not be used or deleted after this.

SepData * sepdata() Return a pointer to a new SepData. As above, the <type>space and Sep- Data share the data, so the <type>space should not be used after this.

<type>space(SepPlane *) SepPlane * sepplane() Same as above, except for SepPlanes instead of SepDatas.

<type>space(<type>Array &,SepInfo *) Construct a <type>space from the <type>Array and the SepInfo. This checks to see if the <type>Array matches the SepInfo, exiting with an error if it doesn't.

<type>space(<type>Array &,Axislist &) Same thing, but with an Axislist instead of a SepInfo.

<type>space(Axislist &) Constructs a <type>space as defined by Axislist, initialized to 0.

<type>space empty() Returns a <type>space the of the same size, but equal to 0.


friend ostream & operator<<(ostream &,<type>space &) To print a <type>space. Actually just prints the matrix, not the axis information.

float norm() float norm2() norm return the square root of the sum of the elements squared. norm2 returns norm squared.

<type> cross(<type>space & s) If s is conformable (matching Axislist), cross multiplies the two <type>space objects, element by element, and sums.

<type>space trans() Returns a <type>space that is the transpose, meaning the first two axes are switched.

<type>space trans(int i,int j=1,int k=2,int l=3) Transposed by giving axis 0 the axis number i, axis 1 the axis number j, etc.

<type> & operator()(int i,int j=0,int k=0,int Gets an element out of the matrix. This element can be changed.

<type>space extract(Axislist & a) Gets a <type>space which is the sub-space of this one defined by a. This <type>space is a copy of the extracted parts, and altering it will not change the original <type>space.

<type>space extractslice(int dim,int num) Extracts a sub-space, with one less dimension than the original, that is slice number num along dimension dim of the <type>space.

void insert(<type>space & s) Inserts s into the <type>space if s is a sub-space.

void insertslice(<type>space s,int dim,int num) Inserts s into the <type>space, making it slice num of dimension dim.

friend <type>space operator*(<type>,<type>space &) friend <type>space operator*(<type>space &,<type>)

friend <type>space operator*(<type>space &,<type>space &) friend <type>space operator/(<type>,<type>space &) friend <type>space operator/(<type>space &,<type>) friend <type>space operator/(<type>space &,<type>space &) friend <type>space operator+(<type>,<type>space &) friend <type>space operator+(<type>space &,<type>) friend <type>space operator+(<type>space &,<type>space &) friend <type>space operator-(<type>,<type>space &) friend <type>space operator-(<type>space &,<type>) friend <type>space operator-(<type>space &,<type>space &) <type>space operator-() <type>space operator+() All the arithmetic operators that are given two <type>spaces require that the <type>spaces are conformable- that is, their axislists are equal.

<type>space & operator=(<type>space &) <type>space & operator=(<type>) <type>space & operator+=(<type>space &) <type>space & operator+=(<type>) <type>space & operator-=(<type>space &) <type>space & operator-=(<type>) <type>space & operator*=(<type>space &) <type>space & operator*=(<type>) <type>space & operator/=(<type>space &) <type>space & operator/=(<type>)

PRIVATE VARIABLES <type>Array array Axislist axislist

PRIVATE OPERATIONS int compatible(<type>space) void checkspace() Index getindex(Axis &,Axis &)

SEE ALSO Axis, Axislist, <type>spacearray, <type>op, <type>Array

The way to do more complex manipulations of spaces is through operators (class op). Following is the base class, from which all ops are derived. The op has two operations: the Forward and Conjugate functions, both of which take a space and return a space. These also exist for spacearrays, but these are just an extension of the space versions. More on spacearrays later.

previous up next print clean
Next: CLASSES USED IN DEFINING Up: Dunbar: Operators and spaces Previous: Introduction
Stanford Exploration Project