Documentation

# `hfarray`

Create an array of hardware floating-point values

MuPAD® notebooks will be removed in a future release. Use MATLAB® live scripts instead.

MATLAB live scripts support most MuPAD functionality, though there are some differences. For more information, see Convert MuPAD Notebooks to MATLAB Live Scripts.

## Syntax

```hfarray(`m1 .. n1`, <`m2 .. n2, …`>)
hfarray(`m1 .. n1`, <`m2 .. n2, …`>, `index1 = number1, index2 = number2, …`)
hfarray(`m1 .. n1`, <`m2 .. n2, …`>, `List`)
hfarray(<`m1 .. n1, m2 .. n2, …`>, `ListOfLists`)
```

## Description

`hfarray(...)` creates an array specialized to hold hardware floating-point values. These values do not react to `DIGITS`, and no symbolic expressions can be placed into an `hfarray`. The values can be real or complex. If you pass symbolic objects to `hfarray`, it throws an error.

`hfarray(m_1..n_1, m_2..n_2, ...)` creates an array of floating-point zeroes, where the first index runs from m1 to n1, the second index runs from m2 to n2, and so on.

`hfarray(m_1..n_1, m_2..n_2, ..., List)` creates an array of floating-point numbers with entries initialized from `List`.

`hfarray(ListOfLists)` creates an array of floating-point numbers with entries initialized from `ListOfLists`. The dimension of the `hfarray` is the same as the dimension of `ListOfLists`.

Arrays are container objects for storing data. In contrast to `tables`, the indices must be sequences of integers. While `tables` can grow in size dynamically, the number of entries in an array created by hfarray is fixed.

Arrays created via `hfarray` are of domain type `DOM_HFARRAY`. They can only contain floating-point numbers as entries. Internally, these floating-point numbers are stored as hardware floating values with about 15 significant decimal digits (“double precision”). This data type serves for storing large amounts of numerical data. For example, an array of floating-point values with 15 significant decimal digits created via `array` (using `DIGITS` = 15) takes nearly 10 times as much storage space as the corresponding array created by `hfarray`.

On input, the entries passed to `hfarray` can be MuPAD® floating-point numbers, integers or rational numbers, or exact numerical expressions such as `PI + sin(sqrt(2))` that can be converted to floating-point numbers. Exact input data are automatically converted to hardware floating-point values of double precision. This conversion does not depend on the current value of `DIGITS`!

### Note

Entries of absolute value smaller than about 10- 308 are stored as 0.0 by `hfarray`!

For an array `A` of type `DOM_HFARRAY` and a sequence of integers `index` forming a valid array index, an indexed call `A[index]` returns the corresponding entry. See Example 1 and Example 5.

An indexed assignment of the form `A[index] := entry` initializes or overwrites the entry corresponding to `index`. See Example 1 and Example 5.

The index boundaries must satisfy m1n1, m2n2, and so on. The dimension of the resulting array is the number of given range arguments; at least one range argument must be specified. The total number of entries of the resulting array is (n1 - m1 + 1) (n2 - m2 + 1) ….

Arrays created by `hfarray` cannot have uninitialized entries. Entries are automatically set to 0.0 if no values are specified. See Example 1.

If equations of the form ```index = entry``` are present, then the array entry corresponding to `index` is initialized with `entry`. This is useful for selectively initializing some particular array entries.

Each index must be a valid array index of the form `i1` for one-dimensional arrays and ```(i1, i2, …)``` for higher-dimensional arrays, where ```i1, i2, …``` are integers within the valid boundaries, satisfying m1i1n1, m2i2n2, and so on, and the number of integers in `index` matches the dimension of the array.

If you use the argument `List`, then the resulting array is initialized with the entries from `List`. This is useful for initializing all array entries at once. The list must have (n1 - m1 + 1) (n2 - m2 + 1) … elements, each becoming an operand of the array to be created. In case of two-dimensional arrays, regarded as a matrix, the list contains the entries row after row.

The argument `ListOfLists` must be a nested list matching the structure of the array exactly. The nesting depth of the list must be greater or equal to the dimension of the array. The number of list entries at the k-th nesting level must be equal to the size of the k-th index range, that is, nk - mk + 1. See Example 7.

A one-dimensional array is printed as a row vector. The index corresponds to the column number.

A two-dimensional array is printed as a matrix. The first index corresponds to the row number, and the second index corresponds to the column number.

Arrays of dimension greater than two are printed in the form ```hfarray(m_1..n_1, m_2..n_2, dots, index_1 = entry_1, index_2 = entry_2, ...)```. See Example 6 and Example 7.

Arithmetic operations are not defined for arrays of domain type `DOM_ARRAY`. Use `matrix` to create 1-dimensional vectors or 2-dimensional matrices in the mathematical sense.

Arithmetic operations are defined for arrays of domain type `DOM_HFARRAY`. For example, linear combination of arrays `A, B` can be computed via `a*A + b*B` if `A, B` have the same format and if the scalar factors `a, b` are numbers (floating-point values, integers, or rationals). Two-dimensional hfarrays `A, B` are processed like matrices: operations, such as matrix multiplication `A*B`, matrix powers `A^n`, or matrix inversion `1/A`, are possible wherever this is meaningful mathematically. See Example 8.

## Examples

### Example 1

Hardware float arrays do not have uninitialized entries. If no initialization value is given, the corresponding entry is set to 0.0:

`hfarray(-1..5)`

Set one of the entries to the floating-point approximation of PI and another entry to the floating-point approximation of `sqrt(2)*exp(2)`:

`hfarray(-1..5, 2 = PI, 4 = sqrt(2)*exp(2))`

Use a list of random values to specify entries of the array:

`hfarray(-1..5, [frandom() \$ i = -1..5])`

Use a nested list to specify entries of an array:

`hfarray(1..2, 1..3, [[1, 2, 3], [4, 5, 6]])`

Alternatively, use a flat list:

`hfarray(1..2, 1..3, [1, 2, 3, 4, 5, 6])`

### Example 2

Array boundaries may be negative integers as well:

```A := hfarray(-1..2, -3..-1, [[-1, -1, -1], [ 0, 0, 0], [ 1, 1, 1], [ 2, 2, 2]])```

`A[-1, -2], A[0, -3], A[2, -3]`

`delete A:`

### Example 3

If the dimension and size of the `hfarray` are not specified explicitly, then both values are taken from the given list:

```hfarray([1.0,2.0,3.0,4.0,5.0]) = hfarray(1..5, [1.0,2.0,3.0,4.0,5.0]); bool(%)```

Note that all subfields of one dimension must have the same size and dimension. Therefore, the following input leads to an error:

`hfarray([[1],[3,4],[5,6]])`
```Error: Invalid argument. [hfarray] ```

### Example 4

You can use the `\$` operator to create a sequence of initialization equations:

`hfarray(1..4, 1..4, (i, i) = 1 \$ i = 1..4)`

Equivalently, you can use the `\$` operator to create an initialization list:

`hfarray(1..8, [i*PI \$ i = 1..8])`

### Example 5

Create a 2×2 matrix as a 2-dimensional array:

`A := hfarray(1..2, 1..2, (1, 1) = 1.0, (2, 2) = 1.0)`

Internally, array entries are stored in a linearized form. They can be accessed in this form via `op` or via indexed access:

`op(A, 1), op(A, 2), op(A, 3), op(A, 4)`

`A[1, 1], A[1, 2], A[2, 1], A[2, 2]`

Modify an array entry by an indexed assignment:

```A[2, 2] := PI: A[1, 2] := 5: A```

`delete A:`

### Example 6

Create a 3-dimensional hfarray:

`A := hfarray(1..2, 2..3, 3..4, (1, 2, 3) = 123, (2, 3, 4) = 234)`
```hfarray(1..2, 2..3, 3..4, [123.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 234.0]) ```
`delete A:`

### Example 7

You can use a nested list to initialize a two-dimensional hfarray. The inner lists are the rows of the created matrix:

`hfarray(1..2, 1..3, [[1, 2, 3], [4, 5, 6]])`

Create a three-dimensional hfarray and initialize it from a nested list of depth three. The outer list has two entries for the first dimension. Each of these entries is a list with three entries for the second dimension. Finally, the innermost lists each have one entry for the third dimension:

```hfarray(2..3, 1..3, 1..1, [ [ [1], [2], [3] ], [ [4], [5], [6] ] ])```
```hfarray(2..3, 1..3, 1..1, [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]) ```

### Example 8

Basic arithmetic is available for arrays of domain type `DOM_HFARRAY`:

```A := hfarray(1..5, [1, 2, 3, 4, 5]): B := hfarray(1..5, [5, 4, 3, 2, 1]): A + B```

`2*A`

`2*A - 3* B`

Two-dimensional arrays of type `DOM_HFARRAY` are regarded as matrices. They can be multiplied accordingly:

```A := hfarray(1..3, 1..3, [frandom() \$ i = 1..9]): B := hfarray(1..3, 1..2, [frandom() \$ i = 1..6]): A, B, A * B, A^10 * B```

The following command computes the matrix inverse of `A`:

`1/A`

Some functions, such as `norm`, accept hfarrays:

`norm(A)`

## Parameters

 ```m1, n1, m2, n2, …``` The index boundaries: integers ```index1, index2, …``` A sequence of integers defining a valid array index ```number1, number2, …``` Real or complex floating-point numbers or numerical expressions that can be converted to real or complex floating-point numbers `List` A plain list of entries for initializing the array `ListOfLists` A nested list (of lists of lists of …) of entries for initializing the array

## Return Values

Object of type `DOM_ARRAY` or `DOM_HFARRAY`, respectively.

#### Mathematical Modeling with Symbolic Math Toolbox

Get examples and videos