# class NumRu::Axis

A class of to handle a descretized physical coordinate.

## Overview

An NumRu::Axis object is meant to represent a dimension in a NumRu::Grid object, which is used in NumRu::Grid (Hereafter, NumRu:: is omitted). An Axis has 1-dimensional data on grid-point posisions as a VArray. In addition, it can have supplementary data (as VArray objects).

Three types of axes are supported in this class:

    1. Simple (mostly point-sampled) axes
    2. Cell-type axes. In this case, grid points are either
       at cell boundaries or within the cells (oftern at the center).
    3. Simple ("bare") indexing (without particular physical meaning)

In most applications, the 1st type would be enough, but the 2nd type would be useful for some type of numerical simulation. The 3rd is not physical and may not be considered as "axes", but this could be convenient for some practical applications.

## Class Methods

#### `Axis.new(cell=false,bare_index=false,name=nil)`

  Constructor. The first two arguments are to specify one of the types explained above.

  ARGUMENTS

  - cell (true or false)
  - bare_index (true or false)
  - name (String or nil): the default name (when nil) is "noname"

  RETURN VALUE

  - an Axis

#### `Axis.defined_operations`

  Returns the name of the methods defined in Axis to do some operation along the axis.

  RETURN VALUE

  - an Array of String. Current default value is ["integrate","average"].

#### `Axis.humane_messaging = t_or_f`

  If false is given, the [] method is changed to return a naive straightforward message if the axis is lost. -- By default, it returns a fancy but sometimes unwanted message if the axis is the time with since field in the form of yyyy-mm-dd....

## Instance Methods

#### `name=(nm)`

  Set a name.

  ARGUMENTS

  - name (String)

  RETURN VALUE

  - name (the argument)

#### `name`

  Returns the name.

  RETURN VALUE

  - a String

#### `cell?`

  Whether or not self is a cell-type axis.

  RETURN VALUE

  - true or false

#### `cell_center?`

  Whether or not self represents data points within the cells (which is often, but not necessarily, the centers of the cells).

  RETURN VALUE

  - true, false, or nil (when the axis is not cell-type)

#### `cell_bounds?`

  Whether or not self represents data points at the cell bondaries.

  RETURN VALUE

  - true, false, or nil (when the axis is not cell-type)

#### `bare_index?`

  Whether or not self is of the bare-index type.

  RETURN VALUE

  - true or false.

#### `flatten`

  Returns the VArray objects in self as a flat Array. No cloning is made.

  RETURN VALUE

  - an Array of VArray objects.

#### `each_varray`

  Iterator for each VArray object in self (dependent on flatten.

  RETURN VALUE

  - an Array of VArray objects (same as flatten).

#### `copy`

  Make a deep clone onto memory. All the VArray objects in the return value will be of the root class of VArray.

  RETURN VALUE

  - an Axis

#### `collect`

  This method is like copy, but it is the 'collect' iterator for each VArray in self (block required).

  RETURN VALUE

  - an Axis

#### `pos=(pos)`

  Sets the grid-point positions (disretized coordinate values).

  ARGUMENTS

  - pos (a 1D VArray)

  RETURN VALUE

  - pos (the argument)

#### `set_pos(pos)`

  Sets the grid-point positions (disretized coordinate values).

  ARGUMENTS

  - pos (a 1D VArray)

  RETURN VALUE

  - self

#### `pos`

  Returns the grid-point positions (disretized coordinate values).

  RETURN VALUE

  - a VArray (no duplication is made)

#### `cell_center`

  When cell-type, returns the positions of grid points at cell centers.

  RETURN VALUE

  - a VArray (no duplication is made)

#### `cell_bounds`

  When cell-type, returns the positions of grid points at cell boundaries.

  RETURN VALUE

  - a VArray (no duplication is made)

#### `length`

  Returns the length of the axis.

  RETURN VALUE

  - an Integer

#### `set_cell(center, bounds, name=nil)`

  Set up cell-type axis, by giving both the cell centers and boundaries. Completion of the set up is deferred until one of set_pos_to_center and set_pos_to_bounds is called.

  ARGUMENTS

  - center (a 1D VArray)
  - bounds (a 1D VArray)
  - name (String)

  RETURN VALUE

  - self

#### `set_cell_guess_bounds(center, name=nil)`

  Set up cell-type axis, by specifing only the cell centers and deriving bounds with a naive assumption.

  ARGUMENTS

  - center (a 1D VArray)
  - name (String)

  RETURN VALUE

  - self

#### `set_pos_to_center`

  Set the position of the current axis to the centers of the cells. This or set_pos_to_bounds is needed to complete the set up with set_cell_* methods.

#### `set_pos_to_bounds`

  Set the position of the current axis to the cell bondaries. This or set_pos_to_center is needed to complete the set up with set_cell_* methods.

#### `set_aux(name,vary)`

  Set auxiliary data

  ARGUMENTS

  - name (String) a tag to express the kind of the data
  - vary (a VArray) the data

  RETURN VALUE

  - vary (the 2nd argument)

#### `get_aux(name)`

  Returns auxiliary data

  ARGUMENTS

  - name (String) a tag to express the kind of the data (see set_aux).

  RETURN VALUE

  - a VArray

#### `aux_names`

  Returns a list of the names of auxiliary data

  RETURN VALUE

  - an Array of String

#### `to_gphys(datavary1d=nil)`

  To construct a GPhys object from an Axis.

  ARGUMENTS

  - datavary1d (nil or VArray) : If nil, the position object of self becomes the main data object. If a VArray, it is used as the main data object.

  RETURN VALUE

  - a GPhys

#### `[slicer]`

  Returns a subset. Its specification is the same as in NArray.

  RETURN VALUE

  - an Axis

#### `cut(coord_cutter)`

  Similar to [], but is based on the physical coordinate.

  RETURN VALUE

  - an Axis

#### `cut_rank_conserving(coord_cutter)`

  Similar to cut, but is always rank-conserving. That is, a subset specification like [i] is treated as [i..i]

  RETURN VALUE

  - an Axis

#### `integrate(ary,dim)`

  Does integration along the axis

  ARGUMENTS

  - ary (NArray or NArray-like multi-dimensional data class) the data, whose dim-th dimension must have the same length as the axis.
  - dim (Integer) : The dimension of ary, to which the operation is applied.

  RETURN VALUE

  - an obejct with the same class as ary, or of a Numeric class if ary is 1D.

#### `integ_weight`

  Returns the integration weight (whose default is nil).

#### `integ_weight=(wgt)`

  Sets the integration weight (whose default is nil).

#### `average(ary,dim)`

  Similar to integrate, but does averaging

  ARGUMENTS

  - see integrate

  RETURN VALUE

  - see integrate

#### `average_weight`

  Returns the integration weight (whose default is nil).

#### `average_weight=(wgt)`

  Sets the integration weight (whose default is nil).

#### `draw_positive`

  Returns the direction to plot the axis, which relies on the VArray#axis_draw_positive method.

  RETURN VALUE

  - one of the following:
    - true: axis should be drawn in the increasing order (to right/upward)
    - false: axis should be drawn in the decreasing order
    - nil: not specified

#### `cyclic?`

  Returns whether the axis is cyclic. (Relies on the VArray#axis_cyclic? method.)

  RETURN VALUE

  - one of the following:
    - true: cyclic
    - false: not cyclic
    - nil: not specified

#### `modulo`

  Returns the modulo of a cyclic axis (Relies on the VArray#axis_modulo method.)

  RETURN VALUE

  - one of the following:
    - Float if the modulo is defined
    - nil if modulo is not found

#### `cyclic_extendible?`

  Returns whether the axis is cyclic and appropriate to extend. (Relies on the VArray#axis_cyclic_extendible? method.)

  RETURN VALUE

  - true or false