com.anylogic.engine.HyperArray

All Implemented Interfaces:: Serializable

public class HyperArray
extends Object
implements 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:: AnyLogic North America, LLC https://anylogic.com
See Also:: Serialized Form

Field Summary

Modifier and Type	Field	Description
`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.

Constructor Summary

Constructor	Description
`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(Dimension... dims)`	Creates a hyper array with the dimensions specified.
`HyperArray(HyperArray original)`	Creates a copy of a given hyper array.

Method Summary

Modifier and Type	Method	Description
`double`	`average()`	Returns the average of all elements of the hyper array.
`void`	`copyFrom(HyperArray original)`	Copies all data from another hyperarray.
`void`	`decrement(int... indexes)`	Decrements (-1) element(s) with the given index(es).
`void`	`decrementBy(double value, int... indexes)`	Decrements value(s) of given element(s) by the given value.
`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.
`void`	`increment(int... indexes)`	Increments value(s) of given element(s) by 1.
`void`	`incrementBy(double value, int... indexes)`	Increments value(s) of given element(s) by the given value.
`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.
`void`	`multiply(double factor, int... indexes)`	Multiplies element(s) with the given index(es) by the given `factor`.
`double`	`prod()`	Returns a product of all hyper array elements.
`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.
`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 Details

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 Details

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 Details

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

prod

public double prod()

Returns a product of all hyper array elements.

Returns:: a product of hyper array elements

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

increment

public void increment(int... indexes)

Increments value(s) of given element(s) by 1. INDEX_CAN_VARY can be used to increment across all the elements of a particular dimension.

Parameters:: indexes - defines the element(s) to be changed. The array of indexes, INDEX_CAN_VARY for varying ones

incrementBy

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

Increments value(s) of given element(s) by the given value. INDEX_CAN_VARY can be used to increment across all the elements of a particular dimension.

Parameters:: value - the value to add to array elements; indexes - defines the element(s) to be changed. The array of indexes, INDEX_CAN_VARY for varying ones

decrement

public void decrement(int... indexes)

Decrements (-1) element(s) with the given index(es). INDEX_CAN_VARY can be used to decrement across all the elements of a particular dimension.

Parameters:: indexes - defines the element(s) to be changed. The array of indexes, INDEX_CAN_VARY for varying ones

decrementBy

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

Decrements value(s) of given element(s) by the given value. INDEX_CAN_VARY can be used to decrement across all the elements of a particular dimension. Calling this method is equal to calling incrementBy( -value, indexes... )

Parameters:: value - the value to subtract from array elements; indexes - defines the element(s) to be changed. The array of indexes, INDEX_CAN_VARY for varying ones

multiply

public void multiply(double factor,
 int... indexes)

Multiplies element(s) with the given index(es) by the given factor. INDEX_CAN_VARY can be used to multiply across all the elements of a particular dimension.

Parameters:: factor - the factor to apply to array elements; indexes - the array of indexes, INDEX_CAN_VARY for varying ones

toString

public 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 Object
Returns:: the textual representation of the hyper array

Class HyperArray

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

INDEX_CAN_VARY

Constructor Details

HyperArray

HyperArray

HyperArray

HyperArray

Method Details

getDimensions

size

getData

getPosOf

get

set

set

setData

set

copyFrom

sum

prod

average

stddev

min

max

equal

equal

hasNegativeValues

sum

prod

min

max

increment

incrementBy

decrement

decrementBy

multiply

toString