Koma项目中的N维数组使用指南

概述

在科学计算和数据处理领域，N维数组是一种基础且强大的数据结构。Koma项目提供了一个灵活的NDArray实现，能够高效地处理任意维度的数据容器。本文将详细介绍如何在Koma中使用N维数组，包括创建、迭代、形状操作和数值计算等核心功能。

N维数组的创建

Koma提供了多种创建NDArray的方式，支持泛型类型和特定数值类型的优化实现。

泛型数组创建

// 创建3x4x5的String类型数组，初始值为null
NDArray.createGenericNulls<String>(3,4,5)

// 创建3x4x5的String类型数组，所有元素初始化为"hello"
NDArray.createGeneric(3,4,5) { "hello" }

// 创建1x2的String类型数组，元素值为"hi"加上索引和
NDArray.createGeneric(1,2) { indices -> "hi ${indices.sum()}" }

// 创建3x4x5的Float类型数组，所有元素初始化为4.5
NDArray.createGeneric(3,4,5) { 4.5f }

数值类型优化创建

对于数值类型，Koma提供了专门的工厂方法，避免了装箱操作，显著提高了性能：

// 创建3x5x6的双精度浮点数组，初始值为0
NDArray.doubleFactory.zeros(3,5,6)

// 创建3x5x6的单精度浮点数组，值为均匀分布的随机数
NDArray.floatFactory.rand(3,5,6)

// 创建1x2x3x4x5的整型数组，初始值为1
NDArray.intFactory.ones(1,2,3,4,5)

// 创建8x8的双精度浮点数组，值为正态分布的随机数
NDArray.doubleFactory.randn(8,8)

数组迭代

N维数组中的每个元素都有两种索引表示方式：N维索引和线性索引。

基本迭代方式

val a: NDArray<Double> = NDArray.doubleFactory.randn(3,5,6)

// 简单迭代，不获取索引
a.forEach { println("元素值为 $it") }

// 带线性索引的迭代
a.forEachIndexed { idx, ele -> println("线性索引$idx处的元素为$ele") }

// 带N维索引的迭代
a.forEachIndexedN { indices, value ->
    println("位置(${indices.joinToString(",")})的元素为$value")
}

映射操作

val a: NDArray<Float> = NDArray.floatFactory.ones(3,5,6)

// 所有元素加1
a.map { ele -> ele + 1.0f }

// 元素值加上其线性索引
a.mapIndexed { idx, ele -> ele + idx }

// 将元素值设为其N维索引的和
a.mapIndexedN { idx, ele -> idx.sum().toFloat() }

数组形状操作

获取和改变形状

val a: NDArray<Float> = NDArray.floatFactory.ones(3,5,6)

// 获取当前形状
val shape = a.shape()  // 返回arrayOf(3,5,6)

// 改变形状
val b = a.reshape(6,3,5)

注意：重塑操作必须保持元素总数不变，否则会抛出异常。

形状重塑的特性

重塑操作会保持元素的线性顺序，只是重新解释其N维索引：

val original = NDArray.floatFactory.rand(3,5,6)
val reshaped1 = original.reshape(6,3,5)
val reshaped2 = original.reshape(1,90)

// 线性迭代结果相同
original.toIterable().forEach {
    assert(it == reshaped1.next() && it == reshaped2.next())
}

数值运算

对于数值类型的NDArray，Koma支持基本的数值运算：

val a = NDArray.floatFactory.rand(3,5,6)
val b = 3 * a + a * a  // 逐元素运算

注意：线性代数运算（如矩阵乘法）不适用于NDArray，因为它们需要特定的二维结构。

类型转换

转换为矩阵

NDArray可以转换为Matrix，但需要满足特定条件：

// 成功转换：2维数值数组
NDArray.floatFactory.rand(3,6).toMatrix()

// 失败情况示例
NDArray.floatFactory.rand(3,5,6).toMatrixOrNull()  // 维度过多
NDArray.createGenericNulls<String>(3,4).toMatrixOrNull()  // 非数值类型

类型安全考虑

对于泛型NDArray，需要使用toMatrixOrNull进行安全转换：

fun <T> safeConvert(a: NDArray<T>) = a.toMatrixOrNull()

总结

Koma的NDArray提供了强大而灵活的N维数据容器功能，无论是创建、迭代、形状操作还是数值计算，都设计得既直观又高效。通过合理使用泛型和特定数值类型的优化实现，开发者可以在保证类型安全的同时获得最佳性能。