# Lagoon (Linear Algebra)

Documentation for the `%base` desk's `/lib/lagoon.hoon` library, which contains linear algebra operations.

Lagoon is a standard library which lives outside of the `/sys` kernel and supports userspace applications which need vectors, matrices, and other linear algebra data structures and operators. Lagoon is not currently subject to kelvin versioning.

Lagoon is intended to support general-purpose linear algebraic types, but at this point it focuses on integers and IEEE 754 floating-point numbers.

## Data Types

Lagoon's data types are supplied by `/sur/lagoon`.

```
/-  lagoon
```

## `$ray`

$$n$$-dimensional data array.

A pair of a bare array as an LSB atom with an associated metadata descriptor.

#### Source

```
+$  ray               ::  $ray:  n-dimensional array
  $:  =meta           ::  descriptor
      data=@ux        ::  data, row-major order, 1-pin MSB
  ==
```

#### Discussion

## `$meta`

Metadata for `$ray`.

A description of the necessary metadata to disambiguate an atom into an array. The dimensionality of the array is derived from `.shape`; the block width from `.bloq`; and the type of data each entry should be interpreted as from `.kind`. An arbitrary noun `.tail` is supplied for various current and future purposes.

#### Source

```
+$  meta              ::  $meta:  metadata for a $ray
  $:  shape=(list @)  ::  list of dimension lengths
      =bloq           ::  logarithm of bitwidth
      =kind           ::  name of data type
      tail=*          ::  placeholder for future data (jet convenience)
  ==
```

#### Discussion

An array has a dimensionality, and a length-$$5$$ vector is not the same as a $$5 \times 1$$ or a $$5 \times 1 \times 1$$ array even if the data representation as an atom is the same.

Metadata are constrained by various factors; for instance, an IEEE 754 floating-point array may only be of `.bloq` sizes 4 (16-bit half-precision, `@rh`), 5 (32-bit regular precision, `@rs`), 6 (64-bit double precision, `@rd`), and 7 (128-bit quadruple-precision, `@rq`). A `.bloq` size of 3 will fail due to no operators being implemented for that bit width.

## `$kind`

Array scalar type.

#### Source

```
+$  kind              ::  $kind:  type of array scalars
  $?  %i754           ::  IEEE 754 float
      %uint           ::  unsigned integer
      %int2           ::  2s-complement integer (/lib/twoc)
  ==
```

#### Discussion

Lagoon is a general-purpose linear algebra platform. At the current time, it provides support for:

* `%i754`, IEEE 754 floating-point numbers.
* `%uint`, unsigned integers (to bit width, not arbitrarily sized like conventional atoms).
* `%int2`, twos-complement integers (to bit width, not `@s`-style ZigZag atoms).

## `$baum`

$$n$$-dimensional array with metadata, unwrapped.

`$baum` is the tape to `$ray` as cord: that is, it unpacks the array atom into a list. This is relatively inefficient, but can be convenient for practical operations.

#### Source

```
+$  baum              ::  $baum:  ndray with metadata
  $:  =meta           ::
      data=ndray      ::
  ==
```

## `$ndray`

$$n$$-dimensional array with metadata, unwrapped.

`$ndray` is the tape to `$data=@ux` as cord: that is, it unpacks the array atom into a list. This is relatively inefficient, but can be convenient for practical operations.

#### Source

```
+$  ndray             ::  $ndray:  n-dim array as nested list
    $@  @             ::  single item
    (list ndray)      ::  nonempty list of children, in row-major order
```

## `$slice`

Submatrix (2D only)

A `$slice` stores index bounds for selecting a submatrix from a 2D array. If the `(unit @)` is `~`, then the index either runs from the beginning of the array or until the end, depending on its position.

#### Source

```
+$  slice  (unit [(unit @) (unit @)])
```

## Operators

* [Convenience functions](/hoon/lagoon/conv.md) - Functions for printing, getting/setting, or otherwise meta-scale operating on an array.
* [Builders](/hoon/lagoon/build.md) - Functions to produce standard arrays.
* [Structures](/hoon/lagoon/structure.md) - Functions to reshape or manipulate arrays.
* [Arithmetic](/hoon/lagoon/math.md) - Functions for arithmetically operating on one or more arrays.

## Jetting

`/lib/lagoon` is jetted as part of the `%non` core. Deterministic IEEE 754 floating-point arithmetic is provided by SoftBLAS built on the reference SoftFloat used by the rest of Urbit's `@rs` etc. support.

* [SoftBLAS](https://github.com/urbit/softblas)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.urbit.org/hoon/lagoon.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.