danger

This module's API is experimental. The main idea is not bad, but there are still a lot of things to think about.

danger

This module's API reference is not yet ready.

Kone: Multidimensional Collections

This module provides an API for multidimensional lists. They are used to represent matrices (and are useful in case you need tensors).

About learning order

This module is based on Kone's own iterables.

Applying the dependencies

Gradle Kotlin DSL

build.gradle.kts

dependencies {
    implementation("dev.lounres:kone.multidimensionalCollections:0.0.0-experiment")
}

Gradle Groovy DSL

build.gradle

dependencies {
    implementation 'dev.lounres:kone.multidimensionalCollections:0.0.0-experiment'
}

Maven

pom.xml

<dependency>
    <groupId>dev.lounres</groupId>
    <artifactId>kone.multidimensionalCollections</artifactId>
    <version>0.0.0-experiment</version>
</dependency>

Multidimensional shapes API

To work with a multidimensional list, you need to know its dimension and size in each dimension. One can represent such information as an array of positive (non-negative) integers. That's why there is type alias MDShape for KoneUIntArray. For example, usual list, row vector, and column vector have shape [n], whereas matrix has shape [n, m]. It's also obvious that each cell in the multidimensional list of shape $[n_1, \dots, n_k]$ has index that looks like $[m_1, \dots, m_k]$ where $0 \leqslant m_i < n_i$ for each $i$ from $1$ to $k$.

How do we iterate over them? Well, you can iterate in any order you want. But in Kone, there is an interface MDShapeIndexer that describes any iterator over the multidimensional list's indices.

💭 Concept: multidimensional list "linearisation"

Say, you want to store a multidimensional list in one place of your memory instead of a lot of different places linked with each other. Then you have to somehow store it in one array. It means there should be mapping of multidimensional indices to usual ("linear") array indices and vice versa. Such representation of multidimensional list as an array is called linearisation of the list. Also, indices in the array are called offsets of the indices (and vice versa, the indices of multidimensional list are called indices of the offsets).

Linearising indexers API

There is a special interface MDShapeOffsetting that also provides conversions of offsets into indices and vice versa. See index and offset functions.

Also, there is MDShapeStrides class that implements MDShapeOffsetting that receives an order of dimensions in the shape and iterates in them by the first dimension in the order, then by the second one, and so on. For example, for shape [2, 3, 4] and order of dimensions [1, 0, 2] the order of indices will be [0, 0, 0], [0, 1, 0], [0, 2, 0], [1, 0, 0], [1, 1, 0], [1, 2, 0], [0, 0, 1], [0, 1, 1], and so on.

And default orders for the class are "column" order from the first to the last and "row" order from the last to the first. Corresponding strides can be obtained via ColumnMDShapeStrides and RowMDShapeStrides functions.

Multidimensional list API

In Kone, multidimensional lists are structures that consist of:

1. a multidimensional shape,
2. and a collection of elements where each corresponding to the shape index is associated with its own element from the collection and all elements from the collections are associated with.

Multidimensional lists are represented via MDList interface. There is a settable version SettableMDList of it that lets to change its elements preserving shape and indices.

Also, there are special inheritors (MDList1 and SettableMDList1 for dimension 1, MDList2 and SettableMDList2 for dimension 2) that represent 1-dimensional and 2-dimensional immutable and settable lists.

See API reference for other declarations.