com.xj.anylogic.engine
Class HyperArray

java.lang.Object
  com.xj.anylogic.engine.HyperArray

All Implemented Interfaces:

java.io.Serializable

public class HyperArray
extends java.lang.Object
implements java.io.Serializable

A storage for multi-dimensional data used primarily in system dynamics models. Each data element is of Java type double. This construct (also known as "data with subscripts" or "array") allows for easy and intuitive writing of formulas and equations, and flexible manipulating with dimensions. Arithmetic operations on arrays are performed element-by-element (unlike on matrixes in linear algebra).

Hyper arrays are constructed by specifying their dimensions and, optionally, the initial data, for example:
people = HyperArray( Region, Gender, AgeGroup ); or
people = HyperArray( initialPeople, Region, Gender, AgeGroup );
where Region, Gender, ... are objects of class Dimension may contain e.g. the population of a country broken down by region, gender and age group.

You can set and get values of individual elements of the hyper array by calling the corresponding methods, e.g:
people.get( NORTH, MALE, ADULT ) or
people.set( 23000, NORTH, MALE, ADULT )

The class also supports calculations over a subsets of elements, like sum, product, minimum or maximum. For example, calling:
people.sum( NORTH, INDEX_CAN_VARY, ADULT )
will calculate the number of adults of both genders in the north region.

The multi-dimensional data is stored in a flat array so that the first dimension index varies first. Thus, for a hyper array [ Region, Gender ] where Region is { N, S, E, W } and Gender is { M, F }, the flat data array woould contain: [ (N,M), (S,M), (E,M), (W,M), (N,F), (S,F), (E,F), (W,F) ]. Position of an element with particular indexes can be obtained by calling getPosOf( indexes... ).

An object of class HyperArray occupies 14 + ( 8 * Number of dimensions ) + ( 8 * Product of sizes of all dimensions ) bytes of memory.

Author:

XJ Technologies Company Ltd. www.anylogic.com

See Also:

Serialized Form

Field Summary

static int

INDEX_CAN_VARY A special constant that, being placed at an index position, tells the methods that perform operation over subsets of hyper array elements that they can vary the corresponding index.

Constructor Summary

HyperArray(Dimension... dims)
Creates a hyper array with the dimensions specified.

HyperArray(double[] values, Dimension... dims)
Creates a hyper array with the dimensions specified and initializes it with the given values from a flat array, where the first dimension index varies first.

HyperArray(double value, Dimension... dims)
Creates a hyper array with the dimensions specified and initializes all its elements with the same value.

HyperArray(HyperArray original)
Creates a copy of a given hyper array.

Method Summary

double	average() Returns the average of all elements of the hyper array.
void	copyFrom(HyperArray original) Copies all data from another hyperarray.
boolean	equal(double val) Checks if all elements of the hyper array equal a particular value.
boolean	equal(HyperArray a) Compares the hyper array with another one.
double	get(int... indexes) Returns the value of the element of this array specified by the given dimension indexes.
double[]	getData() Returns the flat array of doubles holding the hyper array elements.
Dimension[]	getDimensions() Returns the dimensions of the hyper array.
int	getPosOf(int... indexes) Returns the position of the element in the flat data array specified by the given dimension indexes.
boolean	hasNegativeValues() Checks if there are any negative elements in the hyper array.
double	max() Returns the maximum of all elements of the hyper array.
double	max(int... indexes) Returns a partial maximum of hyper array elements, namely maximum across all dimensions whose indexes equal INDEX_CAN_VARY in the given index array.
double	min() Returns the minimum of all elements of the hyper array.
double	min(int... indexes) Returns a partial minimum of hyper array elements, namely minimum across all dimensions whose indexes equal INDEX_CAN_VARY in the given index array.
double	prod(int... indexes) Returns a partial product of hyper array elements, namely product across all dimensions whose indexes equal INDEX_CAN_VARY in the given index array.
void	set(double value) Sets all elements of this array to a given value.
void	set(double[] values) Sets the hyper array elements to the values from a given array, where the first dimension index varies first.
void	set(double value, int... indexes) Sets the element of this array specified by the dimension indexes to a given value.
void	setData(double[] values, int srcPos) Sets the hyper array elements to the values from a given array starting from the specified position, where the first dimension index varies first.
int	size() Returns the total number of elements in the hyper array.
double	stddev() Returns the standard deviation across all elements of the hyper array.
double	sum() Returns the sum of all elements of the hyper array.
double	sum(int... indexes) Returns a partial sum of hyper array elements, namely sum across all dimensions whose indexes equal INDEX_CAN_VARY in the given index array.
java.lang.String	toString() Prints out the hyper array in the following form: - if the hyper array is dimensionless, just prints its only element value - for a uni-dimensional hyper array prints every element value on a separate line - for two-dimensional hyper array prints as a tab separated 2D table with element values (dimension 0 vs dimension 1) - for three and more dimensions prints a number of such tables, a table for each combination of indexes in dimensions 2 and higher.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

INDEX_CAN_VARY

public static final int INDEX_CAN_VARY

A special constant that, being placed at an index position, tells the methods that perform operation over subsets of hyper array elements that they can vary the corresponding index. Other indexes are fixed.

See Also:

Constant Field Values

Constructor Detail

HyperArray

public HyperArray(Dimension... dims)

Creates a hyper array with the dimensions specified. All elements are initialized with 0.

Parameters:

dims - dimensions of the hyper array

HyperArray

public HyperArray(double[] values,
                  Dimension... dims)

Creates a hyper array with the dimensions specified and initializes it with the given values from a flat array, where the first dimension index varies first. The number of values provided may be smaller or bigger than the one actually needed by the array (array has the number of elements equal to the product of its dimension sizes). The extra values are ignored, the missing values are assumed zeros.

Parameters:

values - flat array of initial data values

dims - dimensions of the hyper array

HyperArray

public HyperArray(double value,
                  Dimension... dims)

Creates a hyper array with the dimensions specified and initializes all its elements with the same value.

Parameters:

value - the initial data value

dims - dimensions of the hyper array

HyperArray

public HyperArray(HyperArray original)

Creates a copy of a given hyper array.

Parameters:

original - the original hyper array

Method Detail

getDimensions

public Dimension[] getDimensions()

Returns the dimensions of the hyper array. You should not modify the result!

Returns:

the dimensions of the hyper array

size

public int size()

Returns the total number of elements in the hyper array.

Returns:

the total number of elements in the hyper array

getData

public double[] getData()

Returns the flat array of doubles holding the hyper array elements. The actual array is returned, not a copy!
The multi-dimensional data is stored in the flat array so that the first dimension index varies first. Thus, for a hyper array HA[ Region, Gender ] where Region is { N, S, E, W } and Gender is { M, F }, the flat data array would contain: [ (N,M), (S,M), (E,M), (W,M), (N,F), (S,F), (E,F), (W,F) ]. Position of an element with particular indexes can be obtained by calling getPosOf( indexes... ).

Returns:

the data stored in the hyper array

getPosOf

public int getPosOf(int... indexes)

Returns the position of the element in the flat data array specified by the given dimension indexes. There must be an index for each existing dimension.

Parameters:

indexes - dimension indexes specifying the element

Returns:

the position of the element

get

public double get(int... indexes)

Returns the value of the element of this array specified by the given dimension indexes. There must be an index for each existing dimension.

Parameters:

indexes - dimension indexes specifying the element

Returns:

the value of the hyper array element

set

public void set(double value,
                int... indexes)

Sets the element of this array specified by the dimension indexes to a given value.

Parameters:

value - the value

indexes - dimension indexes specifying the element

set

public void set(double[] values)

Sets the hyper array elements to the values from a given array, where the first dimension index varies first. The number of values provided may be smaller or bigger than the one acually needed by the array (array has the number of elements equal to the product of its dimension sizes). The extra values are ignored, the missing values are not modified.

Parameters:

values - flat array of data values, last dimension varies first

setData

public void setData(double[] values,
                    int srcPos)

Sets the hyper array elements to the values from a given array starting from the specified position, where the first dimension index varies first. The number of values provided may be smaller or bigger than the one acually needed by the array (array has the number of elements equal to the product of its dimension sizes). The extra values are ignored, the missing values are not modified.

Parameters:

values - flat array of data values, last dimension varies first

set

public void set(double value)

Sets all elements of this array to a given value.

Parameters:

value - the value

copyFrom

public void copyFrom(HyperArray original)

Copies all data from another hyperarray. Dimensions of the two arrays must be identical.

Parameters:

original - the original hyperarray

sum

public double sum()

Returns the sum of all elements of the hyper array.

Returns:

the sum of all elements of the hyper array

average

public double average()

Returns the average of all elements of the hyper array.

Returns:

the average of all elements of the hyper array

stddev

public double stddev()

Returns the standard deviation across all elements of the hyper array.

Returns:

the standard deviation across all elements of the hyper array

min

public double min()

Returns the minimum of all elements of the hyper array.

Returns:

the minimum of all elements of the hyper array

max

public double max()

Returns the maximum of all elements of the hyper array.

Returns:

the maximum of all elements of the hyper array

equal

public boolean equal(HyperArray a)

Compares the hyper array with another one. The arrays are equal if the have same dimensions and same element values.

Parameters:

a - another hyper array

Returns:

true if the arrays are equal, false otherwise

equal

public boolean equal(double val)

Checks if all elements of the hyper array equal a particular value.

Parameters:

val - the value

Returns:

true if all elements of a equal val, otherwise false

hasNegativeValues

public boolean hasNegativeValues()

Checks if there are any negative elements in the hyper array.

Returns:

true if at least one element is negative, otherwise false

sum

public double sum(int... indexes)

Returns a partial sum of hyper array elements, namely sum across all dimensions whose indexes equal INDEX_CAN_VARY in the given index array. Other indexes are considered fixed.

Parameters:

indexes - the array of indexes, INDEX_CAN_VARY for varying ones

Returns:

a partial sum of hyper array elements;

prod

public double prod(int... indexes)

Returns a partial product of hyper array elements, namely product across all dimensions whose indexes equal INDEX_CAN_VARY in the given index array. Other indexes are considered fixed.

Parameters:

indexes - the array of indexes, INDEX_CAN_VARY for varying ones

Returns:

a partial product of hyper array elements;

min

public double min(int... indexes)

Returns a partial minimum of hyper array elements, namely minimum across all dimensions whose indexes equal INDEX_CAN_VARY in the given index array. Other indexes are considered fixed.

Parameters:

indexes - the array of indexes, INDEX_CAN_VARY for varying ones

Returns:

a partial minimum of hyper array elements;

max

public double max(int... indexes)

Returns a partial maximum of hyper array elements, namely maximum across all dimensions whose indexes equal INDEX_CAN_VARY in the given index array. Other indexes are considered fixed.

Parameters:

indexes - the array of indexes, INDEX_CAN_VARY for varying ones

Returns:

a partial maximum of hyper array elements;

toString

public java.lang.String toString()

Prints out the hyper array in the following form:
- if the hyper array is dimensionless, just prints its only element value
- for a uni-dimensional hyper array prints every element value on a separate line
- for two-dimensional hyper array prints as a tab separated 2D table with element values (dimension 0 vs dimension 1)
- for three and more dimensions prints a number of such tables, a table for each combination of indexes in dimensions 2 and higher.

Overrides:

toString in class java.lang.Object

Returns:

the textual representation of the hyper array